Promptu ITL Language Help

Help topics

Overview
FAQ
Commands
Lists
ITL
Functions
Value Lists
API Reference

Input Transformation Language (ITL)

ITL is Promptu's language for dynamically evaluating text into expressions.

ITL syntax

< >

The open (<) and close (>) angle brackets denote the beginning and end of an ITL region, respectively, and are the most fundamental part of ITL.

Example usage:

(Execution path)
C:\SomeDirectory\< ITL expression goes here >

(Arguments)
-arg1 < ITL expression goes here > -arg2 value

ITL expressions

An ITL expression is composed of a combination of individual components (listed below) which immediately follow each other. They may, though not necessarily, be separated by spaces (which are ignored).

String literals

String literals are used to add text in your ITL expressions. They begin and end with double quotes.

Note for those not familiar with the term string: a string is a "string" (or group) of characters.

String literals look like this:

"yourText"
where yourText is whatever value you wish to use

Escape sequences in string literals

Sometimes, you may wish to use the double quote within your string literal. You cannot merely use the double quote in your string literal because Promptu would think it is the terminating double quote. To solve this, Promptu allows you to escape the double quote with the backslash (\). Additionally, because the backslash is the escape character, it must be escaped with another backslash if you actually want a backslash character in your string literal.

The following escape sequences are recognized by Promptu:

Escape sequence	Interpreted as
\"	"
\\	\

Example usage:

"my text"
=> my text

"\"my\\Text\""
=> "my\Text"

Function calls

(See also Writing External Functions)

Function calls enable you to invoke code in external .NET assemblies. Functions always return a string and take zero or more string parameters (separated by commas). To use external functions, you must first let Promptu know about the external function (method name, class, number of parameters, assembly reference, etc) and give it a name using the Promptu setup dialog (see function). You may then call it from your ITL expressions using the name you gave it.

Example usage:

myFunction()
calls the function named myFunction which takes 0 parameters

myFunction(expression)
calls the function named myFunction which takes 1 parameter, using the evaluated value of expression for the parameter
myFunction(expression1,expression2,expression3)
calls the function named myFunction which takes 3 parameters, using the evaluated value of expression1 for parameter 1, the evaluated value of expression2 for parameter 2, and the evaluated value of expression3 for parameter 3

Substitutions

Substitutions enable the capturing of arguments typed in the prompt following the command name. There are two types of substitutions:

1. Imperative substitution

An imperative substitution is a substitution which must be made or else the command invocation will fail. The most basic imperative substitution is represented by the following format:

! number !
where number is the 1 based index of the argument to capture or n (which captures all arguments and must capture at least one argument)

This is the second form which an imperative substitution may take:

! startNumber - endNumber !
where startNumber is the 1 based index of the argument to begin capturing from and endNumber is the 1 based index of the last argument to capture or n (which captures all remaining arguments)

Example usage:

!1!
captures argument 1

!n!
captures all arguments (must capture at least one argument)

!1-3!
captures arguments 1 through 3

!3-n!
captures argument 3 and all arguments following it

2. Optional substitution

The optional substitution is similar to the imperative substitution, except that it does not cause command invocation to fail if the argument is not provided.
The most basic optional substitution is represented by the following format:

? number ?
where number is the 1 based index of the argument to capture or n (which captures all arguments, if any are supplied)

This is the second form which an optional substitution may take:

? startNumber - endNumber ?
where startNumber is the 1 based index of the argument to begin capturing from and endNumber is the 1 based index of the last argument to capture or n (which captures all remaining arguments)

The optional substitution may also specify alternate text (in the form of a string literal) or ITL expression to be used if the arguments are not provided.
This is the format for supplying alternate information and it is inserted immediately before the closing '?':

:alternate
where alternate is either a string literal or an ITL expression enclosed in parentheses ' (expression) '

Example usage:

?1?
may capture argument 1

?n?
captures all arguments supplied (if any)

?1-3?
may capture argument 1 through 3

?3-n?
captures argument 3 and all arguments following it (if supplied)

?1:"alternateText"?
may capture argument 1; if not, uses "alternateText"

?n:(function())?
captures all arguments supplied, or if no arguments, evaluates the expression function()

?1-3:"alternateText"?
may capture argument 1 thorugh 3; if not, uses "alternateText"

?3-n:(function()"myText")?
captures argument 3 and all arguments following it; if not, evaluates the expression function()"myText"

A real world example

Wikipedia

A good example of ITL in use is a command which launches Wikipedia and searches using any number of keywords provided as arguments in the prompt.

First, we begin creating a new command and name it enc (short for encyclopedia). Then we manually launch Wikipedia and search for something (anything you want) and find that the URL in the address bar looks like this:

http://en.wikipedia.org/wiki/Special:Search?search=whatever you searched for

To perform Wikipedia searches from Promptu, all we need to do is put any arguments supplied after the search=. Therefore, we construct the ITL which will capture all arguments and place it immediately after search=.

We start with the open angle bracket (<).

Currently, our ITL looks like this:

<

Since we want to capture arguments from the prompt, we will need to use a substitution. We probably want to mandate that the user has to specify arguments; otherwise, our enc command will not behave in a meaningful way. Therefore, we will use an imperative substitution for enc. We want all arguments supplied to end up in the URL, so we will use n as the number of arguments in the most basic form of the imperative substitution.
We add the imperative substitution !n! to our ITL.

Now our ITL looks like this:

<!n!

We finish it off with the close angle bracket (>)

Our final ITL looks like this:

<!n!>

We put the partial Wikipedia URL in the execution path and follow it with the ITL we just created.
The execution path ends up looking like this:

http://en.wikipedia.org/wiki/Special:Search?search=<!n!>

Save your enc command, and then you will be all set to search Wikipedia from your Promptu prompt.
Searching Wikipedia for something such as "hammered dulcimer" is now as easy as typing enc hammered dulcimer in the prompt and hitting Enter!