Interpolation Shortcuts

Interpolation shortcuts are codes embedded in run commands, snippets or templates that, at "execution" time, get replaced with values. For example, the path and name of the current file can be inserted via an interpolation shortcut when a run command is executed.

Interpolation shortcuts embedded in run commands are inserted via the Run Command dialog box. When using interpolation shortcuts in snippets or templates, insert the interpolation code using bracketed syntax. Run commands can be stored in a project or the Toolbox for frequent use.

Interpolation Code List

The following table contains all of the interpolation shortcut codes available in Komodo.

Code Description
% a literal percent sign (%); for example, Path = C:\temp; %%PATH%% inserts the directory "temp" at the beginning of the PATH statement
f the basename of the current file
F the full path and name of the current file
L the line where the editing cursor is located within the current file
d the base directory of the current file
D the entire directory path of the current file
P the full path of the active project
p the directory path of the active project
w the word under the cursor in the editor
W URL-escaped word under cursor; replaces characters that are not valid in a query string, such as spaces and ampersands
s the current selection; interpolates the text that is currently selected in the editor
S URL-escaped selection; replaces characters that are not valid in a query string, such as spaces and ampersands
perl the perl interpreter specified in Komodo's Perl preference
php the php interpreter specified in Komodo's PHP preference
python the python interpreter specified in Komodo's Python preference
tclsh the tclsh interpreter specified in Komodo's Tcl preference
wish the wish interpreter specified in Komodo's Tcl preference
browser the browser specified in Komodo's Web Browser preference
guid a new GUID (Global Unique Identifier)
date * the current date
ask * ask the user for the value when invoked
path * special Komodo directories
pref * values from Komodo preferences
debugger * runtime properties of the debugger system

* Codes marked with asterisks have special options, not the options described in the Basic Interpolation Options section. The options for these codes are described below.

 

Basic Interpolation Code Syntax

Interpolation code blocks come in two forms: bracketed and non-bracketed. Run commands use the non-bracketed format. Snippets and templates use the bracketed format.

 

Non-Bracketed Syntax

The syntax for a non-bracketed interpolation code is:

    %(<code><backref>:<options>...)

where <code> is one of the codes shown in the table above, <backref> is a number and <options>... depend on the specific code. Back-references and options are discussed in separate sections. The following are examples of non-bracketed interpolation code:

    %(perl)
    %w
    %guid2
    %(ask:Your Name:Trent Mick)

The parentheses are optional if the code block does not contain spaces. For example, the following two commands are equivalent:

    %ask:Name:Trent
    %(ask:Name:Trent)

 

Bracketed Syntax

The syntax for a bracketed interpolation code is:

    [[%(<code><backref>:<options>...)]]

where <code> is one of the codes shown in the table above, <backref> is a number and <options>... depend on the specific code. Back-references and options are discussed in other sections. The following are examples of bracketed syntax:

    [[%perl]]
    [[%w]]
    [[%guid2]]
    [[%ask:Your Name:Trent Mick]]

With bracketed interpolation codes, the parentheses are always optional. The double brackets enclose spaces, making parentheses unnecessary. For example, both of the following commands are valid:

    [[%ask:Your Name:Trent Mick]]
    [[%(ask:Your Name:Trent Mick)]]

Bracketed interpolation code blocks permit some excess space immediately adjacent to the double brackets. For example the following are equivalent:

    [[%ask:Your Name:Trent Mick]]
    [[ %ask:Your Name:Trent Mick]]
    [[%(ask:Your Name:Trent Mick) ]]
    [[ %(ask:Your Name:Trent Mick) ]]

 

Basic Interpolation Options

The following table shows the standard options available for most interpolation codes. These options do not apply to the codes displayed with an asterisk in the Interpolation Codes table.

Option Syntax Description
orask %(<code>:orask:<question>) If a value for code cannot be determined automatically, then the user is prompted when the command is invoked. question is text that will be displayed when the user is asked to enter a value.
else %(<code>:else:<default>) If a value for code cannot be determined automatically, then the default is used.

 

