perl-Verilog/Verilog::Preproc(3pm)

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 2005 specification.  Programs can be easily
33       converted from reading a IO::File into reading preprocessed output from
34       Verilog::Preproc.
35
36       See the "Which Package" section of Verilog::Language if you are unsure
37       which 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->getline()
49           Return the next line of text.  Returns undef at EOF.  (Just like
50           IO::File->getline().)
51
52       $self->lineno()
53           Returns the line number of the last getline().  Note that the line
54           number may change several times between getline(), for example when
55           traversing multiple include files.
56
57       $self->new(parameters)
58           Creates a new preprocessor.  See the PARAMETERS section for the
59           options that may be passed to new.
60
61       $self->open(filename=>filename)
62           Opens the specified file.  If called before a file is completely
63           parsed, the new file will be parsed completely before returning to
64           the previously open file.  (As if it was an include file.)
65
66           Open may also be called without named parameters, in which case the
67           only argument is the filename.
68
69       $self->unreadback(text)
70           Insert text into the input stream at the given point.  The text
71           will not be parsed, just returned to the application.  This lets
72           comment() callbacks insert special code into the output stream.
73

PARAMETERS

75       The following named parameters may be passed to the new constructor.
76
77       include_open_nonfatal=>1
78           With include_open_nonfatal set to one, ignore any include files
79           that do not exist.
80
81       keep_comments=>0
82           With keep_comments set to zero, strip all comments.  When set to
83           one (the default), insert comments in output streams.  When set to
84           'sub', call the comment() function so that meta-comments can be
85           processed outside of the output stream.  Note that some programs
86           use meta-comments to embed useful information (synthesis and lint),
87           so use this with caution if feeding to tools other than your own.
88           Defaults to 1.
89
90       keep_whitespace=>0
91           With keep_whitespace set to zero, compress all whitespace to a
92           single space or newline.  When set to one (the default), retain
93           whitespace.  Defaults to 1.
94
95       line_directives=>0
96           With line_directives set to zero, suppress "`line" comments which
97           indicate filename and line number changes.  Use the lineno() and
98           filename() methods instead to retrieve this information. Defaults
99           true.
100
101       options=>Verilog::Getopt object
102           Specifies the object to be used for resolving filenames and
103           defines.  Other classes may be used, as long as their interface
104           matches that of Getopt.
105
106       pedantic=>1
107           With pedantic set, rigorously obey the Verilog pedantic.  This
108           disables the `__FILE__ and `__LINE__ features, and may disable
109           other features that are not specified in the language pedantic.
110           Defaults false.
111

CALLBACKS

113       Default callbacks are implemented that are suitable for most
114       applications.  Derived classes may override these callbacks as needed.
115
116       $self->comment(comment)
117           Called with each comment, when keep_comments=>'sub' is used.
118           Defaults to do nothing.
119
120       $self->undef(defname)
121           Called with each `undef.  Defaults to use options object.
122
123       $self->define(defname, value, params)
124           Called with each `define.  Defaults to use options object.
125
126       $self->def_exists(defname)
127           Called to determine if the define exists.  Return true if the
128           define exists, or argument list with leading parenthesis if the
129           define has arguments.  Defaults to use options object.
130
131       $self->def_substitute(string)
132           Called to determine what string to insert for a define
133           substitution.  Called with the value of the define after parameters
134           have been expanded computed per the SystemVerilog spec.  Generally
135           this function would just return the same string as it is passed,
136           but this can be overridden to allow customized preprocessing.
137
138       $self->def_value(defname)
139           Called to return value to substitute for specified define.
140           Defaults to use options object.
141
142       $self->error(message)
143           Called on errors, with the error message as an argument.  Defaults
144           to die.
145
146       $self->include(filename)
147           Specifies a include file has been found.  Defaults to call
148           $self->open after resolving the filename with the options
149           parameter.
150

COMPLIANCE

152       The preprocessor supports the constructs defined in the Verilog 2005
153       and SystemVerilog 2005 standards.
154
155       Verilog::Preproc adds the following features (unless the pedantic
156       parameter is set.):
157
158       `__FILE__
159           `__FILE__ will be replaced by the current filename. (Like C++
160           __FILE__.)
161
162       `__LINE__
163           `__LINE__  will be replaced by the current line number. (Like C++
164           __LINE__.)
165
166       `error "string"
167           `error will be reported whenever it is encountered. (Like C++
168           #error.)
169
170           These are useful for error macros, similar to assert() in C++.
171

DISTRIBUTION

173       Verilog-Perl is part of the <http://www.veripool.org/> free Verilog EDA
174       software tool suite.  The latest version is available from CPAN and
175       from http://www.veripool.org/verilog-perl
176       <http://www.veripool.org/verilog-perl>.
177
178       Copyright 2000-2009 by Wilson Snyder.  This package is free software;
179       you can redistribute it and/or modify it under the terms of either the
180       GNU Lesser General Public License Version 3 or the Perl Artistic
181       License Version 2.0.
182

AUTHORS

184       Wilson Snyder <wsnyder@wsnyder.org>
185