Command Description Manual

Command description keys
for customizing OnMyCommand
Description format version 2.9 (backward compatible with version 2.0)

Table of Contents

What's new in command description format:
Quick Start
Command Description Keys and Values

What is new in version 2.9 of command description format (OMC v. 1.9 final)

STANDARD_INPUT_PIPE

Allows piping of context information to a tool excuted in COMMAND. The tool needs to be ready to accept piped input. STANDARD_INPUT_PIPE tag takes array of object and sends it to whatever open pipe is ready to take it. It works only with popen family of execution methods (including exe_shell_script).
The advantages of this are:
- no escaping issues and no parsing on shell side
- small script may take big text objects without making the huge script with in-place (as it is the case when classic __OBJ_TEXT__ is used)
- secure transport of passwords (to sudo or similar)
Below is an example code printing lines containing word "hello" from selected text. Previously you could try to do something like this with: echo "__OBJ_TEXT__" | grep hello. Of course you would run into escaping and line break issues. With the new feature, you can write:

<key>COMMAND</key>
<array>
    <string>grep hello 2>&1</string>
</array>
    <key>STANDARD_INPUT_PIPE</key>
<array>
    <string>__OBJ_TEXT__</string>
</array>
<key>TEXT_REPLACE_OPTION</key>
<string>txt_replace_cr_with_lf</string>
<key>EXECUTION_MODE</key>
<string>exe_popen_with_output_window</string>

Environment variables export

Special words can now be exported as environment variables in popen-based execution modes. It does not work for system() or AppleScript execution modes.
The naming convention is that special objects which take form of __XXX__ now become OMC_XXX for environment variables, for example __OBJ_PATH__ becomes OMC_OBJ_PATH and can be used in scripts as "$OMC_OBJ_PATH" or "${OMC_OBJ_PATH}".
OMC scans the command, looking for those special words and exports them as environment variables for the executed command.
The difference between __XXX__ and OMC_XXX is that the former are replaced at runtime with proper values and inserted directly into the script, while the latter are not changed - so the script remains unmodified and gets values form environment variables. The former usually needs escaping because the shell interprets the inserted string, the latter is not escaped because it is not interpreted by the shell and may be simply accessed by "$OMC_XXX". Any escaping settings in the command are ignored for OMC_XXX variables.

<dict>
    <key>COMMAND</key>
   <array>
         <string>echo "$OMC_OBJ_NAME"</string>
    </array>
    <key>EXECUTION_MODE</key>
    <string>exe_popen_with_output_window</string>
</dict>

Additional environment variables, both custom and special objects, can be added explicitly to the ENVIRONMENT_VARIABLES dictionary.
If you put an OMC special word in this dictionary (like OMC_OBJ_PATH in example below), the string you assigned to it is ignored and may be empty - it is just a signal for OMC to export that special word's runtime value as environment variable. This is useful if this variable is accessed in a script indirectly invoked by your command - is such case OMC does not know you need this variable because the main command does not include it (yet the dependent script invoked from main command may use it)

<dict>
    <key>ENVIRONMENT_VARIABLES</key>
    <dict>
       <key>TEST_CUSTOM_VARIABLE</key>
        <string>OMC test</string>
        <key>OMC_OBJ_PATH</key>
      <string></string>
    </dict>
</dict>

POPEN_SHELL

