NAME:

Package: Filesys


SYNOPSIS:

use lib::Filesys;


DIRECTORY/FILE:

The file Filesys.pm is located in the subdirectory './lib'


DESCRIPTION:

This package contains all functions that read/write information stored in the block system that is used in the the configuration files that are: 'edoc.cfg', 'edoc.int', 'edoc.obj', '{backend_name}.out', '{backend_name}.in', '{backend_name}.{object_name}.out' and '{backend_name}.{object_name}.in'.

Actually it does not perform directly on/to the file on disk, the files content has to be transferred into an array and a reference to this filearray has then to be passed through the functions of this package lib::Filesys.

The functions in this packages can also modify this filearray, so that it can be saved again as a file later.

All information in the configuration files in kept in blocks, which can be nested.

All blocks start with a start-tag like <<<BEGIN::block_name>>> and end with an end-tag like <<<END::block_name>>>, where block_name is a placeholder for the actual blocks name. Only the last started block can be closed with the end-tag, of course.

There are several types of blocks:

 #comments are started with an '#' at the beginning

 <<<BEGIN::WRAPPER>>> #this is the start-tag of a wrapper-block which only contains other blocks and has no own content

   <<<BEGIN::HASH_BLOCK>>> #this is the start-tag of a hash-block which contains a set of property/value pairs

     item1 = "something" #this is a text property

     item2 = 2 #this is a number

     item3 = "subitem1||subitem2||subitem3" #This is an list property where || is the items delimiter

   <<<END::HASH_BLOCK>>> #End-tag of the hash-block

   <<<BEGIN::ARRAY_BLOCK>>> #this is the start-tag of an array-block which contains lines that should be taken as an array

     somtext is here   

     and here

     and here too...

   <<<END::ARRAY_BLOCK>>> #End-tag of the array-block

 <<<END::WRAPPER>>> #End-tag of the wrapper block

You see, this is not far away from the basic XML structure and will be transformed sometimes into XML.


STATUS:

Coding: 90%

Documentation: up-do-date


FUNCTIONS:


read_blocklist

@blocklist = Filesys::read_blocklist($ref_file_array)

Reads the whole filearray and produces a list (array) with all blocknames and returns it.

Parameters:

(+) $ref_file_array: A reference to the array that holds the content of the configuration file


delete_block

$line = Filesys::delete_block($ref_file_array, $blockname)

Removes the whole block from the filearray

Parameters:

(+) $ref_file_array: A reference to the array that holds the content of the configuration file

(+) $blockname: The name of the block to remove


read_data_array

@block = Filesys::read_data_array($ref_file_array, $blockname, $process_edoc_commands)

Reads the content of a block as an array and returns it.

Parameters:

(+) $ref_file_array: A reference to the array that holds the content of the configuration file

(+) $blockname: The name of the block to be read

(+) $process_edoc_commands: If set to 1, special edoc-commands like ``%NL%'' or ``%INLINE_MACRO::....%'' are processed. If set to 0, nothing is done. BEWARE: These processing will corrupt all hash-blocks that are inside this array-block ! So this parameter is only set to 1 in the function that reads the macro-code, where no hash-block is inside.


cut_data_array

@block = Filesys::cut_data_array($ref_file_array, $blockname, $process_edoc_commands)

Cuts the content of a block from an array and returns it.

Parameters:

(+) $ref_file_array: A reference to the array that holds the content of the configuration file

(+) $blockname: The name of the block to be read

(+) $process_edoc_commands: If set to 1, special edoc-commands like ``%NL%'' or ``%INLINE_MACRO::....%'' are processed. If set to 0, nothing is done. BEWARE: These processing will corrupt all hash-blocks that are inside this array-block ! So this parameter is only set to 1 in the function that reads the macro-code, where no hash-block is inside.


write_data_array

Filesys::write_data_array($ref_file_array, $blockname, $ref_array_to_write, $no_delete_first)

writes the content of an array as an block into the filearray.

Parameters:

(+) $ref_file_array: A reference to the array that holds the content of the configuration file

(+) $blockname: The name of the block to be read

(+) $ref_array_to_write: A reference to the array that should be written into the filearray

(+) $no_delete_first: If set to 1, the block is not seached first for deletion (if you know it does not exits)


read_data_hash

%block = Filesys::read_data_hash($ref_file_array, $blockname)

Reads the content of a block as a hash and returns it.

Parameters:

(+) $ref_file_array: A reference to the array that holds the content of the configuration file

(+) $blockname: The name of the block to be read


cut_data_hash

%block = Filesys::cut_data_hash($ref_file_array, $blockname)

