NAME

Parrot::Pmc2c::Parser - PMC Parser

SYNOPSIS

    use Parrot::Pmc2c::Parser qw(
        parse_pmc
        extract_balanced
    );

Parrot::Pmc2c::Parser parses a pseudo-C syntax into a perl hash that is then dumped.

This package exports two subroutines on request only.

    $parsed_pmc_hash = parse_pmc($pmc2cMain, $filename);

Purpose: Parse PMC code and return a hash ref of pmc attributes.

Arguments: List of two arguments:

Return Values: Reference to a Parrot::Pmc2c::PMC object

Comments: Called by Parrot::Pmc2c::Dumper::dump_pmc().

    my ($preamble, $hdr_preamble, $pmcname, $flags, $parents, $pmcbody, $post, $chewed_lines)
        = parse_top_level(\$code);

Purpose: Extract a pmc signature from the code ref.

Argument: PMC file contents slurped by parse_pmc().

Return Values: List of eight elements:

the code found before the pmc signature;
the code declared to be the header preamble. will be included at the start of the header.
the name of the pmc
a hash ref containing the flags associated with the pmc (such as extends and provides).
the list of parents this pmc extends
the body of the pmc
the code found after the pmc body
number of newlines in the pmc signature that need to be added to the running total of lines in the file

Comments: Called internally by parse_pmc().

    my ($flags, $parents) = parse_flags($attributes, $pmcname);

Purpose: Extract a pmc signature from the code ref.

Argument: PMC file contents slurped by parse_pmc().

Return Values: List of two elements:

a hash ref containing the flags associated with the pmc (such as extends and provides).
the list of parents this pmc extends

Comments: Called internally by parse_top_level().

    ($pmcbody, $post) = extract_balanced($code);

Purpose: Remove a balanced {} construct from the beginning of $code. Return it and the remaining code.

Argument: The code ref which was the first argument provided to parse_pmc().

Return Values: List of two elements:

String beginning with { and ending with }. In between is found C code where the comments hold strings of Perl comments written in POD.
String holding the balance of the code. Same style as first element, but without the braces.

Comments: Called twice within parse_pmc(). Will die with error message Badly balanced if not balanced.

    $attrs = parse_method_attrs($method_attributes);

Purpose: Parse a list of method attributes and return a hash ref of them.

Arguments: String captured from regular expression.

Return Values: Reference to hash of attribute values.

Comments: Called within parse_pmc().