>  Docs Center  >  Libraries  >  Markwardt  >  HELPFORM






  Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770


  Generate a descriptive string in IDL HELP format

Calling Sequence



  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.


  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.


  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
          Default: 80


  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.


    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)
                      INT = Array[2]
    IDL> print, helpform('fjsldkfjsldfkjslkdfjslkdfjslkdfjsldkfjk',a,/single)
    fjsldkfjsldfkjslkdfjslkdfjslkdfjsldkfjk INT = Array[2]
    ;; Compare the long and short forms

See Also


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

© 2022 Harris Geospatial Solutions, Inc. |  Legal
My Account    |    Store    |    Contact Us