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

NAME

6       Verilog::Parser - Parse Verilog language files
7

SYNOPSIS

9         use Verilog::Parser;
10
11         my $parser = new Verilog::Parser;
12         $string = $parser->unreadback();
13         $line   = $parser->lineno();
14         $parser->parse($text)
15         $parser->parse_file($filename)
16

DESCRIPTION

18       Verilog::Parser will tokenize a Verilog file when the parse() method is
19       called and invoke various callback methods.  This is useful for
20       extracting information and editing files while retaining all context.
21       For netlist like extractions, see Verilog::Netlist.
22
23       See the "Which Package" section of Verilog::Language if you are unsure
24       which parsing package to use for a new application.
25
26       Note the parser allows some constructs that are syntax errors according
27       to the specification (for example "foo.bar(1)++".) This is done when
28       the parser can't easily detect these cases.  It's up to the consumer of
29       the parser to filter out such errors if it cares.
30

METHODS

32       $parser = Verilog::Parser->new (args...)
33           Create a new Parser.
34
35           Adding "symbol_table => []" will use the specified symbol table for
36           this parse, and modify the array reference to include those symbols
37           detected by this parse.  As the SystemVerilog language requires
38           packages and typedefs to exist before they are referenced, you must
39           pass the same symbol_table to subsequent parses that are for the
40           same compilation scope.  The internals of this symbol_table should
41           be considered opaque, as it will change between package versions,
42           and must not be modified by user code.
43
44           Adding "use_cb_{callback-name} => 0" will disable the specified
45           callback.  By default, all callbacks will be called; disabling
46           callbacks can greatly speed up the parser as a large percentage of
47           time is spent calling between C and Perl to invoke the callbacks.
48           When using this feature, use_unreadback=>0 should be used too, as
49           since whole tokens are skipped, skipping whitespace shouldn't
50           matter either.
51
52           Adding "use_protected => 0" will disable callbacks on `protected
53           and "`pragma protect protected" regions, which may improve
54           performance.
55
56           Adding "use_std => 1" will add parsing of the SystemVerilog built-
57           in std:: package, or "use_std => 0" will disable it.  If
58           unspecified it is silently included (no callbacks will be involved)
59           when suspected to be necessary.
60
61           Adding "use_unreadback => 0" will disable later use of the
62           unreadback method, which may improve performance.
63
64           Adding "use_vars => 0" will disable contassign, defparam, pin, var
65           and port callbacks to Verilog::SigParser.  This can greatly speed
66           parsing when variable and interconnect information is not required.
67
68       $parser->callback_names()
69           Return an array of callback function names.  This may be used to
70           automatically create callbacks for all functions, or to test for
71           different callback functionality between versions of Verilog-Perl.
72
73       $parser->eof()
74           Indicate the end of the input stream.  All incomplete tokens will
75           be parsed and all remaining callbacks completed.
76
77       $parser->filename($set)
78           Return (if $set is undefined) or set current filename.
79
80       $parser->lineno($set)
81           Return (if $set is undefined) or set current line number.
82
83       $parser->parse($string)
84           Parse the $string as verilog text.  Can be called multiple times.
85           Note not all callbacks may be invoked until the eof method is
86           called.
87
88       $parser->parse_file($filename);
89           This method can be called to parse text from a file.  The argument
90           can be a filename or an already opened file handle. The return
91           value from parse_file() is a reference to the parser object.
92
93       $parser->parse_preproc_file($preproc);
94           This method can be called to parse preprocessed text from a
95           predeclared Verilog::Preproc object.
96
97       $parser->unreadback($string)
98           Return any input string from the file that has not been sent to the
99           callback.  This will include whitespace and tokens which did not
100           have a callback.  (For example comments, if there is no comment
101           callback.)  This is useful for recording the entire contents of the
102           input, for preprocessors, pretty-printers, and such.
103
104           With the optional argument, set the text to be returned with the
105           next unreadback call.  See also unreadbackCat, which is much
106           faster.
107
108           To use this option, "use_unreadback => 1" must have been passed to
109           the constructor.
110
111       $parser->unreadbackCat($text)
112           Add text to be returned with the next unreadback call.  This is
113           much faster than using "$parser->unreadback($parser->unreadback .
114           $text)".
115

CALLBACKS

