INPUTFORM Name
INPUTFORM
Author
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov Purpose
Generates expression string from an IDL value
Calling Sequence
STRING = INPUTFORM(VALUE, ERRMSG=ERRMSG, STATUS=STATUS, ...)
Description
The INPUTFORM function converts an IDL data value into its string
representation, suitable for execution at the IDL command line or
with EXECUTE(). This is similar to the "InForm" output
representation of Mathematica, which formats output so that it can
be entered again on the command line. INPUTFORM() is a
specialized form of STRING().
For example, the value DBLARR(2,2) has the default representation
'[[0D,0],[0D,0]]'
The formal goal of INPUTFORM is for the resulting textual
expression to be an exact representation of the original data.
Several other output options can be selected by using the /ZERO or
/ARRAY_NOTATION keywords.
Therefore, given the original value VARIABLE, then after executing
R = EXECUTE( 'variable1 = '+INPUTFORM(variable) )
The value, type, and dimension of VARIABLE1 and VARIABLE will be
the same.
Such behavior might useful in several circumstances:
* for printing values meant to be "pasted" back into the
command line by the user;
* for constructing command arguments to be EXECUTE()'d;
* for saving values in ASCII format for later execution.
OUTPUT OPTIONS:
The output of INPUTFORM can be controlled in the following ways.
See the EXAMPLES section for examples of each kind of behavior.
* By default, the output will replicate the exact values of the
input;
* If the /ZERO keyword parameter is set, then the output will
match the type and structure of the input, but all values
will be zero or blank, including IDL strings and structures.
This is useful if one wants to make a "blank template" from
an existing IDL data structure.
* If the /ARRAY_NOTATION keyword parameter is set, then any
input arrays are converted to INTARR(), DBLARR(), STRARR().
Scalars appear as in the input. Obviously the contents of
arrays will be zero/blank in this case. The combination of
/ZERO and /ARRAY_NOTATION produces a nice short-hand
blank template.
LIMITATIONS:
It should be noted that the IDL parser is not perfect.
While IDL has many data types, not all expressions are
representable as a textual string. Pointers and objects can be
represented. Examples of the parser limitation include,
* array expressions can have no more than 90 elements;
* bracketed array notation cannot be nested too deeply;
* anonymous structure arrays have no textual representation;
Given these limitations, the user of this routine must be prepared
for failure and have contingency plans. Error messages and status
indicators are provided to facilitate this. INPUTFORM() does not
call MESSAGE, so it should never intentionally crash.
Also, consider that the textual representation can never really be
suitable for very large arrays. The internal algorithm is thus
not optimized for speed as heavily numeric routines might be, and
instead tries to make the output slightly more readable.
Inputs
VALUE - the IDL value to be converted. Any value which has a
legal textual representation is permitted.
Keywords
ARRAY_NOTATION - if set, then any arrays in the input will be
replaced by their xxxARR() equivalent.
STATUS - upon return, a status indicator. A value of zero
indicates failure; one indicates success.
ERRMSG - upon return, a string message indicating the reason for a
failure, if any. The empty string ('') indicates
success.
MAX_DIMENSIONS - maximum number of array dimensions permitted in
VALUE. The conversion fails if the maximum is
exceeded.
Default: any number of dimensions is permitted.
NOTE: IDL does not permit deep nesting, for
dimensions greater than three.
MAX_ELEMENTS - maximum number of elements permitted in VALUE. The
conversion fails if the maximum is exceeded.
Default: any number of elements is permitted.
NOTE: the conversion may still fail if any array
dimension exceeds 90.
MAX_LEN - approximate maximum length of returned string. If large
string expressions exceed this size as they are being
composed internally, they will be terminated by a '...'
ellipsis and returned. This value is to be used as a
guideline by INPUTFORM(); the precise limit may not be
adhered to.
Default: 16384L
MAX_TAGS - maximum number of structure tags permitted in VALUE.
The conversion fails if the maximum is exceeded.
Default: any number of tags is permitted.
N_FLOAT - for floating point numerical values, N_FLOAT gives the
number of decimal digits to print. By definition,
setting this keyword will involve the loss of some
precision compared to the original value.
Default: full precision is printed.
ZERO - if set, then the output command will have zero values for
all fields, regardless of the contents of the input data.
Returns
The resulting converted string, if successful. Upon failure,
STATUS is set to zero and the empty string ('') is returned.
Example
Convert a double array to text using the default output option,
IDL> x = [[1,2],[3,4]]
IDL> print, inputform(x)
---> [[1,2],[3,4]]
The same input, but using the /ZERO and /ARRAY_NOTATION options,
IDL> print, inputform(x, /zero)
---> [[0,0],[0,0]]
IDL> print, inputform(x, /array_notation)
---> INTARR(2L,2L)
Convert a structure,
IDL> y = create_struct('s1',5,'s2','strvalue','s3',[1,2,3])
IDL> print, inputform(y)
---> [{S1:5,S2:'strvalue',S3:[1,2,3]}]
Also with /ZERO and /ARRAY_NOTATION options,
IDL> print, inputform(y, /zero)
---> {S1:0,S2:'',S3:[0,0,0]}
IDL> print, inputform(y, /array_notation)
---> {S1:5,S2:'strvalue',S3:INTARR(3L)}
(Note that in the final case with /ARRAY_NOTATION alone, S3 is
replaced by INTARR(), but that the scalars are left unchanged.)
IDL> print, inputform(y, /zero, /array_notation)
---> {S1:0,S2:'',S3:INTARR(3L)}
(With /ZERO and /ARRAY_NOTATION combined, then all fields are
zero or blank).
See Also
STRING, PRINT, HELP, HELPFORM
Modification History
Written, CM, 10 Apr 2000
Added HELPFORM to SEE ALSO, CM, 04 Jul 2000
Corrected case of scalar float value, CM, 13 Jul 2000
Put a space after float types like 1E or 1D to ease parsing, CM,
18 Jul 2000
Add ability to print INPUTFORM of pointers, CM, 09 Dec 2002
Add ability to print INPUTFORM of object pointers, CM, 01 Oct 2003
Bug fix: actually obey MAX_ELEMENTS (was being ignored), CM, 22
Oct 2006
Change to square-bracket array syntax, CM, 27 Feb 2007
Add the ZERO and ARRAY_NOTATION keywords; handle NAN and INFINITY
values properly, CM, 02 Jun 2009
Add N_FLOAT keyword, CM, 13 Nov 2010