/ 
Rakudo-Star-2012.08_000
2 ++
/ Parrot::Pmc2c::Emitter

NAME

Parrot::Pmc2c::Emitter

SYNOPSIS

    use Parrot::Pmc2c::Emitter ();

DESCRIPTION

This package provides various methods for composing parts of files created by parsing PMCs. Its methods are called by several other packages under lib/Parrot/Pmc2c/, all of which are ultimately run during the many instances of tools/build/pmc2c.pl invoked during the make build process.

PUBLIC METHODS

new()

  • Purpose

    Parrot::Pmc2c::Emitter constructor.

  • Arguments

        Parrot::Pmc2c::Emitter->new( 'path/to/file' );

    String holding relative path to file to be written.

  • Return Value

    Parrot::Pmc2c::Emitter object.

  • Comment

    The method's argument is, in practice, the return value of a method call. Examples:

        # lib/Parrot/Pmc2c/PMC.pm
    my $c_emitter = Parrot::Pmc2c::Emitter->new( $self->filename(".c") );
    my $h_emitter = Parrot::Pmc2c::Emitter->new( $self->filename(".h", $self->is_dynamic) );

    # lib/Parrot/Pmc2c/PCCMETHOD.pm
    my $e = Parrot::Pmc2c::Emitter->new( $pmc->filename );

text()

  • Purpose

    This, in effect, is a different type of constructor from new(). It takes up to three arguments and returns an object with a more complex structure.

  • Arguments

    List of one to three strings:

    1 body
    2 filename
    3 bline

    Examples:

        # lib/Parrot/Pmc2c/PMC.pm
    body => Parrot::Pmc2c::Emitter->text($body),

    # lib/Parrot/Pmc2c/Parser.pm
    $pmc->preamble( Parrot::Pmc2c::Emitter->text( $preamble, $filename, 1 ) );

    $pmc->postamble( Parrot::Pmc2c::Emitter->text( $post, $filename, $lineno ) );

    body => Parrot::Pmc2c::Emitter->text( $methodblock, $filename, $lineno ),

  • Return Value

    Parrot::Pmc2c::Emitter object, apparently suitable for using as value for a body key in a Parrot::Pmc2c::Method object. MUST VERIFY.

  • Comment

    Also currently (June 2012) used in lib/Parrot/Pmc2c/PMC/Null.pm, lib/Parrot/Pmc2c/PMC/Object.pm, lib/Parrot/Pmc2c/PMC/RO.pm and lib/Parrot/Pmc2c/PMC/default.pm.

find()

  • Purpose

    Recursively returns strings captured from pattern matches.

  • Arguments

    Single argument: compiled regular expression.

  • Return Value

    If a pattern is matched within a list of items, return the matching string. Return the object itself it the match is against the data element. Return a false value otherwise.

  • Comment

    Used in Parrot::Pmc2c::PCCMETHOD. Example:

        $matched = $body->find($signature_re);

subst()

  • Purpose

    Recursively perform substitutions.

  • Arguments

    List of two arguments:

    • Compiled regular expression.

    • Reference to a subroutine which performs a substitution on the string matched by the first argument's pattern.

  • Return Value

    True value.

  • Comment

    Used in Parrot::Pmc2c::Method. Some of these substitutions can be quite simple:

        $body->subst( qr{\bSELF\b},   sub { '_self' } );

    Others are more complex:

        # Rewrite STATICSELF.other_method(args...)
    $body->subst(
        qr{
      \bSTATICSELF\b    # Macro STATICSELF
      \.(\w+)           # other_method
      \(\s*(.*?)\)      # capture argument list
      }x,
        sub {
            "Parrot_${pmcname}"
                . ( $pmc->is_vtable_method($1) ? "" : "_nci" ) . "_$1("
                . full_arguments($2) . ")";
        }
    );

replace()

  • Purpose

  • Arguments

    List of two arguments:

    • Compiled regular expression.

    • Another Parrot::Pmc2c::Emitter object.

  • Return Value

    True value upon success.

  • Comment

    Used in Parrot::Pmc2c::PCCMETHOD::rewrite_RETURNs(). Example:

        $matched->replace( $match, $e );