Parser(3) User Contributed Perl Documentation Parser(3)NAMEVerilog::Parser - Parse Verilog language files
SYNOPSIS
use Verilog::Parser;
my $parser = new Verilog::Parser;
$string = $parser->unreadback ();
$line = $parser->lineno ();
$parser->parse ($text)
$parser->parse_file ($filename)
DESCRIPTIONVerilog::Parser will tokenize a Verilog file when the parse() method is
called and invoke various callback methods. This is useful for
extracting information and editing files while retaining all context.
For netlist like extractions, see Verilog::Netlist.
See the "Which Package" section of Verilog::Language if you are unsure
which parsing package to use for a new application.
Note the parser allows some constructs that are syntax errors according
to the specification (for example "foo.bar(1)++".) This is done when
the parser can't easily detect these cases. It's up to the consumer of
the parser to filter out such errors if it cares.
METHODS
$parser = Verilog::Parser->new (args...)
Create a new Parser.
Adding "symbol_table => []" will use the specified symbol table for
this parse, and modify the array reference to include those symbols
detected by this parse. As the SystemVerilog language requires
packages and typedefs to exist before they are referenced, you must
pass the same symbol_table to subsequent parses that are for the
same compilation scope. The internals of this symbol_table should
be considered opaque, as it will change between package versions,
and must not be modified by user code.
Adding "use_cb_{callback-name} => 0" will disable the specified
callback. By default, all callbacks will be called; disabling
callbacks can greatly speed up the parser as a large percentage of
time is spent calling between C and Perl to invoke the callbacks.
When using this feature, use_unreadback=>0 should be used too, as
since whole tokens are skipped, skipping whitespace shouldn't
matter either.
Adding "use_std => 1" will add parsing of the SystemVerilog built-
in std:: package, or "use_std => 0" will disable it. If
unspecified it is silently included (no callbacks will be involed)
when suspected to be necessary.
Adding "use_unreadback => 0" will disable later use of the
unreadback method, which may improve performance.
Adding "use_vars => 0" will disable contassign, defparam, pin, var
and port callbacks to Verilog::SigParser. This can greatly speed
parsing when variable and interconnect information is not required.
$parser->callback_names ()
Return an array of callback function names. This may be used to
automatically create callbacks for all functions, or to test for
different callback functionality between versions of Verilog-Perl.
$parser->eof ()
Indicate the end of the input stream. All incomplete tokens will
be parsed and all remaining callbacks completed.
$parser->filename ($set)
Return (if $set is undefined) or set current filename.
$parser->lineno ($set)
Return (if $set is undefined) or set current line number.
$parser->parse ($string)
Parse the $string as verilog text. Can be called multiple times.
Note not all callbacks may be invoked until the eof method is
called.
$parser->parse_file ($filename);
This method can be called to parse text from a file. The argument
can be a filename or an already opened file handle. The return
value from parse_file() is a reference to the parser object.
$parser->parse_preproc_file ($preproc);
This method can be called to parse preprocessed text from a
predeclared Verilog::Preproc object.
$parser->unreadback ($string)
Return any input string from the file that has not been sent to the
callback. This will include whitespace and tokens which did not
have a callback. (For example comments, if there is no comment
callback.) This is useful for recording the entire contents of the
input, for preprocessors, pretty-printers, and such.
With the optional argument, set the text to be returned with the
next unreadback call. See also unreadbackCat, which is much
faster.
To use this option, "use_unreadback => 1" must have been passed to
the constructor.
$parser->unreadbackCat ($text)
Add text to be returned with the next unreadback call. This is
much faster than using "$parser->unreadback($parser->unreadback .
$text)".
CALLBACKS
In order to make the parser do anything interesting, you must make a
subclass where you override one or more of the following callback
methods as appropriate.
$self->attribute ( $token )
This method is called when any text in (* *) are recognized. The
first argument, $token, is the contents of the attribute including
the delimiters.
$self->comment ( $token )
This method is called when any text in // or /**/ comments are
recognized. The first argument, $token, is the contents of the
comment including the comment delimiters.
$self->endparse ( $token )
This method is called when the file has been completely parsed, at
the End-Of-File of the parsed file. It is useful for writing clean
up routines.
$self->keyword ( $token )
This method is called when any Verilog keyword is recognized. The
first argument, $token, is the keyword.
$self->number ( $token )
This method is called when any number is recognized. The first
argument, $token, is the number. The
Verilog::Language::number_value function may be useful for
converting a Verilog value to a Perl integer.
$self->operator ( $token )
This method is called when any symbolic operator (+, -, etc) is
recognized. The first argument, $token, is the operator.
$self->preproc ( $token )
This method is called when any Verilog preprocessor `command is
recognized. Most of these are handled by the preprocessor, however
any unrecognized `defines are passed through. For backward
compatibility, if not defined this function will call the symbol
callback.
$self->string ( $token )
This method is called when any text in double quotes are
recognized, or on the text of protected regions. The first
argument, $token, is the contents of the string including the
quotes.
$self->symbol ( $token )
This method is called when any Verilog symbol is recognized. A
symbol is considered a non-keyword bare-word. The first argument,
$token, is the symbol.
$self->sysfunc ( $token )
This method is called when any Verilog $syscall is recognized. The
first argument, $token, is the symbol. For backward compatibility,
if not defined this function will call the symbol callback.
EXAMPLE
Here's a simple example which will print every symbol in a verilog
file.
package MyParser;
use Verilog::Parser;
@ISA = qw(Verilog::Parser);
# parse, parse_file, etc are inherited from Verilog::Parser
sub new {
my $class = shift;
#print "Class $class\n";
my $self = $class->SUPER::new();
bless $self, $class;
return $self;
}
sub symbol {
my $self = shift;
my $token = shift;
$self->{symbols}{$token}++;
}
sub report {
my $self = shift;
foreach my $sym (sort keys %{$self->{symbols}}) {
printf "Symbol %-30s occurs %4d times\n",
$sym, $self->{symbols}{$sym};
}
}
package main;
my $parser = MyParser->new();
$parser->parse_file (shift);
$parser->report();
BUGS
This is being distributed as a baseline for future contributions.
Don't expect a lot, the Parser is still naive, and there are many
awkward cases that aren't covered.
The parser currently assumes the string it is passed ends on a newline
boundary. It should be changed to allow arbitrary chunks.
Cell instantiations without any arguments are not supported, an empty
set of parenthesis are required. (Use "cell cell();", not "cell
cell;".)
DISTRIBUTION
Verilog-Perl is part of the <http://www.veripool.org/> free Verilog EDA
software tool suite. The latest version is available from CPAN and
from http://www.veripool.org/verilog-perl
<http://www.veripool.org/verilog-perl>.
Copyright 2000-2012 by Wilson Snyder. This package is free software;
you can redistribute it and/or modify it under the terms of either the
GNU Lesser General Public License Version 3 or the Perl Artistic
License Version 2.0.
AUTHORS
Wilson Snyder <wsnyder@wsnyder.org>
SEE ALSO
Verilog-Perl, Verilog::Preproc, Verilog::SigParser, Verilog::Language,
Verilog::Netlist, Verilog::Getopt, vrename, vpassert vppreproc
perl v5.14.2 2012-02-27 Parser(3)