Date Code

A date interpolation code will be replaced with the current date, formatted according to a given optional format or the default format.

Date Code Syntax

The syntax of the date code is as follows:

    %(date<backref>:<optional-format>)
    [[%(date:<optional-format>)]]

As noted in the Basic Interpolation Code Syntax section, the parentheses are optional. The <backref> optional parameter is discussed in the Back-references section. The following examples are valid:

    %date
    [[%date]]
    %(date)
    %date:%H:%M:%S
    [[%date:%d/%m/%Y %H:%M:%S]]

Date Code Format Option

If no <optional-format> is specified in a date code, the default date format is used. Configure the default date format using Komodo's Internationalization preferences.

If this format is not appropriate, you can specify the format with a string in accordance with the spec for the "format" argument of Python's *time.strftime()* method [1]_. The table is reproduced here for convenience.

Directive Meaning
%a Locale's abbreviated weekday name.
%A Locale's full weekday name.
%b Locale's abbreviated month name.
%B Locale's full month name.
%c Locale's appropriate date and time representation.
%d Day of the month as a decimal number [01,31].
%H Hour (24-hour clock) as a decimal number [00,23].
%I Hour (12-hour clock) as a decimal number [01,12].
%j Day of the year as a decimal number [001,366].
%m Month as a decimal number [01,12].
%M Minute as a decimal number [00,59].
%p Locale's equivalent of either AM or PM.
%S Second as a decimal number [00,61].
%U Week number of the year (Sunday as the first day of the week) as a decimal number [00,53]. All days in a new year preceding the first Sunday are considered to be in week 0.
%w Weekday as a decimal number [0(Sunday),6].
%W Week number of the year (Monday as the first day of the week) as a decimal number [00,53]. All days in a new year preceding the first Sunday are considered to be in week 0.
%x Locale's appropriate date representation.
%X Locale's appropriate time representation.
%y Year without century as a decimal number [00,99].
%Y Year with century as a decimal number.
%Z Time zone name (or by no characters if no time zone exists).
%% A literal "%" character.

For more information about Python 2.2's time access and conversions, visit http://www.python.org/doc/2.2/lib/module-time.html

 

Ask Code

An "ask" code will prompt the user for the value to use as its replacement. The user is prompted using a pop-up dialog box. If a code snippet or run command includes more than one "ask" code, then the pop-up dialog box will request values for all of these codes.

Ask Code Syntax

The "ask" code prompts users to enter input in the Interpolation Query dialog box before running a command. The complete syntax for the %(ask) code is:

  %(ask[:NAME:[DEFAULT]])

...where "NAME" is an optional name to insert in the Interpolation Query dialog box and "DEFAULT" is an optional default value that appears in the dialog box.

Use the %(...:orask) modifier with other interpolation codes to prompt for input if no value can be determined. The syntax for a modified shortcut is:

  %(SHORTCUT:orask[:NAME])

...where "SHORTCUT" is the shortcut as displayed in the shortcut drop-down list and "NAME" is an optional name to insert in the Interpolation Query dialog box. See the Run Command Tutorial for examples of %(ask) and %(...:orask) shortcuts.

As noted in the Basic Interpolation Code Syntax section, usage of parentheses depends on the context. The following examples are valid:

  %ask
  [[%ask:Name]]
  %ask:Name:Joe
  %(ask:What is Your Name:Joe Smith)

Ask Code Options

An "ask" code takes two optional parameters. The first, <optional-question>, is the text to display to the user when prompting for the value for that code. The second, <optional-default>, is a default string to preload the text entry field in which the user specifies a value. For example:

  %(ask<backref>:<optional-question>:<optional-default>)
  [[%(ask<backref>:<optional-question>:<optional-default>)]]

The <backref> optional parameter is discussed in the Back-references section.

The Query Dialog for "ask"-modified and "orask"-modified Codes

When a list of strings are interpolated using interpolation shortcuts, the user may be prompted to supply values for certain codes. The user is asked via the Interpolation Query dialog box. This dialog will contain one or more text entry fields with labels describing the data expected for that field. These labels are determined from the specific interpolation code (both the "ask" code and the "orask" modifier include an option to specify a label).

The label or question fields maintain recently-entered results that are displayed as a drop-down list of matching recent entries.

 

Path Code

The "path" codes are used to provide special directory paths based on the installation of Komodo that is currently running. These include such items as the common data directory, which may be necessary if you are building run commands that you intend to work on shared files.

Path Code Syntax

The syntax of the path code is as follows:

    %(path<backref>:<pathName>)
    [[%(path<backref>:<pathName>)]]

Path Code Options

The path code takes one required parameter, "pathName". The pathName may be one of the following:

Path Name Meaning
userDataDir User-specific data directory where Komodo stores various information and files.
hostUserDataDir The userDataDir contains some host-specfic directories. This is most common on systems where user directories are shared and used from more than one computer.
commonDataDir The common data directory contains data and files that are shared between multiple users.
installDir This is the directory where Komodo is installed.

 

Debugger Code

The "debugger" codes are used to provide runtime values from the debugger subsystem in Komodo. These codes can be used to provide debugging information to applications such as the PerlApp component in ActiveState's Perl Developer Kit.

Debugger Code Syntax

The syntax of the debugger code is as follows:

    %(debugger<backref>:<value>)
    [[%(debugger<backref>:<value>)]]

Debugger Code Options

The debugger code takes one required parameter, "value". The value may be one of the following:

Debugger Value Meaning
address The hostname or address Komodo is running on.
port The TCP/IP port number that the debugger system is listening on.
proxyAddress The hostname or address of a debugger proxy that Komodo is using.
proxyPort The TCP/IP port number of a debugger proxy that Komodo is using.
proxyKey A session key, typically retrieved from the USER environment variable, that the proxy uses to match debug sessions with a specific running instance of Komodo.

 

Pref Code

This is a very advanced feature and is subject to change in future versions of Komodo.

The "pref" codes are used to provide values from Komodo's preferences, which are configured in the Preferences dialog box (Edit|Preferences). Komodo's preference system is undocumented, but you may examine your preference settings in the file "prefs.xml" located in your user data directory (~./komodo/VERSION on linux, C:\Documents and Settings\USERNAME\Application Data\ActiveState\Komodo\VERSION on Windows).

Pref Code Syntax

The syntax of the pref code is as follows:

    %(pref<backref>:<prefName>)
    [[%(pref<backref>:<prefName>)]]

Preference names may change between versions of Komodo.

 

Back-References

Back-references are particularly useful for code snippets. You can use back-references to interpolate the same value any number of times in the snippet. Back-references make it possible to prompt the user for an input value only once, and then insert that value multiple times. For example, you could create a snippet that prompts for a value, which would then be entered at various places in the snippet text. Without back-referencing, the user would be prompted as many times as there were instances of the interpolation in the snippet.

Back-Reference Syntax

You create a back-referenced set of codes by suffixing an interpolation code with a number. The syntax for back-reference is as follows:

    %(<code><backref>:<options>...)
    [[%(<code><backref>:<options>...)]]

For example:

    %(ask1:Name:Trent)
    %w1:else:Foo
    [[%guid1]]

All interpolation code blocks with the same code name and reference number are part of the same back-reference set. All members of the same back-reference set will be replaced with the first code block in that set. For example, consider this run command:

    echo Hi there %(ask1:Name:Trent). That name again is %ask1

This would generate a Query dialog prompting for one entry, "Name", with a default of "Trent". Whatever value the user entered for "Name" would then be inserted in two places in the command, resulting in the following command:

    echo Hi there Bill. That name again is Bill

Another useful application of back-references is the "guid" code. A guid code is replaced with a new GUID (Globally Unique Identifier). Sometimes it is desirable to have the same GUID inserted in more than one place in a file. In snippets, this can be done by using a code "%guid1" instead of just "%guid" wherever you want the GUID inserted.