NAME

FTN::Outbound::Reference_file - Object-oriented module for working with FTN reference files.

VERSION

version 20170409

SYNOPSIS

  use Log::Log4perl ();
  use Encode ();
  use FTN::Outbound::Reference_file ();

  Log::Log4perl -> easy_init( $Log::Log4perl::INFO );

  my $reference_file = FTN::Outbound::Reference_file -> new( '/var/lib/ftn/outbound/fidonet/00010001.flo',
                                                             sub {
                                                               Encode::decode( 'cp866', shift );
                                                             },
                                                             sub {
                                                               Encode::encode( 'cp866', shift );
                                                             },
                                                             "\x0d\x0a",
                                                           );

  $reference_file
    -> read_existing_file
    -> push_reference( '#', '/tmp/file_to_transfer' )
    -> write_file;

DESCRIPTION

FTN::Outbound::Reference_file module is for working with reference files in FTN following specifications from fts-5005.002 document.

OBJECT CREATION

new

  my $reference_file = FTN::Outbound::Reference_file -> new( 'filename',
                                                             sub {
                                                               Encode::decode( 'UTF-8', shift );
                                                             },
                                                             sub {
                                                               Encode::encode( 'UTF-8', shift );
                                                             },
                                                             chr( 0x0a ),
                                                           );

First parameter is a filename as a character string.

Second parameter is either undef (in case no reading from the file expected (means file does not exist)) or sub reference that takes octet string (read from the existing reference file) and returns character string. In simplest case does just decoding from some predefined character set used by your software. Also might do other transformations. For example if other software uses relative path, this is the place where you transform it to absolute path by some rules. Output result used only in memory processing and won't be written to the file.

Third parameter is either undef (in case no updates expected) or sub reference that takes character string and returns octet stream that will be written to the file. Used only by push_reference method.

Forth parameter defines line joiner as standard allows two of them. If not defined or omitted will be either figured out from existing file (if possible) or character with code 0x0a will be used.

FILE READ/WRITE

read_existing_file

Method for explicit reading of existing file. If file exists, this method has not been called and you're trying to update or write file it will be called implicitly before that.

Does not expect any arguments.

If file exists and isn't empty it will be read and each line will be passed to the sub reference which was passed as second parameter to the constructor.

Returns itself for method chaining.

write_file

Method for writing content from memory to the file. Does not need any parameters. If file exists and its content in memory is empty, it will be deleted.

Returns itself for method chaining.

CONTENT ACCESS

referenced_files

Returns list of hash references describing referenced files in list content. In scalar content returns array reference.

Each hash has fields:

  octet_line_in_reference_file - original line from the file or result returned by third parameter (sub reference) for constructor during push_reference method call.  This is the value that will be written by write_file method call

  character_line_in_reference_file - line that was returned by second parameter (sub reference) for constructor during existing file read or possibly prefixed second argument for push_reference

  full_name - character line without prefix

There might be other fields:

  prefix - if there is one

  size - size in bytes if file existed during read_existing_file or push_reference method call

  mstat - last modify time in seconds since the epoch if file existed during read_existing_file or push_reference method call

CONTENT MODIFICATION

process_lines

Method expects one parameter - function reference. That function will be called for each line in reference file with one parameter - hash reference with all details about the referenced file. Function can change/update fields - they are actual values, not a copy.

Function return value is very important. If it is false then this line will be removed from the memory and after write_file call from the actual file. If return value is true then line stays.

Method returns number of lines removed.

push_reference

Expects referenced filename as a character string. If prefix [-#^~!@] needed, it should be defined as first parameter and filename as second parameter.

Returns itself for method chaining.

cpanm FTN::Outbound::Reference_file

perl -MCPAN -e shell
install FTN::Outbound::Reference_file