Matt S Trout > Rakudo-Star-2012.08_001 > Parrot::Pmc2c::Pmc2cMain

Download:
Rakudo-Star-2012.08_001.tar.gz

Dependencies

Annotate this POD

Source  

NAME ^

Parrot::Pmc2c::Pmc2cMain - Functions called within tools/build/pmc2c.pl

SYNOPSIS ^

    use Parrot::Pmc2c::Pmc2cMain;

DESCRIPTION ^

Parrot::Pmc2c::Pmc2cMain holds subroutines called within tools/build/pmc2c.pl.

FUNCTIONS ^

Publicly Available Methods

new()

    $self = Parrot::Pmc2c::Pmc2cMain->new( {
        include => \@include,
        opt     => \%opt,
        args    => \@args,
    } );

Purpose: Parrot::Pmc2c::Pmc2cMain constructor.

Arguments: Reference to a hash holding 3 required keys:

Return Values: Parrot::Pmc2c::Pmc2cMain object. Will die with error message if arguments are defective.

Comment: Tested in: t/tools/pmc2cutils/01-pmc2cutils.t.

dump_vtable()

    $self->dump_vtable("$Bin/../../src/vtable.tbl");

Purpose: Create a .dump file for the default vtable (from which all PMCs inherit).

Arguments: Scalar holding filename of vtable.

Return Values: Scalar holding path to .dump file.

Comments: In earlier version of pmc2c.pl, this subroutine returned undef upon success. This was changed to more Perl-ish 1.

If the caller of this subroutine has chdir-ed to a tempdir before this subroutine is called -- as ought to be the case during testing of build tools -- then vtable.dump will be created within that tempdir. Otherwise, vtable.dump is created in the caller's working directory. When the caller is make, that directory is the top-level Parrot directory.

Tested in: t/tools/pmc2cutils/03-dump_vtable.t.

dump_pmc()

see lib/Parrot/Pmc2c/Dumper.

read_dump()

  $self->read_dump('filename');

Purpose: A .dump file is the result of a call to dump_pmc() and consists of a binary dump of a hash reference, Storable-style. read_dump() reads in the .dump file, recreates the data structure and returns a new hash reference holding the data structure.

Arguments: Scalar holding name of file whose structure is to be dumped. The method will only process foo.dump files, but you can also pass 'foo.c' or 'foo.pmc' as the argument and it will analyze the corresponding foo.dump file.

Return Values: Reference to hash holding recreated data structure.

Comments: If the appropriate .dump file cannot be located, program will die with error message (see find_file() above). Called internally by gen_c(), gen_parent_list(), dump_pmc().

Tested in: t/tools/pmc2cutils/04-dump_pmc.t.

gen_c()

    $return_value = $self->gen_c();

Purpose: Generate the C source code file for each of the files passed in, using the directories passed in to search for the PMC dump files.

Arguments: None.

Return Values: Returns 1 upon success.

Comments: Internally calls Parrot::Pmc2c::Library::new() and write_all_files(). In earlier version of pmc2c.pl, this subroutine returned undef upon success. This was changed to more Perl-ish 1.

Tested in: t/tools/pmc2cutils/05-gen_c.t.

find_file()

    $path = $self->find_file($file, $die_unless_found_flag);

Purpose: Return the full path to $file. (Search in the directories listed in the include key in the hash passed by reference to the constructor). Optionally, die with an error message if that file cannot be found.

Arguments: Two arguments. Required: string holding name of the file sought. Optional: a flag variable which, if set to a true value, will cause program to die if file is not located.

Return Values: Upon success, string holding a path. Upon failure, undef (unless $die_unless_found_flag is set to a true value, in which case program dies).

Comments: Called inside read_dump() and dump_pmc().

Tested in: t/tools/pmc2cutils/02-find_file.t.

AUTHOR ^

Leopold Toetsch wrote pmc2c.pl. It was cleaned up by Matt Diephouse. James E Keenan extracted the subroutines into lib/Parrot/Pmc2c/Pmc2cMain.pm and wrote the accompanying test suite.

SEE ALSO ^

tools/build/pmc2c.pl, Parrot::Pmc2c, Parrot::Pmc2c::Library.

syntax highlighting: