NCL syntax and semantics

NCL can be thought of as a complete programming language. As a programming language, it has a grammar and syntax rules for constructing statements and commands. This module describes the syntax, semantics, and conventions used for constructing NCL statements, identifiers, comments, array subscripts, data, metadata, and strings.

Symbol set

Any printing ACSII character is a legal character in NCL:

uppercase letters: A B C... Z
lowercase letters: a b c... z
digits: 0 1 2... 9
special characters: + = _ - ( ) * & % # ! | < > . , ; : " / { } ~ \ [ ] ^ @
Also, the three non-printing characters space, newline, and tab are legal NCL characters.


White space is used to separate tokens. The valid NCL separators are space and tab.


Identifiers are used to give unique names to various syntactic objects (variables, function names, and so forth) in a program. NCL identifiers must begin with an uppercase or lowercase letter or the underscore '_' character. The rest of the identifier name can contain any mix of these characters and any digits. The maximum identifier name length is 256 characters.

Examples of valid identifiers:

Examples of invalid identifiers:

a variable name with spaces instead of underscores


The semicolon ';' character is used to produce comments in an NCL statement. Comments must begin with a semicolon, and anything after the semicolon and before the next newline character is ignored by the NCL interpreter. Comments may appear alone in an NCL statement or after an NCL command. Comments cannot appear on the same line before a statement because everything after the comment character is ignored.

For example, the following are valid NCL comments:

; A comment can appear alone on a line. Everything after
; the semicolon is ignored by the interpreter.
temperature = 77.6  ; Comments can also appear with a command.


NCL character strings can be up to 256 characters long, and they may contain any of the characters listed above in the NCL symbol set.

Strings must be enclosed in double quotes, '"'. For example, the following statements create string variables and assign character strings to them.

string_var_1 = "This is the contents of the string variable"
string_var_2 = "Special chars (@#$%^&*_+~`;') are valid"
The maximum length of a string is 256 characters.


NCL keywords are reserved words that have specific meaning to the NCL interpreter. Consequently, keywords cannot be used in other contexts. For a complete listing of the NCL keywords, see the NCL keyword reference page.


