The following table lists the syntax elements used in the IDL help system for documentation on routines, functions, and objects:

Element

Description

[ ] (Square brackets)

Indicates that the contents are optional. Do not include the brackets in your call.

Brackets are also used when creating and accessing arrays.

[ ] (Italicized square brackets)

Indicates that the square brackets are part of the statement (used to define an array).

Argument

Arguments are shown in italics, and must be specified in the order listed.

KEYWORD

Keywords are all caps, and can be specified in any order. For functions, all arguments and keywords must be contained within parentheses.

/KEYWORD

Indicates a boolean keyword.

Italics

Indicates arguments, expressions, or statements for which you must provide values.

{ } (Braces)

  • Indicates that you must choose one of the values they contain
  • Encloses a list of possible values, separated by vertical lines ( | )
  • Encloses useful information about a keyword
  • Defines an IDL structure (this is the only case in which the braces are included in the call).

| (Vertical lines)

Separates multiple values or keywords.

[, Value1, ... , Valuen]

Indicates that any number of values can be specified.

[, Value1, ... , Value8]

Indicates the maximum number of values that can be specified.

Elements of Syntax

Square Brackets ( [ ] )

  • Content between square brackets is optional. Pay close attention to the grouping of square brackets. Consider the following examples:

ROUTINE_NAME, Value1 [, Value2] [, Value3]: You must include Value1. You do not have to include Value2 or Value3. Value2 and Value3 can be specified independently.

ROUTINE_NAME, Value1 [, Value2, Value3]: You must include Value1. You do not have to include Value2 or Value3, but you must include both Value2 and Value3, or neither.

ROUTINE_NAME [, Value1 [, Value2]]: You can specify Value1 without specifying Value2, but if you specify Value2, you must also specify Value1.

  • Do not include square brackets in your statement unless the brackets are italicized. Consider the following syntax:

Result = KRIG2D( Z [, X, Y] [, BOUNDS=[xmin, ymin, xmax, ymax]] )

An example of a valid statement is:

R = KRIG2D( Z, X, Y, BOUNDS=[0,0,1,1] )

  • Note that when [, Value1, ... , Valuen] is listed, you can specify any number of arguments. When an explicit number is listed, as in [, Value1, ... , Value8], you can specify only as many arguments as are listed.

Braces ( { } )

  • For certain keywords, a list of the possible values is provided. This list is enclosed in braces, and the choices are separated by a vertical line ( | ). Do not include the braces in your statement. For example, consider the following syntax:

READ_JPEG [, TRUE={1 | 2 | 3 }]

In this example, you must choose either 1, 2, or 3. An example of a valid statement is:

READ_JPEG, TRUE=1

  • Braces are used to enclose the allowable range for a keyword value. Unless otherwise noted, ranges provided are inclusive. Consider the following syntax:

Result = CVTTOBM( Array [, THRESHOLD=value{0 to 255}] )

An example of a valid statement is:

Result = CVTTOBM( A, THRESHOLD=150 )

  • Braces are also used to provide useful information about a keyword. For example:

[, LABEL=n{label every nth gridline}]

Do not include the braces or their content in your statement.

  • Certain keywords are prefaced by X, Y, or Z. Braces are used for these keywords to indicate that you must choose one of the values it contains. For example, [{X | Y}RANGE=array] indicates that you can specify either XRANGE=array or YRANGE=array.
  • Note that in IDL, braces are used to define structures. When defining a structure, you do want to include the braces in your statement.

Italics

  • Italicized words are arguments, expressions, or statements for which you must provide values. The value you provide can be a numerical value, such as 10, an expression, such as DIST(100), or a named variable. For keywords that expect a string value, the syntax is listed as KEYWORD=string. The value you provide can be a string, such as 'Hello' (enclosed in single quotation marks), or a variable that holds a string value.
  • The italicized values that must be provided for keywords are listed in the most helpful terms possible. For example, [, XSIZE=pixels] indicates that the XSIZE keyword expects a value in pixels, while [, ORIENTATION=ccw_degrees_from_horiz] indicates that you must provide a value in degrees, measured counter-clockwise from horizontal.

Procedures

IDL procedures use the following general syntax:

PROCEDURE_NAME, Argument [, Optional_Argument]

where PROCEDURE_NAME is the name of the procedure, Argument is a required parameter, and Optional_Argument is an optional parameter to the procedure.

Functions

IDL functions use the following general syntax:

Result = FUNCTION_NAME( Argument [, Optional_Argument] )

where Result is the returned value of the function, FUNCTION_NAME is the name of the function, Argument is a required parameter, and Optional_Argument is an optional parameter. Note that all arguments and keyword arguments to functions should be supplied within the parentheses that follow the function’s name.