Cuts the content of a block as a hash and returns it.

Parameters:

(+) $ref_file_array: A reference to the array that holds the content of the configuration file

(+) $blockname: The name of the block to be read


write_data_hash

Filesys::write_data_hash($ref_file_array, $blockname, $ref_hash_to_write, $no_delete_first)

writes the content of a ahsh as an block into the filearray.

Parameters:

(+) $ref_file_array: A reference to the array that holds the content of the configuration file

(+) $blockname: The name of the block to be read

(+) $ref_hash_to_write: A reference to the hash that should be written into the filearray

(+) $no_delete_first: If set to 1, the block is not seached first for deletion (if you know it does not exits)


read_hash_value

$value = Filesys::read_hash_value($ref_file_array, $blockname, $key)

NOT CODED YET, but it should read one property entry in a hash-block.

Parameters:

(+) $ref_file_array: A reference to the array that holds the content of the configuration file

(+) $blockname: The name of the block to be read

(+) $key: The name of the property entry (= key in the hash)


write_hash_value

Filesys::write_hash_value($ref_file_array, $blockname, $key, $value)

NOT CODED YET, but it should write one property / value pair in a hash-block.

Parameters:

(+) $ref_file_array: A reference to the array that holds the content of the configuration file

(+) $blockname: The name of the block to be read

(+) $key: The name of the property entry (= key in the hash)

(+) $value: The value of the property entry (= value in the hash)


split_stringlist

@a_list = Filesys::split_stringlist($source_string, $delimiter)

Splits a list-property into an array and returns it.

Parameters:

(+) $source_string: The string that contains the list

(+) $delimiter: The delimiter used in the stringlist (Default: '||')


is_in_stringlist

$bool = Filesys::is_in_stringlist($searched_string, $source_string, $delimiter)

Checks if the searched string is in the stringlist and returns 1 if it is there and 0 if its not there.

Parameters:

(+) $searched_string: The string that is searched in the stringlist

(+) $source_string: The string that contains the list

(+) $delimiter: The delimiter used in the stringlist (Default: '||')


check

$bool = Filesys::check($ref_file_array)

Checks if the fileformat in the filearray is correct, that means if all blocks are opened and closed correctly.

Returns -1 (<---Attention!!!) if the filearray is correct otherwise the error message is printed to STOUT and the number of the line that contains the error is returned by the function.

Parameters:

(+) $ref_file_array: A reference to the array that holds the content of the configuration file


expand_include

$found_include = Filesys::expand_include($ref_file_array)

Expand the referenced filearray by inlining the files that are mentioned inside of an ``<<<INCLUDE_FILE::....>>>'' statement.

This function returns 0 if no INCLUDE statement was found or the number of the (recursively) found INCLUDE statement

Parameters:

(+) $ref_file_array: A reference to the array that holds the content to be expanded


mask_string

$resut_string = Filesys::mask_string($source_string)

Masks the given string. Characters that are special for e:doc like ``, <, >, :, %, #, |, \, = are masked with a backslash before it.

This function returns the result string.

Parameters:

(+) $source_string: The string to be masked


unmask_string

$resut_string = Filesys::unmask_string($source_string)

Unmasks the given string. masked characters like \`` \< \> \: \% \# \| \= \\ are unmasked again.

This function returns the result string.

Parameters:

(+) $source_string: The string to be masked


build_start_tag

$tag = Filesys::build_start_tag($block_name);

Builds up the start-tag of the given block.

This function returns the tag.

Parameters:

(+) $block_name: The name of the block


build_end_tag

$tag = Filesys::build_end_tag($block_name);

Builds up the end-tag of the given block.

This function returns the tag.

Parameters:

(+) $block_name: The name of the block


string_contains_tag

$tag = Filesys::string_contains_tag($string);

Checks for the existance of a tag in the given string.

Returns 0 if no tag is inside the string or a reference to an anonymous hash that holds the following result parameters:

$result->{'block_name'} contains the name of the block that was found

$result->{'tag_type'} = 'start' if its an start-tag

$result->{'tag_type'} = 'end' if its an end-tag

Parameters:

(+) $string: The string to be searched for a tag


get_block_range

$tag = Filesys::get_block_range($ref_filearray, $blockname);

Gets the arrayindexes of the lines the block spans.

Returns 0 if no tag is inside the string or a reference to an anonymous hash that holds the following result parameters:

$result->{'start_index'} contains startindex of the block

$result->{'end_index'} contains endindex of the block

Parameters:

(+) $ref_filearray: A reference to the filearray

(+) $blockname: The name of the block


KNOWN BUGS:


STILL MISSING: