Script CotEditor on Mac with AppleScript

CotEditor works with AppleScript and JXA (JavaScript for Automation).

It has its own AppleScript dictionary so that you can look up all the classes or commands available with CotEditor. To open the dictionary:

In addition, script hooks can be used to automatically execute scripts in response to specific events. For details, see Run script on specific events.

To confirm the version history of the AppleScript support on CotEditor, see Support different CotEditor versions in AppleScript.

Classes

The original classes and properties that are defined in CotEditor.

Application

The CotEditor application.

Window

A CotEditor window.

Document

A CotEditor document.

Properties
contents
The contents of the document. (text)
text
The contents of the document. (text)
length
The number of characters of the document in UTF-16. (int) deprecated on CotEditor 4.4
selection
The current selection. (text selection)
encoding
The text encoding name of the document. (text)
IANA charset
The IANA charset name of the document. (text, e.g., Shift_JIS, EUC-JP)
has BOM
Has the text encoding a BOM (byte order mark)? (boolean) new on CotEditor 4.1
line ending
The line ending code of the document. (CR / LF / CRLF / NEL / LS / PS)
tab width
The width of a tab character in space equivalents. (int) new on CotEditor 2.1
expands tab
Are tab characters expanded to space? (boolean) new on CotEditor 3.1.2
wrap lines
Whether to wrap lines or not. (boolean)
coloring style
The syntax name of the document. (text)

Text selection

The current selection.

Properties
contents
The contents of the selection.
range
The range of characters in the selection. The format is '{location, length}'.
line range
The range of lines in the selection. The format is '{location, length}'. (length can be omitted, one line is selected even if it were 0 or 1)

Example

contents of selection of document 1
Returns the selected string in the frontmost document.
set contents of selection of front document to "Apple"
Replaces the selection with “Apple.”
range of selection of front document
Returns the selection range with {location, length}.
set range of selection of front document to {1, 12}
Select from the 1st character to the 12th character.
set line range of selection of front document to 10
Select the 10th line (no scrolling).
set range of selection of front document to {-15, -1}
Select from the 15th last character to the last but one (no scrolling).

Discussion

The selection property doesn’t work by itself. Use this property with others such as contents.

Starting form CotEditor 5.0, characters are counted in the Unicode grapheme cluster unit. This is the same as the specification of AppleScript 2.0.

When ‘location’ is a negative value, the selection range starts from the ‘location’-th last character.
When ‘length’ is a positive value, the selection range becomes the ‘length’ characters starting from ‘location.’ If ‘length’ is larger than the number of the rest characters in the document, the range is from ‘location’ to the end.
When ‘length’ is a negative value, the selection range ends at the ‘length’-th last character. If the absolute value of ‘length’ is smaller than ‘location’ (that is, the selection’s end point is before ‘location’), the caret just moves to ‘location’ (same as when {location, 0} was input).

This specifying method is based on substr in PHP.

The command for changing selection doesn’t scroll through the editor. Use the scroll to caret command or jump command to make the selection remain in the view.

Commands

The original commands that are defined in CotEditor.
(properties surrounded by [ ] are options)

write to console

write to console
Print a string on CotEditor’s console window.
[title (boolean)]
Should the script name be displayed with? (added on CotEditor 5.0.7)
[timestamp (boolean)]
Should the timestamp be displayed with? (added on CotEditor 5.0.7)

Availability

CotEditor 3.2.0+

Example

write to console "Script failed."
Appears the message "Script failed." on the CotEditor’s console.
write to console "calculating…" without title and timestamp
Appears the message "calculating…" without the script name and timestamp on the CotEditor’s console.

find

find
Searches a string, selects the string and returns true, if any, otherwise returns false.
for (text)
The string to search for.
[RE (boolean)]
Perform regular expression search or not.
[wrap (boolean)]
Perform wrap search or not.
[ignore case (boolean)]
Ignore case or not.
[backwards (boolean)]
Perform backwards search or not.
Return value
boolean
target
‘document’ object

Example

find front document for "Apple" with ignore case
Searches “Apple” with ignoring case, starting from the current selection to the end of the frontmost document, and returns the result.

Discussion

The search starts from the current selection (caret position).
For example, when not using the wrap or backwards options and when there are no matching string after the current selection, then false is returned.

The regular expression search cannot search backwards. If both options were specified at the same time, RE takes precedence and backwards is ignored.

replace

replace
Searches a string, replaces the string and returns the number of replacements, if any, otherwise returns 0.
for (text)
The string to search for.
to (text)
The string to replace with.
[all (boolean)]
Search the whole document or not.
[RE (boolean)]
Perform regular expression search or not.
[wrap (boolean)]
Perform wrap search or not.
[ignore case (boolean)]
Ignore case or not.
[backwards (boolean)]
Perform backwards search or not.
Return value
int
target
‘document’ object

Example

replace front document for "Apple" to "Orange" with all and ignore case
Searches “Apple” with ignoring case in the frontmost document, replaces the matching strings with “Orange” and returns the number of replacements.

