Tinderbox allows users to extend its capabilities by giving users access to the command line (CL) in a number of ways:
- Action code:
- runCommand()
- back-tick marker (deprecated, use runCommand() instead)
- Attributes:
The above actions and attributes enable execution of stored command lines or action code expressions. For the attributes above, the command line is run on the post-processed of HTML output or AutoFetch input.
The most flexible method is runCommand(). See the referenced note for more detail. The runCommand() operator can also be used to call external scripts, i.e. script files stored in the OS outside the TBX document, using an POSIX-style path (i.e. slash-delimited, not colon-delimited); paths can be absolute or relative.
Scripts used without without a path are assumed to be in the shells current working directory ('pwd'). Tinderbox's default directory is the boot drive's root (/); each new runCommand call thus starts at / even if it was altered in a previous call. To use a script in your home folder, prefix the script name with ~/.
CL code can also be stored in string attributes, such as $Text, but only when using runCommand(); the other methods above require literal CL code. Referenced CL code is called thus:
runCommand($Text("CL example"))
Using a note's $Text to hold code can be very useful for CLs too long or complex to work on easily in a $Rule or $OnAdd box. In the text window you can turn off the sidebar, use a monospace font, crank up the font size, etc. - or use the built-in prototype 'Code';.
Because of the external calls involved, CLs used in action code such as agent actions, can have significant impact on agent cycle time. This is especially true if using CL code to process text. In an agent context, consider turning the agent off (via $AgentPriority) when processing is not needed.
It is worth noting Tinderbox's support for single-quote and double-quote string quoting but bear in mind that there is no method for escaping a double quote character.
Working directory location
When accessing the command line this way the target is the host Mac's current working directory. Regardless of other Terminal sessions that may be active, the current directory for Tinderbox access is the root of the current volume - '/'. Thus, if calling scripts or programs elsewhere on the host system, such as in the user's account's 'Documents' folder, remember to prefix an appropriate path to the script/program.
If the working directory is changed as part of the call from Tinderbox, that change will hold for the remainder of the call. For instance, a runCommand() string "cd ~/Documents; pwd" with return the full path to the user's Documents folder (e.g. '/Users/jdoe/Documents') and will become the working directory for all subsequent commands passed in that string, but not for call from other notes. Observer the trailing semi-colon after the Cd command, this tells the command line that the first command is complete allowing a follow-on command to added with is executed after the previous one. In the example given, a follow-on command would execute within a non-default current working directory.
Script Permissions
External script files also need to be executable. It's not enough to make a new file in something like TextEdit and save code into it, extra permissions are needed. By default a file is 644, a script needs to be 755. Assuming a script in your home folder, and a root working directory, this can be done with a runCommand() call:
runCommand("cd ~; chmod 755 somescript.pl)
Of if the script name is stored in a notes $MyString:
runCommand("cd ~; chmod 755 "+$MyString)