1Preproc(3)            User Contributed Perl Documentation           Preproc(3)
2
3
4

NAME

6       Verilog::Preproc - Preprocess Verilog files
7

SYNOPSIS

9           use Verilog::Getopt;
10
11           my $vp = Verilog::Preproc->new(I<parameters>);
12           $vp->open(filename=>"verilog_file.v");
13           my $line = $vp->getline();
14

EXAMPLE

16           # This is a complete verilog pre-parser!
17           # For a command line version, see vppreproc
18           use Verilog::Getopt;
19           use Verilog::Preproc;
20
21           my $opt = new Verilog::Getopt;
22           @ARGV = $opt->parameter(@ARGV);
23
24           my $vp = Verilog::Preproc->new(options=>$opt,);
25           $vp->open(filename=>"verilog_file.v");
26           while (defined (my $line = $vp->getline())) {
27              print $line;
28           }
29

DESCRIPTION

31       Verilog::Preproc reads Verilog files, and preprocesses them according
32       to the SystemVerilog 2009 (1800-2009) specification.  Programs can be
33       easily converted from reading a IO::File into reading preprocessed
34       output from Verilog::Preproc.
35
36       See the "Which Package" section of Verilog-Perl if you are unsure which
37       parsing package to use for a new application.
38

MEMBER FUNCTIONS

40       $self->eof()
41           Returns true at the end of the file.
42
43       $self->filename()
44           Returns the filename of the most recently returned getline().  May
45           not match the filename passed on the command line, as `line
46           directives are honored.
47
48       $self->getall()
49           Return the entire translated text up to the final EOF, similar to
50           calling join('',$self->getline) but significantly faster.  With
51           optional argument, returns approximately that number of characters.
52           Returns undef at EOF.
53
54       $self->getline()
55           Return the next line of text.  Returns undef at EOF.  (Just like
56           IO::File->getline().)
57
58       $self->lineno()
59           Returns the line number of the last getline().  Note that the line
60           number may change several times between getline(), for example when
61           traversing multiple include files.
62
63       $self->parent()
64           Returns a reference to the Verilog::Netlist::File which created
65           this object, if any.
66
67       $self->new(parameters)
68           Creates a new preprocessor.  See the PARAMETERS section for the
69           options that may be passed to new.
70
71       $self->open(filename=>filename)
72           Opens the specified file.  If filename ends in .gz, decompress
73           while reading.  If called before a file is completely parsed, the
74           new file will be parsed completely before returning to the
75           previously open file.  (As if it was an include file.)
76
77           Open may also be called without named parameters, in which case the
78           only argument is the filename.
79
80       $self->unreadback(text)
81           Insert text into the input stream at the given point.  The text
82           will not be parsed, just returned to the application.  This lets
83           comment() callbacks insert special code into the output stream.
84

PARAMETERS

86       The following named parameters may be passed to the new constructor.
87
88       ieee_predefines=>0
89           With ieee_predefines false, disable defining SV_COV_START and other
90           IEEE mandated definitions.
91
92       include_open_nonfatal=>1
93           With include_open_nonfatal set to one, ignore any include files
94           that do not exist.
95
96       keep_comments=>0
97           With keep_comments set to zero, strip all comments.  When set to
98           one (the default), insert comments in output streams.  When set to
99           'sub', call the comment() function so that meta-comments can be
100           processed outside of the output stream.  Note that some programs
101           use meta-comments to embed useful information (synthesis and lint),
102           so strip with caution if feeding to tools other than your own.
103           Defaults to 1.
104
105       keep_whitespace=>0
106           With keep_whitespace set to zero, compress all whitespace to a
107           single space or newline.  When set to one (the default), retain
108           whitespace.  Defaults to 1.
109
110       line_directives=>0
111           With line_directives set to zero, suppress "`line" comments which
112           indicate filename and line number changes.  Use the lineno() and
113           filename() methods instead to retrieve this information. Defaults
114           true.
115
116       options=>Verilog::Getopt object
117           Specifies the object to be used for resolving filenames and
118           defines.  Other classes may be used, as long as their interface
119           matches that of Getopt.
120
121       pedantic=>1
122           With pedantic set, rigorously obey the Verilog pedantic.  This used
123           to disable the `__FILE__ and `__LINE__ features but no longer does
124           as they were added to the 1800-2009 standard.  It remains to
125           disable `error and may disable other future features that are not
126           specified in the language standard. Defaults false.
127
128       synthesis=>1
129           With synthesis set, define SYNTHESIS, and ignore text bewteen
130           "ambit", "pragma", "synopsys" or "synthesis" translate_off and
131           translate_on meta comments.  Note using metacomments is discouraged
132           as they have led to silicon bugs (versus ifdef SYNTHESIS); see
133           <http://www.veripool.org/papers/TenIPEdits_SNUGBos07_paper.pdf>.
134

CALLBACKS

136       Default callbacks are implemented that are suitable for most
137       applications.  Derived classes may override these callbacks as needed.
138
139       $self->comment(comment)
140           Called with each comment, when keep_comments=>'sub' is used.
141           Defaults to do nothing.
142
143       $self->undef(defname)
144           Called with each `undef.  Defaults to use options object.
145
146       $self->undefineall()
147           Called with each `undefineall.  Defaults to use options object.
148
149       $self->define(defname, value, params)
150           Called with each `define.  Defaults to use options object.
151
152       $self->def_exists(defname)
153           Called to determine if the define exists.  Return true if the
154           define exists, or argument list with leading parenthesis if the
155           define has arguments.  Defaults to use options object.
156
157       $self->def_substitute(string)
158           Called to determine what string to insert for a define
159           substitution.  Called with the value of the define after parameters
160           have been expanded computed per the SystemVerilog spec.  Generally
161           this function would just return the same string as it is passed,
162           but this can be overridden to allow customized preprocessing.
163
164       $self->def_value(defname)
165           Called to return value to substitute for specified define.
166           Defaults to use options object.
167
168       $self->error(message)
169           Called on errors, with the error message as an argument.  Defaults
170           to die.
171
172       $self->include(filename)
173           Specifies a include file has been found.  Defaults to call
174           $self->open after resolving the filename with the options
175           parameter.
176

