NAME

    XS::Parse::Keyword::FromPerl - drive XS::Parse::Keyword directly from
    Perl

DESCRIPTION

    This module provides a Perl-visible API wrapping (some of) the
    functionality provided by XS::Parse::Keyword, allowing extension
    keywords to be added to the Perl language by writing code in Perl
    itself.

    It provides a thin wrapping layer over the XS functions provided by XPK
    itself. No real attempt is made here to provide further abstractions on
    top of the API already provided by Perl and XPK, so users will have to
    be familiar with the overall concepts there as well.

    This module is currently experimental, on top of the
    already-experimental nature of XS::Parse::Keyword itself.

OPTREE FUNCTIONS

    The Optree::Generate module contains a selection of helper functions to
    allow Perl code to get access to various parts of the C-level API that
    would be useful when building optrees for keywords. They used to be
    part of this module, and so are currently re-exported for convenience,
    but a later version of this module may start emitting warnings when
    they are used this way, and eventually that may stop being provided at
    all.

    Code needing these should import them directly:

       use Optree::Generate qw( opcode newUNOP ... );

XPK FUNCTIONS

 register_xs_parse_keyword

       register_xs_parse_keyword "name" => %args;

    Registers a new extension keyword into the XS::Parse::Keyword registry,
    defined using the given name and arguments.

    Takes the following named arguments:

    flags => INT

      Optional. If present, a bitmask of the following flag constants:

      XPK_FLAG_EXPR

	The build phase is expected to return KEYWORD_PLUGIN_EXPR.

      XPK_FLAG_STMT

	The build phase is expected to return KEYWORD_PLUGIN_STMT.

      XPK_FLAG_AUTOSEMI

	The syntax forms a complete statement, which should be followed by
	;.

    pieces => ARRAY

      Optional. If present, contains definitions for the syntax pieces to
      be parsed for the syntax of this keyword. This must be composed of a
      list of calls to the various XPK_... piece-generating functions;
      documented below.

    permit_hintkey => STRING

      Optional. A string value to use for the "permit_hintkey".

    permit => CODE

      Optional. Callback function for the "permit" phase of keyword
      parsing.

         $ok = $permit->( $hookdata );

      When invoked, it is passed a single arugment containing the
      (optional) hookdata value, and its result should be a boolean scalar.

      At least one of permit_hintkey or permit must be provided.

    check => CODE

      Optional. Callback function for the "check" phase of keyword parsing.

         $check->( $hookdata );

      When invoked, it is passsed a single argument containing the
      (optional) bookdata value.

    build => CODE

      Callback function for the "build" phase of keyword parsing.

         $ret = $build->( \$out, \@args, $hookdata );

      When invoked, it is passed a SCALAR ref to store the output optree
      into, an ARRAY reference containing the parsed arguments, and the
      (optional) hookdata value.

      The @args array will contain object references referring to the
      individual arguments parsed by the parser pieces. See "Parser
      Arguments".

      The callback function should be build an optree as a B::OP fragment,
      possibly by calling the various new*OP() functions defined above, and
      store the eventual result into the scalar referred to by the first
      argument.

      The callback should return one of KEYWORD_PLUGIN_EXPR or
      KEYWORD_PLUGIN_STMT to indicate how its syntax should be interpreted
      by the perl parser.

    hookdata => SCALAR

      Optional. If present, this scalar value is stored by the keyword
      definition and passed into each of the phase callbacks when invoked.
      If not present then undef will be passed to the callbacks instead.

 Piece Type Functions

    The following functions can be used to generate parsing pieces.

    Many simple piece types have an variant which is optional; if the input
    source does not look like the expected syntax for the piece type then
    it will emit undef rather than raise an error. These piece types have
    their names suffixed by _OPT.

  XPK_BLOCK

    A block of code, returned in the op field.

  XPK_ANONSUB

    An anonymous subroutine, returned in the cv field.

  XPK_ARITHEXPR, XPK_ARITHEXPR_OPT

    An arithemetic expression, returned in the op field.

  XPK_TERMEXPR, XPK_TERMEXPR_OPT

    A term expression, returned in the op field.

  XPK_LISTEXPR, XPK_LISTEXPR_OPT

    A list expression, returned in the op field.

  XPK_IDENT, XPK_IDENT_OPT

    An identifier, returned as a string in the sv field.

  XPK_PACKAGENAME, XPK_PACKAGENAME_OPT

    A package name, returned as a string in the sv field.

  XPK_LEXVARNAME

       XPK_LEXVARNAME($kind)

    A lexical variable name, returned as a string in the sv field.

    The $kind must be a bitmask of XPK_LEXVAR_SCALAR, XPK_LEXVAR_ARRAY,
    XPK_LEXVAR_HASH; or XPK_LEXVAR_ANY for convenience to set all three.

  XPK_VSTRING, XPK_VSTRING_OPT

    A version string, returned as a version object instance in the sv
    field.

  XPK_LEXVAR

       XPK_LEXVAR($kind)

    A lexical variable that already exists in the pad, returned as a pad
    offset in the padix field.

    $kind is specified as in XPK_LEXVARNAME.

  XPK_LEXVAR_MY

       XPK_LEXVAR_MY($kind)

    A lexical variable, parsed as if it appeared in a my expression. It
    will be added to the pad and returned as a pad offset in the padix
    field.

  XPK_COMMA

  XPK_COLON

  XPK_EQUALS

    A literal comma, colon or equals sign. These do not appear in the
    arguments list.

  XPK_LITERAL

       XPK_LISTEXPR($string)

    A literal string match. No value is returned.

    This should be avoided if at all possible, in favour of the character
    matches above, or XPK_KEYWORD.

  XPK_KEYWORD

       XPK_KEYWORD($string)

    A literal string match, which requires that the following text does not
    begin with an identifier character (thus avoiding prefix-match
    problems). No value is returned.

  XPK_INTRO_MY

    Calls the perl intro_my() function immediately. No input is consumed
    and no output value is generated.

  XPK_WARNING

       XPK_WARNING($message)

    Emits a warning by callling the core perl warn() function immediately.

  XPK_WARNING_...

       XPK_WARNING_AMBIGUOUS($message)
       XPK_WARNING_DEPRECATED($message)
       XPK_WARNING_EXPERIMENTAL($message)
       XPK_WARNING_PRECEDENCE($message)
       XPK_WARNING_SYNTAX($message)

    Several variants of "XPK_WARNING" that are conditional on various
    warning categories being enabled.

  XPK_SEQUENCE

       XPK_SEQUENCE(@pieces)

    A sub-sequence. Normally this is not necessary, as most of the
    structure-forming functions already take a sequence of pieces. It is
    mostly useful as as an option to the XPK_CHOICE function.

    Nothing extra is returned, beyond the values from the individual
    pieces.

  XPK_OPTIONAL

       XPK_OPTIONAL(@pieces)

    An optional sequence of pieces that may or may not be present. Returns
    an integer value in the i field of 0 if the sequence was not found, or
    1 followed by its values if the sequence was found.

  XPK_REPEATED

       XPK_REPEATED(@pieces)

    A repeating sequence of pieces. Returns an integer value in the i field
    indicating how many times the sequence repeated, followed by all the
    values returned by each.

  XPK_CHOICE

       XPK_CHOICE(@pieces)

    The pieces of this function are not interpreted as a sequence, but
    instead as a list of possible choices. Returns an integer value in the
    i field indicating which choice was found, followed by all the values
    returned by that sequence.

    The first possible choice is numbered 0. If no choice matched, it
    returns -1. To cause an error instead, use XPK_FAILURE.

  XPK_FAILURE

       XPK_FAILURE($message)

    Attempting to parse this piece type will immediately cause a
    compile-time failure with the given message. This can be used as the
    final option in XPK_CHOICE to ensure a valid match.

  XPK_PARENS

       XPK_PARENS(@pieces)

    Expects to find a sequence of pieces, all surrounded by parentheses
    (round brackets, ( ... )).

    Nothing extra is returned, beyond the values from the individual
    contained pieces.

  XPK_ARGS

       XPK_ARGS(@pieces)

    A container similar to XPK_PARENS except that the parentheses
    themselves are optional, similar to perl's parsing of calls to known
    functions.

  XPK_BRACKETS

       XPK_BRACKETS(@pieces)

    Expects to find a sequence of pieces, all surrounded by square brackets
    ([ ... ]).

    Nothing extra is returned, beyond the values from the individual
    contained pieces.

  XPK_BRACES

       XPK_BRACES(@pieces)

    Expects to find a sequence of pieces, all surrounded by braces ({ ...
    }).

    Nothing extra is returned, beyond the values from the individual
    contained pieces.

  XPK_CHEVRONS

       XPK_CHEVRONS(@pieces)

    Expects to find a sequence of pieces, all surrounded by chevrons (angle
    brackets, < ... >).

    Nothing extra is returned, beyond the values from the individual
    contained pieces.

 Parser Arguments

    Each of the values given in the @args array for the "build" phase
    callback are given as object references having the following methods

  op

       $op = $arg->op;

    Returns an optree.

  cv

       $cv = $arg->cv;

    Returns a CV wrapped in a CODE reference.

  sv

       $sv = $arg->sv;

    Returns the SV itself, or undef if the optional SV was absent.

  has_sv

       $ok = $arg->has_sv;

    Returns true if the optional SV was present (even if it was undef), or
    false if it was absent.

  i

       $i = $arg->i;

    Returns an integer.

  padix

       $padix = $arg->padix;

    Returns a pad offset index as an integer.

  line

       $line = $arg->line;

    Returns the line number of the source text on which the piece was
    started.

AUTHOR

    Paul Evans <leonerd@leonerd.org.uk>