117       In order to make the parser do anything interesting, you must make a
118       subclass where you override one or more of the following callback
119       methods as appropriate.
120
121       $self->attribute($token)
122           This method is called when any text in (* *) are recognized.  The
123           first argument, $token, is the contents of the attribute including
124           the delimiters.
125
126       $self->comment($token)
127           This method is called when any text in // or /**/ comments are
128           recognized.  The first argument, $token, is the contents of the
129           comment including the comment delimiters.
130
131       $self->endparse($token)
132           This method is called when the file has been completely parsed, at
133           the End-Of-File of the parsed file.  It is useful for writing clean
134           up routines.
135
136       $self->keyword($token)
137           This method is called when any Verilog keyword is recognized.  The
138           first argument, $token, is the keyword.
139
140       $self->number($token)
141           This method is called when any number is recognized.  The first
142           argument, $token, is the number.  The
143           Verilog::Language::number_value function may be useful for
144           converting a Verilog value to a Perl integer.
145
146       $self->operator($token)
147           This method is called when any symbolic operator (+, -, etc) is
148           recognized.  The first argument, $token, is the operator.
149
150       $self->preproc($token)
151           This method is called when any Verilog preprocessor `command is
152           recognized.  Most of these are handled by the preprocessor, however
153           any unrecognized `defines are passed through.  For backward
154           compatibility, if not defined this function will call the symbol
155           callback.
156
157       $self->string($token)
158           This method is called when any text in double quotes are
159           recognized, or on the text of protected regions.  The first
160           argument, $token, is the contents of the string including the
161           quotes.
162
163       $self->symbol($token)
164           This method is called when any Verilog symbol is recognized.  A
165           symbol is considered a non-keyword bare-word.  The first argument,
166           $token, is the symbol.
167
168       $self->sysfunc($token)
169           This method is called when any Verilog $syscall is recognized.  The
170           first argument, $token, is the symbol.  For backward compatibility,
171           if not defined this function will call the symbol callback.
172

EXAMPLE

174       Here's a simple example which will print every symbol in a verilog
175       file.
176
177         package MyParser;
178         use Verilog::Parser;
179         @ISA = qw(Verilog::Parser);
180
181         # parse, parse_file, etc are inherited from Verilog::Parser
182         sub new {
183             my $class = shift;
184             #print "Class $class\n";
185             my $self = $class->SUPER::new();
186             bless $self, $class;
187             return $self;
188         }
189
190         sub symbol {
191             my $self = shift;
192             my $token = shift;
193
194             $self->{symbols}{$token}++;
195         }
196
197         sub report {
198             my $self = shift;
199
200             foreach my $sym (sort keys %{$self->{symbols}}) {
201                printf "Symbol %-30s occurs %4d times\n",
202                $sym, $self->{symbols}{$sym};
203             }
204         }
205
206         package main;
207
208         my $parser = MyParser->new();
209         $parser->parse_file(shift);
210         $parser->report();
211

BUGS

213       This is being distributed as a baseline for future contributions.
214       Don't expect a lot, the Parser is still naive, and there are many
215       awkward cases that aren't covered.
216
217       The parser currently assumes the string it is passed ends on a newline
218       boundary.  It should be changed to allow arbitrary chunks.
219
220       Cell instantiations without any arguments are not supported, an empty
221       set of parenthesis are required.  (Use "cell cell();", not "cell
222       cell;".)
223

DISTRIBUTION

225       Verilog-Perl is part of the <https://www.veripool.org/> free Verilog
226       EDA software tool suite.  The latest version is available from CPAN and
227       from <https://www.veripool.org/verilog-perl>.
228
229       Copyright 2000-2020 by Wilson Snyder.  This package is free software;
230       you can redistribute it and/or modify it under the terms of either the
231       GNU Lesser General Public License Version 3 or the Perl Artistic
232       License Version 2.0.
233

AUTHORS

235       Wilson Snyder <wsnyder@wsnyder.org>
236

SEE ALSO

238       Verilog-Perl, Verilog::Preproc, Verilog::SigParser, Verilog::Language,
239       Verilog::Netlist, Verilog::Getopt, vrename, vpassert vppreproc
240
241
242
243perl v5.32.0                      2020-10-30                         Parser(3)
Impressum