NAME

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

SYNOPSIS

use Parrot::Pmc2c::Utils;

DESCRIPTION

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

FUNCTIONS

Publicly Available Methods

`new()`

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

Purpose: Parrot::Pmc2c::Utils constructor.

Arguments: Reference to a hash holding 3 required keys:

include

Array reference. Array passed holds list of paths in which various methods should try to locate files.
opt

Hash reference. Holds results of processing of options to pmc2c.pl().
args

Array reference. In most cases, the array passed will hold the elements of @ARGV remaining after options processing.

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

`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).

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

`dump_vtable()`

$self->dump_vtable("$FindBin::Bin/../../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.

`print_tree()`

$self->print_tree( {
    depth   => 0,
    files   => [ @files_to_be_printed ],    # optional
} );

Purpose: Print the inheritance tree for each of the files, using the given directories to search for all of correct PMCs.

Arguments: Reference to hash holding key-value pairs.

depth

Number holding the display depth. Used for the recursive definition of this function. Defaults to 0 if not specified.
files

Optional. Reference to an array holding a list of files. If not supplied, the value of the args key in Parrot::Pmc2c::Utils::new() will be used. (This is used for the recursive call.)

Return Values: 1 upon successful printing.

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

The purpose of this method is unclear. (1) It is not called by Makefile. (2) Since internally calls read_dump(), a .dump file must already exist for this method to generate meaningful output. But since .dump files do not exist prior to calling make, this can only be viewed as an attempt at a utility method to be called after make has run. That might be useful. It would be responding to a request such as, "Given these .dump files, reconstruct the inheritance trees of their ancestral .pmc files." But that's a very different purpose from the other methods in this program, whose point is to go from .pmc to .c files.

`read_dump()`

$self->read_dump('filename');

Purpose: A .dump file is the result of a call to dump_pmc() and consists of a print-out of a hash reference Data::Dumper-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.

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

`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.

Comment: 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.

`dump_pmc()`

$return_value = $self->dump_pmc();

Purpose: Create a .dump file for each file listed in the constructor's arg key (which can be found in the directories listed in the include key).

A '*.pmc' glob may also be passed to emulate a proper shell in the presence of a dumb one.

$self = Parrot::Pmc2c::Utils->new( {
    include => \@include,
    opt     => \%opt,
    args    => [ ( q{*.pmc} ) ],
} );
$self->dump_pmc();

Arguments: None.

Return Values: Returns 1 upon success.

Comments: Called when --dump is specified as the command-line option to pmc2c.pl.

Non-Public Methods

These functions are expressed as methods called on the Parrot::Pmc2c::Utils object, but only because they make use of data stored in that object. They are called within the publicly available methods described above and are not intended to be publicly callable.

`find_and_parse_pmc()`

($class, $result) = $self->find_and_parse_pmc($file);

Purpose: Returns the class structure from $file for a .dump file.

Arguments: String holding a file name. The file is one of those provided by the arg key of the constructor.

Return Values: find_and_parse_pmc() internally calls parse_pmc and directly returns the latter's list of two return values: a string holding a classname and a reference to a hash holding the class's attributes.

Comments: Called internally by dump_pmc(). Formerly called dump_1_pmc(); name was changed because this function doesn't actually do any 'dumping' in the sense of using Data::Dumper to print the contents of a variable. Rather, it is a step called by dump_pmc() to prepare for dumping.

`gen_parent_list()`

$self->gen_parent_list($name, \%all);

Purpose: Generate an ordered list of parent classes to put in the $classes-{class}->{parents}> array, using the given directories to find parents.

Arguments: List of two arguments:

String holding class name.
Hash reference holding data structure being built up within dump_pmc().

Return Value: Reference to hash holding the data structure being built up within dump_pmc(), suitably modified.

Comments: Called within dump_pmc().

Subroutines

These are auxiliary subroutines called inside the methods described above.

`open_file()`

$fh = open_file( "<", $file, $verbose);

Purpose: Utility subroutine.

Arguments: List of scalars: two required, one optional.

action

String holding action/direction desired: < for reading or >> for writing or appending.
filename

String holding name of file to be opened.
verbose

Optional. True value if verbose output is desired. That output will be the action followed by the filename. In most cases, the third argument will be $self-{opt}{verbose}>.

Return Values: Filehandle to file so opened.

Comment: Called within dump_vtable(), read_dump(), find_and_parse_pmc(), and dump_pmc().

`parse_pmc()`

($classname, $attributesref)  = parse_pmc($contents, $opt);

Purpose: Parse PMC code and return the class name and a hash ref of attributes.

Arguments: List of two arguments:

Code reference holding results of parsing PMC code found in file provided as argument to find_and_parse_pmc().
The hash reference which is the value of the opt key provided to constructor.

Return Values: List of two elements:

String holding a classname.
Reference to a hash of the class's attributes. Keys:
```
pre
flags
methods
post
class
has_method
```

Comments: Called internally by find_and_parse_pmc().

`parse_flags()`

($pre, $classname, $flags_ref)   = parse_flags(\$code);

Purpose: Extract a class signature from the code ref.

Argument: De-reference the code ref which was the first argument provided to parse_pmc().

Return Values: List of three elements:

the code found before the class signature;
the name of the class; and
a hash ref containing the flags associated with the class (such as extends and does).

Comments: Called internally by parse_pmc().

`extract_balanced()`

($classblock, $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.

`parse_method_attrs()`

$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().

`dump_is_newer()`

dump_is_newer($existing);

Purpose: Determines whether the dump of a file is newer than the PMC file. (If it's not, then the PMC file has changed and the dump has not been updated.)

Arguments: String holding filename.

Return Values: Returns true if timestamp of existing is more recent than that of PMC.

Comments: Called within find_and_parse_pmc().

`gen_super_meths()`

$class = gen_super_meths($name, $all, $vt);

Purpose: Generate a list of inherited methods for $name by searching the inheritance tree. The method list is found in $vt.

Arguments: List of three elements:

String holding name of class being dumped.
Reference to the hash holding the data structure being built up within dump_pmc().
The result of a call of read_dump() on vtable.pmc.

Return Value: Hash reference representing the class being dumped.

Comments: Called within dump_pmc().

`inherit_attrs()`

$class = inherit_attrs($class, $meth);

Purpose: Modify $attrs to inherit attrs from $super_attrs as appropriate.

Arguments: List of two arguments:

Reference to hash holding the data structure being built up within dump_pmc().
Method name.

Return Values: Reference to hash holding the data structure being built up within dump_pmc().

Comments: Called within gen_super_meths().

AUTHOR

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

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

FUNCTIONS

Publicly Available Methods

new()

find_file()

dump_vtable()

print_tree()

read_dump()

gen_c()

dump_pmc()

Non-Public Methods

find_and_parse_pmc()

gen_parent_list()

Subroutines

open_file()

parse_pmc()

parse_flags()

extract_balanced()

parse_method_attrs()

dump_is_newer()

gen_super_meths()

inherit_attrs()

AUTHOR

SEE ALSO

Module Install Instructions

`new()`

`find_file()`

`dump_vtable()`

`print_tree()`

`read_dump()`

`gen_c()`

`dump_pmc()`

`find_and_parse_pmc()`

`gen_parent_list()`

`open_file()`

`parse_pmc()`

`parse_flags()`

`extract_balanced()`

`parse_method_attrs()`

`dump_is_newer()`

`gen_super_meths()`

`inherit_attrs()`