COMPLIANCE

178       The preprocessor supports the constructs defined in the SystemVerilog
179       2017 standard (IEEE 1800-2017), which is a superset of Verilog 1995
180       (IEEE 1364-1995), Verilog 2001 (IEEE 1364-2001), Verilog 2005 (IEEE
181       1364-2005) SystemVerilog 2005 (IEEE 1800-2005), SystemVerilog 2009
182       (IEEE 1800-2009), and SystemVerilog 2012 (IEEE 1800-2012).
183
184       Verilog::Preproc adds the `error macro (unless the pedantic parameter
185       is set.):
186
187       `__FILE__
188           The __FILE__ define expands to the current filename as a string,
189           like C++'s __FILE__.  This was incorporated into to the 1800-2009
190           standard (but supported by Verilog-Perl since 2004!)
191
192       `__LINE__
193           The __LINE__ define expands to the current filename as a string,
194           like C++'s __LINE__.  This was incorporated into to the 1800-2009
195           standard (but supported by Verilog-Perl since 2004!)
196
197       `error "string"
198           `error will be reported whenever it is encountered. (Like C++
199           #error.)
200
201           These are useful for error macros, similar to assert() in C++.
202

DISTRIBUTION

204       Verilog-Perl is part of the <http://www.veripool.org/> free Verilog EDA
205       software tool suite.  The latest version is available from CPAN and
206       from <http://www.veripool.org/verilog-perl>.
207
208       Copyright 2000-2018 by Wilson Snyder.  This package is free software;
209       you can redistribute it and/or modify it under the terms of either the
210       GNU Lesser General Public License Version 3 or the Perl Artistic
211       License Version 2.0.
212

AUTHORS

214       Wilson Snyder <wsnyder@wsnyder.org>
215

SEE ALSO

217       Verilog-Perl, Verilog::Language, Verilog::Getopt
218
219       IO::File
220
221       This package is layered on a C++ interface which may be found in the
222       kit.
223
224
225
226perl v5.28.0                      2018-10-28                        Preproc(3)
Impressum