NAME

       Devel::Declare::Parser - Higher level interface to Devel-Declare

DESCRIPTION

       Devel-Declare-Parser is a higher-level API sitting on top of Devel::Declare.  It is used
       by Devel::Declare::Exporter to simplify exporting of Devel::Declare magic. Writing custom
       parsers usually only requires subclassing this module and overriding a couple methods.

DOCUMENTATION

       Devel::Declare::Interface
           This is the primary interface for those who want to use Devel-Declare-Parser magic,
           and don't wantto use Exporter-Declare.

       Devel::Declare::Parser
           This Document covers the API for Devel::Declare::Parser. This API is a useful
           reference when writing or modifying a custom parser.

SYNOPSIS

           package Devel::Declare::Parser::MyParser;
           use strict;
           use warnings;

           use base 'Devel::Declare::Parser';
           use Devel::Declare::Interface;

           # Create an accessor (See INTERNALS WARNING below)
           __PACKAGE__->add_accessor( 'my_accessor' );

           # Register the parser for use.
           Devel::Declare::Interface::register_parser( 'myparser' );

           # Override the rewrite() method to take the parsed bits (parts) and put the
           # ones you want into new_parts.
           sub rewrite {
               my $self = shift;

               my $parts = $self->parts;

               $new_parts = $self->process_parts( $parts );

               $self->new_parts( $new_parts );
               1;
           }

           1;

