Working with AppleScript

CotEditor supports AppleScript and JXA (JavaScript for Automation).

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

Classes

The original classes and properties that are defined in CotEditor.

Application
The CotEditor application.
Window
A CotEditor window.
view opacity
The opacity of the view. (real, from ‘0.2’ to ‘1.0’) deprecated on CotEditor 3.5
Document
CotEditor document.
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)
line ending
The line ending code of the document. (CR / LF / CRLF)
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.
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)

Sample codes for selection

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).

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 modelled after that of PHP's substr.

The command for changing selection doesn't scroll the window. Use the scroll to caret 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. new on CotEditor 3.2.0
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

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.

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.

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

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.

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.

scroll to caret

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

convert

convert
Converts the text encoding of the document.
to (Unicode text)
The new encoding.
lossy (boolean)
Whether to allow “lossy” conversion (might result in loss of character that couldn't be converted) or not.
return value
boolean
convert front document to "Unicode (UTF-8)" without lossy
Converts the text encoding of the frontmost window to UTF-8, returns the result.

reinterpret

reinterpret
Reinterpret the document with the specified text encoding.
as (Unicode text)
The encoding for reinterpreting.
return value
boolean

Returns false if the file has never been saved.

Changes that are not yet saved will be lost.

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

shift

shift left
Shifts the current line left.
shift right
Shifts the current line right.
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.

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.

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

string

string
Returns the string in the specified range regardless of the current selection.
in (list)
The range.
return value
Unicode text

Returns an empty string if the specified range was invalid.

This command does not change the specified range.

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

change case

change case
Uppercases/Lowercases/Capitalizes words.
to upper/lower/capitalized
The case type to change.

Works only for ‘selection’ objects.

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.

Works only for ‘selection’ objects.

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.

Works only for ‘selection’ objects.

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. new on CotEditor 3.9.7
straighten quotes
Convert typographical quotes in the selected text to straight quotes if exists. new on CotEditor 3.9.7

Works only for ‘selection’ objects.

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

smart dashes

smarten quotes
Convert straight double hyphens in the selected text to dashes if exists.new on CotEditor 3.9.7

Works only for ‘selection’ objects.

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.

Works only for ‘selection’ objects.

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. new on CotEditor 2.3.0
move line down
Swap selected lines with the line just below. new on CotEditor 2.3.0

Works only for ‘selection’ objects.

sort lines

sort lines
Sort selected lines ascending. new on CotEditor 2.3.0
reverse lines
Reverse selected lines. new on CotEditor 2.3.0

Works only for ‘selection’ objects.

delete duplicate line

delete duplicate line
Delete duplicate lines in selection. new on CotEditor 2.3.0

Works only for ‘selection’ objects.

See also