Welcome to the Harris Geospatial product documentation center. Here you will find reference guides, help documents, and product libraries.


  >  Docs Center  >  Libraries  >  Markwardt  >  HELPFORM

HELPFORM

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
  $Id: helpform.pro,v 1.6 2009/01/04 09:18:18 craigm Exp $



© 2018 Harris Geospatial Solutions, Inc. |  Privacy Policy
My Account    |    Store    |    Contact Us