Preproc(3) User Contributed Perl Documentation Preproc(3)NAMEVerilog::Preproc - Preprocess Verilog files
SYNOPSIS
use Verilog::Getopt;
my $vp = Verilog::Preproc->new(I<parameters>);
$vp->open(filename=>"verilog_file.v");
my $line = $vp->getline();
EXAMPLE
# This is a complete verilog pre-parser!
# For a command line version, see vppreproc
use Verilog::Getopt;
use Verilog::Preproc;
my $opt = new Verilog::Getopt;
@ARGV = $opt->parameter(@ARGV);
my $vp = Verilog::Preproc->new(options=>$opt,);
$vp->open(filename=>"verilog_file.v");
while (defined (my $line = $vp->getline())) {
print $line;
}
DESCRIPTIONVerilog::Preproc reads Verilog files, and preprocesses them according
to the SystemVerilog 2009 (1800-2009) specification which is the most
recent extension of SystemVerilog 2005 (1800-2005). Programs can be
easily converted from reading a IO::File into reading preprocessed
output from Verilog::Preproc.
See the "Which Package" section of Verilog-Perl if you are unsure which
parsing package to use for a new application.
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->getall()
Return the entire translated text up to the final EOF, similar to
calling join('',$self->getline) but significantly faster. With
optional argument, returns approximately that number of characters.
Returns undef at EOF.
$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=>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.)
Open may also be called without named parameters, in which case the
only argument is the filename.
$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.
include_open_nonfatal=>1
With include_open_nonfatal set to one, ignore any include files
that do not exist.
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 strip with caution if feeding to tools other than your own.
Defaults to 1.
keep_whitespace=>0
With keep_whitespace set to zero, compress all whitespace to a
single space or newline. When set to one (the default), retain
whitespace. 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 retrieve 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 used
to disable the `__FILE__ and `__LINE__ features but no longer does
as they were added to the 1800-2009 standard. It remains to
disable `error and may disable other future features that are not
specified in the language standard. Defaults false.
synthesis=>1
With synthesis set, define SYNTHESIS, and ignore text bewteen
"ambit", "pragma", "synopsys" or "synthesis" translate_off and
translate_on meta comments. Note using metacomments is discouraged
as they have led to silicon bugs (versus ifdef SYNTHESIS); see
<http://www.veripool.org/papers/TenIPEdits_SNUGBos07_paper.pdf>.
CALLBACKS
Default callbacks are implemented that are suitable for most
applications. Derived classes may override these callbacks as needed.
$self->comment(comment)
Called with each comment, when keep_comments=>'sub' is used.
Defaults to do nothing.
$self->undef(defname)
Called with each `undef. Defaults to use options object.
$self->undefineall()
Called with each `undefineall. Defaults to use options object.
$self->define(defname, value, params)
Called with each `define. Defaults to use options object.
$self->def_exists(defname)
Called to determine if the define exists. Return true if the
define exists, or argument list with leading parenthesis if the
define has arguments. Defaults to use options object.
$self->def_substitute(string)
Called to determine what string to insert for a define
substitution. Called with the value of the define after parameters
have been expanded computed per the SystemVerilog spec. Generally
this function would just return the same string as it is passed,
but this can be overridden to allow customized preprocessing.
$self->def_value(defname)
Called to return value to substitute for specified define.
Defaults to use options object.
$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.
COMPLIANCE
The preprocessor supports the constructs defined in the SystemVerilog
2009 standard (IEEE 1800-2009), which is a superset of Verilog 1995
(IEEE 1364-1995), Verilog 2001 (IEEE 1364-2001), Verilog 2005 (IEEE
1364-2005) and SystemVerilog 2005 (IEEE 1800-2005).
Verilog::Preproc adds the `error macro (unless the pedantic parameter
is set.):
`__FILE__
The __FILE__ define expands to the current filename as a string,
like C++'s __FILE__. This was incorporated into to the 1800-2009
standard (but supported by Verilog-Perl since 2004!)
`__LINE__
The __LINE__ define expands to the current filename as a string,
like C++'s __LINE__. This was incorporated into to the 1800-2009
standard (but supported by Verilog-Perl since 2004!)
`error "string"
`error will be reported whenever it is encountered. (Like C++
#error.)
These are useful for error macros, similar to assert() in C++.
DISTRIBUTION
Verilog-Perl is part of the <http://www.veripool.org/> free Verilog EDA
software tool suite. The latest version is available from CPAN and
from http://www.veripool.org/verilog-perl
<http://www.veripool.org/verilog-perl>.
Copyright 2000-2012 by Wilson Snyder. This package is free software;
you can redistribute it and/or modify it under the terms of either the
GNU Lesser General Public License Version 3 or the Perl Artistic
License Version 2.0.
AUTHORS
Wilson Snyder <wsnyder@wsnyder.org>
SEE ALSO
Verilog-Perl, Verilog::Language, Verilog::Getopt
IO::File
This package is layered on a C++ interface which may be found in the
kit.
perl v5.14.2 2012-02-27 Preproc(3)
