Parrot::Ops2c::Utils - Methods holding functionality for tools/build/ops2c.pl.
$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();
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.
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.
print_c_header_file()
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
None. (All data needed is already in the object.)
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.
print_c_source_file()
Writes out a C source file. Calls print_c_source_top and print_c_source_bottom to do the dirty work.
Returns the filename it created. Caller need not do anything useful with this.
print_c_source_top()
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
Returns a still-open filehandle to the C-source file.
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.
print_c_source_bottom()
Writes the bottom half of a C-source file corresponding to a particular op.
One argument: the filehandle returned by print_c_source_top().
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.
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.
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.
tools/build/ops2c.pl
Parrot::Ops2c::Auxiliary
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.