;----------------------------------------------------------------------------
; SCCS/s.all_vars_to_struct.pro 1.9 01/11/30 15:38:56
;+
; Name:
;   ALL_VARS_TO_STRUCT
;
; Purpose:
;   Creates a structure containing all the variables that are defined
;   in the calling level (i.e. the level one before this function) at 
;   the time ALL_VARS_TO_STRUCT is called.  This function is unable to
;   put calling-level variables defined by ASSOC into the output structure.
;   As their presence will cause an error, if ASSOC defined variables
;   exist, they need to noted in the Exclude_Var keyword for this function
;   to work.
;
; Calling Sequence:
;   out_struct = ALL_VARS_TO_STRUCT()
;
; File I/O:
;   None.
;
; Entry and Exit States:
;   N/A.
;
; Input Parameters:
;   None.
;
; Output Parameter:
;   out_struct    Anon. structure containing all variables that are defined 
;                 in the calling level at the time ALL_VARS_TO_STRUCT is 
;                 called.  Tag names of the members of the structure are 
;                 the names of the calling level variables.  Note system
;                 variables are not included in the structure.  If there
;                 are no variables defined, out_struct is set to a scalar
;                 equal to -1L.  Created.
;
; Keywords (optional unless otherwise noted):
;   EXCLUDE_VAR   String vector who's elements are the names of variables
;                 that you are manually telling this function are not
;                 to be placed into out_struct.  This generally does not 
;                 need to be used, because the function automatically does 
;                 not put in undefined variables.  The exception is 
;                 variables defined by ASSOC.  In those cases, ROUTINE_NAMES 
;                 will consider it "defined", but will not return the value 
;                 of the variable, and thus, the function will not execute 
;                 properly.  This keyword can also be used if you don't 
;                 want to pass a particularly large variable.  String 
;                 vector is unchanged by function.
;
; Revision History:
; - 3 May 2001:  Orig. ver. by Johnny Lin, CIRES/Univ. of Colo.  Email:
;   air_jlin@yahoo.com.  Passed passably reasonable tests.
; - 18 May 2001:  Exclude_Var keyword added.  Passed passably reasonable 
;   tests.
;
; Notes:
; - Written for IDL 5.2.1.
; - No procedures called with _Extra keyword invoked.
; - No user-written procedures called.  However, this function depends upon
;   the built-in function ROUTINE_NAMES, which is undocumented by RSI, and 
;   RSI considers obsolete.  See Craig Markwardt's IDL page for unofficial 
;   documentation:  http://cow.physics.wisc.edu/~craigm/idl/introspect.html
; - No common blocks are used in this program.
;-
; Copyright (c) 2001 Johnny Lin.  For licensing and contact information, 
; see http://www.johnny-lin.com/lib.html.  
;----------------------------------------------------------------------------

FUNCTION ALL_VARS_TO_STRUCT  $
                           , EXCLUDE_VAR = in_exclude_var  $
                           , _EXTRA      = extra



; --> Error checking:

ON_ERROR, 0

if (N_ELEMENTS(in_exclude_var) gt 0) then begin   ;- Protect keyword input
   exclude_var = STRUPCASE(in_exclude_var)
endif



; --> Information re calling levels and variable names:

levnum = ROUTINE_NAMES(/Level)             ;- Level no. inside this function
lev_m1 = levnum-1L                         ;- Level no. one level up
vars   = ROUTINE_NAMES(Variables=lev_m1)   ;- All var. names (string array),
                                           ;  defined and undefined



; --> Create structure of variables (only defined ones, and ones that
;     are not specified in keyword Exclude_Var):

for ivar=0L,N_ELEMENTS(vars)-1L do begin

    if (N_ELEMENTS(ROUTINE_NAMES(vars[ivar], Fetch=lev_m1)) gt 0) then begin

       tmp = WHERE(exclude_var eq vars[ivar], count)           ;+ ignore some
       if (count eq 0) then begin                              ;  variables
          value = ROUTINE_NAMES(vars[ivar], Fetch=lev_m1)

          if (N_ELEMENTS(out_struct) eq 0) then  $             ;+ fill output
             out_struct = CREATE_STRUCT(vars[ivar], value)  $  ;  structure
          else  $
             out_struct = CREATE_STRUCT(out_struct, vars[ivar], value)
       endif

    endif

endfor



; --> Output structure:

if (N_ELEMENTS(out_struct) eq 0) then out_struct = -1L

RETURN, out_struct



END         ; ===== end of function =====

; ========== end file ==========