idlastro / Miscellaneous (Non-Astronomy) Procedures: FORPRINT

[Source code]

NAME
FORPRINT
PURPOSE
Print a set of vectors by looping over each index value.
EXPLANATION
If W and F are equal length vectors, then the statement
        IDL> forprint, w, f   
is equivalent to 
        IDL> for i = 0L, N_elements(w)-1 do print,w[i],f[i]    
CALLING SEQUENCE
forprint, v1,[ v2, v3, v4,....v18, FORMAT = , TEXTOUT = ,STARTLINE =,
                           SUBSET=, NUMLINE =, /SILENT, COMMENT= ] 
INPUTS
V1,V2,...V18 - Arbitrary IDL vectors.  If the vectors are not of
        equal length then the number of rows printed will be equal
        to the length of the smallest vector.   Up to 18 vectors
        can be supplied.
OPTIONAL KEYWORD INPUTS
TEXTOUT - Controls print output device, defaults to !TEXTOUT
        textout=1       TERMINAL using /more option if available
        textout=2       TERMINAL without /more option
        textout=3       file 'forprint.prt'
        textout=4       file 'laser.tmp' 
        textout=5      user must open file
        textout =      filename (default extension of .prt)
        textout=7       Append to .prt file if it exists
COMMENT - String scalar or vector to write to the first line of output 
         file if  TEXTOUT > 2.    By default, FORPRINT will write a time
         stamp on the first line.   Use /NOCOMMENT if you don't want 
         FORPRINT to write anything in the output file.    If COMMENT
         is a vector then one line will be written for each element.
FORMAT - Scalar format string as in the PRINT procedure.  The use
        of outer parenthesis is optional.   Ex. - format="(F10.3,I7)"
        This program will automatically remove a leading "$" from
        incoming format statements. Ex. - "$(I4)" would become "(I4)".
        If omitted, then IDL default formats are used.
/NOCOMMENT  - Set this keyword if you don't want any comment line
        line written as the first line in a harcopy output file.
/SILENT - Normally, with a hardcopy output (TEXTOUT > 2), FORPRINT will
         print an informational message.    If the SILENT keyword
        is set and non-zero, then this message is suppressed.
SUBSET - Index vector specifying elements to print.   No error checking
        is done to make sure the indicies are valid.  The statement
       IDL> forprint,x,y,z,subset=s
                is equivalent to 
       IDL> for i=0,n-1 do print, x[s[i]], y[s[i]], z[s[i]]
STARTLINE - Integer scalar specifying the first line in the arrays
        to print.   Default is STARTLINE = 1, i.e. start at the
        beginning of the arrays.    (If a SUBSET keyword is supplied
        then STARTLINE refers to first element in the subscript vector.)
STDOUT - If set, the force standard output unit (=-1) if not writing 
        to a file.   This allows the FORPINT output to be captured
        in a journal file.    Only needed for non-GUI terminals 
WIDTH - Line width for wrapping, passed onto OPENW when using hardcopy.
OUTPUTS
None
SYSTEM VARIABLES
If keyword TEXTOUT is not used, the default is the nonstandard 
keyword !TEXTOUT.    If you want to use FORPRINT to write more than 
once to the same file then set TEXTOUT=5, and open and close the 
file yourself (see documentation of TEXTOPEN for more info).
The non-standard system variables !TEXTOUT and !TEXTUNIT are 
automatically added if not present to start with.
EXAMPLE
Suppose W,F, and E are the wavelength, flux, and epsilon vectors for
a spectrum.   Print these values to a file 'output.dat' in a nice 
format.
IDL> fmt = '(F10.3,1PE12.2,I7)'
IDL> forprint, F = fmt, w, f, e, TEXT = 'output.dat'
RESTRICTIONS
Uses the EXECUTE() function and so is not compatible with the IDL
virtual machine.
PROCEDURES CALLED
TEXTOPEN, TEXTCLOSE
REVISION HISTORY
Written    W. Landsman             April, 1989
Keywords textout and format added, J. Isensee, July, 1990
Made use of parenthesis in FORMAT optional  W. Landsman  May 1992
Added STARTLINE keyword W. Landsman    November 1992
Set up so can handle 18 input vectors. J. Isensee, HSTX Corp. July 1993
Handle string value of TEXTOUT   W. Landsman, HSTX September 1993
Added NUMLINE keyword            W. Landsman, HSTX February 1996
Added SILENT keyword             W. Landsman, RSTX, April 1998
Much faster printing to a file   W. Landsman, RITSS, August, 2001
Use SIZE(/TNAME) instead of DATATYPE() W. Landsman SSAI October 2001
Fix skipping of first line bug introduced Aug 2001  W. Landsman Nov2001
Added /NOCOMMENT keyword, the SILENT keyword now controls only 
the display of informational messages.  W. Landsman June 2002
Skip PRINTF if IDL in demo mode  W. Landsman  October 2004
Assume since V5.4 use BREAK instead of GOTO W. Landsman April 2006
Add SUBSET keyword, warning if different size vectors passed. 
                              P.Broos,W.Landsman. Aug 2006
Change keyword_set() to N_elements W. Landsman  Oct 2006
Added /STDOUT keyword  W. Landsman Oct 2006
Fix error message for undefined variable W. Landsman  April 2007
Added WIDTH keyword    J. Bailin  Nov 2010
Allow multiple (vector) comment lines  W. Landsman April 2011
Define !TEXTOUT and !TEXTUNIT if needed. W. Landsman October 2012
eturn to caller
ormat flag
Remove "$" sign from format string and append parentheses if not 
already present
ormat present
em. '$' from format if present
et number of elements in smallest array
Use default output dev.
ake numeric
se default formats
id user press 'Q' key?
ser specified format
lose unit opened by TEXTOPEN