POPEN_SHELL allows customization of the shell (and flags) executed by popen. The default popen() shell is "sh" and is invoked as:
/bin/sh -c <command>
POPEN_SHELL key takes an array of strings. First string is the path to the shell, next strings are shell command-line options. As the last argument, OMC will append the command string itself (you don't include it in the array).

For example, if you want to invoke tcsh shell, you may write:

<dict>
    <key>COMMAND</key>
    <array>
        <string>env</string>
    </array>
    <key>EXECUTION_MODE</key>
    <string>exe_popen_with_output_window</string>
    <key>POPEN_SHELL</key>
    <array>
        <string>/bin/tcsh</string>
        <string>-c</string>
    </array>
</dict>

Activation by context data match

New activation option: checking file name, path or selected text for a match. Now you can create commands that are visible when file name includes some text or path matches some predefined path. This may also work on text content (so you can have commands which show up only on URL text selection for example). Regular expression matching is not Unicode-aware. New activation mode XML tags:

<key>ACTIVATION_OBJECT_STRING_MATCH</key>
<dict>

    <key>MATCH_STRING</key>
    <string>Hello</string> {required parameter}

    <key>MATCH_METHOD</key>
    <string>match_exact</string> {default value}
    <string>match_contains</string>
    <string>match_regular_expression</string>

    <key>FILE_OPTIONS</key>
    <string>match_file_name</string> {default value}
    <string>match_file_path</string>

    <key>COMPARE_CASE_INSENSITIVE</key>
    <false/> {default value}
    <true/>

</dict>

What is new in version 2.8 of command description format (OMC v. 1.8 final)

DataBrowser control support in nib dialogs:

The new control support and newspecial word: __NIB_TABLE_NNN_COLUMN_MMM_VALUE__
See Nib dialogs section for details.

Dynamic menu name:

NAME upgraded to array of strings with special objects to allow dynamic names:
<key>NAME</key>
<array>
   <string>Selected object name: </string>
   <string>__OBJ_NAME__</string>
</array>
Both forms of NAME key are supported: simple string for static menu name and array of strings for dynamic name.

NAME_PLURAL key defined so the menu name may be different when more than one file is selected.
<key>NAME</key>
<string>One Object Selected</string>
<key>NAME_PLURAL</key>
<string>Multiple Objects Selected</string>

Key NAME is required, NAME_PLURAL is optional. NAME_PLURAL must be a string. It is not dynamic.

Progress dialog:

Displays indeterminate progress bar for commands which do not operate on objects, process only one object or process objects together. If more than one object is processed separately, each ending task advances the progress bar. Progress dialog displays last line of the the task output as a status text under the progress bar.

<key>PROGRESS</key>
<dict>
    <key>TITLE</key>
    <string>Task in progress</string>
    <key>DELAY</key>
    <real>2.0</real>
</dict>

DELAY key with time in seconds may be used to defer the progress dialog display — the dialog will not show up if the task ends before the specified time passes. TITLE is the window title. If not specified, command name is used.

Task end notification:

Many tasks execute asynchronously in OMC 1.8 so the end notification might be useful:

<key>END_NOTIFICATION</key>
<dict>
    <key>TITLE</key>
    <string>Task End</string>
    <key>MESSAGE</key>
    <string>This task has ended</string>
</dict>

TITLE is the window title and is optional. If keyword does not exist, command name is used for window title. MESSAGE is optional as well. If the keyword does not exist, the last status line from finished task output is used. exe_silent_system does not produce any output text so it cannot be used this way.

Nib dialog termination handlers:

Called after dialog is closed but before returning to command which invoked it. 2 types of termination handlers: one for OK and the other for Cancel or window close. Default IDs are 'end!' for OK and 'cnc!' for Cancel. Termination command IDs can be overridden with the following:

<key>NIB_DIALOG</key>
<dict>
   <key>END_OK_SUBCOMMAND_ID</key>
    <string>end!</string>
    <key>END_CANCEL_SUBCOMMAND_ID</key>
    <string>cnc!</string>
</dict>

Non-blocking nib dialog:

<key>NIB_DIALOG</key>
<dict>
    <key>IS_BLOCKING</key>
     <false/>
   </dict>

The default behavior is blocking (modal) dialog and this is how it was implemented in previous OMC versions. In this mode the dialog blocks the main thread of host application, running its own modal loop, until it is dismissed (closed, canceled, OK-eyed) and then the main command which invoked the dialog is executed (most likely using some control values from the dialog).

In the new, non-blocking mode, the dialog does not run the modal loop and returns the control to host application immediately. The side effect is that the command which invoked the dialog executes immediately — in this case you will probably want to leave the main command empty and perform the task you want in subcommand invoked when closing the dialog. OMC nib dialog defines 2 default termination handlers: 'end!' when dialog is OK-eyed and 'cnc!' when dialog is canceled. In most cases you will want to create a subcommand with 'end!' ID and perform your closing task here. Those IDs can be overridden with END_OK_SUBCOMMAND_ID and END_CANCEL_SUBCOMMAND_ID tags.

Showing invisible files and folders in Navigation dialogs:

<key>CHOOSE_FILE_DIALOG</key>
<dict>
<key>SHOW_INVISIBLE_ITEMS</key>
<true/>
</dict>
This option is available for SAVE_AS_DIALOG, CHOOSE_FILE_DIALOG,
CHOOSE_FOLDER_DIALOG, CHOOSE_OBJECT_DIALOG

Setting default location for navigation dialogs:

<key>CHOOSE_FOLDER_DIALOG</key>
<dict>
   <key>MESSAGE</key>
   <string>Select Folder</string>
   <key>DEFAULT_LOCATION</key>
   <array>
      <string>__OBJ_PARENT_PATH__</string>
   </array>
</dict>

Special words allowed. Tilde in front of the path resolved as user's home folder. Example above opens navigation dialog in parent folder of control-clicked object.

External bundle special word:

__MY_EXTERNAL_BUNDLE_PATH__
special object pointing to path defined by EXTERNAL_BUNDLE_PATH tag (redundant, but much needed for portability)

    <key>COMMAND</key>
    <array>
        <string>echo </string>
        <string>__MY_EXTERNAL_BUNDLE_PATH__</string>
    </array>

    <key>EXTERNAL_BUNDLE_PATH</key>
    <string>~/Library/Application Support/OnMyCommand/My Command.omc</string>

If explicit path EXTERNAL_BUNDLE_PATH in command description is not specified, __MY_EXTERNAL_BUNDLE_PATH__ resolves to default external bundle location which is: /Users/you/Library/Application Support/OnMyCommand/CurrentCommandName.omc where "CurrentCommandName" is the name of the command (and menu item). This will allow easy access to private command resources (nibs, images, scripts, etc.). The net result is that if you place a ".omc" bundle of the same name as your command in ~/LibraryApplication Support/OnMyCommand/, it will be found automatically.
DropletBuilder is able to install the .omc bundle for you in default location and copy the command from "Command.plist" to your main list of commands. Just drag the .omc bundle on the DropletBuilder icon. This way the self-contained command with resources (images, nibs, external scripts, etc.) may be distributed as .omc bundle and is easy to install.

Multiple objects sorting:

<key>MULTIPLE_OBJECT_SETTINGS</key>
<dict>
    <key>SORT_METHOD</key>
    <string>sort_by_name</string>
    <key>SORT_OPTIONS</key>
    <dict>
        <key>SORT_ASCENDING</key>
        <true/>
        <key>COMPARE_CASE_INSENSITIVE</key>
        <true/>
        <key>COMPARE_NONLITERAL</key>
        <true/>
        <key>COMPARE_LOCALIZED</key>
        <true/>
        <key>COMPARE_NUMERICAL</key>
        <true/>
     </dict>
</dict>

SORT_METHOD: sort_none (default), sort_by_name
SORT_OPTIONS (only valid if SORT_METHOD is different from sort_none):
    SORT_ASCENDING - default true: a-z, 0-9 , if false: z-a, 9-0
    All other options are corresponding to CFStringCompareFlags. See description in Apple documentation.

    COMPARE_CASE_INSENSITIVE — if true: Finder-like. Default is false: case sensitive, Unix-like
    COMPARE_NONLITERAL — default is false: literal
    COMPARE_LOCALIZED — default is false: not locale-aware
    COMPARE_NUMERICAL — if true: numeric values compared so "version 2" < "version 2.5", default is false: alphabetical

Additional positioning method for output window:

FRACT_POSITION_LEFT and FRACT_POSITION_TOP are the new positioning methods for output window. The value is a floating point number between 0.0 and 1.0 and describes approximate position on screen. 0.0 is top or left, 1.0 is right or bottom, 0.5 is center, etc. This method places the center of the output window in desired location but also makes sure the whole window is visible on the screen (placing window at {0.0, 0.0} will not place its center in top left corner of the screen but rather places top left corner of the window there). This method takes menu bar and dock into account so the window is placed correctly within available area.

For example, positioning a window about 1/3 of the screen height from the top and 2/3 of the screen width from the left:

<key>OUTPUT_WINDOW_SETTINGS</key>
<dict>
   <key>FRACT_POSITION_LEFT</key>
   <real>0.66</real>
   <key>FRACT_POSITION_TOP</key>
   <real>0.33</real>
   <key>WINDOW_POSITION</key>
   <string>absolute</string>
</dict>

Task manager settings:

<key>MAX_PARALLEL_TASK_COUNT</key>
<integer>1</integer>
If tag is not present the default value is 0. 0 is a special value and it means the maximum number of concurrent tasks depends on the number of CPUs (or cores) in your computer and the maximum task count is calculated as 2 x CPU count. So single processor, single core will run 2 tasks, single processor dual core machine will run 4 tasks at a time. If you know that the process you are going to start is very processor-intensive, you will probably want to set this value to 1 so there will be only one task running at a time and if there are more objects to be processed, they will be scheduled one after another.
This option is under "Misc" tab in OMCEdit.

Statically assigned next command id:

In previous versions of OMC the next command could be set using command line tool: omc_next_command. In many cases, however, it may be easier to assign the next command statically in command description itself. In this case the next command will be executed unconditionally, provided the previous command succeeded and was not canceled. The new tag is:
<key>NEXT_COMMAND_ID</key>
<string>NeXT</string>

If you use both statically assigned next command id and dynamic one, assigned at runtime with omc_next_command tool, the dynamic id is used. This way you can override static assignment if needed.
This option is at the bottom of the main edit window in OMCEdit.

New ESCAPE_SPECIAL_CHARS option:

esc_with_percent_all
The behavior of previously available esc_with_percent is that it escapes only illegal URL chars (as defined by RFC 2396). The new method escapes all illegal URL chars plus legal non-alphanumeric chars. The additional escaped characters are: !$&'()*+,-./:;=?@_~. Those chars need to be escaped in order to avoid conflicts in shell execution. The end result is that only A-Z, a-z, 0-9 are left unescaped.

iTerm startup shell support:

<key>ITERM_SHELL_PATH</key>
<string>/bin/bash</string>

What is new in version 2.7.2 of command description format (OMC v. 1.7.2 final)

Dynamic command ids in nib dialog controls
omc_dialog_control now allows you to change command ids of nib dialog controls on the fly. This way a button in a dialog can perform different actions depending on other controls state. Suppose you have an "Run" button in dialog, now depending on popup menu choice in this dialog it may execute different commands because we are able to change the command ID of the "Run" button when the popup menu choice changes. This can be done by invoking omc_dialog_control with new option: omc_set_command_id and provide four character code as a command id, for example:
omc_dialog_control __NIB_DLG_GUID__ 1 omc_set_command_id "Exec"

What is new in version 2.7.1 of command description format (OMC v. 1.7.1 final)

Dialog autoclose on success only
New tag is introduced for output windows which use autoclose timeout: AUTO_CLOSE_ON_SUCCESS_ONLY. It is a Boolean value with "true" as default.
In most cases you will probably prefer to autoclose result window when the task finished successfully but you'd rather want it to stay open in case of error. This is the deafult behavior now, you don't have to add this tag if you want it, but if you really prefer window autoclose regardless of result, you need to set the value to false.

<key>OUTPUT_WINDOW_SETTINGS</key>
<dict>
    <key>AUTO_CLOSE_TIMEOUT</key>
    <real>1.0</real>
    <key>AUTO_CLOSE_ON_SUCCESS_ONLY</key>
    <true/>
</dict>

You can test it with the following commands:
echo "This should autoclose"
echo "This should not autoclose"; exit 1

New ESCAPE_SPECIAL_CHARS option:
esc_wrap_with_single_quotes_for_shell
This is a special quoting method for use with shell. The behavior is to wrap the text with single quotes and work around the problem of any possible single quote inside. The text:
Don't do it
will become wrapped as:
'Don'\'' do it'

omc_list_append_items_from_file & omc_list_append_items_from_stdin
omc_dialog_control gets two new methods for adding menu items to popup menus: reading from file or standard input/pipe. Each non-empty line is treated as one item to add. The stdin method is especially useful for accepting piped output from awk, sed, grep, ls, cat, plister or other tools.
Example usage:
omc_dialog_control __NIB_DLG_GUID__ 4 omc_list_append_items_from_file menu_items.txt
ls | omc_dialog_control __NIB_DLG_GUID__ 4 omc_list_append_items_from_stdin

What is new in version 2.7 of command description format (OMC v. 1.7 final)

Dialog autoclose timeout
Timeout is in seconds. Negative values mean "don't autoclose". Default value when tag not present: -1.0.

<key>OUTPUT_WINDOW_SETTINGS</key>
<dict>
<key>AUTO_CLOSE_TIMEOUT</key>
<real>2.0</real>
</dict>

Default "save as" filename

</key>SAVE_AS_DIALOG</key>
<dict>
    <key>DEFAULT_FILE_NAME</key>
    <array>
        <string>__OBJ_NAME_NO_EXTENSION__</string>
        <string>.txt</string>
    </array>
</dict>

DEFAULT_VALUE
Default text for input dialog is now an array of strings instead of single string and resolves special objects
DEFAULT_VALUE key deprecates old DEFAULT key:

<key>INPUT_DIALOG</key>
<dict>
    <key>DEFAULT_VALUE</key>
    <array>
        <string>__OBJ_NAME_NO_EXTENSION__</string>
        <string>.txt</string>
    </array>
</dict>

Two new special objects:
__FRONT_APPLICATION_NAME__ Front application name.
__FRONT_PROCESS_ID__ This is a Unix process ID of the front application as obtained by running ps in Terminal.

Version requirements
If the Mac OS X or OMC version requirement is not met, a warning dialog will be displayed.

<key>REQUIRED_OMC_VERSION</key>
<string>1.7</string>
OMC is backward compatible so this means: minimum OMC version required to run this command. Default value: "1.3.1"

<key>REQUIRED_MAC_OS_MIN_VERSION</key>
<string>10.2</string>
Minimum Mac OS X version to run the command. Default value "10.1"

<key>REQUIRED_MAC_OS_MAX_VERSION</key>
<string>10.2.8</string>
Last Mac OS X version supporting given feature. The default value is infinite. Don't put if not needed.

Categories
This keyword is for organizing commands into logical groups. Does not affect the command execution.
<key>CATEGORIES</key>
<array>
    <string>Clipboard</string>
    <string>Command Line</string>
    <string>Selection</string>
</array>

The submenu name is now a path, for example:
<key>SUBMENU_NAME</key>
<string>/Disk Image/Create</string>

The submenu path should start with "/". If it does not start with "/", it is added by OMC.
If the submenu name is "/" - it is root. If the submenu name is ".." it is root too.
If the keyword is missing, the default submenu is "On My Command". The trailing "/" is ignored.

The key to disable command:
<key>DISABLED</key>
<true/>
The default value is false.

omc_list_append_items & omc_list_remove_all
omc_dialog_control gains new feature: ability to populate lists for some controls. Currently it works for popup button menu and combo box menu only.
Special value of omc_list_append_items tells omc_dialog_control that there is variable length of arguments following. For example, if you have a popup button with ID 4 and you want to add items to its menu, you can do it like this:
omc_dialog_control __NIB_DLG_GUID__ 4 omc_list_append_items "Item 1" "Item 2" "Item 3"
To remove items from list:
omc_dialog_control __NIB_DLG_GUID__ 4 omc_list_remove_all

omc_live_update (obsolete)
omc_live_update is obsolete in version OMC 1.8 and higher.
It used to be a special parameter to tell remote dialog to update control value immediately.
In version 1.8 omc_dialog_control always tries to establish direct communication with the dialog and only if it fails, the data is saved to a file and the dialog picks it after the subcommand execution is finished.

What is new in version 2.7b1 of command description format (OMC v. 1.7b1)

Send Task to Background Application (OMCDeputy)
<key>SEND_TASK_TO_BACKGROUND_APP</key>
<true/>
Command is executed by OMCDeputy background app.

Custom output windows with shape and background defined by PNG image.
<key>OUTPUT_WINDOW_SETTINGS</key>
<dict>
    <key>WINDOW_TYPE</key>
    <string>custom</string>
    <key>CUSTOM_WINDOW_PNG_IMAGE</key>
    <string>Bezel.png</string>
</dict>

Textbox. Defines where the text should be placed in custom window.

<key>OUTPUT_WINDOW_SETTINGS</key>
<dict>
    <key>CUSTOM_TEXTBOX_POSITION_TOP</key>
    <integer>20</integer>
    <key>CUSTOM_TEXTBOX_POSITION_LEFT</key>
    <integer>20</integer>
    <key>CUSTOM_TEXTBOX_WIDTH</key>
    <integer>100</integer>
    <key>CUSTOM_TEXTBOX_HEIGHT</key>
    <integer>50</integer>
</dict>

Closebox. Defines the rectangle where mouse click closes the window. Only for custom windows.
<key>OUTPUT_WINDOW_SETTINGS</key>
<dict>
    <key>CUSTOM_CLOSEBOX_POSITION_TOP</key>
    <integer>0</integer>
    <key>CUSTOM_CLOSEBOX_POSITION_LEFT</key>
    <integer>0</integer>
    <key>CUSTOM_CLOSEBOX_WIDTH</key>
    <integer>16</integer>
    <key>CUSTOM_CLOSEBOX_HEIGHT</key>
    <integer>16</integer>
</dict>

Fade in and fade out for output windows. Can be used with any type of window.
<key>OUTPUT_WINDOW_SETTINGS</key>
<dict>
    <key>WINDOW_OPEN_FADE_IN</key>
    <true/>
    <key>WINDOW_CLOSE_FADE_OUT</key>
    <true/>
</dict>

Subcommands
Subcommands look just like regular commands but they have a unique four character identifier: COMMAND_ID. Main command should not have this tag or use 'top!' value. Subcommands must have the same name as a main command. Subcommands are not displayed in the contextual menu because they are treated as a part of one command group. OMCEdit displays subcommands in italic font.
<key>COMMAND_ID</key>
<string>Subc</string>
Subcommands can be triggered by controls in nib dialog or with omc_next_command. More information in "Subcommands" section.

Next Command
Next command can be scheduled with omc_next_command CLI tool so your script can decide at runtime if another subcommand should follow. More information in "Next Command" section.

Nib Dialog Enhancements
omc_dialog_control command line tool to set the control value. You may also enable/disable and show/hide controls.

More controls supported including pictures, icons, bevel buttons, static text, progress controls, tab control. Controls can trigger subcommands if command id is assigned in Interface Builder.

Icons & pictures. Custom icons & pictures can be displayed in nib dialogs.

New special object: __NIB_DLG_GUID__. This special word is replaced dynamically with current dialog unique id. It is used with omc_dialog_control.

New keyword for nib dialog group: INIT_SUBCOMMAND_ID to use initialization subcommand to set control values before the dialog shows up.
<key>NIB_DIALOG</key>
<dict>
    <key>NIB_NAME</key>
    <string>dialog</string>
    <key>WINDOW_NAME</key>
    <string>Dialog</string>
    <key>INIT_SUBCOMMAND_ID</key>
    <string>ini!</string>
</dict>

External bundles for putting nibs and custom window PNG images
It is useful for contextual menu items using nib dialogs - you do not have to put the nib inside OnMyCommandCM.plugin bundle.
<key>EXTERNAL_BUNDLE_PATH</key>
<string>/Users/Shared/OMC/Extension.omc</string>
The path to bundle should be absolute. You can use /Users/Shared/OMC/ folder for this. /Users/Shared/ is a very good place to put things and it is often overlooked and not used by most OS X users. The advantage is that everybody has a read-write permissions to this folder.

Option to replace line endings for __OBJ_TEXT__:
<key>TEXT_REPLACE_OPTION</key>
<string>txt_replace_none</string>
<string>txt_replace_lf_with_cr</string>
<string>txt_replace_cr_with_lf</string>

What is new in version 2.6.1 of command description format (OMC v. 1.6.1 final)

New EXECUTION_MODE options:

exe_shell_script
exe_shell_script_with_output_window

Full support for shell scripts. You do not need to put your shell script in a separate file - just type the code in the body of your command description. At the beginning of each shell script you need to specify which shell to use. For example:
#!/bin/sh
Finally you can use perl, python or other scripting language directly in your command. This execution mode creates a temporary script file:
/tmp/OMC/OMC_temp_script_XXX
and then "exec /tmp/OMC/OMC_temp_script_XXX" is called.
When editing the command manually, please make sure you have proper line endings in your script. You need Unix linefeeds (LFs) instead of Mac carriage returns (CRs).

New activation option to tell in which applications the command should or must not show:
ACTIVATE_ONLY_IN or NEVER_ACTIVE_IN. Those 2 options are logically exclusive. You can use one or the other but not both in one command. You provide an array of application names like this:
    <key>ACTIVATE_ONLY_IN</key>
    <array>
        <string>TextEdit</string>
        <string>BBEdit Lite</string>
    </array>

The name of the application is what you see in manu bar when you launch given application, not the name of the bundle (which may be different).

Nib Dialogs.
You can build a dialog in Interface Builder and access control values via:
__NIB_DIALOG_CONTROL_N_VALUE__
"N" has to be replaced with control id number, for example __NIB_DIALOG_CONTROL_3_VALUE__
There are certain predefined rules how to design such dialog and which controls are supported but basically you are able to use a completely visual environment of Interface Builder to construct a dialog and there is no limitation on the number of controls you want/need to use. It requires no programming just putting together some resources to obtain a very nice GUI for some script. The nib dialog settings have to be explicitly present in command description to load the dialog. Two parameters are required: NIB_NAME & WINDOW_NAME. For example:
    <key>NIB_DIALOG</key>
    <dict>
        <key>NIB_NAME</key>
        <string>mydialog</string>
        <key>WINDOW_NAME</key>
        <string>Dialog</string>
    </dict>

Detailed information in "Nib dialogs" section of this manual.

What is new in version 2.6 of command description format (OMC v. 1.6 final)

New EXECUTION_MODE options:

exe_popen_with_output_window
exe_applescript
exe_applescript_with_output_window

AppleScript is natively supported in OMC 1.6: you do not have to use call osascript to execute AppleScript code, just type it in command description and choose appropriate execution mode.

Output window displays the result of command execution. Various output window settings can be controlled in OUTPUT_WINDOW_SETTINGS group described in "Output window settings" section of this document.

New ESCAPE_SPECIAL_CHARS option:
esc_for_applescript
Escape objects inserted into AppleScript command.

PASTE_AFTER_EXECUTION instruction. Tells OMC to paste clipboard content in current context after command execution. Makes sense in text context with pbcopy or AppleScript's set the clipboard to...

New objects:
__MY_BUNDLE_PATH__
__MY_HOST_BUNDLE_PATH__

These new words do not make much sense for contextual menus because they point to OnMyCommandCM.plugin or host application but they might be extremely useful for droplets because you may put things in bundle resources and access them with __MY_HOST_BUNDLE_PATH__/Contents/Resources/

What is new in version 2.5.4 of command description (OMC v. 1.5.4 final)

Extensive reorganization of special words. The new naming scheme is as follows:
- context object words start with __OBJ_XXX__ (as it was before)
- dialog words start with __DLG_XXX__.
As a result the following existing words have been renamed:
__INPUT_TEXT__ --> __DLG_INPUT_TEXT__
__SAVE_AS_PATH__ --> __DLG_SAVE_AS_PATH__
__SAVE_AS_PARENT_PATH__ --> __DLG_SAVE_AS_PARENT_PATH__
__SAVE_AS_FILE_NAME__ --> __DLG_SAVE_AS_NAME__

The old style names are still supported but are no longer recommended. __PASSWORD__ is deprecated and has not been renamed according to the new convention.

Three new Navigation Services dialogs have been added:
- choose file invoked by special word __DLG_CHOOSE_FILE_PATH__ & family
- choose folder invoked by special word__DLG_CHOOSE_FOLDER_PATH__ & family
- choose object (file or folder) invoked by special word __DLG_CHOOSE_OBJECT_PATH__ & family

Each navigation dialog object has new flavors: NAME_NO_EXTENSION and EXTENSION_ONLY to match combinations available for context file objects (__OBJ_XXX__)

Navigation services dialogs currently support only one option: text message appearing on top of the dialog. If not defined, the dialog will be displayed without any message text. For example, the message text for "save as" dialog can be defined as follows:

<key>SAVE_AS_DIALOG</key>
<dict>
<key>MESSAGE</key>
<string>Save the new file as:</string>
</dict>

__OBJ_PATH_NO_EXTENSION__ is deprecated (although still supported) because it can be constructed easily from __OBJ_PARENT_PATH__ + __OBJ_NAME_NO_EXTENSION__ and redundant objects may create more confusion.

New execution modes have been added including basic support for iTerm and silent execution with "system()" call. The old style silent execution was done with "popen()" call. To learn more about popen & system, open your terminal and type "man popen" and "man system".

New EXECUTION_MODE options:
exe_silent_popen
exe_silent_system
exe_terminal
exe_iterm

Old style exe_silent is still supported and is equivalent to exe_silent_popen but no longer recommended.

What is new in version 2.5.3 of command description (OMC v. 1.5.3 final)

Added new "Save As" dialog. The dialog has no additional settings (yet). It is invoked when one of the following special words is encountered in command text: __SAVE_AS_PATH__, __SAVE_AS_PARENT_PATH__ or __SAVE_AS_FILE_NAME__.
For INPUT_DIALOG a new INPUT_TYPE is added: input_combo_box. The dialog is shown with edit field and popup choice. Handy for pre-defined items but allows entering custom value.

What is new in version 2.5.2 of command description (OMC v. 1.4.3 final)

Added new keyword: REFRESH_PATH for refreshing objects in Finder. A common problem was that when some file or folder attribute was changed by a command (file type and creator for example), Finder was not refreshing the object. The new keyword takes a path to object which needs refreshing. The path is an array of strings and can be composed of the same elements which are used for main command description (__OBJ_XXX__)

What is new in version 2.5.1 of command description (OMC v. 1.4.2 final)

Added 2 new options for ACTIVATION_MODE: act_folder_not_finder_window and act_file_or_folder_not_finder_window. The new activation modes are similar to corresponding act_folder and act_file_or_folder options but exclude a context when user ctrl-clicks on a Desktop or open Finder window. These options are useful for "dangerous" commands like those deleting folders with their content. This is a safeguard against accidental deleting of whole desktop folder!

What is new in version 2.5 of command description (OMC v. 1.4 final)

Input dialog. Special word __INPUT_TEXT__ in command description invokes a dialog where you can input text. Three input methods are currently supported: clear text, password text, popup menu choice. There is a new description format for customizing the input dialog. Look below in section "Input dialog" for more information.
__PASSWORD__ keyword is deprecated now since the same effect can be achieved with __INPUT_TEXT__ and proper dialog description. Please change your command descriptions.
VERSION keyword added for keeping track of incremental updates to commands.

What is new in version 2.4 of command description (OMC v. 1.3.1 final)

Version 1.3.1b1 was supposed to be feature complete, but...
This version brings new special word: __PASSWORD__. When it is encountered in command description, a password dialog is displayed before execution. Useful for sudo commands or protected http or ftp access. The second new feature is enhanced warning support with two new keywords: WARNING_EXECUTE and WARNING_CANCEL. These keywords define button names in warning dialog for further customization.

What is new in version 2.3 of command description (OMC v. 1.3.1b1)

Implemented __OBJ_COMMON_PARENT_PATH__ and __OBJ_PATH_RELATIVE_TO_COMMON_PARENT__ (finally). Added WARNING keyword which may be provided for potentially destructive commands. Added SUBMENU_NAME keyword so you may place commands in submenu of your choice. This version is considered feature complete and enters beta testing phase.

What is new in version 2.2.1 of command description (OMC v. 1.3.1a9)

Changes to ESCAPE_SPECIAL_CHARS behavior. Previously esc_with_backslash was never applied to __OBJ_TEXT__. As it has been demonstrated by some code examples (thanks to Daniel A. Shockley) escaping text with backslash is needed and desired in some cases. What's more, a problem of text with multiple lines emerged so CR and LF characters have been added to a list of characters being escaped with backslash. A subtle but significant change is in default behavior (when ESCAPE_SPECIAL_CHARS keyword is not present). Previously the default value for path objects was esc_with_backslash while default value for __OBJ_TEXT__ was esc_none. Now it has changed: the default value in both cases is esc_with_backslash and it may affect already existing commands. The general rule of the thumb is not to use any escapes â€” explicitly set to esc_none â€” when you enclose a path or text in quotes. If you pass raw text or path, you should escape special chars, otherwise in some cases your command will not work or its behavior will be undetermined. Do you remember infamous iTunes 2.0 installer? They used rm -rf with non escaped path to delete old version of iTunes. However if you had 2 disks: one named HD and the other named HD X (with space inside) you ended up with your whole HD partition erased. This is the worst case scenario but it is a good example. Stay alert.

What is new in version 2.2 of command description (OMC v. 1.3.1a8 private seed)

Added two new keywords: TERM_OPEN_NEW_SESSION and TERM_BRING_TO_FRONT. These keywords take Boolean values and determine Terminal behavior for a command. These keywords are ignored for silent execution.

What is new in version 2.1.1 of command description (OMC v. 1.3.1a7)

Implemented escaping special characters with percent for Internet URLs. See description of ESCAPE_SPECIAL_CHARS for more details.

What is new in version 2.1 of command description (OMC v. 1.3.1a6)

Added ACTIVATION_FILE_TYPES and ACTIVATION_EXTENSIONS â€” or actually activated them, since 2.0 draft already had these keywords.
Added support for treating multiple objects together â€” a lot is done, but still in progress. Thanks to Mike Fischer for ideas on how to make things more complicated :-) ... and powerful.

