Writing Scripts

Wiki Home

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

Introduction

What are scripts?

Scripts are small snippets of source code that are created outside of the main bundle of Textual. They are intended to be created by third party developers to extend the functionality of Textual in a easy to download and manage format.

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 actual command to execute a script is the same as the filename which was installed. Therefore, if a script was named host.scpt, then the command /host would be used to execute it. Whether or not a script requires a parameter for input processing depends on the purpose of the script.

Technical

Where are scripts stored?

Scripts are stored in the following folder:

[home folder] > Library > Application Scripts > com.codeux.irc.textual

Any script placed within this folder will be executed outside of the Mac sandbox environment.

Is AppleScript the only supported scripting language?

No, but it is the recommended one and the only one officially supported. Textual supports Python (.py), Ruby (.rb), Perl (.pl), Shell Executables (.sh, .bash), and PHP (.php) for scripts.

These follow the same design. User input is supplied and a return of one or more lines of data is expected. They cannot return something then continue to run. Death occurs after Textual has processed the first result.

Note: Set non-AppleScript files as executables (chmod +x) else Textual will crash when trying to run them in the shell.

How do I make a Script?

Textual supports two types of scripts. They are scripts that require input from the end user and those that do not. Both of these scripts share similar design.

Once developed, a script can be either saved in a plain format which can be edited by anyone or it can be compiled and saved as a run only file. Textual supports both of these file types. For more information regarding the applications needed and the methods used to save AppleScript files please see the Apple website.

What type of input do scripts have access to?

The actual command in AppleScript executed by Textual is called   textualcmd(inputString, destinationChannel).

This command 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 an actual channel name, a nickname for private messages, or nothing if it is the server console. The destination channel is the name of the channel in which the script was executed. Use this in the script's return value to target the actual channel.

Where does script output go to when returned?

If plain text is returned by the script, then Textual tries its best to post that plain text in the channel that was selected when the script was first executed. 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 parameters. 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 Mac OS Console. This can be reached by typing "Console" into spotlight or browsing to Console.app under the Utilities folder.

Examples

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


 
Last modified: April 24, 2014


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