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 which is the most
33 recent extension of SystemVerilog 2005 (1800-2005). Programs can be
34 easily converted from reading a IO::File into reading preprocessed
35 output from Verilog::Preproc.
36 See the "Which Package" section of Verilog-Perl if you are unsure which
38 parsing package to use for a new application.
39
41 $self->eof()
42 Returns true at the end of the file.
43 $self->filename()
45 Returns the filename of the most recently returned getline(). May
46 not match the filename passed on the command line, as `line
47 directives are honored.
48 $self->getall()
50 Return the entire translated text up to the final EOF, similar to
51 calling join('',$self->getline) but significantly faster. With
52 optional argument, returns approximately that number of characters.
53 Returns undef at EOF.
54 $self->getline()
56 Return the next line of text. Returns undef at EOF. (Just like
57 IO::File->getline().)
58 $self->lineno()
60 Returns the line number of the last getline(). Note that the line
61 number may change several times between getline(), for example when
62 traversing multiple include files.
63 $self->new(parameters)
65 Creates a new preprocessor. See the PARAMETERS section for the
66 options that may be passed to new.
67 $self->open(filename=>filename)
69 Opens the specified file. If called before a file is completely
70 parsed, the new file will be parsed completely before returning to
71 the previously open file. (As if it was an include file.)
72 Open may also be called without named parameters, in which case the
74 only argument is the filename.
75 $self->unreadback(text)
77 Insert text into the input stream at the given point. The text
78 will not be parsed, just returned to the application. This lets
79 comment() callbacks insert special code into the output stream.
80
82 The following named parameters may be passed to the new constructor.
83 include_open_nonfatal=>1
85 With include_open_nonfatal set to one, ignore any include files
86 that do not exist.
87 keep_comments=>0
89 With keep_comments set to zero, strip all comments. When set to
90 one (the default), insert comments in output streams. When set to
91 'sub', call the comment() function so that meta-comments can be
92 processed outside of the output stream. Note that some programs
93 use meta-comments to embed useful information (synthesis and lint),
94 so use this with caution if feeding to tools other than your own.
95 Defaults to 1.
96 keep_whitespace=>0
98 With keep_whitespace set to zero, compress all whitespace to a
99 single space or newline. When set to one (the default), retain
100 whitespace. Defaults to 1.
101 line_directives=>0
103 With line_directives set to zero, suppress "`line" comments which
104 indicate filename and line number changes. Use the lineno() and
105 filename() methods instead to retrieve this information. Defaults
106 true.
107 options=>Verilog::Getopt object
109 Specifies the object to be used for resolving filenames and
110 defines. Other classes may be used, as long as their interface
111 matches that of Getopt.
112 pedantic=>1
114 With pedantic set, rigorously obey the Verilog pedantic. This used
115 to disable the `__FILE__ and `__LINE__ features but no longer does
116 as they were added to the 1800-2009 standard. It remains to
117 disable `error and may disable other future features that are not
118 specified in the language standard. Defaults false.
119
121 Default callbacks are implemented that are suitable for most
122 applications. Derived classes may override these callbacks as needed.
123 $self->comment(comment)
125 Called with each comment, when keep_comments=>'sub' is used.
126 Defaults to do nothing.
127 $self->undef(defname)
129 Called with each `undef. Defaults to use options object.
130 $self->undefineall()
132 Called with each `undefineall. Defaults to use options object.
133 $self->define(defname, value, params)
135 Called with each `define. Defaults to use options object.
136 $self->def_exists(defname)
138 Called to determine if the define exists. Return true if the
139 define exists, or argument list with leading parenthesis if the
140 define has arguments. Defaults to use options object.
141 $self->def_substitute(string)
143 Called to determine what string to insert for a define
144 substitution. Called with the value of the define after parameters
145 have been expanded computed per the SystemVerilog spec. Generally
146 this function would just return the same string as it is passed,
147 but this can be overridden to allow customized preprocessing.
148 $self->def_value(defname)
150 Called to return value to substitute for specified define.
151 Defaults to use options object.
152 $self->error(message)
154 Called on errors, with the error message as an argument. Defaults
155 to die.
156 $self->include(filename)
158 Specifies a include file has been found. Defaults to call
159 $self->open after resolving the filename with the options
160 parameter.
161
163 The preprocessor supports the constructs defined in the SystemVerilog
164 2009 standard (IEEE 1800-2009), which is a superset of Verilog 1995
165 (IEEE 1364-1995), Verilog 2001 (IEEE 1364-2001), Verilog 2005 (IEEE
166 1364-2005) and SystemVerilog 2005 (IEEE 1800-2005).
167 Verilog::Preproc adds the `error macro (unless the pedantic parameter
169 is set.):
170 `__FILE__
172 The __FILE__ define expands to the current filename as a string,
173 like C++'s __FILE__. This was incorporated into to the 1800-2009
174 standard (but supported by Verilog-Perl since 2004!)
175 `__LINE__
177 The __LINE__ define expands to the current filename as a string,
178 like C++'s __LINE__. This was incorporated into to the 1800-2009
179 standard (but supported by Verilog-Perl since 2004!)
180 `error "string"
182 `error will be reported whenever it is encountered. (Like C++
183 #error.)
184 These are useful for error macros, similar to assert() in C++.
186
188 Verilog-Perl is part of the <http://www.veripool.org/> free Verilog EDA
189 software tool suite. The latest version is available from CPAN and
190 from http://www.veripool.org/verilog-perl
191 <http://www.veripool.org/verilog-perl>.
192 Copyright 2000-2010 by Wilson Snyder. This package is free software;
194 you can redistribute it and/or modify it under the terms of either the
195 GNU Lesser General Public License Version 3 or the Perl Artistic
196 License Version 2.0.
197
199 Wilson Snyder <wsnyder@wsnyder.org>
200
202 Verilog-Perl, Verilog::Language, Verilog::Getopt
203 IO::File
205 This package is layered on a C++ interface which may be found in the
207 kit.
208perl v5.12.2 2010-10-25 Preproc(3)