/ 
parrot-0.6.1
/ Parrot::Ops2c::Utils

NAME

Parrot::Ops2c::Utils - Methods holding functionality for tools/build/ops2c.pl.

SYNOPSIS

$self = Parrot::Ops2c::Utils->new( {
    argv    => [ @ARGV ],
    flag    => Parrot::Ops2c::Auxiliary::getoptions(),
    script  => $0,
} );

$c_header_filename = $self->print_c_header_file();

$c_source_filename = $self->print_c_source_file();

DESCRIPTION

Parrot::Ops2c::Utils provides methods called by tools/build/ops2c.pl, a program which is called at various points in the Parrot make process. The program's function is to create a pair of C header (*.h) and implementation (*.c) files from the operation definitions found in one or more *.ops files.

The functionality originally found in tools/build/ops2c.pl has been extracted into this package's methods in order to support component-focused testing and future refactoring.

METHODS

new()

  • Purpose

    Process command-line arguments provided to tools/build/ops2c.pl; construct and initialize a Parrot::Ops2c::Utils object.

  • Arguments

    Hash reference with the following elements:

    argv        :   reference to @ARGV
flag        :   hash reference which is the return value of
                Parrot::Ops2c::Utils::getoptions();
                hash will have keys such as 'core', 'dynamic' or 'nolines'
script      :   name of the script to be executed by 'make'
                (generally, $0 or tools/build/ops2c.pl)

  • Return Value

    Parrot::Ops2c::Utils object. At this point, the caller is ready to open a handle to the C-header file and write to it.

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

  • Purpose

    Creates a C-header file corresponding to a particular op. Such files will have names like these:

    include/parrot/oplib/core_ops.h
include/parrot/oplib/myops_ops_switch.h

  • Arguments

    None. (All data needed is already in the object.)

  • Return Value

    Returns the name of the C-header file created. You do not need to capture or make use of this return value during production, but it has proven useful in testing.

  • Comment

  • Purpose

    Writes out a C source file. Calls print_c_source_top and print_c_source_bottom to do the dirty work.

  • Arguments

    None. (All data needed is already in the object.)

  • Return Value

    Returns the filename it created. Caller need not do anything useful with this.

  • Purpose

    Writes the top half of a C-source file corresponding to a particular op. Such files will have names like these:

    src/ops/core_ops.c
src/ops/myops_ops_switch.c

  • Arguments

    None. (All data needed is already in the object.)

  • Return Value

    Returns a still-open filehandle to the C-source file.

  • Comment

    Q: Why does this method write only the top-half of the C-source file rather than the whole thing?

    A: Mainly for convenience in maintenance and testing. Internally, a handle is opened to the file, the file is written to, and the handle is closed and returned. That same handle is then re-opened, a line count on the file so far is taken, the handle is closed, then opened again for writing the bottom half of the source file. There are quite a few private methods implementing the first and last of these steps. It made sense to group these private methods into two public methods corresponding to the two points where the filehandle is opened and the C-source file is written to.

    Q: Why return a filehandle?

    A: It is re-used as an argument to the next method.

  • Purpose

    Writes the bottom half of a C-source file corresponding to a particular op.

  • Arguments

    One argument: the filehandle returned by print_c_source_top().

  • Return Value

    Returns the name of the C-source file created. You do not need to capture or make use of this return value during production, but it has proven useful in testing.

  • Comment

DEPENDENCIES

  • Parrot::OpsFile

  • Parrot::OpLib::core

    This package is not part of the Parrot distribution. It is created during Parrot's make process before the first invocation of tools/build/ops2c.pl.

AUTHOR

See tools/build/ops2c.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::Ops2c::Utils. Jim Keenan extracted that functionality and placed it in this package's methods.

SEE ALSO

  • tools/build/ops2c.pl

  • Parrot::OpsFile

  • Parrot::Ops2c::Auxiliary