./toolbox/io
index_file_section__define.pro

Last modification date:

Wed Sep 28 13:27:14 2016

This is the base class for managing a section in an index file. Sections are started with a line: '[section_name]'. This class manages all basic i/o functions for a section. See UML for all IO Classes

Fields Summary
LINES_INCR longword integer	number of lines that buffers grow by internally as necessary. Placed here for consistency only.
MAX_LINE_WIDTH longword integer	maximum number of chars allowed on each line
NUM_LINES longword integer	the current number of lines in this section
FILENAME string	full pathname to the file where this section resides
SECTION_MARKER string	name of section
LINE_NUMS pointer	pointer to an array of indicies locating each line in file (line #s zero based)
ALL_LINES pointer	pointer to an array holding all lines in this section - not normally used except during testing. Derived classes should NOT rely on this.
SECTION_READ longword integer	boolean flag for wether section is in memory or not
ALLOW_APPEND longword integer	boolean flag for wether this section allows appends
PAD_WIDTH longword integer	boolean flag determines wether lines are padded to max width
DEBUG longword integer	boolean flag for wether this class is verbose or not

Routine Summary  27 routines

procedure index_file_section__define
This is the base class for managing a section in an index file.

function INDEX_FILE_SECTION::init(section, filename)	private
Class Constructor

procedure INDEX_FILE_SECTION::cleanup	private
Class Destructor

procedure INDEX_FILE_SECTION::set_file_name, file_name
Sets file name of file to be written to

procedure INDEX_FILE_SECTION::pad_width_on
Sets object to pad lines written with spaces to their max width

procedure INDEX_FILE_SECTION::pad_width_off
Sets object to NOT pad lines written with spaces to their max width

procedure INDEX_FILE_SECTION::create[, start_line_number], [lines=string array], [append=bool], not_in_memory=not_in_memory
Creates the section in the file.

function INDEX_FILE_SECTION::pad_line(line)
Adds extra blank characthers to end of given line, if this line is less then the max line width.

function INDEX_FILE_SECTION::has_valid_lines()
Tests the validity of the pointer to array of lines in section

function INDEX_FILE_SECTION::has_valid_line_numbers()
Tests the validity of the pointer to array of line numbers in section

function INDEX_FILE_SECTION::get_line_nums([count])
Retrieves the location of each section line in the file

function INDEX_FILE_SECTION::get_num_lines()
Retrieves the number of lines in this section

procedure INDEX_FILE_SECTION::increment_num_lines	private
Increments the number of lines this class believes are in the section.

function INDEX_FILE_SECTION::count_section_lines()
Counts lines in the section, not including the section line itself

function INDEX_FILE_SECTION::get_lines([count])
Retrieves array of lines in section; commented out lines are not included.

procedure INDEX_FILE_SECTION::process_line, line, index
Procedure to process each line.

function INDEX_FILE_SECTION::read_file([max_nrows=long])
Reads the file, locates the section, and loads all lines and metainfo into objects memory

procedure INDEX_FILE_SECTION::go_to_line, line_number, lun	private
Advances file pointer to right before the line number parameter.

function INDEX_FILE_SECTION::get_index_by_location(location)
Retrurns the index associated with the given location in the file, the line number.

procedure INDEX_FILE_SECTION::set_line, line_number, line[, line_index]
Replaces a line already in the index with a new string.

function INDEX_FILE_SECTION::get_current_file_length()
Uses the line numbers in memory to return what the last line number is for the file

procedure INDEX_FILE_SECTION::append_lines, lines
Appends lines to end of section (if allowed).

procedure INDEX_FILE_SECTION::set_debug_on
Makes object verbose

procedure INDEX_FILE_SECTION::set_debug_off
Makes object quiet

function INDEX_FILE_SECTION::is_section_read()
Has the section been read?

procedure INDEX_FILE_SECTION::set_allow_append_on
Set this if the section can be appended to

procedure INDEX_FILE_SECTION::show_state
Print out useful debugging information

Routine Details

index_file_section__define

procedure index_file_section__define

This is the base class for managing a section in an index file. Sections are started with a line: '[section_name]'. This class manages all basic i/o functions for a section. See UML for all IO Classes

INDEX_FILE_SECTION::init

private

function INDEX_FILE_SECTION::init(section, filename)

Class Constructor

Parameters
section	.
filename	.

INDEX_FILE_SECTION::cleanup

private

procedure INDEX_FILE_SECTION::cleanup

Class Destructor

INDEX_FILE_SECTION::set_file_name

procedure INDEX_FILE_SECTION::set_file_name, file_name

Sets file name of file to be written to

Parameters
file_name in string	name of index file

INDEX_FILE_SECTION::pad_width_on

procedure INDEX_FILE_SECTION::pad_width_on

Sets object to pad lines written with spaces to their max width

INDEX_FILE_SECTION::pad_width_off

procedure INDEX_FILE_SECTION::pad_width_off

Sets object to NOT pad lines written with spaces to their max width

INDEX_FILE_SECTION::create

procedure INDEX_FILE_SECTION::create[, start_line_number], [lines=string array], [append=bool], not_in_memory=not_in_memory

Creates the section in the file.

Parameters
start_line_number in, optional long	what line to start section on in file

Keywords
lines in, optional string array	array of lines to be written in section upon creation (does not include section marker).
append in, optional bool	exclusive with start_line_number: if set, lines get written at end of section
not_in_memory	.

INDEX_FILE_SECTION::pad_line

function INDEX_FILE_SECTION::pad_line(line)

Adds extra blank characthers to end of given line, if this line is less then the max line width.

Returns

string with added blank chars to make it the max line width

INDEX_FILE_SECTION::has_valid_lines

function INDEX_FILE_SECTION::has_valid_lines()

Tests the validity of the pointer to array of lines in section

Returns

0 - not valid, 1 -valid

INDEX_FILE_SECTION::has_valid_line_numbers

function INDEX_FILE_SECTION::has_valid_line_numbers()

Tests the validity of the pointer to array of line numbers in section

Returns

0 - not valid, 1 -valid

INDEX_FILE_SECTION::get_line_nums

function INDEX_FILE_SECTION::get_line_nums([count])

Retrieves the location of each section line in the file

Returns

integer array which is location of each section line in file

INDEX_FILE_SECTION::get_num_lines

function INDEX_FILE_SECTION::get_num_lines()

Retrieves the number of lines in this section

Returns

long integer - number of lines in the section

INDEX_FILE_SECTION::increment_num_lines

private

procedure INDEX_FILE_SECTION::increment_num_lines

Increments the number of lines this class believes are in the section.

INDEX_FILE_SECTION::count_section_lines

function INDEX_FILE_SECTION::count_section_lines()

Counts lines in the section, not including the section line itself

Returns

-1 on failure

INDEX_FILE_SECTION::get_lines

function INDEX_FILE_SECTION::get_lines([count])

Retrieves array of lines in section; commented out lines are not included. This only works for testing and it should be replaced by the suitable version for any derived class as necessary.

Returns

array of lines in section, -1 if no lines

INDEX_FILE_SECTION::process_line

procedure INDEX_FILE_SECTION::process_line, line, index

Procedure to process each line. Invoked by index_file_section::read_file. This is a dummy version that must be replaced by any derived class wanting to make use of read_file.

Parameters
line in, required string	The line to handle.
index in, required integer	The index number for this line

INDEX_FILE_SECTION::read_file

function INDEX_FILE_SECTION::read_file([max_nrows=long])

Reads the file, locates the section, and loads all lines and metainfo into objects memory

Returns

0 - failure, 1 - success

INDEX_FILE_SECTION::go_to_line

private

procedure INDEX_FILE_SECTION::go_to_line, line_number, lun

Advances file pointer to right before the line number parameter. To be used to write to a specific line in file. File must be opened beforehand and closed after call. This is something that idl should provide.

Parameters
line_number in, required long	line number to go to (0-based)
lun in, required integer	Already opened file unit number

INDEX_FILE_SECTION::get_index_by_location

function INDEX_FILE_SECTION::get_index_by_location(location)

Retrurns the index associated with the given location in the file, the line number.

Returns

the index number associated with that location

INDEX_FILE_SECTION::set_line

procedure INDEX_FILE_SECTION::set_line, line_number, line[, line_index]

Replaces a line already in the index with a new string.

Parameters
line_number in, required long	the file line number (first line, second line, etc. ) to replace.
line in, required string	new line to place in section
line_index out, optional variable	index in array of lines for this section specified by line_number

INDEX_FILE_SECTION::get_current_file_length

function INDEX_FILE_SECTION::get_current_file_length()

Uses the line numbers in memory to return what the last line number is for the file

Returns

the last line number in memory for this file

INDEX_FILE_SECTION::append_lines

procedure INDEX_FILE_SECTION::append_lines, lines

Appends lines to end of section (if allowed). Keeps objects memory in sync with section

Parameters
lines in, required string array	lines to append to section

INDEX_FILE_SECTION::set_debug_on

procedure INDEX_FILE_SECTION::set_debug_on

Makes object verbose

INDEX_FILE_SECTION::set_debug_off

procedure INDEX_FILE_SECTION::set_debug_off

Makes object quiet

INDEX_FILE_SECTION::is_section_read

function INDEX_FILE_SECTION::is_section_read()

Has the section been read?

Returns

0 - no, 1 - yes

INDEX_FILE_SECTION::set_allow_append_on

procedure INDEX_FILE_SECTION::set_allow_append_on

Set this if the section can be appended to

INDEX_FILE_SECTION::show_state

procedure INDEX_FILE_SECTION::show_state

Print out useful debugging information