; docformat = 'rst'

;+
; Object representing an HDF 5 group.
;
; :Categories: 
;    file i/o, hdf5, sdf
;
; :Requires:
;    IDL 8.0
;
; :Author:
;    Michael Galloy
;
; :Copyright:
;    This library is released under a BSD-type license.
;    
;    Copyright (c) 2007-2010, Michael Galloy <mgalloy@idldev.com>
;    
;    All rights reserved.
;    
;    Redistribution and use in source and binary forms, with or without 
;    modification, are permitted provided that the following conditions are 
;    met:
;    
;        a. Redistributions of source code must retain the above copyright 
;           notice, this list of conditions and the following disclaimer.
;        b. Redistributions in binary form must reproduce the above copyright 
;           notice, this list of conditions and the following disclaimer in 
;           the documentation and/or other materials provided with the 
;           distribution.
;        c. Neither the name of Michael Galloy nor the names of its 
;           contributors may be used to endorse or promote products derived 
;           from this software without specific prior written permission.
;    
;    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS 
;    IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 
;    THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 
;    PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR 
;    CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 
;    EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 
;    PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 
;    PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 
;    LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 
;    NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 
;    SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
;-


;+
; Open an HDF 5 group.
;
; :Private:
; 
; :Keywords:
;    error : out, optional, type=long
;       error code: 0 for none
;-
pro mgffhdf5group::_open, error=error
  compile_opt strictarr

  catch, error
  if (error ne 0L) then begin
    catch, /cancel
    return
  endif
  
  self.id = h5g_open(self.parentId, self.name)
end


;+
; Close an HDF 5 group.
;
; :Private:
; 
; :Keywords:
;    error : out, optional, type=long
;       error code: 0 for none
;-
pro mgffhdf5group::_close, error=error
  compile_opt strictarr

  catch, error
  if (error ne 0L) then begin
    catch, /cancel
    return
  endif
  
  h5g_close, self.id
end


;+
; Get object info for child object inside group.
;
; :Private:
; 
; :Params:
;    name : in, required, type=string
;       name of child object
;
; :Keywords:
;    error : out, optional, type=long
;       error code: 0 for none
;-
function mgffhdf5group::_statObject, name, error=error
  compile_opt strictarr

  catch, error
  if (error ne 0L) then begin
    catch, /cancel
    return, -1
  endif

  for i = 0L, h5g_get_num_objs(self.id) - 1L do begin
    ; find first case-insensitive match
    objName = h5g_get_obj_name_by_idx(self.id, i)
    if (strcmp(objName, name, /fold_case)) then begin
      name = objName
      break
    endif
  endfor
      
  return, h5g_get_objinfo(self.id, name)
end


;+
; Output for `HELP` for group.
;
; :Returns:
;    string
; 
; :Params:
;    varname : in, required, type=string
;       name of variable containing group object
;-
function mgffhdf5group::_overloadHelp, varname
  compile_opt strictarr

  type = obj_class(self)
  specs = string(self.name, format='(%"<%s>")')
  return, string(varname, type, specs, format='(%"%-15s %-9s = %s")')  
end


;+
; Output for `PRINT` for group.
;
; :Returns:
;    string
;-
function mgffhdf5group::_overloadPrint
  compile_opt strictarr

  self->_open, error=error
  if (error ne 0L) then message, 'invalid HDF5 file'
  
  nmembers = h5g_get_num_objs(self.id)
  names = strarr(nmembers)
  types = strarr(nmembers)
  for g = 0L, nmembers - 1L do begin
    names[g] = h5g_get_obj_name_by_idx(self.id, g)    
    info = h5g_get_objinfo(self.id, names[g])
    types[g] = info.type
  endfor
  
  listing = mg_strmerge('  ' + names + ' (' + strlowcase(types) + ')')

  return, string(self.name, listing, format='(%"HDF5 group: %s\n%s")')
end


function mgffhdf5group::_overloadBracketsRightSide, isRange, $
                                                    ss1, ss2, ss3, ss4, $
                                                    ss5, ss6, ss7, ss8
  compile_opt strictarr
  on_error, 2
  
  objInfo = self->_statObject(ss1, error=error)
  if (error ne 0L) then message, string(ss1, format='(%"object %s not found")')

  ; TODO: search existing children before creating a new one
  
  case objInfo.type of
    'GROUP': result = obj_new('MGffHDF5Group', parent_identifier=self.id, name=ss1)
    'DATASET': result = obj_new('MGffHDF5Dataset', parent_identifier=self.id, name=ss1)
    'TYPE': ; TODO: implement
    'LINK': ; TODO: implement
    'UNKNOWN': message, string(ss1, format='(%"object %s unknown")')
    else: begin
        ; TODO: check for attribute
        message, string(ss1, format='(%"object %s unknown")')
      end
  endcase
  
  self.children->add, result
  
  if (n_elements(ss2) gt 0L) then begin
    return, result->_overloadBracketsRightSide(isRange[1:*], ss2, ss3, ss4, ss5, ss6, ss7, ss8)
  endif else begin
    return, result
  endelse  
end


;+
; Free resources.
;-
pro mgffhdf5group::cleanup
  compile_opt strictarr
  
  obj_destroy, self.children
  self->_close
end


;+
; Create a group object.
;
; :Returns:
;    1 for success, 0 for failure
;-
function mgffhdf5group::init, parent_identifier=parentId, name=name, _extra=e
  compile_opt strictarr
  on_error, 2
  
  self.parentId = n_elements(parentId) eq 0L ? '' : parentId
  self.name = n_elements(name) eq 0L ? '' : name
  self.children = obj_new('IDL_Container')

  self->_open, error=error
  if (error ne 0L) then message, 'invalid HDF5 group'
  
  return, 1
end


;+
; Define instance variables and class inheritance.
;
; :Fields:
;    name
;       name of the group
;    parentId
;       HDF 5 identifier for the parent of the group
;    id
;       HDF 5 identifier for the group
;-
pro mgffhdf5group__define
  compile_opt strictarr
  
  define = { MGffHDF5Group, inherits IDL_Object, $
             name: '', $
             parentId: 0L, $             
             id: 0L, $
             children: obj_new() $
           }
end