Hardware::Vhdl::Lexer(User Contributed Perl DocumentatHardware::Vhdl::Lexer(3)NAMEHardware::Vhdl::Lexer - Split VHDL code into lexical tokens
SYNOPSIS
use Hardware::Vhdl::Lexer;
# Open the file to get the VHDL code from
my $fh;
open $fh, '<', 'device_behav.vhd' || die $!
# Create the Lexer object
my $lexer = Hardware::Vhdl::Lexer->new({ linesource => $fh });
# Dump all the tokens
my ($token, $type);
while( (($token, $type) = $lexer->get_next_token) && defined $token) {
print "# type = '$type' token='$token'\n";
}
DESCRIPTION
"Hardware::Vhdl::Lexer" splits VHDL code into lexical tokens. To use
it, you need to first create a lexer object, passing in something which
will supply chunks of VHDL code to the lexer. Repeated calls to the
"get_next_token" method of the lexer will then return VHDL tokens (in
scalar context) or a token type code and the token (in list context).
"get_next_token" returns undef when there are no more tokens to be
read.
NB: in this documentation I refer to "lines" of VHDL code and "line"
sources etc., but in fact the chunks of code don't have to be broken up
at line-ends - they can be broken anywhere that isn't in the middle of
a token. New-line characters just happen to be a simple and safe way
to split up a file. You don't even have to split up the VHDL at all,
you can pass in the whole thing as the first and only "line".
CONSTRUCTOR
new({ linesource => <source> [, nhistory => N] })
Note that from version 1.0 of this module the arguments must now be
given as a hash reference rather than a hash, so the curly brackets
above are required.
The linesource argument is required: it defines where the VHDL source
code will be taken from (see below).
The optional nhistory argument sets how many "code" tokens (see the
"get_next_token" method) will be remembered for access by the "history"
method.
new({ linesource => $filehandle_reference [, nhistory => N] })
To read from a file, pass in the filehandle reference like this:
use Hardware::Vhdl::Lexer;
my $fh;
open $fh, '<', $filename || die $!;
my $lexer = Hardware::Vhdl::Lexer->new({ linesource => $fh });
new({ linesource => \@array_of_lines [, nhistory => N] })
new({ linesource => \$scalar_containing_vhdl [, nhistory => N] })
To read VHDL source that is already in program memory, the
linesource argument can be a reference to either an array of lines
or a single string which can have embedded newlines.
new({ linesource => $object_with_get_next_line_method [, nhistory => N]
})
The linesource argument can be an object with a "get_next_line"
method. This method must return undef when there are no more lines
to read.
new({ linesource => \&subroutine_that_returns_lines [, nhistory => N]
})
If none of the above input methods suits your needs, you can give a
subroutine reference and wrap whatever code you need to get the
VHDL source. When called, this subroutine must return each line of
source code in turn, and then return undef when there are no more
lines.
METHODSget_linesource()
Returns the linesource argument passed into the constructor.
Before version 1.0 of this module, this method was called
"linesource()".
"get_next_token()"
In scalar context, returns the next VHDL token.
In list context, returns a token type code and the token
Nothing is removed from the source code: if you concatenate all the
tokens returned by "get_next_token()", you will get the same result
as if you concatenate all the strings returned by the linesource
object.
The token type codes are 1 or 2-character strings. When the codes
are 2 characters, the first character gives the general class of
the token and the second indicates its type more specifically. The
first character will be 'w' for whitespace, 'r' for comments
(remarks) or 'c' for code. It should be possible to remove all
comment tokens, and change whitespace tokens for different
whitespace, and always end up with functionally equivalent code.
The token type codes are:
wn Whitespace:Newline. This could be any of \012, \015, \015\012
or \012\015.
ws Whitespace:Spaces. A group of whitespace characters which
match the /s regexp pattern but which do not include any
carriage-return or linefeed characters.
r Remark. The token will start with two dashes and include the
remainder of the source code line, not including any newline
characters. The next token will either be a newline or undef.
cs Code:String literal. The lexer accepts multi-line strings,
even though the VHDL specification does not allow them.
cc Code:Character literal.
cb Code:Bit_vector literal. For example, "B"001_1010"" or
"O"7720"" or "H"A7_DEAD"".
cn Code:Numeric literal. This could be a specified-base literal
like "8#7720#" or a simple integer or floating-point value.
ci Code:Identifier or keyword. For example, "package" or
"my_signal_23" or "/extended identifier$%!/"..
cp Code:Punctuation. A 1 or 2-character group of punctuation
symbols that is part of VHDL syntax. For example, '<=' is
returned as a single 'cp' token, as is '&', but '#' would be
returned as an unexpected character (see below).
cu Unexpected character. Any character in the source that does
not match any of the above definitions, and cannot be part of
valid VHDL code. Note that prior to version 1.0 of this
module, these would be returned with the 'cp' token type code.
history(N)
Returns previous code tokens. N must not be larger than the
nhistory argument passed to the constructor. history(0) will
return the text of the last token returned by "get_next_token"
whose type started with a 'c', history(1) will return the code
token before that, and so on.
AUTHOR
Michael Attenborough, "<michael.attenborough at physics.org>"
DEPENDENCIES
This module requires the following modules to be available:
Carp: any version Class::Std: any version Readonly: version 1.03 or
later
ERRORS AND WARNINGS
"Argument to Hardware::Vhdl::Lexer->new() must be hash reference"
Have you remembered to put curly brackets around the argument list?
Pre-1.0 versions of this module used to take the arguments to new()
as a direct hash, but version 1.0 onwards need a hash reference.
This means that the curly brackets need to be added when migrating
from pre-1.0 to 1.0 or later.
# Old style (argument list is hash) - doesn't work any more
my $lexer = Hardware::Vhdl::Lexer->new( linesource => $fh );
# New style (argument is a hash ref) - do it this way now
my $lexer = Hardware::Vhdl::Lexer->new({ linesource => $fh });
"Hardware::Vhdl::Lexer constructor requires a linesource to be
specified"
The 'linesource' argument to Hardware::Vhdl::Lexer->new() is
required, and it is a fatal error not to provide one.
"Hardware::Vhdl::Lexer->new 'linesource' parameter is not of a valid
type (it is not a reference)"
The linesource parameter needs to be a reference to something. If
your VHDL code to be passed is in a scalar string, you need to pass
in a reference to the string, not the string itself.
"Hardware::Vhdl::Lexer->new 'linesource' parameter is not of a valid
type (type is '<type>')"
The linesource parameter that you have passed to new() does not
appear to be a reference to a scalar, a list, a filehandle, a
subroutine or an object with a get_next_line method. You have
passed a reference to something (otherwise you would see the
previous message) and the error message will tell you what it
appears to be a reference to.
"Internal error (token failed to match anything)"
This is a "this should never happen" type of error, and is a sign
that I have included a bug. If you ever see this error, I would
appreciate a bug report describing how to reproduce the error.
BUGS AND LIMITATIONS
Please report any bugs or feature requests to "bug-hardware-vhdl-lexer
at rt.cpan.org", or through the web interface at
http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Hardware-Vhdl-Lexer
<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Hardware-Vhdl-Lexer>.
I will be notified, and then you'll automatically be notified of
progress on your bug as I make changes.
SUPPORT
You can find documentation for this module with the perldoc command.
perldoc Hardware::Vhdl::Lexer
You can also look for information at:
· AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/Hardware-Vhdl-Lexer
<http://annocpan.org/dist/Hardware-Vhdl-Lexer>
· CPAN Ratings
http://cpanratings.perl.org/d/Hardware-Vhdl-Lexer
<http://cpanratings.perl.org/d/Hardware-Vhdl-Lexer>
· RT: CPAN's request tracker
http://rt.cpan.org/NoAuth/Bugs.html?Dist=Hardware-Vhdl-Lexer
<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Hardware-Vhdl-Lexer>
· Search CPAN
http://search.cpan.org/dist/Hardware-Vhdl-Lexer
<http://search.cpan.org/dist/Hardware-Vhdl-Lexer>
LICENSE AND COPYRIGHT
Copyright 2006 Michael Attenborough, all rights reserved.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
perl v5.14.1 2006-09-15 Hardware::Vhdl::Lexer(3)
