NAME

Verilog::Preproc - Preprocess Verilog files Files

SYNOPSIS

    use Verilog::Getopt;

    my $vp = Verilog::Preproc->new(I<parameters>);
    $vp->open("verilog_file.v");
    my $line = $vp->getline();

EXAMPLE

    # This is a complete verilog pre-parser!
    use Verilog::Getopt;
    use Verilog::Preproc;

    my $opt = new Verilog::Getopt;
    @ARGV = $opt->parameter(@ARGV);

    my $vp = Verilog::Preproc->new(options=>$opt,);
    $vp->open("verilog_file.v");
    while (defined (my $line = $vp->getline())) {
       print $line;
    }

DESCRIPTION

Verilog::Preproc reads Verilog files, and preprocesses them according to the Verilog 2001 specification. Programs can be easily converted from reading a IO::File into reading preprocessed output from Verilog::Preproc.

MEMBER FUNCTIONS

$self->eof()

Returns true at the end of the file.

$self->filename()

Returns the filename of the most recently returned getline(). May not match the filename passed on the command line, as `line directives are honored.

$self->getline()

Return the next line of text. Returns undef at EOF. (Just like IO::File->getline().)

$self->lineno()

Returns the line number of the last getline(). Note that the line number may change several times between getline(), for example when traversing multiple include files.

$self->new(parameters)

Creates a new preprocessor. See the PARAMETERS section for the options that may be passed to new.

$self->open(filename)

Opens the specified file. If called before a file is completely parsed, the new file will be parsed completely before returning to the previously open file. (As if it was an include file.)

$self->unreadback(text)

Insert text into the input stream at the given point. The text will not be parsed, just returned to the application. This lets comment() callbacks insert special code into the output stream.

PARAMETERS

The following named parameters may be passed to the new constructor.

keep_comments=>0

With keep_comments set to zero, strip all comments. When set to one (the default), insert comments in output streams. When set to 'sub', call the comment() function so that meta-comments can be processed outside of the output stream. Note that some programs use meta-comments to embed useful information (synthesis and lint), so use this with caution if feeding to tools other then your own. Defaults to 1.

line_directives=>0

With line_directives set to zero, suppress "`line" comments which indicate filename and line number changes. Use the lineno() and filename() methods instead to retrive this information. Defaults true.

options=>Verilog::Getopt object

Specifies the object to be used for resolving filenames and defines. Other classes may be used, as long as their interface matches that of Getopt.

pedantic=>1

With pedantic set, rigorously obey the Verilog pedantic. This disables the `__FILE__ and `__LINE__ features, and may disable other features that are not specified in the language pedantic. Defaults false.

CALLBACKS

Default callbacks are implemented that are suitable for most applications. Derrived classes may override these callbacks as needed.

$self->error(message)

Called on errors, with the error message as an argument. Defaults to die.

$self->include(filename)

Specifies a include file has been found. Defaults to call $self->open after resolving the filename with the options parameter.

$self->comment(comment)

Called with each comment, when keep_comments=>'sub' is used.

COMPLIANCE

Parameterized macros are not yet supported. Otherwise, the preprocessor should be Verilog 2001 compliant.

Verilog::Preproc adds the following features (unless the pedantic parameter is set.):

`__FILE__ will be replaced by the current filename. (Like C++ __FILE__.)

`__LINE__ will be replaced by the current line number. (Like C++ __LINE__.)

`error "string" will be reported whenever it is encountered. (Like C++ #error.)

These are useful for error macros, similar to assert() in C++.

SEE ALSO

Verilog::Language, Verilog::Getopt

IO::File

This package is layered on a C++ interface which may be found in the kit.

DISTRIBUTION

The latest version is available from CPAN and from http://veripool.com/.

AUTHORS

Wilson Snyder <wsnyder@wsnyder.org>