Flag replacement
Worker replaces placeholders (flags) with actual file names when starting external programs (and in some other places too). Basically there are two different types: A placeholder can be replaced by the name of the first selected entry (file or directory) or by all selected entries.
When executing a command Worker builds a temporary list of all selected entries. For the "first selected entry" Worker uses the first entry in this list, for "all selected entries" Worker uses all entries in the list.
However, although it says "first/all selected" not in every case it does what it says. It depends on the context what will be inserted in the list and eventually replaced for a placeholder.
- No context
If you click on a button or press a hotkey the commands in the corresponding command list are executed without a context. This means that all currently selected entries are stored in a temporary list. Using this list Worker replaces all placeholders. This is what normally is expected to happen. - Context
For double click actions, drag'n'drop and context menus the behavior is slightly different as the flags will be replaced in the context of the current entry. The flags basically works just as for the "no context" case. However, the only difference is that {f} will be the highlighted entry and not literally the first one.
Some words about reusing of some entries: In normal operation the entry is removed from the list when it is replaced in a command string. For example using {f} twice will not results in a double insertion of the same file name but in the insertion of the first and second selected file. It is possible to prevent this by using the "no unselect" modifier for the flag (in this example {uf}). This way the file remains in the list and will be used for another flag replacement.
Quoting
By default, all flag replacements are carefully single-quoted to avoid code execution or other side effect for files containing special characters. As a side effect, you don't need to add special handling for files containing spaces which often creates some problems when used in shell scripts. It will just work most of the time.There are some exceptions when quoting is done. If the string containing flags is not used for external commands like when modifying stacks in Script command, it will not be quoted at this point. When however, the value is used as part of another flag, it will then be quoted for use in external programs.
Quoting can also be explicitly disabled on a per-flag basis by using a dash as a first character for flag value.
Quoting takes the surrounding quotes into account when replacing the content but putting a flag inside quotes basically will only make it one argument of the external command instead of multiple arguments when the flag is expanded to multiple items.
Limitations
Quoting is done carefully to avoid arbitrary code execution via code injection as part of specially crafted file names. External commands are always executed within a generated shell script so quoting is an important security feature.There however also limitations:
- Only limited support for shell features is available.
- &&, ||, |, ; and & can be used to combine multiple commands.
- File redirection is possible but no spaces are allowed between the redirection symbol the file.
- Other features like variable replacement via $... etc or code execution in subshells is not possible.
- No recursive quoting is done. For example, it is not possible to create a
single quoted shell argument containing multiple flags (like "echo
'{lp} {rp}'" to have the left and right directory as one argument to
echo). This example will only create a single argument string containing
both flags correctly quoted for the outer single quote.
- Example: If {lp} is "a b" and {rp} is "c d", '{lp} {rp}' will be 'a b c d' and not 'a\ b c\ d'
- If you need this for example to call another command with those arguments, you have to use a wrapper script and give this script the flags without any quoting around them.