;+
;
; @file_comments
; Allows to read an array or a structure corresponding to a field.
; If we have in input:
;   - an array, litchamp send back the array.
;   - a structure, litchamp send back the first element of the structure
;   which must be the field in an array.
; litchamp profit of this to look other elements of the structure and
; update if needed global variables which refer to the field:
; vargrid, varname, varunit, vardate, varexp , valmask et time
;
; @categories
; Graphics
;
; @param STRUCT {in}{required}{type=array or struct}{type=array or structure}
;  If STRUCT is a structure, it must follow following rules:
;        -the first element is the array containing the field.
;        -other elements are strings containing informations on the field except
;        for the one about the date. This one can be either a string to designate
;        a particular date (ex: 'August 1999') or a vector of Julian days (of IDL)
;        corresponding  to the calendar to be associated with the field if it is a
;        temporal series.
;        -the order of elements (except the first) has not any importance.
;        -the other elements (except the first) are optional.
;        -they are recognized by the first letter of their names:
;             g  to update vargrid,
;             u  to update varunit,
;             e  to update varexp,
;             d  to update vardate,
;             n  to update varname,
;             m  to update valmask
;
; @keyword GRID
; We activate this keyword if we want litchamp to send back the variable
; associated with the element of the structure starting by 'g' if it exist
; and '' if it does not.
;
; @keyword UNIT
; We activate this keyword if we want litchamp to send back the variable
; associated with the element of the structure starting by 'u' if it exist
; and '' if it does not.
;
; @keyword EXP
; We activate this keyword if we want litchamp to send back the variable
; associated with the element of the structure starting by 'u' if it exist
; and '' if it does not.
;
; @keyword DATE
; We activate this keyword if we want litchamp to send back the variable
; associated with the element of the structure starting by 'd' if it exist
; and '' if it does not.
;
; @keyword NAME
; We activate this keyword if we want litchamp to send back the variable
; associated with the element of the structure starting by 'n' if it exist
; and '' if it does not.
;
; @keyword LEVEL
; We activate this keyword if we want litchamp to send back the variable
; associated with the element of the structure starting by 'l' if it exist
; and -1 if it does not.
;
; @keyword MASK
; We activate this keyword if we want litchamp to send back the variable
; associated with the element of the structure starting by 'm' if it exist
; and -1 if it does not.
;
; @returns
; It is the array containing the field.
;
; @uses
; <pro>common</pro>
;
; @restrictions
; Update if needed global variables vargrid,
; varname, varunit, vardate, varexp, valmask and time.
;
; @examples
;
;   IDL> print, vargrid,', ', varname,', ', varunit,', ', vardate,', ', varexp
;    T,  ,  , 0,
;   IDL> help, litchamp({a:indgen(5), u:'C', name:'toto'})
;    <Expression>    INT       = Array[5]
;   IDL> print, vargrid,', ', varname,', ', varunit,', ', vardate,', ', varexp
;    T, toto, C, 0,
;   IDL> help, litchamp({a:indgen(5), da:'1999'})
;    <Expression>    INT       = Array[5]
;   IDL> print, vargrid,', ', varname,', ', varunit,', ', vardate,', ', varexp
;    T, toto, C, 1999,
;
; @history
; Sebastien Masson (smasson\@lodyc.jussieu.fr)
;                       28/5/1999
;
; @version
; $Id$
;
;-
FUNCTION litchamp, struct, GRID=grid, NAME=name, UNIT=unit $
                 , EXP=exp, DATE=date $
                 , LEVEL=level, MASK=mask
;
  compile_opt idl2, strictarrsubs
;
@common
;
  if size(struct, /type) ne 8 then BEGIN ; so contour is not a structure.
      if keyword_set(grid) then return, ''
      if keyword_set(name) then return, ''
      if keyword_set(unit) then return, ''
      if keyword_set(exp)  then return, ''
      if keyword_set(date)  then return, ''
      if keyword_set(level)  then return, -1
      if keyword_set(mask)  then return, -1
      return,  struct
   ENDIF
;------------------------------------------------------------
   IF n_tags(struct) EQ 1 then BEGIN ; The structure has only one element.
      if keyword_set(grid) then return, ''
      if keyword_set(name) then return, ''
      if keyword_set(unit) then return, ''
      if keyword_set(exp)  then return, ''
      if keyword_set(date)  then return, ''
      if keyword_set(level)  then return, -1
      if keyword_set(mask)  then return, -1
      return,  struct.(0)
   ENDIF
;------------------------------------------------------------
   nomelements = tag_names(struct)
   for i = 1, n_tags(struct)-1 do begin
      case strlowcase(strmid(nomelements[i], 0, 1)) of
         'g':BEGIN
            if keyword_set(grid) then return, strupcase(struct.(i))
            vargrid = strupcase(struct.(i))
         END
         'n':BEGIN
            if keyword_set(name) then return, struct.(i)
            varname = struct.(i)
         END
         'u':BEGIN
            if keyword_set(unit) then return, struct.(i)
            varunit = struct.(i)
         END
         'e':BEGIN
            if keyword_set(exp) then return, struct.(i)
            varexp = struct.(i)
         END
         'm':BEGIN
            if keyword_set(mask) then return, struct.(i)
            valmask = struct.(i)
         END
         'd':BEGIN
            if size(struct.(i),/type) EQ 7 THEN BEGIN
               vardate = struct.(i)
            ENDIF ELSE BEGIN
               time = struct.(i)
               jpt = n_elements(time)
               if jpt EQ 1 then vardate =  strtrim(vairdate((struct.(i))[0]), 2)$
               ELSE vardate =  strtrim(vairdate((struct.(i))[0]), 2)+' - ' $
                +strtrim(vairdate((struct.(i))[jpt-1]), 2)
            ENDELSE
            if keyword_set(date) then return, vardate
         END
         'h':BEGIN
            computehopegrid, (struct.(i)).xaxis, (struct.(i)).yaxis $
             , (struct.(i)).zaxis, (struct.(i)).linetype $
             , FIRSTS = (struct.(i)).firsts, LASTS = (struct.(i)).lasts $
             , FORTHEMASK = struct.(0), pttype = (struct.(i)).pttype
         END
         ELSE:BEGIN
            ras = report('Le nom '+nomelements[i]+' ne correspond a aucun element reconnu de la structure. cf. IDL> xhelp, ''litchamp''')
         end
      endcase
   endfor
;------------------------------------------------------------
   if keyword_set(grid) then return, ''
   if keyword_set(name) then return, ''
   if keyword_set(unit) then return, ''
   if keyword_set(exp)  then return, ''
   if keyword_set(date)  then return, ''
   if keyword_set(level)  then return, -1
   if keyword_set(mask)  then return, -1

   return,  struct.(0)
end