/ 
Rakudo-Star-2012.08002
/ 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 );