The following is a quick introduction to the scripting engine of Textual.
This webpage assumes that you, the reader, have a basic understanding of AppleScript and the use of scripting languages in general. If this is not you, then the Introduction to AppleScript Language Guide may prove to be helpful.
Scripts are designed to create custom commands which can be performed from the main input text field of Textual.
There are plans to expand scripting support in Textual to provide more than custom commands, but concerns over performance have made these plans take a step to the side for now.
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 filename of the original file. Therefore, if a script was named host.scpt, then the command /host would be used to perform it.
Scripts are stored in the following folder:
Any script placed within this folder will be performed outside of the OS X sandbox environment.
Textual supports Python (.py), Ruby (.rb), Perl (.pl), Shell Executables (.sh, .bash), and PHP (.php) for scripts.
These all follow the same design concept: 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 text field "/host what is this?", then the input 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.
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.
on textualcmd() 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.