.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "PPI::Lexer 3pm"
.TH PPI::Lexer 3pm 2024-03-16 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
PPI::Lexer \- The PPI Lexer
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&  use PPI;
\&  
\&  # Create a new Lexer
\&  my $Lexer = PPI::Lexer\->new;
\&  
\&  # Build a PPI::Document object from a Token stream
\&  my $Tokenizer = PPI::Tokenizer\->load(\*(AqMy/Module.pm\*(Aq);
\&  my $Document = $Lexer\->lex_tokenizer($Tokenizer);
\&  
\&  # Build a PPI::Document object for some raw source
\&  my $source = "print \*(AqHello World!\*(Aq; kill(Humans\->all);";
\&  $Document = $Lexer\->lex_source($source);
\&  
\&  # Build a PPI::Document object for a particular file name
\&  $Document = $Lexer\->lex_file(\*(AqMy/Module.pm\*(Aq);
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
The is the PPI Lexer. In the larger scheme of things, its job is to take
token streams, in a variety of forms, and "lex" them into nested structures.
.PP
Pretty much everything in this module happens behind the scenes at this
point. In fact, at the moment you don't really need to instantiate the lexer
at all, the three main methods will auto-instantiate themselves a
\&\f(CW\*(C`PPI::Lexer\*(C'\fR object as needed.
.PP
All methods do a one-shot "lex this and give me a PPI::Document object".
.PP
In fact, if you are reading this, what you \fBprobably\fR want to do is to
just "load a document", in which case you can do this in a much more
direct and concise manner with one of the following.
.PP
.Vb 1
\&  use PPI;
\&  
\&  $Document = PPI::Document\->load( $filename );
\&  $Document = PPI::Document\->new( $string );
.Ve
.PP
See PPI::Document for more details.
.PP
For more unusual tasks, by all means forge onwards.
.SH METHODS
.IX Header "METHODS"
.SS new
.IX Subsection "new"
The \f(CW\*(C`new\*(C'\fR constructor creates a new \f(CW\*(C`PPI::Lexer\*(C'\fR object. The object itself
is merely used to hold various buffers and state data during the lexing
process, and holds no significant data between \->lex_xxxxx calls.
.PP
Returns a new \f(CW\*(C`PPI::Lexer\*(C'\fR object
.ie n .SS "lex_file $filename"
.el .SS "lex_file \f(CW$filename\fP"
.IX Subsection "lex_file $filename"
The \f(CW\*(C`lex_file\*(C'\fR method takes a filename as argument. It then loads the file,
creates a PPI::Tokenizer for the content and lexes the token stream
produced by the tokenizer. Basically, a sort of all-in-one method for
getting a PPI::Document object from a file name.
.PP
Returns a PPI::Document object, or \f(CW\*(C`undef\*(C'\fR on error.
.ie n .SS "lex_source $string"
.el .SS "lex_source \f(CW$string\fP"
.IX Subsection "lex_source $string"
The \f(CW\*(C`lex_source\*(C'\fR method takes a normal scalar string as argument. It
creates a PPI::Tokenizer object for the string, and then lexes the
resulting token stream.
.PP
Returns a PPI::Document object, or \f(CW\*(C`undef\*(C'\fR on error.
.ie n .SS "lex_tokenizer $Tokenizer"
.el .SS "lex_tokenizer \f(CW$Tokenizer\fP"
.IX Subsection "lex_tokenizer $Tokenizer"
The \f(CW\*(C`lex_tokenizer\*(C'\fR takes as argument a PPI::Tokenizer object. It
lexes the token stream from the tokenizer into a PPI::Document object.
.PP
Returns a PPI::Document object, or \f(CW\*(C`undef\*(C'\fR on error.
.SS errstr
.IX Subsection "errstr"
For any error that occurs, you can use the \f(CW\*(C`errstr\*(C'\fR, as either
a static or object method, to access the error message.
.PP
If no error occurs for any particular action, \f(CW\*(C`errstr\*(C'\fR will return false.
.SH "TO DO"
.IX Header "TO DO"
\&\- Add optional support for some of the more common source filters
.PP
\&\- Some additional checks for blessing things into various Statement
and Structure subclasses.
.SH SUPPORT
.IX Header "SUPPORT"
See the support section in the main module.
.SH AUTHOR
.IX Header "AUTHOR"
Adam Kennedy <adamk@cpan.org>
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright 2001 \- 2011 Adam Kennedy.
.PP
This program is free software; you can redistribute
it and/or modify it under the same terms as Perl itself.
.PP
The full text of the license can be found in the
LICENSE file included with this module.