User's Guide - Language Delimeters

## 10.3 Language Delimiters

As the preceding examples show, the Data Explorer scripting language resembles a conventional programming language. Unlike some programming languages that treat all characters as uppercase, the scripting language is case sensitive. Also, you can type statements beginning at any column in the line. This allows you to indent sections to clarify the program structure.

Data Explorer uses the following characters to separate or delimit elements of the scripting language:

`;` | A semicolon terminates a script statement.
`,` | A comma separates keywords, arguments, lists, or vectors.
`[ ]` | Brackets enclose vectors, matrices, and tensors.
`{ }` | Braces enclose lists and blocks of statements in macros.

In some places, one or more blank spaces can be used in place of a comma (e.g., in separating elements of a vector).

### Commenting Scripts

A comment is defined as two slashes (//) followed by a sequence of characters and terminated by the end of the line. Comments have no effect on the script other than to enhance its readability. For example:

    // This is a valid comment

### Naming Variables and Macros

You can name the variables and macros with identifiers. Identifiers are sequences of characters selected from the following:

- Uppercase alphabetic characters (`A-Z`)
- Lowercase alphabetic characters (`a-z`)
- Numerals (`0-9`)
- Special characters:
  - Underscore (`_`)
  - Single quote (`'`)
  - "At" sign (`@`)

All identifiers must start with either an alphabetic character, an underscore (_), or an "at" sign (@). Remember that the Data Explorer script language is case sensitive: identifiers that differ in the case of at least one character are considered to be different identifiers. Identifiers are currently limited to a length of 200 characters.

Note: | IBM reserves the definition and use of most identifiers that begin with @. However, there are some built-in @ variables that you can set; these are discussed in 10.7 , "Using Data Explorer Script Commands".

The following are valid, unique identifiers:

    ComputeSine
    Compute_Sine
    c0mpute_sine
    compute_s1ne
    compute_sine'

Identifiers can be used as:

- variable names
- function names.

Some identifiers are reserved and cannot be used as a variable or a function name. Every other identifier can be used both as a variable and as a function name. The proper use of the identifier is determined by its context.

#### Reserved Words

The identifiers in the following list cannot be used for variable or function names. Those marked with asterisks are reserved for use in future releases.

`and* backward cancel* else* false* for* forward if* include` | `loop macro not* off on palindrome pause play quit` | `repeat* or* sequence step stop then* true* until* while*`

The identifier `NULL` is a reserved variable name. It can be used to initialize other variables or function arguments to have no value assigned to them.

The keyword $sync forces all pending assignments/definitions are processed by the executive before continuing.

### Specifying Values in a Script

You can specify values in a Data Explorer script as any of the following:

- String constants
- Scalar numeric constants
- Vectors, matrices, and tensors
- Lists

You can use any of the formats described in the following sections to specify values to Data Explorer. To have Data Explorer use a particular format to echo these values to you, you must first format a string with the Format module (as described in Format), and then echo the string using the Echo module.

#### String Constants

String constants consist of a sequence of any characters delimited by the double quote character (`"`). However, a null character in a string delimited by double quotation marks (for example, "str\0ing") causes the string to be terminated at the null character.

String constants have the following characteristics:

- They are delimited with double quotes.

- They can be up to 4000 characters long.

- They may extend over multiple lines, providing that the last character on each line (except for the last line) is a backslash. For example, the following lines,

      a = "123\
      456";

  are equivalent to

      a = "123456";

You can use the following escape sequences to include special characters in a string constant:

Description | Character | Escape Sequence
--- | --- | ---
newline | NL (LF) | `\n`
horizontal tab | HT | `\t`
vertical tab | VT | `\v`
backspace | BS | `\b`
carriage return | CR | `\r`
formfeed | FF | `\f`
audible alert | BEL | `\a`
backslash | \ | `\\`
question mark | ? | `\?`
single quote | ' | `\'`
double quote | " | `\"`
octal number (ooo) |  | `\`ooo
hex number (hh) |  | `\x`hh

The following are examples of valid string constants:

>     ""           // an empty string
>     "this a string:  ~!@#$%^()_+"

#### Scalar Numeric Constants

Scalar numeric constants are sequences of numeric characters that can be used in two ways:

- As values themselves
- As components of a vector, matrix, tensor, or list.

There are two kinds of scalar numeric constants:

- Integer
- Floating point

The following sections describe these constants.

##### Integer

Integers are the set of counting numbers, or their negatives (e.g., 0, 1, 2,...). By virtue of their 32-bit internal representation, integer values range from -231 to 231 - 1. They can be prefixed with a minus sign (`-`) to represent a negative number. Integers in Data Explorer can be represented in the following base systems:

Decimal | Decimal notation (base 10) is the most common notation for integers. Decimal numbers are constructed from sequences of numerals (0, 1, ..., 9).
Octal | When a sequence of numerals begins with the numeral zero (0) followed by a numeral from 0 to 7, Data Explorer treats it as an octal, or base-8, number. If a numeric sequence starts with a zero but contains either an 8 or 9, then these digits are identified as invalid octal digits. They are, however, correctly converted. For example, although the following octal numbers are both converted to the decimal number 17, the first produces an error message, but the second does not:
    019
    021
Hexadecimal | Hexadecimal, or base 16, numbers can be constructed from both the numerals (0 to 9) and the extended hex-digits (a to f, or A to F). To differentiate them from decimal and octal integers, hexadecimal numbers start with either the sequence `0x` or the sequence `0X` (the numeral zero followed by the letter X).

The following are examples of valid integers, all of which have the value 95 base 10:

      95
    0137
    0x5f

##### Floating Point

Floating-point numbers are used to represent the set of real numbers. These numbers encompass both rational and irrational numbers. By virtue of their 32-bit, IEEE single-precision internal representation, they lie in the range of ±3.4028 x 1038. The smallest step between values is ±1.1754 x 10-38. Like integers, floating-point numbers can be prefixed by a minus sign (`-`) to represent a negative number. Floating-point numbers can be expressed in two ways:

Standard representation | The standard representation of a floating-point number consists of a decimal number followed by a decimal point (`.`), followed by another decimal number. The first decimal number represents the whole part of the floating-point number. The second represents the fractional part. Either the first or the second of the numbers surrounding the decimal point can be omitted, but not both. If the first is omitted, then the number is purely fractional. If the second is omitted, then the number does not contain a fractional part. This second alternative is useful for representing integer values that lie outside of the range representable by the integer format.
Scientific notation | Scientific notation is an alternative means of representing floating-point numbers. A number in scientific notation has the form xey (or xEy). The number x can be either a standard floating-point number or a decimal integer. The number y must be a decimal integer. It can be prefixed by a minus sign. This scientific notation is simply shorthand for writing x×10y. The effect of the decimal value y is to specify the number of places the decimal point should be shifted to the right, or if y is negative, to the left.

The following are examples of valid floating-point numbers, all of which have the value 95.0:

    95.
    95.0
    95e0
    9.5E1
    950e-1
    9.50e+1

#### Vectors, Matrices, and Tensors

Vectors, matrices, and tensors are higher dimensional mathematical entities that are used for the representation of specific kinds of data.

##### Vectors

A vector is a quantity that has both magnitude and direction in n-dimensional space. It corresponds to a directed line segment whose length represents the magnitude of the vector and whose orientation corresponds to its direction.

Vectors are composed of a sequence of scalar values enclosed by square brackets `[ ]`. The scalar values can be separated by commas if desired, although this is not necessary. If the elements of a vector are not homogeneous, (e.g., if they are both integer and floating-point elements), then the integer elements are converted to floating point. The following are all valid vectors:

    [0.0 0.0 0.0]              // the origin of a 3-D space
    [0, 0, 1]                  // an axis in a 3-D coordinate system
    [1, 1.0  1, 1.0  1]        // a vector in a 5-D space

##### Matrices

Matrices are 2-dimensional collections of scalars. They are used to represent, among other things, the coefficients of a set of simultaneous equations or a transformation of a vector.

Matrices are constructed from a sequence of vectors enclosed by square brackets. Each of the vectors contained in a matrix must have the same length as all of the others. The following are all valid matrices:

    [[1 0 0 0][0 1 0 0][0 0 1 0][0 0 0 1]]          // a 4x4 identity matrix
    [[ 0.707 0.707 0.000]          // a 45-degree rotation
     [-0.707 0.707 0.000]          //     about the Z axis
     [ 0.000 0.000 1.000]]
    [[1 1 1 1][2 2 2 2]]           // a 2x4 matrix

##### Tensors

Tensors are a generalization of the concept of vectors. On one hand, the elements in a tensor have meanings that are independent of the coordinate system in which they are embedded. On the other hand, one can associate certain metrics to them that vary among coordinate systems.

In general, a rank n tensor can be formed by surrounding k rank n-1 tensors with square brackets. (Note that scalars, vectors, and matrices are rank 0, 1, and 2 tensors, respectively.) As with the matrices, all of the subtensors must have the same shape.

The following are valid tensors:

    [[[[[0xabcd]]]]]           // a 1x1x1x1x1 rank 5 tensor
    [[[1 0 0]                 // a 3x3x3 rank 3 tensor with
      [0 0 0]                 //        1's on the diagonal
      [0 0 0]]
     [[0 0 0]
      [0 1 0]
      [0 0 0]]
     [[0 0 0]
      [0 0 0]
      [0 0 1]]]

#### Lists

Unlike the vector, matrix, and tensor constructions that aggregate several lower dimensional data elements into a single higher one; the list construction collects several homogeneous elements together so that they can be handled as a single entity while still retaining their individuality.

Lists are constructed by enclosing a sequence of scalars, vectors, matrices, rank n tensors, or string constants in braces (`{ }`). The elements of a list can be separated by commas, although they need not be. In Data Explorer, a list is the same as an Array (see "Arrays").

The following are examples of valid lists:

    {1.0 2.0 3.0}             // 3 scalar values (for isovalues)
    {[0.0 0.0 0.0],           // 4 vector values for use as
     [1.0 0.0 0.0],           //     streamline seed points
     [2.0 0.0 0.0],
     [3.0 0.0 0.0]}

    {"a" "list" "of" "string"
    "constants"}

Lists of scalars can also be defined with a convenient shorthand notation that specifies the following:

- The list's starting value
- The list's ending value
- A stepping increment (optional).

If you do not specify a stepping increment, then the default is 1. If any of the values in the list constructor (including the stepping increment) are specified as floating point numbers, then the generated list contains floating-point numbers; otherwise, it contains integers. If the starting value is smaller than the ending value, the list elements are generated in increasing order; otherwise they are generated in decreasing order. Also, only the magnitude of the stepping increment is important, not the sign. A negative stepping increment produces the same results as a positive one.

The values included in the list are generated by continually adding the value of the stepping increment to the starting value until the resultant value passes the ending value. Each of the following produces the same list:

    {-1 1 3 5 7 9}
    {-1 .. 9 : 2}
    {-1 .. 9 : -2}
    {-1 .. 10 : 2}

Note: | Spaces are required around the .. operator.

Lists specified using this notation will be represented as a Regular Array of 1-vectors. See "Arrays" for a discussion of Array types.

[ OpenDX Home at IBM | OpenDX.org ]