# Writing Scripts

> Historical reference: 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](<https://en.wikipedia.org/wiki/Scripting_language>), such as [AppleScript](<https://en.wikipedia.org/wiki/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:

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

Otherwise, Textual will look at the following path:

```text
~/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:** Make non-AppleScript scripts executable (chmod +x) and start them with a `#!` line. Textual ignores script files that are neither AppleScript nor executable; typing their command then goes to the server like any unknown command.*

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

Scripts in other languages receive the same information as command line arguments. The first argument is the destination channel (empty in the server console), and each word the user typed follows as its own argument. If the user entered “/example one two” in #textual, a shell script receives `#textual` as `$1`, `one` as `$2` and `two` as `$3`. To use the typed text as one string, join every argument after the first, for example `shift; echo "$*"`.

Nothing else is passed to a script: not your nickname and not the server. A script always runs because you typed its command, so you are always the user who invoked it.

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?

The output of a script is handled exactly as if you had typed it into the channel that was selected. Plain text is sent to the channel, and a line that starts with “/” is performed as a command. Start a line with “//” to send text that begins with a slash.

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](<https://www.textualapp.com/docs/legacy/reference/commands>) for a complete list of commands that support a destination.

### How do I show a message only to myself?

Return it as an ***“/echo”*** command. ***“/echo”*** prints its text in your own window and nothing is sent to the server, which makes it the right choice for errors and usage hints:

```text
on textualcmd(inputString, destinationChannel)
    if inputString is "" then
        return "/echo Usage: /example <text>"
    end if
    return inputString
end textualcmd
```

A script in another language does the same by writing the command to its output, for example `echo "/echo Usage: /example <text>"`.

### 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?

If a script cannot be performed, or an AppleScript reports an error, Textual shows the error in the selected window and also writes it to Console. Console can be reached by typing “Console” into Spotlight or browsing to Console.app under the **Utilities** folder of **Applications**. Only what a script writes to its standard output is used; anything written to standard error is not shown.

To output nothing, return an empty string (`return ""`). In Textual 7.2.8 and earlier, an AppleScript that returns something other than text (a list, for example), or a script whose output is not valid UTF-8, makes Textual quit. This is fixed in Textual 7.2.9.

## Example of No Input Information Required

***Filename:** example.scpt*
 ***Command:** /example*

```text
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?*

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