What is new in version 2.0 of command description (OMC v. 1.3.1a3)

Command description syntax has been changed with version 1.3.1a3 of OnMyCommand. Initial syntax was not not designed very well (in fact it was not designed at all but done ad hoc). The new version is simpler, more flexible and more powerful - it will be easier to develop and add new features.
Unfortunately version 2.0 of command description syntax is not compatible with version 1.0. You need to re-edit your commands. Sorry about this but in long term it will be worthy to have a better foundation to build upon and it also opens new possibilities for complicated commands right now.
The main difference in version 2.0 is that command is composed of an array of strings which will be glued together on execution. There are also several pre-defined special words with a naming scheme of __OBJ_XXX__. These special words will be replaced with proper text on execution. Look below for more detailed description of what is currently available.

Quick Start

Here is the quick manual how to edit command descriptions. Take one command description as an example:

<dict>
    <key>ACTIVATION_EXTENSIONS</key>
    <array>
        <string>gz</string>
        <string>tgz</string>
    </array>
    <key>ACTIVATION_MODE</key>
    <string>act_file</string>
    <key>COMMAND</key>
    <array>
        <string>gzip -d </string>
        <string>__OBJ_PATH__</string>
    </array>
    <key>EXECUTION_MODE</key>
    <string>exe_silent_popen</string>
    <key>NAME</key>
    <string>Uncompress with gzip</string>
    <key>NOTES</key>
    <string>Look Ma, no Terminal for uncompressing with GZip!</string>
    <key>VERSION</key>
    <integer>1</integer>
