Script CotEditor 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:

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.

Properties
view opacity
The opacity of the view. (real, from ‘0.2’ to ‘1.0’) deprecated on CotEditor 3.5

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. (int)
selection
The current selection. (selection-object)
encoding
The text encoding name of the document. (Unicode text)
IANA charset
The IANA charset name of the document. (Unicode text, e.g.Shift_JIS, EUC-JP)
has BOM
Has the file 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 coloring style name of the document. (Unicode text)
line spacing
The spacing between lines. (real, from ‘0.0’ to ‘10.0’) deprecated on CotEditor 2.6

Selection-object

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 will be selected even if it were 0 or 0)

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.

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 will be 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’ (i.e. 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 the window. 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
Display a string on CotEditor’s console window.
target
‘document’ object

Availability

CotEditor 3.2.0+

Example

write to console "Script failed."
Display the massege "Script failed." on the CotEditor’s console.

find

find
Searches a string, selects the string and returns true, if any, otherwise returns false.
for (Unicode 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 (Unicode text)
The string to search for.
to (Unicode 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 caret to the last line and scroll the editor so that the speficifed area can be seen.

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 (Unicode 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 (Unicode 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 will be 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 style 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
Unicode 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