1Parser(3) User Contributed Perl Documentation Parser(3)
2
6 Verilog::Parser - Parse Verilog language files
7
9 use Verilog::Parser;
10 my $parser = new Verilog::Parser;
12 $string = $parser->unreadback();
13 $line = $parser->lineno();
14 $parser->parse($text)
15 $parser->parse_file($filename)
16
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 See the "Which Package" section of Verilog::Language if you are unsure
24 which parsing package to use for a new application.
25 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
32 $parser = Verilog::Parser->new (args...)
33 Create a new Parser.
34 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 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 Adding "use_protected => 0" will disable callbacks on `protected
53 and "`pragma protect protected" regions, which may improve
54 performance.
55 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 Adding "use_unreadback => 0" will disable later use of the
62 unreadback method, which may improve performance.
63 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 $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 $parser->eof()
74 Indicate the end of the input stream. All incomplete tokens will
75 be parsed and all remaining callbacks completed.
76 $parser->filename($set)
78 Return (if $set is undefined) or set current filename.
79 $parser->lineno($set)
81 Return (if $set is undefined) or set current line number.
82 $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 $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 $parser->parse_preproc_file($preproc);
94 This method can be called to parse preprocessed text from a
95 predeclared Verilog::Preproc object.
96 $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 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 To use this option, "use_unreadback => 1" must have been passed to
109 the constructor.
110 $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
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 $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 $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 $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 $self->keyword($token)
137 This method is called when any Verilog keyword is recognized. The
138 first argument, $token, is the keyword.
139 $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 $self->operator($token)
147 This method is called when any symbolic operator (+, -, etc) is
148 recognized. The first argument, $token, is the operator.
149 $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 $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 $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 $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
174 Here's a simple example which will print every symbol in a verilog
175 file.
176 package MyParser;
178 use Verilog::Parser;
179 @ISA = qw(Verilog::Parser);
180 # 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 sub symbol {
191 my $self = shift;
192 my $token = shift;
193 $self->{symbols}{$token}++;
195 }
196 sub report {
198 my $self = shift;
199 foreach my $sym (sort keys %{$self->{symbols}}) {
201 printf "Symbol %-30s occurs %4d times\n",
202 $sym, $self->{symbols}{$sym};
203 }
204 }
205 package main;
207 my $parser = MyParser->new();
209 $parser->parse_file(shift);
210 $parser->report();
211
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 The parser currently assumes the string it is passed ends on a newline
218 boundary. It should be changed to allow arbitrary chunks.
219 Cell instantiations without any arguments are not supported, an empty
221 set of parenthesis are required. (Use "cell cell();", not "cell
222 cell;".)
223
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 Copyright 2000-2022 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
235 Wilson Snyder <wsnyder@wsnyder.org>
236
238 Verilog-Perl, Verilog::Preproc, Verilog::SigParser, Verilog::Language,
239 Verilog::Netlist, Verilog::Getopt, vrename, vpassert vppreproc
240perl v5.36.0 2023-01-20 Parser(3)