Function gxpar,hdr,name,count=count,comment=comment

;+------------------------------------------------------------------------
;
; GXPAR             10/2006
;
; Obtain parameter value from a FITS header.  Parameter names may have
; any length.
;
; GXPAR achieves the same result as SXPAR and FXPAR, but allows parameter
; names to have any length, rather than at most 8 characters.  The parsing
; algorithm works on the following assumptions:
;
;    - Any line of a FITS header that contains both a '=' and a '/' is
;      considered a parameter entry.
;    - Whatever preceeds the '=' is the parameter name.
;    - Whatever is between the '=' and the '/' is the parameter value.
;    - Leading and trailing 's in the parameter value are discarded.
;    - Whatever comes after the '/' is the comment.
;
; NOTE: This program should probably consider any line with just a '='
; to be an entry, as some entries will not have comments.
;
; Due to its ability to find parameters with arbitrary length names,
; GXPAR runs more slowly than SXPAR and FXPAR.
;
; INPUTS
;        hdr      - String, FITS header array
;        name     - String, name of parameter to return (not 
;                   case-sensitive)
;
; KEYWORDS
;        count    - Scalar, number of occurances of the requested 
;                   parameter.
;        comment  - String, comment associated with parameter
;
; OUTPUTS
;        <result> - Parameter value, which may be a string or a scalar.
;                   If more than one instance of the requested parameter
;                   is found, the value of the first one is returned.
;
; HISTORY
;        Written 10/23/2006 GDB
;-------------------------------------------------------------------------

if (n_params() lt 2) then begin
   print,'CALLING SEQUENCE:'
   print,'    value = gxpar(hdr,name,count=count,comment=comment)'
   count   = 0
   comment = '' 
   return,-1
endif

; Compile a list of parameter names, values, and comments
n_entries = n_elements(hdr)
n_params  = 0
for i=0,n_entries-1 do begin
   ; Search this entry for = and /.
   entry = hdr(i)
   equal_pos = strpos(entry,'=')
   slash_pos = strpos(entry,'/',equal_pos)
   if (equal_pos ne -1 and slash_pos ne -1) then begin
      tmp_name    = strtrim(strmid(entry,0,equal_pos),2)
      tmp_value   = strtrim(strmid(entry,equal_pos+1,slash_pos-equal_pos-1),2)
      tmp_comment = strtrim(strmid(entry,slash_pos+1),2)
      if (n_params eq 0) then begin
         name_list    = [tmp_name]
         value_list   = [tmp_value]
         comment_list = [tmp_comment]
      endif else begin
         name_list    = [name_list,tmp_name]
         value_list   = [value_list,tmp_value]
         comment_list = [comment_list,tmp_comment]
      endelse
      n_params = n_params + 1
   endif
endfor

; Force all parameter names to be upper case.
name_list = strupcase(name_list)

; Look for matches to the requested parameter
match = where(name_list eq strupcase(name),count)

; Retrieve and process parameter value
if (count ge 1) then begin
   j = match(0)
   raw_value = value_list(j)
   ; If this is a string, then remove leading and trailing 's and 
   ; spaces.
   quote1 = strpos(raw_value,"'")
   if (quote1 ne -1) then begin
      quote2 = strpos(raw_value,"'",0,/reverse_offset,/reverse_search)
      value = strtrim(strmid(raw_value,quote1+1,quote2-quote1-1),2)
   endif else begin
      ; Return a long, floating, or double scalar
      long_value   = long(raw_value)
      float_value  = float(raw_value)
      double_value = double(raw_value)
      if (long_value eq double_value) then value = long_value else begin
         if (float_value eq double_value) then value = float_value $
            else value = double_value
      endelse
   endelse
   comment = comment_list(j)
   ; Print a warning if more than one occurance of parameter was found
   if (count gt 1) then $
      print,'GXPAR: WARNING - More than one occurance of '+name+' found.'
endif else begin
   value    = -1
   comment  = ''
endelse

return,value
end