The following is a quick introduction to the scripting engine of Textual.
A script can be used to create a custom command which can be accessed through the main input text field of Textual.
For example, a script named itunes, which would be invoked by typing “/itunes” into the main input text field of Textual, could be engineered to output information related to the iTunes application such as the song that is currently playing.
Control click (right click) the file and select the option to open the scpt file with Textual.
The command to perform a script is the same as the name of the original file.
If a script was named itunes.scpt, then the command “/itunes” would be used to perform it.
Textual will look at one of two locations to locate custom scripts.
A copy of Textual downloaded through the Mac App Store will look at the following path:
Otherwise, Textual will look at the following path:
This folder may not exist and may need to be created manually.
Textual supports Python (.py), Ruby (.rb), Perl (.pl), Shell Executables (.sh, .bash), and PHP (.php) for scripts.
These all follow the same design pattern: User input is supplied and a return of one or more lines of data is expected. Return values are processed all at once, once a script has finished executing.
Note: Set non-AppleScript files as executables (chmod +x) else Textual will crash when trying to run them in the shell.
The function in AppleScript invoked by Textual is called
This function takes two parameters. The first parameter is an unedited copy of the user input. The user input is anything supplied to the script. For example, if a the user entered into the main input text field “/host what is this?”, then the inputString parameter would be equal to “what is this?”
The second parameter is the destination channel. This value can be a channel name, a nickname for private messages, or nothing if it is the server console. The destination channel is the name of the channel that was selected when the script was invoked. Use this in the script's return value to target the channel.
In addition, scripts are performed outside of the OS X sandbox which means that they can access any AppleScript enabled part of the operating system in order to retrieve relevant information for their purpose.
If plain text is returned by the script, then Textual tries its best to forward that plain text to the channel that was selected when the script was first invoked. However, if a command such as “/me” is returned, then it is the responsibility of the script to use the destination channel supplied to it to determine where the output will be sent to.
Several commands such as “/me” however cannot take a channel as a destination parameter. The command “/sme” must be used in those cases. See the command reference for a complete list of commands that support a destination.
Each line returned by a script is treated as separate input. This means that a script can send multiple messages or perform multiple commands by placing each on a new line.
Textual outputs all errors that it captures to the OS X Console. This can be reached by typing “Console” into spotlight or browsing to Console.app under the Utilities folder of Applications.
on textualcmd(inputString, destinationChannel) return "This message will be sent to selected channel." end textualcmd
Command: /example does this thing work?
on textualcmd(inputString, destinationChannel) return "/sme " & destinationChannel & " " & inputString end textualcmd
This example takes in the “does this thing work?” input from the user and returns it right back to them in the form of an action. It also sends the action to the channel that was selected when the script was invoked.