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 (now 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 working directory is the user's home folder (i.e. /users/[shortusername] or in short form ~); each new runCommand call thus starts at even if it was altered in a previous call.
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 use a monospace font, crank up the font size, etc., Tinderbox provides an easy method via 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 targeted location is the host Mac's home directory. Regardless of other Terminal sessions that may be active, the current directory for Tinderbox access is the root of the current volume, i.e. '~'. 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 (or set a new directory via the method described below).
If the working directory is changed as part of the runCommand 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 calls from other notes. Observe 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.
Setting the working directory
runCommand(command[,input(s),directory])
If the optional directory is specified as a POSIX path, it sets the working directory in which command is executed. Otherwise, by default, the working directory is the user's home folder (i.e. /users/[shortusername] or in short form~).
Script Permissions
External script files also need to be executable. It is 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)