=encoding utf8

=head1 NAME

Pegex::Input - Pegex Parser Input Abstraction

=head1 SYNOPSIS

This:

    use Pegex;
    use Pegex::Input;
    my $ast = pegex(Pegex::Input->new(file => 'foo-grammar-file.pgx'))
        ->parse(Pegex::Input->new(string => $foo_input));

is the long way to do this:

    use Pegex;
    my $ast = pegex('foo-grammar-file.pgx')->parse($foo_input);

=head1 DESCRIPTION

Pegex::Parser parses input. The input can be a string, a string reference, a
file path, or an open file handle. Pegex::Input is an abstraction over any
type of input. It provides a uniform inteface to the parser.

It also give the end user total control, when it is needed. In the rare case
when you need to have Pegex parse a string that happens to be a filename,
you'll need to use a Pegex::Input object.

=head1 USAGE

There are 2 ways to create a Pegex::Input object. You can call new() with two
arguments, where the first argument is the input type:

    Pegex::Input->new(file => 'file.txt')

or you can call new() with no type specifier and let it guess.

    Pegex::Input->new($somesuch)

The second form is usually used internally when you call a Pegex facility,
like these:

    pegex($somesuch)->parse($someothersuch);
    Pegex::Grammar::Foo->parse($somefoo);

It is nice syntax to not need to specify the type when it is obvious.
Sometimes it is not obvious and you need to use Pegex::Input directly:

    pegex(Pegex::Input(file => $somesuch))
        ->parse(Pegex::Input->new(stringref => $someothersuch));
    Pegex::Grammar::Foo->parse(Pegex::Input->new(handle => $somefoo));

If you do specify the type, use one of these:

=over

=item string

Input is a string.

=item stringref

Input is a string reference. This may be desirable for really long strings.

=item file

Input is a file path name to be opened and read.

=item handle

Input is from a opened file handle, to be read.

=back

=head1 AUTHOR

Ingy döt Net <ingy@cpan.org>

=head1 COPYRIGHT AND LICENSE

Copyright (c) 2011. Ingy döt Net.

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

See http://www.perl.com/perl/misc/Artistic.html

=cut
