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 = $self->print_c_header_file();

    $SOURCE = $self->print_c_source_top();

    $c_source = $self->print_c_source_bottom($SOURCE);

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.

print_header_file()

• 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

print_c_source_top()

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

print_c_source_bottom()

• 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