Operators are the special characters, such as the `+',`*', `-', and `=' characters, that perform various functions like arithmetic and assignment. Operators are described in detail in the NCL expressions and operators module.

Arrays and subscripts

NCL arrays and subscripts use several special symbols for specifying arrays and subsets of array data. An array expression combines either scalar values or other arrays into a single array result. An array expression is made up of expressions separated by commas (','), enclosed in '(/' and '/)' characters. Arrays can be made up of any of the basic types as well as graphic objects. Arrays of files are not supported. To specify the contents of an entire array, no special symbols are needed. For example, if the array is named temp, then using "temp" with no subscripts specifies the entire contents of the array.

Array subscripts are enclosed in parentheses, '(' and ')'. For example, if temp is a one-dimensional array, then the first element can be specified as temp(0) when using standard subscripting. If temp is a three-dimensional array, then the subscripts are separated by commas. So, the first element in a three-dimensional array is specified as temp(0,0,0) using standard subscripting.

Ranges and strides are specified using the colon ':' character. For example, the first through tenth elements in a one-dimensional array are specified as temp(0:9) using standard subscripting. Similarly, this syntax is expanded for variables with multiple dimensions by separating the dimension ranges with commas, as in temp(0:9, 3:7, 2:20). Strides, for thinning data, are appended after the range using another colon. For example, a stride of 3 in a one-dimensional array is specified as temp(0:9:3). Again, this can be expanded to a multi-dimensional array by separating the subscripts with commas, as in temp(0:9:3, 4:7:2, 7:20). This last example uses a stride of 3 in the first dimension, a stride of 2 in the second dimension, and no stride in the third dimension.

Curly braces, '{' and '}', are used to surround subscripts when using coordinate subscripting. For example, if the coordinates for the temp array range from -200 to 600, then curly braces can be used to select individual elements and ranges. The following NCL statements demonstrate how braces are used.

; Select the element that corresponds to coordinate index -150.
; Assume temp is a one-dimensional array.
scalarvar = temp({-150}) 

; Select a range of data from the beginning to the end.
; Assume temp is a one-dimensional array.
vectorvar = temp({-200:600})

; Select a range of data from a three-dimensional variable
; Assume temp is a three-dimensional array.
var_3D = temp({-200:50}, {45}, {30:100})
The vertical bar '|' character is used to specify named subscripts. For example, if the coordinate name of the first dimension of the temp variable is called "time", then the vertical bar is used as follows.

; Select the first element using named subscripting.
scalarvar = temp((time|0))

; Select ranges using named subscripting. Assume temp is
; a two-dimensional array with dimensions time by lat.

var_2D = temp ((time|0:5), (lat|4:9))

; Select ranges using name subscripting but use names to
; reorder the dimensions of two-dimensional array temp to
; be lat by time

var_2D2 = temp((lat | 4:9),(time | 0:5))

Array data

An array expression is made up of expressions separated by commas ',' enclosed in '(/' and '/)' character pairs. Each element separated by commas must have the same dimensionality as the rest of the elements in the array expression.

For example, the following are all NCL statements containing valid array expressions.

; Create a one-dimensional array of 5 elements
var1 =  (/ 1, 2, 3, 4, 5 /)

; Create a two-dimensional array of 10 elements
var2 = (/(/ 1, 2, 3, 4, 5 /),(/ 1, 2, 3, 4, 5 /)/) 

; Create a two-dimensional array from variable references

var3 = (/var1,var2(0,:),var2(1,:)/)


Metadata are the named attributes, dimensions, and coordinates that describe data. Several special symbols are used to reference metadata, including the '!', '&', and the '@' symbols.


Variable dimension names are referenced using the '!' symbol. If a variable called temp has three dimensions, then the dimension names are referenced as temp!0, temp!1, and temp!2. Note that the dimension number uses the convention used in C and always starts at 0.

For example, the following NCL statements assign the names "time", "lat", and "lon" to each dimension of the temp variable.

temp!0 = "time"
temp!1 = "lat"
temp!2 = "lon"


Coordinate variables are referenced using the '&' character. If a variable called temp has three dimensions named time, lat, and lon, respectively, then the coordinate variables along each of its dimensions are referenced as temp&time, temp&lat, and temp&lon.

For example, the following NCL statements assign coordinate vectors (defined elsewhere) to each dimension of the variable called temp.

temp&time = vector_of_time_coordinates
temp&lat = vector_of_lat_coordinates
temp&lon = vector_of_lon_coordinates


NCL attributes are the metadata that describe a variable or data file and its contents. File and variable attributes are referenced using the '@' symbol. If temp is a variable name with attributes called "units" and "max", then the NCL syntax for these references is temp@units and temp@max. File variables can also have attributes. Common file attributes are "title" and "date". The NCL syntax for these references is filevar@title and filevar@date, where filevar is the file variable name.

For example, the following NCL statements demonstrate the assignment of file and variable attributes.

; File attributes called "title" and "date"
filevar@title = "South American Climate Data"
filevar@date = "November 23, 1994"

; Variable attributes called "units" and "max"
temp@units = "Degrees C"

File variable references

The '->' symbol is used to reference variables stored in an external file. For example, if an external file is read into NCL, then a file variable exists that points to descriptive information in a file record. If filevar is the name of the file variable, then references to the external variables and their attributes are made in the following manner.

; Print the data from external variable called precip
print (filevar->precip)

; Print the longname of the external precip variable
print (filevar->precip@longname)

User Guide Control Panel

NG4.1 Home, Index, Examples, Glossary, Feedback, UG Contents, UG WhereAmI?

$Revision: 1.7 $ $Date: 1998/06/15 22:08:57 $