NAME

Class::ParseText::Base - Base class for modules using Parse::RecDescent parsers

SYNOPSIS

    package My::Parser;
    use strict;
    
    use base qw(Class::ParseText::Base);
    
    # you need to provide an init method, to set the parser and start rule
    sub init {
        my $self = shift;
        
        # set the parser and start rule that should be used
        $self->{parser} = Parse::RecDescent->new($grammar);
        $self->{start_rule} = 'foo';
        $self->{ensure_newline} = 1;
        
        return $self;
    }
    
    package main;
    
    my $p = My::Parser->new;
    
    $p->parse_text($source_text);
    $p->parse(\$source_text);
    
    $p->parse_array(@source_lines);
    $p->parse(\@source_lines);
    
    $p->parse_file($filename);
    $p->parse($filename);

REQUIRES

This base class is in turn based on Class::Base.

DESCRIPTION

All of the parse rules set $self->{built} to false, to indicate that a fresh source has been read, and (probably) needs to be analyzed.

new

    my $p = My::Parser->new;

Creates a new parser object. In general, calling new explicitly is not necessary, since all of the parse methods will invoke the constructor for you if they are called as a class method.

    # as a class method
    my $p = My::Parser->parse_file('some_source.txt');

parse_file

    $p->parse_file($filename);

Parses the contents of of the file $filename. Returns the parser object.

parse_handle

    $p->parse_handle($fh);

Slurps the remainder of the file handle $fh and parses the contents. Returns the parser object.

parse_array

    $p->parse_array(@lines);

Joins @lines with newlines and parses. Returns the parser object.

parse_text

    $p->parse_text($source);

Parse the literal $source. Returns the parser object.

parse

    $p->parse($src);

Automagic method that tries to pick the correct parse_* method to use.

    ref $src            method
    ========            ==================
    ARRAY               parse_array(@$src)
    SCALAR              parse_text($$src)
    undef               parse_file($src)

Passing other ref types in $src (e.g. HASH) will cause parse to die.

SUBCLASSING

This class is definitely intended to be subclassed. The only method you should need to override is the init method, to set the parser object that will do the actual work.

init

The following properties of the object should be set:

parser

The Parse::RecDescent derived parser object to use.

start_rule

The name of the initial rule to start parsing with. The results of the parse are stored in the object with this same name as their key.

ensure_newline

Set to true to ensure that the text to be parsed ends in a newline.

Be sure that you explicitly return the object! This is a bug that has bitten me a number of times.

TODO

parse_handle method

Expand to use other sorts of parsing modules (e.g. Parse::Yapp)

AUTHOR

Peter Eichman, <peichman@cpan.org>

COPYRIGHT AND LICENSE

Copyright ©2005 by Peter Eichman.

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

cpanm Text::FormBuilder

perl -MCPAN -e shell
install Text::FormBuilder