/ 
Text-Parser-0.916
River stage zero No dependents
/ Text::Parser::Multiline

NAME

Text::Parser::Multiline - Adds multi-line support to the Text::Parser object.

VERSION

version 0.916

SYNOPSIS

use Text::Parser;

my $parser = Text::Parser->new(multiline_type => 'join_last');
$parser->read('filename.txt');
print $parser->get_records();
print scalar($parser->get_records()), " records were read although ",
    $parser->lines_parsed(), " lines were parsed.\n";

RATIONALE

Some text formats allow users to split a single line into multiple lines, with a continuation character in the beginning or in the end, usually to improve human readability.

This extension allows users to use the familiar save_record interface to save records, as if all the multi-line text inputs were joined.

OVERVIEW

To handle these types of text formats with the native Text::Parser class, the derived class would need to have a save_record method that would:

  • Detect if the line is continued, and if it is, save it in a temporary location. To detect this, the developer has to implement a function named is_line_continued.

  • Keep appending (or joining) any continued lines to this temporary location. For this, the developer has to implement a function named join_last_line.

  • Once the line continuation has stopped, create and save a data record. The developer needs to write this the same way as earlier, assuming that the text is already joined properly.

It should also look for the following error conditions (see Text::Parser::Errors):

  • If the end of file is reached, and the line is expected to be still continued.

  • If the first line in a text input happens to be a continuation of a previous line, that is impossible, since it is the first line

To create a multi-line text parser you need to determine if your parser is a 'join_next' type or a 'join_last' type.

METHODS TO BE IMPLEMENTED

These methods must be implemented by the developer. There are default implementations provided in Text::Parser but they do nothing.

$parser->is_line_continued($line)

Takes a string argument as input. Should returns a boolean that indicates if the current line is continued from the previous line, or is continued on the next line (depending on the type of multi-line text format). If parser is a 'join_next' parser, then a true value from this routine means that some data is expected to be in the next line which is expected to be joined with this line. If instead the parser is 'join_last', then a true value from this method would mean that the current line is a continuation from the previous line, and the current line should be appended to the content of the previous line.

$parser->join_last_line($last_line, $current_line)

Takes two string arguments. The first is the line previously read which is expected to be continued on this line. You can be certain that the two strings will not be undef. Your method should return a string that has stripped any continuation characters, and joined the current line with the previous line.

BUGS

Please report any bugs or feature requests on the bugtracker website http://github.com/balajirama/Text-Parser/issues

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

AUTHOR

Balaji Ramasubramanian <balajiram@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2018-2019 by Balaji Ramasubramanian.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.