; docformat = 'rst'
;
; NAME: 
;    mp3cReadMeta
; PURPOSE:
;    Read meta data in ini-style format and store it in a structure
;
;+
; :Description:
;    Read meta data in ini-style format and store it in a structure
;
; :Categories:
;    MP3C
;
; :Params:
;    file: in, required, type=string
;        Path to the file to parse
;
; :Returns: A structure containing the meta data. Fields are::
;    id   : Field unique identifier
;    name : Name of the field
;    desc : Description of the field
;    ucd  : Unified Content Descriptor (follows http://www.ivoa.net/documents/latest/UCD.html)
;    unit : Unit (follows http://ivoa.net/documents/VOUnits/)
;    type : Type of variable (char, int, float, ...)
;    size : Number of characters coding the value
;    xml  : VOTable header PARAM line [returned empty here]
;
; :Keywords:
;
; :Uses:
;
; :Author:
;    B.Carry (OCA)
;
; :History:
;     Change History::
;        Original Version written in September 2016, B. Carry (OCA)
;-
function mp3cReadMeta, file
;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;
;---  TAG ---    I -- Variables Declaration and Definition               -----------------------;
;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;
  COMPILE_OPT hidden, idl2

 ;--I.1-- Valid Input Parameter  ---------------------------------------------------------------
  if not keyword_set(file) then begin
    message, /ioError, 'syntax: meta = mp3cReadMeta( file )'
    return, -1
  endif

 ;--I.2-- Check if Input File Exists  ----------------------------------------------------------
  if not file_test(file,/Read) then begin
    message, /ioError, 'Meta file cannot be read: '+strtrim(file,2)
    return, -1
  endif

 ;--I.3-- Metadata Structure  ------------------------------------------------------------------
  nd={name:'',desc:''}
  empty={id:'',name:'',desc:'',ucd:'',unit:'',type:'',size:'',min:'',max:'',xml:''}
  head=nd
  table=nd
  meta=replicate(empty,200)
  kMeta=-1

;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;
;---  TAG ---   II -- Parse Input File  and Store it Into Structure      -----------------------;
;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;
 ;--II.1-- Open the File for Reading  ----------------------------------------------------------
  openR, idIn, file, /get_lun
  line = ' ' 
  section = ' ' 
  while ~EoF(idIn) do begin

   ;--II.2-- Read Current Line  ----------------------------------------------------------------
    readf, idIn, line

   ;--II.3-- Update Meta Index  ----------------------------------------------------------------
    if strMid(line,0,1) eq '[' then begin

     ;--II.3.1-- Table Header or Column Description?
      split=strSplit(line, '[]', /Extract, count=nbField )
      if strcmp(split[0],'table description',/fold) then begin
        section='header'
      endif else begin
        section='column'
        kMeta++
      endelse

   ;--II.4-- Update Metadata Fields  -----------------------------------------------------------
    endif else begin

     ;--II.4.1-- Split Line upon Equal Sign
      split=strSplit(line, '=', /Extract, count=nbField )
      key = strTrim(split[0],2)
      if nbField gt 1 then case section of 

       ;--II.4.2-- HEADER: Assign Value to Keys
        'header': begin
           case key of 
             'name': head.name = strTrim(split[1],2)
             'desc': head.desc = strTrim(split[1],2)
             'table name': table.name = strTrim(split[1],2)
             'table desc': table.desc = strTrim(split[1],2)
             else: 
           endcase
         end

       ;--II.4.3-- COLUMN: Assign Value to Keys
        'column': begin
           case key of 
             'id'  : meta[kMeta].id   = strTrim(split[1],2)
             'name': meta[kMeta].name = strTrim(split[1],2)
             'desc': meta[kMeta].desc = strTrim(split[1],2)
             'ucd' : meta[kMeta].ucd  = strTrim(split[1],2)
             'unit': meta[kMeta].unit = strTrim(split[1],2)
             'type': meta[kMeta].type = strTrim(split[1],2)
             'size': meta[kMeta].size = strTrim(split[1],2)
             'min':  meta[kMeta].min  = strTrim(split[1],2)
             'max':  meta[kMeta].max  = strTrim(split[1],2)
             else: 
           endcase
         end
      endcase

    endelse

  endwhile    ;--End of II.1-- Loop over Filelines

 ;--II.5-- Close File and Return  --------------------------------------------------------------
  free_lun, idIn
  meta=meta[0:kMeta+1]
  return, {head:head, table:table, column:meta}

end