; docformat = 'rst'
;
; NAME:
;    LXPAR
; PURPOSE:
;    Obtain the value of a parameter with a long key (inc. spaces) in a FITS header
;
;+
; :Description:
;    Obtain the value of a parameter with a long key (inc. spaces) in a FITS header
;
;    A more complete routine for parameter extraction from FITS header is
;    SXPAR. However, SXPAR handles keywords with 8 characters only, thus
;    incompatible with the HIERARCH standard of long keywords. LXPAR provides
;    a less robust and extensive alternative but handles long keywords.
;
; :Categories:
;    FITS
;    
; :Params:
;    HDR: in, required, type=string
;        FITS header array, (e.g., as returned by READFITS) 
;        string array, each element should have a length of 80 characters      
;
;    NAME: in, required, type=string
;        String name of the parameter to return.   If NAME is of the
;        form 'keyword*' then an array is returned containing values of
;        keywordN where N is a positive (non-zero) integer.  The value of 
;        keywordN will be placed in RESULT[N-1].  The data type of RESULT 
;        will be the type of the first valid match of keywordN found.
;
; :Returns: Value of requested parameter in header.
;           If parameter is double precision, floating, long or string,
;           the result is of that type.  Apostrophes are removed
;           from strings.  If the parameter is logical, 1b is
;           returned for T, and 0b is returned for F.
;           If NAME was of form 'keyword*' then a vector of values
;           are returned.
;
; :Keywords:
;    COUNT: out, optional, type=integer
;        Optional keyword to return a value equal to the number of 
;        parameters found by SXPAR, integer scalar
;    COMMENT: out, optional, type=string
;        Array of comments associated with the returned values
;    silent: in, optional, type=boolean
;        Lxpar does not print messages to stdout.
;
; :Examples:
;    Search the value of exposure time from an ESO header::
;      IDL> VAL = LXPAR( HEADER, 'HIERARCH ESO DET DIT' )
;
; :Author:
;    B.Carry (OCA)
;
; :History:
;     Change History::
;        Written in 2006, B. Carry (ESO/LESIA)
;        2013-Nov.: B.Carry (IMCCE) - Allows input coords in two variables
;        2014-Dec.: B.Carry (IMCCE) - Added exit code for keyword not found
;-
function lxpar, hdr, name, count=count, comment=comment, silent=silent

 ;--I-- Initialization And Input Verification
 ;--I.1-- Make Compilation Silent
  COMPILE_OPT hidden

 ;--I.2-- Check Presence of Arguments
  if N_params() LT 2 then begin
    if not keyword_set(silent) then $
      message, /IOERROR,'Syntax -  result =  lxpar( hdr, name, [count=, comment=])'
    return, -1
  endif


 ;--II-- Input Keyword to Search
 ;--II.1-- Convert Input Name into a Test String
  inKey = strupcase(strtrim(name,2))
  lenKey = strlen(inKey)

 ;--II.2-- Search for Multiple Occurences?
  posStar = strpos( inKey, '*')
  if posStar eq lenKey-1 then begin
    tKey = strmid(inKey,0,lenKey-1)
    lenKey--
    vector=1
  endif else begin
    tKey = inKey
    vector=0
  endelse


 ;--III-- Search the Header 
 ;--III.1-- Shorten Header's Keywords to Test Chain
  keyword = strmid(hdr,0,lenKey)

 ;--III.2-- Location of Matching Strings
  idFound = where(strpos(keyword,tKey) GE 0, nbFound)
  if nbFound gt 0 then begin
    resArr = replicate( {key: '', val: '', com: '', match: 0}, nbFound)

   ;--III.3-- Analyze Matched Entries
    for kF=0, nbFound-1 do begin
  
     ;--III.3.1-- Search '=' and '/' Delimiters
      line = hdr(idFound(kF))
      equal=strpos( line, '=' )+1
      slash=strpos( line, '/' )+1
  
     ;--III.3.2-- Bookeep the Keyword, its Value, and Comment
      resArr(kF).key = strtrim(strmid(line, 0, equal-1),2)
      if slash ge 1 then begin
        resArr(kF).val = strtrim(strmid(line, equal, slash-equal-1),2)
        resArr(kF).com = strtrim(strmid(line, slash, strlen(line)-slash),2)
      endif else begin
        resArr(kF).val = strtrim(strmid(line, equal, strlen(line)-equal),2)
        resArr(kF).com = ''
      endelse
  
     ;--III.3.3-- Clean Apostrophs from strings
      if ( strmid(resArr(kF).val,0,1) EQ "'" ) then begin
         test = strmid( resArr(kF).val,1,strlen( resArr(kF).val )-1)
         next_char = 0
         endap = strpos(test, "'", next_char)
         resArr(kF).val = strmid( test, next_char, endap-next_char )  

     endif

      resArr(kF).match = strcmp( resArr(kF).key, tKey )
  
    endfor
  
  
   ;--IV-- Select Valid Keywords
    strictMatch = where( resArr.match eq 1, nbMatch )
  
   ;--IV.1-- Single Keyword Searched for --> Trim
    if vector eq 0 then begin
      if nbMatch gt 1 and not keyword_set(silent) then $
         message, /INFORMATIONAL, 'Warning - keyword "'+name+'" located more than once in FITS Header'
      resArr = resArr(strictMatch)
      nbFound = nbMatch
    endif
  
   ;--IV.2-- Optional Outputs
    count = nbFound
    comment = resArr.com
  
   ;--IV.3-- Return Keyword Value
    return, resArr.val


 ;--V-- No Keyword found
  endif else begin
    return, -2
  endelse
end