</dict>

The result will be as follows:
1. The name displayed in menu will be Uncompress with gzip.
2. The command executed will be gzip -d path/to/clicked/file.gz.
3. Special characters in inserted path will be escaped with backslash (default behavior).
4. The command will be executed "silently", Terminal.app will not be opened (controlled by EXECUTION_MODE).
5. The command will be available only when a file is control-clicked (ACTIVATION_MODE).
6. The command will be available only when a file with "gz" or "tgz" extension is control-clicked.
7. NOTES key is ignored by plugin but may contain additional information (e.g. about requirements for given command or info about the author).
8. VERSION key is ignored by plugin itself but is useful for OMCEdit.
9. This example does not demonstrate all possible keywords - it is just a quick start guide.

Command Description Keys and Values

Name of the command appearing in menu

<key>NAME</key>
<string>My Command</string>
This key is required.

Example:

<key>NAME</key>
<string>Compress with gzip</string>

New in 1.8:
NAME is upgraded to array of strings with special objects to allow dynamic names:

<key>NAME</key>
<array>
<string>Selected object name: </string>
<string>__OBJ_NAME__</string>
</array>

Both forms of NAME key are supported: simple string for static menu name and array of strings for dynamic name.

NAME_PLURAL key defined so the menu name may be different when more than one file is selected.

