Package: Filesys
use lib::Filesys;
The file Filesys.pm is located in the subdirectory './lib'
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.
Coding: 90%
Documentation: up-do-date
@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
$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
@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.
@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.
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)
%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
%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
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)
$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)
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)
@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: '||')
$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: '||')
$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
$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
$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
$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
$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
$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
$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
$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