Ubuntu Manpage: Verilog::Preproc - Preprocess Verilog files

Provided by: libverilog-perl_3.482-1build2_amd64

NAME

       Verilog::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;
           }

DESCRIPTION

       Verilog::Preproc reads Verilog files, and preprocesses them according to the SystemVerilog 2009
       (1800-2009) specification.  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->parent()
           Returns a reference to the Verilog::Netlist::File which created this object, if any.

       $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 filename ends in .gz, decompress while reading.   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.

ieee_predefines=>0
With ieee_predefines false, disable defining SV_COV_START and other IEEE mandated definitions.

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 between "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
<https://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_params(defname)
           Called  to  determine if the define exists and the parameters it expects.  Return undef if the define
           doesn't exist, 0 if the define exists with no arguments, or argument list with leading parenthesis if
           the define has arguments.  Defaults to use options object's defparams method.

       $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  2017  standard  (IEEE  1800-2017),
       which  is  a superset of Verilog 1995 (IEEE 1364-1995), Verilog 2001 (IEEE 1364-2001), Verilog 2005 (IEEE
       1364-2005) SystemVerilog 2005 (IEEE 1800-2005), SystemVerilog 2009 (IEEE  1800-2009),  and  SystemVerilog
       2012 (IEEE 1800-2012).

       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 <https://www.veripool.org/> free Verilog EDA software tool suite.  The latest
       version is available from CPAN and from <https://www.veripool.org/verilog-perl>.

       Copyright  2000-2024  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>