Provided by: libverilog-perl_3.460-1_amd64 bug

NAME

       Verilog::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)

DESCRIPTION

       Verilog::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_protected => 0" will disable callbacks on `protected and "`pragma protect
           protected" regions, which may improve performance.

           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>.

       Copyright 2000-2019 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