# 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 can be inserted in Run Commands using the drop-down list to the right of Command field in the "Add Command..." and "Properties" dialog boxes, or entered manually. When using interpolation shortcuts in snippets or templates, insert the interpolation code using bracketed syntax. Run commands and snippets can be stored in a project or the Toolbox for frequent use.

## Interpolation Code List

The following table shows the interpolation shortcuts available in Komodo. Windows users should enclose shortcuts for files and directories in double quotes (e.g. "%F") to ensure that spaces in the file name or file path are interpreted correctly.

Code | Description
%% | a literal percent sign (%) (e.g. %%PATH%% instead of %PATH% on Windows)
%f | the basename of the current file
%b | the basename of the current file without its extension
%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
%(pythonw) | the pythonw interpreter for python scripts that display a GUI (Windows and OS X only - requires ActivePython)
%(ruby) | the ruby interpreter specified in Komodo's Ruby 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 (see %(date) Format Options)
%(ask) | ask the user for a value when invoked (see %(ask) Syntax)
%(askpass) | ask the user for a password when invoked (see %(askpass) Syntax)
%(path) | special Komodo directories (see %(path) Syntax)
%(pref) | values from Komodo preferences (see %(pref) Syntax)
%(debugger) | runtime properties of the debugger system (see %(debugger)

## Basic Interpolation Shortcut Syntax

Interpolation shortcut 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>

For shortcuts with options:

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

For example:

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

The parentheses are optional if the 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>...)]]

<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 shortcuts, though the %(ask), %(askpass), %(path), %(pref) and %(debugger) shortcuts have their own additional options and syntax.

Option | Syntax | Description
orask | %(<code>:orask:<question>) | If a value for the shortcut cannot be determined automatically, the user is prompted when the command is invoked. The <question> is text that will be displayed when the user is asked to enter a value.
else | %(<code>:else:<default>) | If a value for the shortcut cannot be determined automatically, then <default> is used.
lowercase | %(<code>:lowercase) | The interpolation result will all be lower cased.
uppercase | %(<code>:uppercase) | The interpolation result will all be upper cased.
capitalize | %(<code>:capitalize) | The first character of the interpolation result will be upper cased.
dirname | %(<code>:dirname) | The parent directory of the resulting shortcut code.
basename | %(<code>:basename) | The base name (leaf name) of the resulting shortcut code.

Use the `%(...:orask)` modifier with other interpolation shortcuts to prompt for input if no value can be determined. For example:

    %(s:orask:Element Name)

If there is no selected text, a pop-up dialog box appears with a text field called "Element Name".

See Using Command Query Shortcuts in the Run Command Tutorial for examples of `%(ask)` and `%(...:orask)` shortcuts.

## %(date)

A %(date) shortcut is replaced with the current date, formatted according to a given optional format or the default format.

### %(date) Syntax

The syntax of the %(date) shortcut 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) Format Options

If no <optional-format> is specified in a date shortcut, 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 a different one using the following date formatting codes (from Python's `time.strftime()` method):

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's time access and conversions, see http://www.python.org/doc/2.2/lib/module-time.html

## %(ask) and %(askpass)

The `%(ask)` and `%(askpass)` shortcuts will prompt the user with a pop-up dialog box for a replacement value. The `%(askpass)` shortcut is appropriate for prompting for passwords as the text is obscured in the dialog box and the password is not stored in a most-recently-used list. If a snippet or run command includes more than one "ask" shortcut, the dialog box shows a field for each one.

### %(ask) and %(askpass) Syntax

The `%(ask)` and `%(askpass)` shortcuts can be used without options, or with optional "name" and "default" values. The syntax is:

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

"NAME" appears next to the corresponding field in pop-up dialog box, and "DEFAULT" is an optional default value. A "DEFAULT" cannot be specified without a "NAME".

Typical usage of the `%(askpass)` shortcut would use "Password" for the "NAME" and not set a "DEFAULT". For example:

    %(askpass:Password)

As noted in Basic Interpolation Code Syntax, 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) and %(askpass) Options

The `%(ask)` and `%(askpass)` shortcuts take two optional parameters. The first, <question>, is the text to display to the user when prompting for the value for that shortcut. The second, <default>, is the string used to preload the text field. 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.

## %(path)

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

The syntax of the path shortcut is as follows:

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

### %(path) Options

The %(path) shortcut 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.
roamingUserDataDir | The roaming user-data-directory only applies to Windows. This is used for shared Komodo profile files.
commonDataDir | The common data directory contains data and files that are shared between multiple users.
userCacheDir | The user cache directory is where Komodo stores cached data.
supportDir | Komodo's data support directory. This is somewhere under the Komodo install dir.
sdkDir | Komodo's SDK support directory. Contains files relating to add-ons and extension development.
docDir | Komodo's documentation directory. This is where Komodo's help files are located.
installDir | Komodo's installation directory.
binDir | The directory containing the Komodo executable.
mozBinDir | The directory containing the Mozilla binary library files.
komodoPythonLibDir | The Komodo-specific python library directory.

## %(debugger)

The %(debugger) shortcuts 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 PerlApp.

### %(debugger) Syntax

The syntax of the debugger shortcut is as follows:

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

### %(debugger) Options

The %(debugger) shortcut requires a <value> parameter, which can 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)

The %(pref) shortcut is used to provide values from Komodo's Preferences. The back-end of Komodo's preference system is undocumented, but you can examine the settings in the prefs.xml file in the user data directory to find the preference IDs.

### %(pref) Syntax

The syntax of the `%(pref)` shortcut is:

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

Preference names may change between Komodo versions.

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

### Back-Reference Syntax

You create a back-referenced set of shortcuts by suffixing the 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 blocks with the same shortcut/number pairs 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:

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

This opens a pop-up dialog box 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.