;+
; This extends the index_file_section class to properly handle the header section
; of an index file.  The added basic functionality is to treat the header section
; like a dictionary, that is, a list of keyword-value pairs.
; See <a href="../../../IDL_IO_classes.jpg">UML</a> for all IO Classes
;
; @field header a key_value_parser object for converting the lines in the section
; to a structure
; 
; @file_comments
; This extends the index_file_section class to properly handle the header section
; of an index file.  The added basic functionality is to treat the header section
; like a dictionary, that is, a list of keyword-value pairs.
; See <a href="../../../IDL_IO_classes.jpg">UML</a> for all IO Classes
;
; @field header a key_value_parser object for converting the lines in the section
; to a structure
; 
; @inherits index_file_section
; @private_file
;
;-
PRO header_index_section__define

    his = { HEADER_INDEX_SECTION, $ 
        inherits index_file_section,  $
        header:obj_new() $
    }

END

;+
; Class Constructor
; @private
;-
FUNCTION HEADER_INDEX_SECTION::init, lun, filename
    compile_opt idl2, hidden

    if n_elements(filename) ne 0 then begin
        r = self->INDEX_FILE_SECTION::init(lun, "header", filename)
    endif else begin    
        r = self->INDEX_FILE_SECTION::init(lun, "header")
    endelse

    self.pad_width = 1
    return, r

END    

;+
; Class Destructor
; @private
;-
PRO HEADER_INDEX_SECTION::cleanup
    compile_opt idl2, hidden

    self->INDEX_FILE_SECTION::cleanup

    if obj_valid(self.header) then obj_destroy, self.header

END    

;+
; Creates the header section, given the strings to place there.
;
; @param hdr_lines {in}{required}{type=string array} lines to be placed in header 
; section; must be of form 'keyword = value' for each line.
; @param start_line_number {in}{optional}{type=long} line to start at, 
; defaults to zero
;
;-
PRO HEADER_INDEX_SECTION::create, hdr_lines, start_line_number
    compile_opt idl2, hidden

    if n_elements(start_line_number) eq 0 then start_line_number = 0

    self->INDEX_FILE_SECTION::create, start_line_number, lines=hdr_lines

    if obj_valid(self.header) then obj_destroy, self.header

    self.header = obj_new("key_value_parser", hdr_lines)
    
END

;+
; Reads the header section of an index file.  After reading in the lines, creates a 
; key_value_parser object to manage them.
;-
FUNCTION HEADER_INDEX_SECTION::read_file
    compile_opt idl2, hidden

    result = self->INDEX_FILE_SECTION::read_file()

    if result ne -1 then begin
        if obj_valid(self.header) then obj_destroy, self.header
        self.header = obj_new("key_value_parser",self->get_lines())
    endif

    return, result
END

;+
; Retrieves the value for a header keyword.
; @param keyword {in}{required}{type=string} keyword whose value is returned
; @returns string value of keyword passed in. -1 if keyword is not found.
;-
FUNCTION HEADER_INDEX_SECTION::get_value, keyword
    compile_opt idl2, hidden

    if self.section_read ne 1 then message, "section not read yet"

    return, self.header->get_key_value(keyword)

END

;+ 
; Retrieves the position in the file of the header keyword supplied
; @param keyword {in}{required}{type=string} keyword whose position is returned
; @returns position in the file of the header keyword supplied
; @private
;-
FUNCTION HEADER_INDEX_SECTION::get_line_number, keyword
    compile_opt idl2, hidden

    keys = self.header->get_keys()
    
    line_number = -1
    for i=0,n_elements(keys)-1 do begin
        if strtrim(strlowcase(keys[i]),2) eq strtrim(strlowcase(keyword),2) then begin
            line_number = (*self.line_nums)[i]
        endif
    endfor

    return, line_number

END

;+
; Sets the value for the keyword in the file header
; @param keyword {in}{required}{type=string} keyword whose value is set
; @param value {in}{required}{type=string} value to set for keyword
; @returns 0 - failure, 1 - success
; @uses get_line_number
; @uses header->set_key_value
;-
FUNCTION HEADER_INDEX_SECTION::set_value, keyword, value
    compile_opt idl2, hidden

    if self.section_read ne 1 then message, "section not read yet"
    
    line_number =  self->get_line_number(keyword)
    
    if line_number eq -1 then message, "keyword not found in header: "+keyword

    self->set_line, line_number, strtrim(strlowcase(keyword),2) + " = " + strtrim(value,2)
        
    return, self.header->set_key_value(keyword, value)
    
END

;+
; Prints out the contents of the header (in it's structure form)
; @uses header->list
;-
PRO HEADER_INDEX_SECTION::list
    compile_opt idl2, hidden

    if self.section_read ne 1 then message, "section not read yet"

    self.header->list

END