Mode Central

Scripting SubEthaEdit

SubEthaEdit can be scripted using AppleScript and, by proxy, other languages. Scripts can be placed within a mode's "Resources/Scripts/" directory to appear in the mode's "Mode" menu and its toolbar. If the Script is universally useful it can also be placed in "~/Library/Application Support/SubEthaEdit/Scripts/" to appear in the AppleScript menu. Scripts can also be installed in "/Library/Application Support/SubEthaEdit/Scripts/" if all users of the machine should benefit from them. The order the scripts appear in the menu is derived from their filenames.

Images for the script's toolbar icon should be placed either in the mode's "Resources" directory for mode-internal scripts or in the same directory as the script if it is a global script. Additional you can also use one of SubEthaEdit's built-in icons which include "ToolbarIconBuild", "ToolbarIconBuildAndRun", "ToolbarIconRun", "ToolbarIconRunInTerminal", "ToolbarIconTerminal", "ToolbarIconColorChooser" and "ToolbarIconOpenURL".

Each script should implement a "seescriptsettings()" handler that is called by SubEthaEdit to inquiry about the script's name, keyboard shortcut and other settings. The example script below does implement a list of all settings and documents their use in a comment.

Example: Rotate13

The following script can be used as a canonical example of scripting SubEthaEdit. It shows basic interaction with selections and the clipboard and uses a call to a perl script to implement the ROT13 algorithm.

-- see settings
on seescriptsettings()
    
    return {displayName:"Rotate13", shortDisplayName:"Run", keyboardShortcut:"^~$@r", toolbarIcon:"ToolbarIconRunInTerminal", inDefaultToolbar:"yes", toolbarTooltip:"Super secure encryption", inContextMenu:"yes"}
    
    -- Here is a overview of currently supported settings
    -- displayName: Name displayed in menus
    -- shortDisplayName: The short display name used for Toolbar
    -- keyboardShortcut: A keyboard shortcut. alt=~, ctrl=^, shift=$, cmd=@
    -- toolbarIcon: A toolbar image
    -- inDefaultToolbar: Should be in default toolbar?
    -- toolbarTooltip: Tooltip for the toolbar icon
    -- inContextMenu: Should it appear in the ctrl-click menu?
    
end seescriptsettings


-- the actual script

tell application "SubEthaEdit"
    set savedClipboard to the clipboard
    if (length of selection = 0) then
        set the clipboard to contents of front document as text
    else
        set the clipboard to contents of selection as text
    end if
end tell


-- the following is a command to call an external script, in this case perl
-- notice the export preamble which is essential to make pbpaste work with
-- utf8 content.
set shellscriptString to "export __CF_USER_TEXT_ENCODING=0x1F5:0x8000100:0x8000100; pbpaste | /usr/bin/perl -pe 'y/A-Za-z/N-ZA-Mn-za-m/'"
set shellresult to do shell script shellscriptString without altering line endings

tell application "SubEthaEdit"
    set the clipboard to savedClipboard
    
    if (length of selection = 0) then
        set contents of front document to shellresult
    else
        set contents of selection of front document to shellresult as text
    end if
end tell

Odds and ends of scripts running inside SubEthaEdit

When your scripts are running inside SubEthaEdit there are some subtle differences:

  • In Cocoa Scripting when you do a save, e.g. "save front document", you get an immediate timeout. So if you have to save a document prior to doing something else, you have to use something like this:

    The try block around the "save front document" catches the timeout and continues. The save still takes place. The if block is needed because if the document has not been saved before a save dialog is displayed, and since the "save front document" returns immediatly without waiting for the save action to happen you'd get the wrong data.
  • Another issue is context. The statements in your script which are not inside tell blocks run in a slightly different environment than in the Script Editor.
  • Currently there is a bug in Cocoa Scripting that prevents "path to resource" from working correctly and actually finding resources of SubEthaEdit when run from inside SubEthaEdit.