Variables

A variable is like a labeled bin for data. Data can be placed "into" a variable by a number of different methods, then retrieved later for further use.

• A variable is a core aspect of computer programming; read more at the Variable page on Wikipedia

Initializing and Setting the Values of Variables

Variables must be initialized before use, meaning the pipeline must know they exist and will be used.

Core.InitVar -var:name

Multiple variables can be initialized at the same time.

Core.InitVar -var:name -var:age -var:address

The value of a variable can be set multiple ways. For example, with the SetVar filter:

Core.SetVar -var:deane -value:"James Bond"

Variables can be appended to with the AppendVar filter:

Core.InitVar -var:name
Core.AppendVar -var:name -value:James
Core.AppendVar -var:name -value:" "
Core.AppendVar -var:name -value:Bond

At the end of this script, the name variable would contain "James Bond".

Variables can be read from the current input text, and written to it using the special filters ReadFrom and WriteTo. See Non-Sequential-Scripts.

Using Variables in Arguments

The value of a variable can be retrieved and passed as the value of a command argument:

Text.Append -suffix:$introduction

Variable replacements always start with the dollar sign: $. In the example above, the value of the $introduction variable is used for the suffix argument, but the value is still retained in $introduction and can be used again later if desired.

You may have noticed that in some cases we have used the $, and in some cases we haven't. When to use it or not can be a little confusing, but consider this --

Some filters take the names of variables as arguments. For example:

Core.SetVar -var:name -value:"James Bond"

In these cases, you do not prefix the variable name with a dollar sign. This is because the engine interprets the dollar sign as "replace this with the value of the variable." Consider:

# WARNING: This is not correct
Core.SetVar -var:$name -value:"James Bond"

In this case, the engine would attempt to replace $name with the value of that variable...which hasn't been set yet.

In general, whenever you see a variable name prefaced with the dollar sign, think "I am intending to move data into or out of this variable." When you don't use the dollar sign, think "I'm just referring to the name of this variable."

Redirecting Filter Output to Variables

Normally, a filter outputs data to the next filter. However, this data can be "redirected" to a variable using =>, where it can be held until needed. When a filter's output is redirected, that filter's input is simply passed through to the next filter, unchanged, as if the filter never existed. For example:

Http.Get -url:http://gadgetopia.com
Http.Extract -path:title => $title
Http.Extract -path:body

In this example, an HTML document is retrieved in Step #1. In Step #2, the TITLE tag of that document is extracted and the output of that operation is redirected to a variable. Because of the redirection, the entire HTML document is passed on to Step #3.

The standard redirection operator (=>) will replace all the output in a variable with the output of the filter.

If you use ==> (so, two equals signs instead of one), the output is instead appended to an existing variable. (The variable must exist first.)

# Initialize the variable for the consolidated output
InitVar -var:xml

# Get the first web service call, wrap it in a tag, and append the output
Http.Get -url:http://webservice1.com
Xml.MakeFragment
Text.Format -template:<service1>{0}</service1> ==> $xml

# Get the second web service call, wrap it in a tag, and append the output
Http.Get -url:http://webservice2.com
Xml.MakeFragment
Text.Format -template:<service2>{0}</service2> ==> $xml

# Read the XML from the variable, wrap it in a master tag, and output it
ReadFrom xml
Text.Format -template:<services>{0}</services>

The output of this script would look something like this:

<services>
  <service1>
    [entire content of the first service call]
  </service1>
  <service2>
    [entire content of the second service call]
  </service2>
</services>

This XML could then be further transformed or templated for output.

• Next: Non-Sequential Scripts