Discussion

As in the case of the find command, the search starts from the current selection (caret position). Use the all option for searching the whole document.

After replacing the whole document using the all option, the caret moves to the head of the document. If there were no matching string, the caret doesn’t move.

The regular expression search cannot search backwards. If both options were specified at the same time, the backwards option is ignored.

scroll to caret

scroll to caret
Scrolls the window so that the caret or the selection can be seen.
target
‘document’ object

Example

scroll to caret front document
Scrolls the frontmost window so that the caret or the selection can be seen.

jump

jump
Move the caret to the specified location. At least, either one of a parameter is required.
to line (int)
The number of the line to jump.
[column (int)]
The location in the line to jump.

Availability

CotEditor 2.1.0+

Example

jump front document to line -1
Move the insertion point to the last line and scroll through the editor to view the specified area.

Discussion

If a negative value is provided, the line/column is counted from the end.

convert

convert
Converts the text encoding of the document.
to (text)
The new encoding, either in localized encoding name or an IANA charset name.
[lossy] (boolean)
Whether to allow “lossy” conversion (might result in loss of character that couldn’t be converted) or not.
[BOM] (boolean)
Whether to add a BOM (byte order mark). (added on CotEditor 4.1)
Return value
boolean
target
‘document’ object

Example

convert front document to "Unicode (UTF-8)" with BOM without lossy
Converts the text encoding of the frontmost window to Unicode (UTF-8) with BOM, returns the result.

Discussion

From CotEditor 4.0.7 on, the new encoding name accepts also IANA charset names.

reinterpret

reinterpret
Reinterpret the document with the specified text encoding.
as (text)
The encoding for reinterpreting, either in localized encoding name or an IANA charset name.
Return value
boolean
target
‘document’ object

Example

reinterpret front document as "Japanese (EUC)"
Reinterprets the document with EUC-JP, returns the result.

Discussion

Returns false if the file has never been saved.

Changes that are not yet saved are lost.

From CotEditor 4.0.7 on, the new encoding name accepts also IANA charset names.

shift

shift left
Shifts the current line left.
shift right
Shifts the current line right.
target
‘selection’ object

Example

shift right selection of front document
Shifts the line where the selection/caret is positioned right.

comment out

comment out
Append comment delimiters to selected text if possible.
uncomment
Remove comment delimiters from selected text if possible.
target
‘selection’ object

Availability

CotEditor 2.0.1+

Example

comment out selection of front document
Comment out the selected text.

Discussion

These commands do nothing if not possible for example in cases where no delimiters are set in the current syntax or no comment delimiters to remove are available.

string

string
Returns the string in the specified range regardless of the current selection.
in (list)
The range.
Return value
text
target
‘selection’ object

Example

string front document in {0, 10}
Returns the first ten letters of the document.

Discussion

Returns an empty string if the specified range was invalid.

This command does not change the specified range.

change case

change case
Uppercases/Lowercases/Capitalizes words.
to upper/lower/capitalized
The case type to change.
target
‘selection’ object

Example

change case selection of front document to upper
Uppercases alphabetic words in the selection.

change roman width

change roman width
Converts between halfwidth and full-width characters.
to half/full
The text width to change.
target
‘selection’ object

Example

change roman width selection of front document to full
Converts ASCII characters in the selection to their full-width equivalents.

change kana

change kana
Converts between Japanese Hiragana and Katakana.
to hiragana/katakana
The Japanese character mode to change.
target
‘selection’ object

Example

change kana selection of front document to katakana
Converts Hiragana in the selection to Katakana.

smart quotes

smarten quotes
Convert straight quotes in the selected text to typographical quotes if exists.
straighten quotes
Convert typographical quotes in the selected text to straight quotes if exists.
target
‘selection’ object

Availability

CotEditor 3.9.7+

Example

smarten quotes selection of front document
Convert straight quotes in the selected text to typographical quotes.

smart dashes

smarten dashes
Convert double hyphens in the selected text to dashes if exists.
target
‘selection’ object

Availability

CotEditor 3.9.7+

Example

smarten dashes selection of front document
Convert straight double hyphens in the selected text to dashes.

normalize unicode

normalize unicode
Performs Unicode normalization.
to NFKC/NFD/NFC/NFKD/NFKC Casefold/Modified NFC/Modified NFD
The normalized forms of Unicode text.
target
‘selection’ object

Availability

CotEditor 2.0.0+

Example

normalize unicode selection of front document to NFC
Perform Unicode normalization on the selection using normalization form C (NFC).

move line

move line up
Swap selected lines with the line just above.
move line down
Swap selected lines with the line just below.
target
‘selection’ object

Availability

CotEditor 2.3.0+

sort lines

sort lines
Sort selected lines ascending.
reverse lines
Reverse selected lines.
target
‘selection’ object

Availability

CotEditor 2.3.0+

delete duplicate line

delete duplicate line
Delete duplicate lines in selection.
target
‘selection’ object

Availability

CotEditor 2.3.0+

See also