NAME

Parrot::Ops2pm - Methods holding functionality for tools/build/ops2pm.pl.

SYNOPSIS

    use Parrot::Ops2pm;

    $self = Parrot::Ops2pm->new( {
        argv            => [ @ARGV ],
        nolines         => $nolines_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();
    $self->load_op_map_files();
    $self->sort_ops();
    $self->prepare_real_ops();
    $self->print_module();
    $self->print_h();
    exit 0;

DESCRIPTION

Parrot::Ops2pm 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 once (pre-April 2007) found in tools/build/ops2pm.pl has been extracted into this package's methods in order to support component-focused testing and future refactoring.

METHODS

new()

Inherited from Parrot::Ops2pm::Base and documented in lib/Parrot/Ops2pm/Base.pm.

prepare_ops()

Inherited from Parrot::Ops2pm::Base and documented in lib/Parrot/Ops2pm/Base.pm.

load_op_map_files()

• Purpose

  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.

• Arguments

  None. (Implicitly requires that the argv and script keys have been provided to the constructor.)

• Return Value

  Returns true value upon success. Internally, sets these values in these elements in the object's data structure: max_op_num, skiptable and optable.

• Comments

  This is the default case. In addition to src/ops/ops.num, this method also draws upon information in src/ops/ops.skip.

sort_ops()

• Purpose

  Internal manipulation of the Parrot::Ops2pm object: sorting by number of the list of op codes found in the object's {ops}->{OPS} element.

• Arguments

  None.

• Return Value

  None. Internally, sets the ops key of the object's data structure.

• Comment

  Will emit warnings under these circumstances:

prepare_real_ops()

• Purpose

  Final stage of preparation of ops.

• Arguments

  None. (Same implicit requirements for the constructor as load_op_map_files() above.)

• Return Value

  None. Internally, sets the real_ops key of the object's data structure.

• Comment

print_module()

• Purpose

  Uses information in the object's data structure -- principally the real_ops element -- to create lib/Parrot/OpLib/core.pm.

• Arguments

  None. (Implicitly requires that the constructor have the following keys defined: argv, script, moddir and module.)

• Return Value

  Returns true value upon success.

• Comment

print_h()

• Purpose

  Uses information in the object's data structure -- principally the real_ops key -- to create include/parrot/oplib/ops.h.

• Arguments

  None. (Implicitly requires that the constructor have the following keys defined: argv, script, inc_dir and inc_f.)

• Return Value

  Returns true value upon success.

• Comment

NOTE ON TESTING

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 (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:

1. Write the specification for any additions or modifications to Parrot::Ops2pm' interface.

2. Write tests that reflect any such modifications.

3. Write the additional or modified code that reflects the new specification.

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

5. Use Devel::Cover to measure the extent to which the existing and new tests cover the existing and revised code.

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

AUTHOR

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. Jim Keenan extracted that functionality and placed it in this package's methods.