OVERVIEW

       This is a brief overview of how a parser is used.

   WORKFLOW
       Parser is constructed
           Name, Declarator, and Offset are provided by Devel::Declare.

       The process() method is called
           The process method calls all of the following in sequence, if any returns false,
           process() will return.

           pre_parse()
                   Check if we want to process the line at all.

           parse() Turn the line into 'parts' (see below).

           post_parse()
                   Hook, currently does nothing.

           rewrite()
                   Hook, currently takes all the arguments between the declarator and the
                   codeblock/semicolon (which have been turned into 'parts' structures in the
                   parts() attribute) and puts them into the new_parts() attribute.

                   This is usually the method you want to override.

           write_line()
                   Opens, fills in, and closes the line as a string, then rewrites the actual
                   line using Devel::Declare.

           edit_line()
                   Hook, currently does nothing.

   "PARTS"
       'Parts' are datastructures created by the parse() method. Every argument on the line
       (space separated) up until an opening curly brace ({) or a semicolon (;) will be turned
       into a part. Here are the parts to expect:

       Parts will either be a plain string, or an arrayref containing a string and the quote
       character used to define the string. "String" or [ "String", '"' ].  Variables and
       operators (excluding those containing only string characters) are typically the only parts
       left in a plain string form.

       See the format_parts() method for an easy way to get what you need from a 'part'
       datastructure.

       Bareword or Package Name
           A barword name is anythign that starts with [a-zA-z] and contains only alpha-numerics
           plus underscore. It is also not quoted. Examples include my_name, something5, etc.

           The structure will be an arrayref, the first element will be the string form of the
           bareword name, the second element will be undef.

           Example:

               # my_keyword My::Package;
               $part = [
                   'My::Package',
                   undef,
               ];

               # my_keyword some_name;
               $part = [
                   "some_name",
                   undef,
               ];

       Quoted or Enclosed Element
           A quoted or enclosed element includes strings quoted with single or double quotes, and
           text contained within opening and closing brackets, braces or parens (excluding the
           curly brace '{').

           Example Structures:

               # my_keyword "double quoted string";
               $part = [
                   'double quoted string',
                   '"',
               ];

               # my_keyword 'single quoted string';
               $part = [
                   'double quoted string',
                   '"',
               ];

               # my_keyword ... ( a => 'b', c => 'd' );
               $part = [
                   " a => 'b', c => 'd' ",
                   "(",
               ];

       Variable or Operator
           Anything starting with a non-alphanumeric, non-quoting character will be placed as-is
           (not interpolated) into a string. This catches most variables and operators, the
           exception are alpha-numeric operators such as 'eq', 'gt', 'cmp', etc. Eventually I
           plan to add logic to catch all oeprators, but it appears I will have to hard-code
           them.

               # my_keyword $variable
               $part = '$variable';

               # my_keyword <=>
               $part = '<=>';

   EVENTUAL OUTPUT
       Parser is designed such that it will transform any and all uses of your keyword into
       proper function calls.

       That is this:

           function x { ... }

       Will become this:

           function( 'x', sub { ... });

       Note Parser does not read in the entire codeblock, rather it injects a statement into the
       start of the block that uses a callback to attach the ');' to the end of the statement.
       This is per the documentation of Devel::Declare. Reading in the entire sub is not a
       desirable scenario.

DEVEL-DECLARE-PARSER API

   INTERNALS WARNING
       Parser objects are blessed arrays, not hashrefs.

       If you want to create a new accessor use the add_accessor() class method. It will take
       care of assigning an unused array element to the attribute, and will create a read/write
       accessor sub for you.

           __PACKAGE__->add_accessor( 'my_accessor' );

       There are many public and private methods on the parser base class. Only the public
       methods are fully documented. Be sure to refer often to the list of private methods at the
       end of this document, accidently overriding a private method could have devestating
       consequences.

   CLASS METHODS
       $class->new( $name, $declarator, $offset )
           The constructor, "DO NOT OVERRIDE THIS!"

       $class->DEBUG($bool)
           Turn debugging on/off. This will output the line after it has been modified, as well
           as some context information.

           NOTE: This has a global effect, all parsers will start debugging.

   UTILITY METHODS
       bail( @messages )
           Like croak, dies providing you context information. Since any death occurs inside the
           parser, carp provides useless information.

       diag( @message )
           Like carp, warns providing you context information. Since the warn occurs inside the
           parser carp provides useless information.

       end_quote($start_char)
           Find the end-character for the provide starting quote character. As in '{' returns '}'
           and '(' returns ')'. If there is no counter-part the start character is returned: "'"
           returns "'".

       filename()
           Filename the rewrite is occuring against.

       linenum()
           Linenum the rewrite is occuring on.

       format_part()
           Returns the stringified form of a part datastructure. For variables and operators that
           is just the item itself as a string. For barewords or package names it is the item
           itself with single quotes wrapped around it. For quoted items it is the string wrapped
           in its proper quoting characters. If a second parameter is provided (and true) no
           single quotes will be added to barewords.

   ACCESSORS
       These are the read/write accessors used by Parser. Not all of these act on an array
       element, some will directly alter the current line.

       line()
           This will retrieve the current line from Devel-Declare. If given a value, that value
           will be set as the current line using Devel-Declare.

       name()
           Name of the declarator as provided via the parser.

       declarator()
           Name of the declarator as provided via the Devel-Declare.

       original_offset()
           Offset on the line when the parsing was started.

       offset()
           Current line offset.

       parts()
           Arrayref of parts (may be undef)

       new_parts()
           Arrayref of new parts (may be undef)

       end_char()
           Will be set to the character just after the completely parsed line (usually '{' or
           ';')

       prototype()
           Used internally for prototype tracking.

       contained()
           True if the parser determined this was a contained call. This means your keyword was
           followed by an opening paren, and the statement ended with a closing paren and
           semicolon. By default Parser will not modify such lines.

   OVERRIDABLE METHODS
       These are methods you can, should, or may override in your baseclass.

       quote_chars()
           Specify the starting characters for quoted strings. (returns a list)

       end_chars()
           Characters to recognise as end of statement characters (';' and '{') (returns a list)

       inject()
           Code to inject into functions enhanced by this parser.

       pre_parse()
           Check if we want to process the line at all.

       parse()
           Turn the line into 'parts'.

       post_parse()
           Hook, currently does nothing.

       rewrite()
           Hook, currently takes all the arguments between the declarator and the
           codeblock/semicolon (which have been turned into 'parts' structures in the parts()
           attribute) and puts them into the new_parts() attribute.

           This is usually the method you want to override.

       write_line()
           Opens, fills in, and closes the line as a string, then rewrites the actual line using
           Devel::Declare.

       edit_line()
           Hook, currently does nothing.

       open_line()
           Usually returns '('. This is how to start a line following your keyword

       close_line()
           End the line, this means either re-inserting the opening '{' on the codeblock, along
           with any injections, or returning ');'

   POSITION TRACKING
       advance( $num_chars )
           Advances the offset by $num_chars.

       skip_declarator()
           Skips the declarator at the start of the line.

       skipspace()
           Advances the offset past any whitespace.

   LINE EXAMINATION (NON-MODIFYING)
       These are used by pre_parse() to examine the line prior to any modification.

       is_contained()
           True if the line is of the format:

               keyword( ... );

       is_arrow_contained()
           True if the line is of the format:

               keyword word_or_string => ( ... );

       is_defenition()
           True if the line matches the regex m/sub[\s\n]+$name/sm

   PART EXAMINATION
       These are methods that let you investigate the parts already parsed and placed in the
       parts() attribute.

       has_non_string_or_quote_parts()
           Returns a list of parts that are not strings, quotes, or barewords.

       has_string_or_quote_parts()
           Returns a list of parts that are strings, quotes, or barewords.

       has_keyword( $word )
           Check for a keyword in the parts

       has_comma()
       has_fat_comma()

   LINE EXAMINATION (MODIFYING)
       This examines the line returning part structures and removing elements from the line each
       time they are called.

       strip_item()
       strip_length()
       strip_remaining_items()

   LOOKING AHEAD
       These methods help the parser determine what comes next in a line. In most cases these are
       non-modifying.

       peek_is_block()
       peek_is_end()
       peek_is_other()
       peek_is_quote()
       peek_is_word()
       peek_item()
       peek_item_type()
       peek_num_chars()
       peek_other()
       peek_quote()
       peek_remaining()
       peek_word()

   PRIVATE METHODS
       Do not use these, and definitely do not override them in a subclass.

       _block_end_injection()
       _debug()
       _edit_block_end()
       _item_via_()
       _linestr_offset_from_dd()
       _move_via_()
       _peek_is_package()
       _peek_is_word()
       _quoted_from_dd()
       _scope_end()
       _stash()
       _unstash()

AUTHORS

       Chad Granum exodist7@gmail.com

COPYRIGHT

       Copyright (C) 2010 Chad Granum

       Devel-Declare-Parser is free software; Standard perl licence.

       Devel-Declare-Parser is distributed in the hope that it will be useful, but WITHOUT ANY
       WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
       PURPOSE.  See the license for more details.