<key>NAME</key>
<string>One Object Selected</string>
<key>NAME_PLURAL</key>
<string>Multiple Objects Selected</string>

Key NAME is required, NAME_PLURAL is optional. NAME_PLURAL must be a string. It is not dynamic.

Command itself

<key>COMMAND</key>
<array>
<string></string>
</array>

Command is an array of strings which will be combined together before execution. There are several predefined special strings which will be replaced by proper data before execution.
This key is required.

Example:

<key>COMMAND</key>
<array>
<string>gzip </string>
<string>__OBJ_PATH__</string>
</array>

Special Words

Special words are in form of __SOMETHING_HERE__. There are 2 underscores at the beginning and 2 at the end. Spaces are not allowed (substituted wth underscore) and the word is all capital letters.

Please note that any special object in the body of command must be the only string in single <string></string> element and cannot contain preceding or trailing spaces. You cannot compose a command like:

<string>cd __OBJ_PATH__; ls -la</string>

What you should do is to split the command so __OBJ_PATH__ is a single element:

<string>cd </string>
<string>__OBJ_PATH__</string>
<string>; ls -la</string>

However, if you are using OMCEdit, you enter the command with special words in one line and the application does the dirty work of splitting the command into appropriate chunks for you.

Important thing to note is that esc_with_backslash option is the default escaping method for inserted objects so you should not use quotes around it to ensure proper path interpretation because every effort is made to produce proper path string.

