| Operator Type: | Function |
| Operator Scope of Action: | Item |
| Operator Purpose: | Data manipulation |
The operator, runCommand(), lets rules and actions use the command line.
runCommand(command[,input(s)])
passes command to the OS's Unix shell. The new process receives input, if any, as its standard input; the process's standard output is returned as the result of calling runCommand. Using just command on its own is akin to using the back-tick action syntax. The above syntax - in one-line command line usage - can also be thought of as:
runCommand(command, stdin)
Understanding the latter can help avoid trying to echo data into a command within the 'command' string. See the 'quotify' example further below.
For example, if a note called "Jane Doe" is dropped on a container with this OnAdd action:
$MyResult = runCommand("sendmail -f "+$Email+" "+$Email(parent), "Subject:"+$Name+"\nHello\n.")
This assumes both dropped and container notes have a valid email address in Email. If so, Jane Doe will get an email with subject line "Jane Doe" and body text "Hello"; the email will be from the dropped note's $Email address and to the container's $Email address. In the above example:
command: sendmail - f jade@doe.com someone@other.com'
input (i.e. stdin): "Subject: Jane Doe\nHello\n."
User attribute 'MyResult' will receive any message back from standard output.
From v4.6, this operator does not require a left-side to the expression where the result of the command line is not needed by Tinderbox. Thus the same example as above can run as:
runCommand("sendmail -f "+$Email+" "+$Email(parent), "Subject:"+$Name+"\nHello\n.")
Bear in mind that in this latter case there is no way of knowing if the command executed successfully.
To use external commands like above you may need to check the encoding of the strings you extract from your TBX attributes. Don't forget to allow for characters like spaces/quotes/apostrophes in attribute values; these will invariably need escaping for safe use in a command line using operators like urlEncode():
$MyResult=runCommand("/usr/bin/curl -d 'status="+urlEncode($Name)+"' -u myusername:mypassword http://twitter.com/statuses/update.atom");
In the above, if the value of $Name were "Mark's project", the use of urlEncode() will ensure the string passed to the command line is actually "Mark%27s%20project".
exportedString() can also help with ensuring the necessary encoding, allowing a template to be used to help with formatting the string passed into the command.
Exactly where you do/don't need to encode attribute values will depend on the syntax of the particular operation you are performing.
To help get around issues of quoting, a note's text (or other string attribute) can be used for either or both arguments. Consider a note called 'quotify' holding this command line:
sed 's:"\([^"]*\)":“\1”:g'
A stamp might then hold this code:
$Text = runCommand($Text(quotify),$Text);
This effectively adds a menu item to the Stamps to change ordinary double quotes to their 'smart form', allowing the process to be run once, on demand, avoiding repeat use every agent cycle as would happen if using a rule or agent action.
