; docformat = 'rst'
;
; NAME:
;    GENOIDE_XMLMERGE
; PURPOSE:
;    Merge several Genoide VOTable into one, with possible sorting of entrie
;
;+
; :Description:
;    Merge several Genoide VOTable into one, with possible sorting of entrie
;
;    The suite of small routines GENOIDE_XML... allow to open, complete, close, read
;    an XML file in the Genoid standards. 
;
; :Categories:
;    Disk I/O, Genoide
;    
; :Params:
;    IN: in, required, type=string
;        A list of paths to the individual XML files
;    DUMP: in, required, type=string
;        The path to the merged XML file
;
; :Keywords:
;    SORT: in, optional, type=boolean, default=0
;        If set, the entries in the final file will be sorted by date
;
; :Uses:
;    genoide_xmlOpen, genoide_xmlAdd, genoide_xmlClose
;
; :Author:
;    B.Carry (IMCCE)
;
; :History:
;     Change History::
;        Written in July 2013, B. Carry (IMCCE)
;        2013 Sep. - B.Carry (IMCCE) - Cleaned
;        2014 Jun. - B.Carry (IMCCE) - Verification of inputs added
;-
pro genoide_xmlMerge, in, dump, sort=sort


;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;
;---  TAG ---    I -- Initialization And Input Verification              -----------------------;
;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;
  COMPILE_OPT hidden

 ;--I.1-- Input Syntax Verification  ----------------------------------------------------
  if N_PARAMS() lt 2 then begin
    message, /IOERROR, 'Syntax : genoide_xmlMerge, in, dump  [,/SORT]'
    stop
  endif


 ;--I.2-- Input XML Files  --------------------------------------------------------------
  nbFile=n_elements(in)
  goOut=0
  for kFile=0, nbFile-1 do begin
;    help, in(kFile)
    if ~file_test(in(kFile),/READ) then begin
      goOut=1
      message, /INFO, 'Input XML file not found: '+strtrim(in(kFile),2)
    endif
  endfor
  if goOut eq 1 then stop



 ;--I.3-- Output XML Structure  ---------------------------------------------------------
  maxDate = 1000
  sat = replicate( {jd: 0.0d, iso: '', $
                    refName: '', refsys: '', $
                    xobs: 0., yobs: 0., $
                    xerr: 0., yerr: 0., $
                    xcal: 0., ycal: 0., $
                    xomc: 0., yomc: 0., $
                    timescale: '', $
                    centerFrame: 0., typeFrame: 0., $
                    coordType: 0., refFrame: 0., $
                    obsIAU: '', bib: ''}, maxDate )



;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;
;---  TAG ---   II -- Read Individual Input XML Files                    -----------------------;
;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;

 ;--II.1-- Loop Over Files  --------------------------------------------------------------
  kDate=0
  for kFile=0, nbFile-1 do begin

   ;--II.2-- Read Current XML  -------------------------------------------------------------
    curSat = genoide_xmlRead( in(kFile) )
    nbCur = n_elements(curSat)

   ;--II.3-- Store Current XML in Output Structure  ----------------------------------------
    for kCur=0, nbCur-1 do begin
      sat(kDate) = curSat(kCur)
      kDate++
    endfor

  endfor


 ;--II.4-- Clean Output Structure  -------------------------------------------------------
  nbDate = kDate
  sat=sat(0:nbDate-1)



;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;
;---  TAG ---  III -- Sort and Export                                    -----------------------;
;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;


 ;--III.1-- Sort Entries by Date if Requested  --------------------------------------------
  if keyword_set( SORT ) then begin
    order = sort( sat(*).jd )
    sat = sat(order)
  endif

 ;--III.2-- Write Merged Genoide Structure to Disk  ---------------------------------------
  unit = genoide_xmlOpen( dump, nbDate )
  genoide_xmladd, unit, sat
  genoide_xmlclose, unit

end