Currently available special words to be replaced at runtime are:
(assume that we clicked on object file://localhost/Users/tom/Desktop/My Stuff/test.plist)

__OBJ_TEXT__
will be replaced at runtime with selected text or the text in clipboard;
when both selected text and clipboard are present, selected text takes precedence;
if current context is a clicked file or folder, __OBJ_TEXT__ will insert clipboard content

__OBJ_PATH__
will be replaced at runtime with: /Users/tom/Desktop/My\ Stuff/test.plist

__OBJ_PATH_NO_EXTENSION__
will be replaced at runtime with: /Users/tom/Desktop/My\ Stuff/test
This object is deprecated (although still supported) because it can be constructed easily from __OBJ_PARENT_PATH__ + __OBJ_NAME_NO_EXTENSION__

__OBJ_PARENT_PATH__
will be replaced at runtime with:/Users/tom/Desktop/My\ Stuff

__OBJ_NAME__
will be replaced at runtime with: test.plist

__OBJ_NAME_NO_EXTENSION__
will be replaced at runtime with: test

__OBJ_EXTENSION_ONLY__
will be replaced at runtime with: plist

__OBJ_DISPLAY_NAME__
will be replaced at runtime with: test.plist or test depending on the extension visibility in Finder

__OBJ_COMMON_PARENT_PATH__
will be replaced with: /Users/tom/Desktop/My\ Stuff/ (notice slash at the end)
for multiple objects it will insert one path representing a parent container for all selected objects
only one common parent path will be inserted regardless of processing mode (together or separately)

__OBJ_PATH_RELATIVE_TO_COMMON_PARENT__
will be replaced with: test.plist
for multiple objects it will insert paths relative to a common parent container

__DLG_INPUT_TEXT__ (old, deprecated name: __INPUT_TEXT__)
before execution you will be prompted to enter a string; three input methods are currently supported: clear text, password text, popup menu choice; there is a new description format for customizing the input dialog; look below in section "Input dialog" for more information;
please note that this word does not belong to __OBJ_XXX__ family because it has nothing to do with current context

__PASSWORD__(deprecated, use __DLG_INPUT_TEXT__ password edit field instead)
before execution you will be prompted to enter a password which then will be used in your command
please note that this word does not belong to __OBJ_XXX__ family because it has nothing to do with current context

New in 1.5.3:

__DLG_SAVE_AS_PATH__ (old, deprecated name: __SAVE_AS_PATH__)
"Save As..." dialog will be displayed before execution. The path to chosen save file will be inserted on execution.

__DLG_SAVE_AS_PARENT_PATH__ (old, deprecated name: __SAVE_AS_PARENT_PATH__)
"Save As..." dialog will be displayed before execution. The path to selected save location (parent folder) will be inserted on execution.

__DLG_SAVE_AS_NAME__ (old, deprecated name: __SAVE_AS_FILE_NAME__)
"Save As..." dialog will be displayed before execution. The file name entered in this dialog will be inserted on execution.

All __DLG_SAVE_AS_XXX__ paths are escaped according to settings provided in ESCAPE_SPECIAL_CHARS.

New in 1.5.4:

__DLG_SAVE_AS_NAME_NO_EXTENSION__
"Save As..." dialog will be displayed before execution. The file name without extension entered in this dialog will be inserted on execution.

__DLG_SAVE_AS_EXTENSION_ONLY__
"Save As..." dialog will be displayed before execution. The extension of the file name entered in this dialog will be inserted on execution.

__DLG_CHOOSE_FILE_PATH__
"Choose file" dialog will be displayed before execution. The path to chosen file will be inserted on execution.

__DLG_CHOOSE_FILE_PARENT_PATH__
"Choose file" dialog will be displayed before execution. The path to parent folder of chosen file will be inserted on execution.

__DLG_CHOOSE_FILE_NAME__
"Choose file" dialog will be displayed before execution. The name of chosen file will be inserted on execution.

__DLG_CHOOSE_FILE_NAME_NO_EXTENSION__
"Choose file" dialog will be displayed before execution. The name without extension of chosen file will be inserted on execution.

__DLG_CHOOSE_FILE_EXTENSION_ONLY__
"Choose file" dialog will be displayed before execution. The extension of chosen file will be inserted on execution.

__DLG_CHOOSE_FOLDER_PATH__
"Choose folder" dialog will be displayed before execution. The path to chosen folder will be inserted on execution.

__DLG_CHOOSE_FOLDER_PARENT_PATH__
"Choose folder" dialog will be displayed before execution. The path to parent folder of chosen folder will be inserted on execution.

__DLG_CHOOSE_FOLDER_NAME__
"Choose folder" dialog will be displayed before execution. The name of chosen folder will be inserted on execution.

__DLG_CHOOSE_FOLDER_NAME_NO_EXTENSION__
"Choose folder" dialog will be displayed before execution. The name without extension of chosen folder will be inserted on execution.

__DLG_CHOOSE_FOLDER_EXTENSION_ONLY__
"Choose folder" dialog will be displayed before execution. The extension of chosen folder will be inserted on execution.

__DLG_CHOOSE_OBJECT_PATH__
"Choose object" dialog (file or folder) will be displayed before execution. The path to chosen file or folder will be inserted on execution.

__DLG_CHOOSE_OBJECT_PARENT_PATH__
"Choose object" dialog will be displayed before execution. The path to parent folder of chosen file or folder will be inserted on execution.

__DLG_CHOOSE_OBJECT_NAME__
"Choose object" dialog will be displayed before execution. The name of chosen file or folder will be inserted on execution.

__DLG_CHOOSE_OBJECT_NAME_NO_EXTENSION__
"Choose object" dialog will be displayed before execution. The name without extension of chosen file or folder will be inserted on execution.

__DLG_CHOOSE_OBJECT_EXTENSION_ONLY__
"Choose object" dialog will be displayed before execution. The extension of chosen file or folder will be inserted on execution.

New in 1.6:

__MY_BUNDLE_PATH__
The path pointing to plugin or droplet bundle.

__MY_HOST_BUNDLE_PATH__
The path pointing to host application or droplet bundle.

These new "bundle" paths do not make much sense for contextual menus because they point to OnMyCommandCM.plugin or host application but they might be extremely useful for droplets because you may put things in bundle resources and access them with __MY_HOST_BUNDLE_PATH__/Contents/Resources/
One example is that you may put CLI executable in droplet resources and run it from command description. This way you have everything you need in one bundle and no additional installation is required.

__MY_BUNDLE_PATH__ is obtained using bundle identifier, for example com.abracode.CommandDroplet. If used within plug-in you may obtain a path where the plug-in is installed. If used within droplet, it should return the droplet location. However, the problem with this approach may be that if there are several droplets with the same identifier (suppose you were not careful with changing identifiers for them) it may point to a wrong place. The other method: __MY_HOST_BUNDLE_PATH__ obtains the location of running application by querying process manager. If you use it in CM plug-in you will obtain the path to host application. If you run it in droplet, you will receive the path to droplet. Summarizing: both methods should return the same result for droplet but __MY_HOST_BUNDLE_PATH__ should be more reliable and is recommended.

New in 1.7:

__NIB_DLG_GUID__
This special word is replaced dynamically with current dialog unique id. It is used for setting dialog control data in subcommands. For example:
omc_dialog_control __NIB_DLG_GUID__ 4 "Menu Item 1"

__CURRENT_COMMAND_GUID__
It returns the unique id for each command (subcommands are unique too). It is different from regular command id (four char characters). __CURRENT_COMMAND_GUID__ is a globally unique ID - guaranteed. It is used to identify which command is currently running in order to avoid conflicts if more than one is running concurrently. Potentially the globally unique ID can also be used for different purposes - for example for saving a temporary file without worrying that a file with the same name exists.
Example usage:
omc_next_command __CURRENT_COMMAND_GUID__ "NeXT"

New in 1.8:
__MY_EXTERNAL_BUNDLE_PATH__
It is a special object pointing to path defined by EXTERNAL_BUNDLE_PATH tag (redundant, but much needed for portability)

   <key>COMMAND</key>
    <array>
        <string>echo </string>
        <string>__MY_EXTERNAL_BUNDLE_PATH__</string>
    </array>

    <key>EXTERNAL_BUNDLE_PATH</key>
    <string>~/Library/Application Support/OnMyCommand/My Command.omc</string>

If explicit path EXTERNAL_BUNDLE_PATH in command description is not specified, __MY_EXTERNAL_BUNDLE_PATH__ resolves to default external bundle location which is: /Users/you/Library/Application Support/OnMyCommand/CurrentCommandName.omc where "CurrentCommandName" is the name of the command (and menu item). This will allow easy access to private command resources (nibs, images, scripts, etc.). The net result is that if you place a ".omc" bundle of the same name as your command in ~/LibraryApplication Support/OnMyCommand/, it will be found automatically.
DropletBuilder is able to install the .omc bundle for you in default location and copy the command from "Command.plist" to your main list of commands. Just drag the .omc bundle on the DropletBuilder icon. This way the self-contained command with resources (images, nibs, external scripts, etc.) may be distributed as .omc bundle and is easy to install.

The following option controls when the command should show

<key>ACTIVATION_MODE</key>

<string>act_always</string> (Default value assumed if key not present)
Command active always.

<string>act_file</string>
Command active when file is control-clicked.
Extended checking is available for this activation mode via ACTIVATION_FILE_TYPES and ACTIVATION_EXTENSIONS. Look below for more details.

<string>act_folder</string>
Command active when folder is control-clicked.
Extended checking is available for this activation mode via ACTIVATION_EXTENSIONS. Look below for more details.

<string>act_file_or_folder</string>
Command active when file or folder is control-clicked.
Extended checking is available for this activation mode via ACTIVATION_FILE_TYPES and ACTIVATION_EXTENSIONS. Look below for more details.

<string>act_finder_window</string>
Command active when open Finder window or desktop is control-clicked.
Extended checking is available for this activation mode via ACTIVATION_EXTENSIONS. Look below for more details.

<string>act_selected_text</string>
Command active when a selected text is control-clicked.

<string>act_clipboard_text</string>
Command active when there is a text in clipboard.

<string>act_selected_or_clipboard_text</string>
Command active when a selected text is control-clicked or there is a text in clipboard.
When both conditions are met - text is clicked and clipboard contains text - the menu is displayed and clicked text takes precedence over text in clipboard.

NEW in 1.4.2:

<string>act_file_or_folder_not_finder_window</string>
Command active when file or folder is control-clicked but not open Finder window or Desktop.

<string>act_folder_not_finder_window</string>
Command active when folder is control-clicked but not open Finder window or Desktop.

The following options control WHERE your menu item should show

<key>ACTIVATE_ONLY_IN</key>
<array>
<string></string>
</array>

<key>NEVER_ACTIVE_IN</key>
<array>
<string></string>
</array>

Starting with version 1.6.1 there is a new activation option to tell in which applications the command should or must not show:
ACTIVATE_ONLY_IN or NEVER_ACTIVE_IN. Those 2 options are logically exclusive. You can use one or the other but not both in one command. You provide an array of application names like this:

    <key>ACTIVATE_ONLY_IN</key>
    <array>
        <string>TextEdit</string>
        <string>BBEdit Lite</string>
    </array>

or:

    <key>NEVER_ACTIVE_IN</key>
    <array>
        <string>Finder</string>
    </array>

The name of the application is what you see in manu bar when you launch given application, not the name of the bundle (which may be different).

The following option controls how your command is executed

<key>EXECUTION_MODE</key>

<string>exe_silent_popen</string> (Default value assumed if key not present)
Execute silently using popen() call, only errors are output to Console.app. Old, deprecated name was: exe_silent
Default shell in Mac OS 10.3.x & 10.4.x: sh
Executes asynchronously starting with OMC 1.8

<string>exe_silent_system</string>
Execute silently using system() call. Use with quick commands not producing much result text.
Default shell in Mac OS 10.3.x & 10.4.x: sh
Executes synchronously, blocking the host during execution.

<string>exe_terminal</string>
Launch Terminal.app and execute the command there.
Default shell in Mac OS 10.3.x: bash

<string>exe_iterm</string>
Launch iTerm.app and execute the command there.
Default shell in Mac OS 10.3.x: bash

<string>exe_popen_with_output_window</string>
Execute command using popen() call and display result in output window.
Default shell in Mac OS 10.3.x: sh
Executes asynchronously starting with OMC 1.8

<string>exe_applescript</string>
The command must be an AppleScript code. Executes the code silently.
Executes synchronously.

<string>exe_applescript_with_output_window</string>
The command must be an AppleScript code. Displays result window.
Executes synchronously.

<string>exe_shell_script</string>
The command must be a shell script. At the beginning of each shell script you need to specify which shell to use. For example: #!/bin/sh
Shell script is saved to temporary file before execution. Make sure your line endings are Unix linefeeds (LFs).
Executes asynchronously starting with OMC 1.8

<string>exe_shell_script_with_output_window</string>
The command must be a shell script. Displays result window.
Executes asynchronously starting with OMC 1.8

Options exe_silent_popen, exe_silent_system & exe_iterm are new or renamed in version 1.5.4.
Options exe_popen_with_output_window, exe_applescript & exe_applescript_with_output_window are new in version 1.6.
Options exe_shell_script & exe_shell_script_with_output_window are new in version 1.6.1.

For execution modes with output window you may control various settings of the window. The dictionary group is named: OUTPUT_WINDOW_SETTINGS. Full description in "Output window settings" section of this document.

Version 1.6 of OMC fixed a long standing bug with popen() call. The symptom was that commands displaying several lines of result were aborted prematurely. Now it should execute anything you throw at it. Current recommendation is that you should use exe_silent_popen or exe_popen_with_output_window modes for commands which are time consuming and produce several lines of result. One example is "hdiutil create" which can work for several seconds displaying status in several lines. exe_silent_system should be used for quick commands, for example: "touch some_file"

Version 1.6 add native support for AppleScript. A lot of commands used osascript call to put AppleScript code in OMC item. Now you can write AppleScript code directly in command description and choose exe_applescript or exe_applescript_with_output_window execution mode. You should use esc_for_applescript for proper escaping of objects. You can use "POSIX file" to get access to files with Unix path, for example:

<key>COMMAND</key>
<array>
    <string>tell app "Finder"
move POSIX file "</string>
    <string>__OBJ_PATH__</string>
    <string>" to (path to documents folder)
end tell</string>
</array>

New in 1.7b1:

Send Task to Background Application (OMCDeputy)
<key>SEND_TASK_TO_BACKGROUND_APP</key>
<false/> - default value if key not present
<true/> - command is executed by OMCDeputy background app
This option is for commands with or without output window but it makes sense when you have an output window or nib-based progress bar to monitor the progress. Host app will no longer be blocked. It is very handy for time consuming tasks started by contextual menu in Finder. It is also very important for AppleScripts which try to talk back to the host app. This option has no effect if command is sent to Terminal or iTerm.

Escape characters option

<key>ESCAPE_SPECIAL_CHARS</key>

<string>esc_with_backslash</string> (Default value for path objects assumed if key not present)
Escape special characters with backslash (i.e. ~/My Folder/ will be replaced with ~/My\ Folder/)
Beginning with version 1.3.1a9 this type of escape is also applied to __OBJ_TEXT__. Another change in version 1.3.1a9 is that line breaks LF (0x0A) and CR (0x0D) are escaped with backslash too.

<string>esc_none</string>
No change is made to added string

<string>esc_with_percent</string>
Internet URL style escape (i.e. Hello Friend.html will be replaced with Hello%20Friend.html)
Escapes only illegal URL chars (as defined by RFC 2396)
This type of escape is applied to paths and __OBJ_TEXT__ as well.

<string>esc_with_percent_all</string>
This method escapes all illegal URL chars plus legal non-alphanumeric chars. The additional escaped characters are: !$&'()*+,-./:;=?@_~. Those chars need to be escaped in order to avoid conflicts in shell execution. The end result is that only A-Z, a-z, 0-9 are left unescaped.

<string>esc_for_applescript</string>
New in OMC 1.6. Escapes backslash and double quote mark only.
\ becomes \\
" becomes \"

<string>esc_wrap_with_single_quotes_for_shell</string>
This is a special quoting method for use with shell. The behavior is to wrap the text with single quotes and work around the problem of any possible single quote inside. The text:
Don't do it
will become wrapped as:
'Don'\'' do it'

NOTES:
"esc_with_backslash" option MUST NOT be used at the same time with quotes around inserted object. You can use either way to make sure the proper path is set but not together because such combination is not going to work. cd ~/My\ Folder/ is going to work and cd "~/My Folder/" is going to work, but cd "~/My\ Folder/" will not work.

New in 1.7b1
__DLG_INPUT_TEXT__ is now escaped according to the escape method described by ESCAPE_SPECIAL_CHARS

New in 1.8
You can override escaping method in nib controls. You may specify the control property with creator 'OMC!', tag 'esc!' and Unicode text value string like esc_none, esc_with_backslash, etc.

Line endings replacement

Option to replace line endings for __OBJ_TEXT__:

<key>TEXT_REPLACE_OPTION</key>
<string>txt_replace_none</string>
Default, no change

<string>txt_replace_lf_with_cr</string>
Change Unix line breaks to Mac line breaks

<string>txt_replace_cr_with_lf</string>
Change Mac line breaks to Unix line breaks

This is for replacement within __OBJ_TEXT__ object: selection or clipboard. This option was added in OMC 1.7b1.

The following key may contain comments from command author

<key>NOTES</key>
<string></string>
This keyword is ignored by plug-in but may contain additional information (e.g. about requirements for given command or info about the author).

Extended file/folder type checking

A. File type list. This extended checking is available when ACTIVATION_MODE is act_file or act_file_or_folder.
You may provide a list of file types. If any of your types is matched, your command will be activated.
Example:

<key>ACTIVATION_FILE_TYPES</key>
<array>
<string>TEXT</string>
<string>utxt</string>
</array>

NOTES:
File types are usually represented as four character code. If you specify longer file type, only first four characters will be used. If you specify shorter file type, the remaining characters are assumed to be zero (true zero, not character '0').

B. Extension list. This extended checking is available when ACTIVATION_MODE is act_file, act_folder,act_file_or_folder or act_finder_window. You may provide a list of extensions. If any of them matches the extension of a clicked object the command will be activated.

Example:

<key>ACTIVATION_EXTENSIONS</key>
<array>
    <string>htm</string>
    <string>html</string>
    <string>shtml</string>
</array>

NOTES:
1. Extension comparison is case insensitive.
2. Do not include dot preceding the extension.

If you specify both ACTIVATION_FILE_TYPES and ACTIVATION_EXTENSIONS then any match is enough for activation.
For programmers: it is logical operator OR.
For laymen: if you specify file type 'TEXT' and extension "txt" then the following documents will activate the command:
1. "document.txt" of any file type, including 'TEXT'
2. "document.ext" of type 'TEXT'
3. "document" of type 'TEXT'
However, a file named "document" or "document.ext" without file type specified will not activate the command.

Multiple object insertion

Subgroup with settings for multiple object processing. If key not present, proc_separately is assumed.
<key>MULTIPLE_OBJECT_SETTINGS</key>
<dict>
    <key>PROCESSING_MODE</key>
    <string>proc_together</string>
    <key>PREFIX</key>
    <string></string>
    <key>SUFFIX</key>
    <string></string>
    <key>SEPARATOR</key>
    <string></string>
</dict>

<key>PROCESSING_MODE</key>

<string>proc_separately</string> (Default value assumed if key not present)
Command is executed for each file or folder separately

<string>proc_together</string>
All objects are processed together by one command, inserted paths are composed of prefix+path+suffix+separator+prefix+path+suffix...etc.

<key>PREFIX</key> (No prefix is used if key not present)
<string></string>
A prefix text to be inserted before every object

<key>SUFFIX</key> (No suffix is used if key not present)
<string></string>
A suffix text to be inserted after every object

<key>SEPARATOR</key> (No separator is used if key not present)
<string></string>
A separator text to be inserted between objects

Example:
Consider the following settings for multiple objects:

<key>MULTIPLE_OBJECT_SETTINGS</key>
<dict>
    <key>PROCESSING_MODE</key>
    <string>proc_together</string>
    <key>PREFIX</key>
    <string>"</string>
    <key>SUFFIX</key>
    <string>"</string>
    <key>SEPARATOR</key>
    <string> </string>
</dict>

When multiple files are clicked:

/Users/You/Folder1/file1.txt
/Users/You/Folder2/file2.txt
/Users/You/Folder3/file3.txt

and the command is:

<key>COMMAND</key>
<array>
<string>echo </string>
<string>__OBJ_PATH__</string>
</array>

The resulting command text will be as follows:

echo "/Users/You/Folder1/file1.txt" "/Users/You/Folder2/file2.txt" "/Users/You/Folder3/file3.txt"

New in 1.8

Multiple objects sorting:

<key>MULTIPLE_OBJECT_SETTINGS</key>
<dict>
    <key>SORT_METHOD</key>
    <string>sort_by_name</string>
    <key>SORT_OPTIONS</key>
    <dict>
        <key>SORT_ASCENDING</key>
        <true/>
        <key>COMPARE_CASE_INSENSITIVE</key>
        <true/>
        <key>COMPARE_NONLITERAL</key>
        <true/>
        <key>COMPARE_LOCALIZED</key>
        <true/>
        <key>COMPARE_NUMERICAL</key>
        <true/>
     </dict>
</dict>

SORT_METHOD: sort_none (default), sort_by_name
SORT_OPTIONS (only valid if SORT_METHOD is different from sort_none):
    SORT_ASCENDING - default true: a-z, 0-9 , if false: z-a, 9-0
    All other options are corresponding to CFStringCompareFlags. See description in Apple documentation.

    COMPARE_CASE_INSENSITIVE — if true: Finder-like. Default is false: case sensitive, Unix-like
    COMPARE_NONLITERAL — default is false: literal
    COMPARE_LOCALIZED — default is false: not locale-aware
    COMPARE_NUMERICAL — if true: numeric values compared so "version 2" < "version 2.5", default is false: alphabetical

Terminal behavior settings

The following terminal settings are applied to each command individually. They apply to Terminal or iTerm only and are ignored when command is executed silently.

<key>TERM_OPEN_NEW_SESSION</key>
<true/> (Default value assumed if key not present)
Command will be executed in new terminal window.

<false/>
Command will be executed in frontmost terminal window. If there is no window open, the command will not be executed. In Mac OS 10.1.x Terminal.app is less advanced and does not support execution is frontmost window, so a new session is always opened and TERM_OPEN_NEW_SESSION setting is ignored.

<key>TERM_BRING_TO_FRONT</key>
<true/>(Default value assumed if key not present)
"Activate" event is sent to terminal after command event. This brings terminal to front.

<false/>
The window with executed command will not come to front. Useful for longer tasks like downloading files so you may stay in your context while terminal does its job in background. If Terminal is not launched yet, it