HELPFORM Name
HELPFORM
Author
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov Purpose
Generate a descriptive string in IDL HELP format
Calling Sequence
STRINGS = HELPFORM(NAME, VALUE, [/SHORTFORM,] [/SINGLE,] [WIDTH=width])
Description
The HELPFORM function converts an IDL data value into a
representation very similar to the format produced by the built-in
command HELP. Programmers can thus present data types and values
to users in a format they are familiar with.
For example, if the variable A is defined in the following manner,
and HELP is called, then the following transcript will result:
IDL> a = [1,2]
IDL> help, a
A INT = Array[2]
The same result can be achieved with the HELPFORM function:
IDL> print, helpform('A', a)
A INT = Array[2]
The benefit is that the output of HELPFORM is a string that can be
outputted or reformatted. This capability is not available in all
versions of IDL.
HELPFORM actually produces *two* forms of output. The above
output is considered the "long" form, as it appears in the IDL
HELP command, and is the default. A "short" form can also be
produced, and is very similar to the information that appears in
certain terse IDL error messages. It is activated by setting the
SHORTFORM keyword.
If the variable name is too long, the HELPFORM may be forced to be
two lines long to have consistent formatting. In that case a
two-element string is returned. If a single line is desired, use
the SINGLE keyword, but this comes at the expense of consistent
output formatting. Inputs
NAME - A scalar string containing the name of the IDL variable.
An empty string is permitted. The name is ignored if the
SHORTFORM keyword is set.
VALUE - Any IDL value to be examined. VALUE is optional if the
SIZE keyword is passed and uniquely describes the data.
VALUE should be passed for scalars and structures, since
the help form for these values requires additional
information beyond the SIZE. Keywords
SIZE - the IDL SIZE descriptor for the value to be printed.
Default: information is taken from VALUE.
SINGLE - if set, then output which would normally
appear on two lines for consistent formatting, appears on
one single line instead.
FULL_STRUCT - if set, then a detailed output is printed for
structures, similar to HELP, VALUE, /STRUCTURE.
RECURSIVE_STRUCT - if both this keyword and FULL_STRUCT are set,
and if VALUE itself has sub-structures, then
print the full contents of those sub-structures
as well. The contents will be slightly indented.
SHORTFORM - set this keyword for a shorter output format that can
be used in error messages.
WIDTH - the width of the terminal in characters (used for
formatting).
Default: 80
Returns
An array of strings containing the HELPFORM output, which may have
more than one element depending on the length of NAME, SHORTFORM
and SINGLE. The helpforms of pointer- and object-typed values
does not include the sequence number, but are otherwise correct.
Example
IDL> print, helpform('A', size=[1,2,1,2])
A BYTE = Array[2]
;; Do not pass VALUE and instead use SIZE to specify the type
IDL> print, helpform('A', size=[1,2,1,2], /shortform)
BYTE (Array[2])
;; Compare to the short form, which is meant to be placed in
;; error messages
IDL> print, helpform('fjsldkfjsldfkjslkdfjslkdfjslkdfjsldkfjk',a)
fjsldkfjsldfkjslkdfjslkdfjslkdfjsldkfjk
INT = Array[2]
IDL> print, helpform('fjsldkfjsldfkjslkdfjslkdfjslkdfjsldkfjk',a,/single)
fjsldkfjsldfkjslkdfjslkdfjslkdfjsldkfjk INT = Array[2]
;; Compare the long and short forms
See Also
INPUTFORM, HELP
Modification History
Written, CM, 13 May 2000
Documented, 04 Jul 2000
Improved output for objects, CM, 11 Jan 2001
Added support for full structure output, CM 08 Feb 2001
Added forward_function declaration for safety, CM 08 Apr 2001
Print more info about POINTER type, CM 08 Apr 2001
Add the RECURSIVE_STRUCT keyword, CM 04 Jan 2009