Writing Scripts


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.


What are scripts?

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.

How do I install a script that somebody gave me?

Right click the file and select the option to open the scpt file with Textual.

How do I use scripts?

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.


Where are scripts stored?

Scripts are stored in the following folder:

~/Library/Application Scripts/com.codeux.irc.textual5

Any script placed within this folder will be performed outside of the OS X sandbox environment.

Is AppleScript the only supported scripting language?

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.

What type of input do scripts have access to?

The function in AppleScript invoked by Textual is called   textualcmd(inputString, destinationChannel).

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.

Where does script output go to when returned?

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.

My script did nothing. What is wrong?

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.


Example of No Input Information Required

Filename: example.scpt
Command: /example

on textualcmd()
    return "This message will be sent to selected channel."
end textualcmd

Example of Input Information Required

Filename: example.scpt
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.

Last modified: December 26, 2014

The contents of this webpage are released into the Public Domain for unlimited distribution.