Parrot::Ops2pm::Utils - Methods holding functionality for tools/build/ops2pm.pl.
use Parrot::Ops2pm::Utils; $self = Parrot::Ops2pm::Utils->new( { argv => [ @ARGV ], nolines => $nolines_flag, renum => $renum_flag, moddir => "lib/Parrot/OpLib", module => "core.pm", inc_dir => "include/parrot/oplib", inc_f => "ops.h", script => "tools/build/ops2pm.pl", } ); $self->prepare_ops(); if ($renum_flag) { $self->renum_op_map_file(); exit 0; } $self->load_op_map_files(); $self->sort_ops(); $self->prepare_real_ops(); $self->print_module(); $self->print_h(); exit 0;
Parrot::Ops2pm::Utils provides methods called by tools/build/ops2pm.pl, a program which is called at the very beginning of the Parrot make process. The program's function is to build two files:
lib/Parrot/OpLib/core.pm
include/parrot/oplib/ops.h
The functionality originally found in tools/build/ops2pm.pl has been extracted into this package's methods in order to support component-focused testing and future refactoring.
new()
Purpose
Process files provided as command-line arguments to tools/build/ops2pm.pl and construct a Parrot::Ops2pm::Utils object.
Arguments
Hash reference with the following elements:
argv : reference to @ARGV nolines : set to true value to eliminate #line directives in output renum : set to true value if moddir : directory where output module is created (generally, lib/Parrot/OpLib) module : name of output module (generally, core.pm) inc_dir : directory where C-header file is created (generally, include/parrot/oplib) inc_f : name of output C-header file (generally, ops.h) script : name of the script to be executed by 'make' (generally, tools/build/ops2pm.pl)
Return Value
Parrot::Ops2pm::Utils object.
Comment
Arguments for the constructor have been selected so as to provide subsequent methods with all information needed to execute properly and to be testable. A Parrot::Ops2pm::Utils object can be constructed lacking some of these arguments and still suffice for the execution of particular methods -- this is done during the test suite -- but such an object would not suffice for make's call to tools/build/ops2pm.pl.
prepare_ops()
Call Parrot::OpsFile::new(), then populate the resulting $opts hash reference with information from each of the .ops files provided as command-line arguments to tools/build/ops2pm.pl.
Parrot::OpsFile::new()
$opts
None. (Implicitly requires that at least the argv and script elements were provided to the constructor.)
argv
script
None. Internally, sets the ops key in the object's data structure.
ops
This method calls Parrot::OpsFile::new() on the first .ops file found in @ARGV, then copies the ops from the remaining .ops files to the object just created. Experimental ops are marked as such.
@ARGV
renum_op_map_file()
Triggered when tools/build/ops2pm.pl is called with the --renum flag, this method renumbers src/ops/ops.num based on the already existing file of that name and additional .ops files.
--renum
String holding name of an .ops file; defaults to src/ops/ops.num. (Implicitly requires that the argv, script and renum elements were provided to the constructor.)
renum
Returns true value upon success.
When tools/build/ops2pm.pl is called with the --renum option, this method is triggered, after which ops2pm.pl exits. Consequently, this is the only Parrot::Ops2pm::Utils method which is not a stepping stone on the path to building lib/Parrot/OpLib/core.pm.
load_op_map_files()
When tools/build/ops2pm.pl is called by make, this method checks the number of ops strictly against src/ops/ops.num and renumbers as needed.
None. (Implicitly requires that the argv and script keys have been provided to the constructor and that the renum key not have a true value -- which will be the case when the --renum option is not provided to tools/build/ops2pm.pl.)
Returns true value upon success. Internally, sets these values in these elements in the object's data structure: max_op_num, skiptable and optable.
max_op_num
skiptable
optable
Comments
This is the default case, i.e., the case that prevails when tools/build/ops2pm.pl is not called with the --renum flag. In addition to src/ops/ops.num, this method also draws upon information in src/ops/ops.skip.
sort_ops()
Internal manipulation of the Parrot::Ops2pm::Utils object: sorting by number of the list of op codes found in the object's {ops}->{OPS} element.
{ops}->{OPS}
None.
None. Internally, sets the ops key of the object's data structure.
Will emit warnings under these circumstances:
prepare_real_ops()
Final stage of preparation of ops.
None. (Same implicit requirements for the constructor as load_op_map_files() above.)
None. Internally, sets the real_ops key of the object's data structure.
real_ops
print_module()
Uses information in the object's data structure -- principally the real_ops element -- to create lib/Parrot/OpLib/core.pm.
None. (Implicitly requires that the constructor have the following keys defined: argv, script, moddir and module.)
moddir
module
print_h()
Uses information in the object's data structure -- principally the real_ops key -- to create include/parrot/oplib/ops.h.
None. (Implicitly requires that the constructor have the following keys defined: argv, script, inc_dir and inc_f.)
inc_dir
inc_f
A suite of test files to accompany this package is found in t/tools/ops2pmutils. This suite has been developed to maximize its coverage of the code of Parrot::Ops2pm::Utils (as measured by Perl module Devel::Cover). Should you wish to refactor this package, it is recommended that you do so in a test-driven manner:
Write the specification for any additions or modifications to Parrot::Ops2pm::Utils' interface.
Write tests that reflect any such modifications.
Write the additional or modified code that reflects the new specification.
Test the new code and debug. The tests in the suite should be run after Parrot's Configure.pl has run but before make has run. Example:
$> perl Configure.pl $> prove -v t/tools/ops2pmutils/*.t $> make
Use Devel::Cover to measure the extent to which the existing and new tests cover the existing and revised code.
Refactor and retest to ensure high test coverage.
This package's methods are called by tools/build/ops2pm.pl, which in turn is invoked by make in the Parrot build process. Successful execution of make proves that the functionality in this package achieved its overall objective but does not necessarily invoke many of the individual code statements in the package. That is the rationale for the component-focused testing provided by the test suite.
See tools/build/ops2pm.pl for a list of the Parrot hackers who, over a period of several years, developed the functionality now found in the methods of Parrot::Ops2pm::Utils. Jim Keenan extracted that functionality and placed it in this package's methods.
To install Parrot::Op, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Parrot::Op
CPAN shell
perl -MCPAN -e shell install Parrot::Op
For more information on module installation, please visit the detailed CPAN module installation guide.