Writing Scripts

The following is a quick introduction to the scripting engine of Textual.

Introduction

What is a “script”?

A “script” is a file that Textual can access in order to add features that do not already exist. The file itself contains a scripting language, such as AppleScript, that Textual is able to interpret.

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.

How do I install a script that somebody gave me?

Control click (right click) the file and select the option to open the scpt file with Textual.

How do I use a script?

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.

Technical

Where are scripts stored?

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:

~/Library/Application Scripts/com.codeux.apps.textual-mas/

Otherwise, Textual will look at the following path:

~/Library/Application Scripts/com.codeux.apps.textual/

This folder may not exist and may need to be created manually.

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 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.

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 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.

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.

Can a script perform more than one action?

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.

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 of Applications.

Example of No Input Information Required

Filename: example.scpt
Command: /example

on textualcmd(inputString, destinationChannel)
    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.