Macros in Komodo can be written in JavaScript or Python. The Macro API for
JavaScript is a subset of the Komodo JavaScript
API. Python macros have access to the XPCOM interface. The
komodo.
namespace for macro functions is deprecated, but
currently still available for supporting older macros and providing functions
in Python for which there are not direct equivalents in XPCOM.
The interfaces for the two macro languages are described separately:
The macro system is a powerful mechanism by which Komodo users can execute arbitrary code inside the Komodo process. It is easy for novices to write macros that can significantly disrupt Komodo's behavior, leading to instability and data loss. Avoid experimenting with macros while working with important files.
Of particular note:
The Komodo JavaScript API is under active development. If you have questions or feedback about the API, please post to the Komodo Macros and Extensions forum.
The API described below may change in future releases (we will of course try to minimize backwards-incompatible changes).
For macros, the most important parts of the Komodo JavaScript API are:
ko.views.manager.currentView
object which contains:
scimoz
object for
manipulation of code buffers.document
object for
manipulation of documents in memory.document.file
object,
corresponding to files on disk.ko.commands.doCommand(...)
function to execute Komodo commands.ko.open.URI(...)
function to open a local or remote file using a URI.ko.projects.findPart(...)
function to find other components (snippets, run commands, other macros,
etc).ko.interpolate
object which contains:
interpolateStrings(...)
function for evaluation of interpolation
codesgetWordUnderCursor()
function to retrieve the word under the editing cursor.ko.run.runEncodedCommand(...)
function to open a local or remote file using a URI.The ko.views.manager.currentView.scimoz
object corresponds to
the main text editing widget that contains and manipulates files in the Editor
Pane. It is a thin wrapper around the Scintilla widget, an open-source
component written by Neil Hodgson (www.scintilla.org).
The Scintilla API is large, complex and subject to change. This document only contains the calls most relevant to Komodo, and notes some common patterns of use relevant to changing the editor widget.
ko.commands.doCommand('cmdCut')
is the preferred
method).ko.commands.doCommand('cmd_newlineExtra')
.start
and end at
end
.pos
.Invalid Parameters: The Scintilla API assumes that users of the API do their own error-checking. Passing arguments that are out of bounds or otherwise erroneous can result in Komodo crashing.
The Undo
Stack: Scintilla manages the "undo" stack. To treat
a sequence of operations as a single operation for the sake of
Undo/Redo, wrap these operations in a beginUndoAction
/ endUndoAction
pair. The
endUndoAction
must be called even in the case of an
exception in the code. Otherwise, the undo stack will be
corrupted and might lose data.
For example, for JavaScript:
ko.views.manager.currentView.scimoz.beginUndoAction() try { ... // do your sequence here } finally { ko.views.manager.currentView.scimoz.endUndoAction() }
The ko.views.manager.currentView.document
object refers to the
current document. A document contains the contents of the file being edited.
These contents will be different than those of the file on disk if the file is
unsaved or "dirty".
"myfile.txt"
)."C:\Code\myfile.txt"
)."Python"
, "Perl"
, etc.The file
object is an attribute of document
objects, and corresponds to a
wrapper object around the file object.
document.file
attributes"file:///C:/Code/myfile.txt"
)."C:\Code\myfile.txt"
), or the URI if the URI is
not of the file://
scheme."myfile.txt"
)."C:\Code"
).Signature:
ko.commands.doCommand(commandId)
Execute the internal Komodo command specified by
commandId
.
Command IDs and their corresponding functions are available in the Command ID reference.
Most editor-related commands require that the Editor Pane be
in focus. To ensure focus before invoking doCommand
,
set the focus explicitly as follows:
ko.views.currentView.setFocus()
Signature:
ko.open.URI(uri_string#line_number)
Open the file specified by the URI string and move the cursor to the line number specified after '#' (if any).
All file access protocols used by Komodo are valid. For example:
ko.open.URI("file:///home/user/example.txt#33"); ko.open.URI("ftp://example.org/pub/example.xml"); ko.open.URI("scp:///host.example.org/home/user/file.txt#11");
Signature:
ko.projects.findPart(type, name, where) -> part
Find a "part" (the internal name for a component such as a snippet, another macro, a run command, etc) in the Toolbox or a project.
type
: The type of component to search for. It
can be one of:"snippet"
"command"
"macro"
"file"
"folder"
"dialog"
"URL"
"template"
"DirectoryShortcut"
name
: The component's name.where
: A string corresponding to the component
container that should be searched. Supported values are:
"toolbox"
"shared toolbox"
"toolboxes"
"container"
"*"
Signature:
ko.interpolate.interpolateString(s[, bracketed]) -> string
Evaluate interpolation shortcuts in the given string.
s
: The string to interpolate.bracketed
: An optional boolean value
indicating whether plain (e.g. %F
) or bracketed
(e.g. [[%F]]
) syntax is being used. If not
specified, plain interpolation is used (i.e.
bracketed=false
)</.Signature:
ko.interpolate.getWordUnderCursor() -> string
This function returns the word under the cursor in the current buffer.
Signature:
ko.run.runEncodedCommand(window, command[, callback]) -> string
Runs a shell command and optional callback function.
window
: Required (literal) argument indicating
Komodo's top-level window object. This allows the method to be
called from dialog boxes or other sub-windows.command
: The shell command to run. Can include
arguments in Python dict
format.callback
: An optional callback function.For example:
function did_it() { alert("Done."); } ko.run.runEncodedCommand(window, 'sleep 5', did_it);
Command options and environment variables can be added in
curly braces "{...}" after the command in Python
dict
format. For example:
ko.run.runEncodedCommand(window, 'svn up "%F" {"cwd": "%D", "env": "SVN_SSH=plink.exe"}')
The following JavaScript macro uses Komodo's
cmd_refreshStatus
function as the callback in
ko.run.runEncodedCommand()
. This updates the SCC
status information after running 'svn up
' on the
file in the current editor tab:
if (komodo.view) { komodo.view.setFocus(); ko.run.runEncodedCommand(window, 'svn up "%F"', (function (view) { return function () { view.setFocus(); komodo.doCommand('cmd_refreshStatus'); } })(komodo.view) ); };
Macros written in Python can use the XPCOM interface. Though it
is deprecated, komodo.
namespace is still available for those
functions (interpolate()
and getWordUnderCursor()
)
which cannot be done easily with XPCOM.
To use the XPCOM components described below, add the following to your macro:
from xpcom import components
There is no global object in Python macros to get the current "view" (i.e. the main active Komodo tab) because this can change during macro execution. Instead, a view object can be created in the macro at the point where it will be used. For example:
viewSvc = components.classes["@activestate.com/koViewService;1"]\ .getService(components.interfaces.koIViewService) view = viewSvc.currentView
The view
object will have the same properties as
ko.views.manager.currentView
, exposing:
scimoz
object for
manipulation of code buffers.document
object for
manipulation of documents in memory.document.file
object,
corresponding to files on disk.To open a URI:
obsvc = components.classes["@mozilla.org/observer-service;1"].\ getService(components.interfaces.nsIObserverService); obsvc.notifyObservers(None, 'open-url', uri);
There is currently no equivalent in XPCOM for evaluating interpolation codes.
This can be done using the old komodo
namespace as follows:
import komodo komodo.interpolate()
Some interpolation shortcuts cannot be used within Python
macros. These include %P
and %ask
, and
the :orask
modifier on other shortcuts. A
ValueError
is raised if they are used.
There is currently no equivalent in XPCOM to retrieve the word under the
editing cursor. This can be done using the old komodo
namespace
as follows:
import komodo komodo.getWordUnderCursor()
To execute Komodo command:
def doCommand(commandId): _observerSvc = components.classes["@mozilla.org/observer-service;1"]\ .getService(components.interfaces.nsIObserverService) _observerSvc.notifyObservers(None, 'command-docommand', commandId);
To find other components (snippets, run commands, other macros, etc):
var _partSvc = components.classes["@activestate.com/koPartService;1"] .getService(components.interfaces.koIPartService); _partSvc.findPartForRunningMacro(type, name, where);