1Preproc(3) User Contributed Perl Documentation Preproc(3)
2
6 Verilog::Preproc - Preprocess Verilog files
7
9 use Verilog::Getopt;
10 my $vp = Verilog::Preproc->new(I<parameters>);
12 $vp->open(filename=>"verilog_file.v");
13 my $line = $vp->getline();
14
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 my $opt = new Verilog::Getopt;
22 @ARGV = $opt->parameter(@ARGV);
23 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
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 See the "Which Package" section of Verilog-Perl if you are unsure which
37 parsing package to use for a new application.
38
40 $self->eof()
41 Returns true at the end of the file.
42 $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 $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 $self->getline()
55 Return the next line of text. Returns undef at EOF. (Just like
56 IO::File->getline().)
57 $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 $self->parent()
64 Returns a reference to the Verilog::Netlist::File which created
65 this object, if any.
66 $self->new(parameters)
68 Creates a new preprocessor. See the PARAMETERS section for the
69 options that may be passed to new.
70 $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 Open may also be called without named parameters, in which case the
78 only argument is the filename.
79 $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
86 The following named parameters may be passed to the new constructor.
87 ieee_predefines=>0
89 With ieee_predefines false, disable defining SV_COV_START and other
90 IEEE mandated definitions.
91 include_open_nonfatal=>1
93 With include_open_nonfatal set to one, ignore any include files
94 that do not exist.
95 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 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 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 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 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 synthesis=>1
129 With synthesis set, define SYNTHESIS, and ignore text between
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
136 Default callbacks are implemented that are suitable for most
137 applications. Derived classes may override these callbacks as needed.
138 $self->comment(comment)
140 Called with each comment, when keep_comments=>'sub' is used.
141 Defaults to do nothing.
142 $self->undef(defname)
144 Called with each `undef. Defaults to use options object.
145 $self->undefineall()
147 Called with each `undefineall. Defaults to use options object.
148 $self->define(defname, value, params)
150 Called with each `define. Defaults to use options object.
151 $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 $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 $self->def_value(defname)
165 Called to return value to substitute for specified define.
166 Defaults to use options object.
167 $self->error(message)
169 Called on errors, with the error message as an argument. Defaults
170 to die.
171 $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
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 Verilog::Preproc adds the `error macro (unless the pedantic parameter
185 is set.):
186 `__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 `__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 `error "string"
198 `error will be reported whenever it is encountered. (Like C++
199 #error.)
200 These are useful for error macros, similar to assert() in C++.
202
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 Copyright 2000-2020 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
214 Wilson Snyder <wsnyder@wsnyder.org>
215
217 Verilog-Perl, Verilog::Language, Verilog::Getopt
218 IO::File
220 This package is layered on a C++ interface which may be found in the
222 kit.
223perl v5.30.1 2020-01-30 Preproc(3)