Functions do not always have to be used in assignment statements (i.e., A=SIN(10.2)), they can be used just like any other IDL expression. For example, you could print the result of SIN(10.2) by entering the command:

PRINT, SIN(10.2)

Arguments

The “Arguments” section describes each valid argument to the routine. Note that these arguments are positional parameters that must be supplied in the order indicated by the routine’s syntax.

Named Variables

Often, arguments that contain values upon return from the function or procedure (“output arguments”) are described as accepting “named variables”. A named variable is a valid IDL variable name. This variable does not need to be defined before being used as an output argument. Note, however that when an argument calls for a named variable, only a named variable can be used—sending an expression causes an error.

Keywords

The “Keywords” section describes each valid keyword argument to the routine. Keyword arguments are formal parameters that can be supplied in any order.

Keyword arguments are supplied to IDL routines by including the keyword name followed by an equal sign (“=”) and the value to which the keyword should be set. The value can be a value, an expression, or a named variable (a named variable is a valid IDL variable name).

Note: If you set a keyword equal to an undefined named variable, IDL will quietly ignore the value.

For example, to produce a plot with diamond-shaped plotting symbols, the PSYM keyword should be set to 4 as follows:

PLOT, FINDGEN(10), PSYM=4

Note the following when specifying keywords:

  • Certain keywords are boolean, meaning they can only be set to 0 or 1. These keywords are switches used to turn an option on and off. Usually, setting such keywords equal to 1 causes the option to be turned on. Explicitly setting the keyword to 0 (or not including the keyword) turns the option off. In the syntax listings in this reference, all keywords that are preceded by a slash can be set by prefacing them by the slash. For example, SURFACE, DIST(10), /SKIRT is a shortcut for SURFACE, DIST(10), SKIRT=1. To turn the option back off, you must set the keyword equal to 0, as in SURFACE, DIST(10), SKIRT=0.

In rare cases, a keyword’s default value is 1. In these cases, the syntax is listed as KEYWORD=0, as in SLIDE_IMAGE [, Image] [, CONGRID=0]. In this example, CONGRID is set to 1 by default. If you specify CONGRID=0, you can turn it back on by specifying either /CONGRID or CONGRID=1.

  • Some keywords obtain values that can be used upon return from the function or procedure. These keywords are listed as KEYWORD=variable. Any valid variable name can be used for these keywords, and the variable does not need to be defined first. Note, however, that when a keyword calls for a named variable, only a named variable can be used—sending an expression causes an error.

For example, the WIDGET_CONTROL procedure can return the user values of widgets in a named variable using the GET_UVALUE keyword. To return the user value for a widget ID (contained in the variable mywidget) in the variable userval, you would use the command:

  WIDGET_CONTROL, mywidget, GET_UVALUE = userval

Upon return from the procedure, userval contains the user value. Note that userval did not have to be defined before the call to WIDGET_CONTROL.

  • Some routines have keywords that are mutually exclusive, meaning only one of the keywords can be present in a given statement. These keywords are grouped together, and separated by a vertical line. For example, consider the following syntax:

PLOT, [X,] Y [, /DATA | , /DEVICE | , /NORMAL]

In this example, you can choose either DATA, DEVICE, or NORMAL, but not more than one. An example of a valid statement is:

PLOT, SIN(A), /DEVICE

  • Keywords can be abbreviated to their shortest unique length. For example, the XSTYLE keyword can be abbreviated to XST because there are no other keywords in IDL that begin with XST. You cannot shorten XSTYLE to XS, however, because there are other keywords that begin with XS, such as XSIZE.

Properties

The “Properties” section describes each valid property for the routine. Properties are formal parameters that you can supply in any order during the routine's call. In some instances, you can also change the values of properties after you have initially called a routine.

  • Properties are assigned by stating the property name, followed by the "=" sign and finally the value you are assigning.
  • Some properties are Boolean, meaning they can only be set to 0 or 1. Boolean properties can be set during a routine's initial call by explicitly assigning a value or by the alternate "/" syntax. In the following example, both versions of the HIDE syntax have the same effect on the graphic:

result = PLOT(X, Y, /HIDE)

result = PLOT(X, Y, HIDE=1)

Usually, setting such properties equal to 1 causes the option to be turned on. Explicitly setting the property to 0 (or not including the property) turns the option off. In the syntax listings in this reference, all properties that are preceded by a slash can be set by prefacing them by the slash. For example, PLOT(myData, /HIDE) is a shortcut for PLOT(myData, HIDE=1). To turn the option back off, you must set the keyword equal to 0, as in PLOT(myData, HIDE=0) or change the property using the dot syntax.

For more detailed information on setting and changing Properties, see: Modifying Object Properties and Changing Graphics Properties.