NAME

Zoidberg::StringParser - Simple string parser

SYNOPSIS

        my $base_gram = {
            esc => '\\',
            quotes => {
                q{"} => q{"},
                q{'} => q{'},
            },
        };

        my $parser = Zoidberg::StringParser->new($base_gram);

        my @blocks = $parser->split(
            qr/\|/, 
            qq{ls -al | cat > "somefile with a pipe | in it"} );

        # @blocks now is: 
        # ('ls -al ', ' cat > "somefile with a pipe | in it"');
        # So it worked like split, but it respected quotes

DESCRIPTION

This module is a simple syntax parser. It originaly was designed to work like the built-in split function, but to respect quotes. The current version is a little more advanced: it uses user defined grammars to deal with delimiters, an escape char, quotes and braces.

Yes, I know of the existence of Text::Balanced, but I wanted to do this the hard way :)

All grammars and collections of grammars should be considered PRIVATE when used by a Z::SP object.

EXPORT

None by default.

GRAMMARS

TODO

esc

FIXME

Collection

The collection hash is simply a hash of grammars with the grammar names as keys. When a collection is given all methods can use a grammar name instead of a grammar.

Base grammar

This can be seen as the default grammar, to use it leave the grammar undefined when calling a method. If this base grammar is defined and you specify a grammar at a method call, the specified grammar will overload the base grammar.

METHODS

new(\%base_grammar, \%collection, \%settings)

Simple constructor. See "Collection", "Base grammar" and "settings" for explanation of the arguments.

split($grammar, $input, $int)

Splits $input as specified by $grammar,

$input can be either a string or a reference to an array of strings. Such a array reference is used as provided, so it should be possible to use for example tied arrays here.

$int is an optional arguments specifying the maximum number of parts the input should be splitted in. Remaining strings are joined and returned as the last part. If you use a grammar with named tokens these are not counted as a part of the string.

Blocks will by default be passed as scalar refs (unless the grammar's meta function altered them) and tokens as scalars. To be a little compatible with CORE::split all items (blocks and tokens) are passed as plain scalars if $grammar is or was a Regexp reference. ( This behaviour can be faked by giving your grammr a value called 'was_regexp'. ) This behaviour is turned off by the "no_split_intel" setting.

settings

The %settings hash contains options that control the general behaviour of the parser. Supported settings are:

allow_broken

If this value is set the parser will not throw an exception if for example an unmatched quote occurs

no_esc_rm

Boolean that tells the parser not to remove the escape char when an escaped token is encountered. Double escapes won't be replaced either. Usefull when a string needs to go through a chain of parsers.

no_split_intel

Boolean, disables "intelligent" behaviour of split() when set.

AUTHOR

Jaap Karssenberg || Pardus [Larus] <pardus@cpan.org>

Copyright (c) 2011 Jaap G Karssenberg and Joel Berger. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Contains some code derived from Tie-Hash-Stack-0.09 by Michael K. Neylon.

SEE ALSO

Zoidberg, Text::Balanced