Hardware::Vhdl::Tidy(3User Contributed Perl DocumentatiHardware::Vhdl::Tidy(3)NAMEHardware::Vhdl::Tidy - VHDL code prettifier
VERSION
This documentation refers to Hardware::Vhdl::Tidy version 0.80.
SYNOPSIS
Command-line call to make a tidied version of a VHDL file:
perl -MHardware::Vhdl::Tidy -e "Hardware::Vhdl::Tidy::parse_commandline" < messy.vhd > tidied.vhd
# or:
perl -MHardware::Vhdl::Tidy -e "Hardware::Vhdl::Tidy::parse_commandline" messy.vhd > tidied.vhd
Command-line call for an in-place tidy of one or more VHDL files:
perl -MHardware::Vhdl::Tidy -e "Hardware::Vhdl::Tidy::parse_commandline" -- -b <filenames...>
To tidy a VHDL file from a perl script:
use Hardware::Vhdl::Tidy qw/ tidy_vhdl_file /;
tidy_vhdl_file( {
source => $infile,
destination => $outfile,
# the following args are optional, and the values shown are the defaults:
indent_spaces => 4, # integer value, >= 0
cont_spaces => 2, # integer value, >= 0
tab_spaces => 0, # integer value, >= 0
starting_indentation => 0, # integer value, >= 0
preprocessor_prefix => '#', # string
indent_preprocessor => 0, # boolean
} );
To tidy some stored VHDL code in a perl script:
use Hardware::Vhdl::Tidy qw/ tidy_vhdl /;
tidy_vhdl( {
source => $souce_thing, # a scalar, array ref, filehandle ref, object...
destination => $dest_thing, # a scalar, array ref, filehandle ref, object...
# options can be set here, as for tidy_vhdl_file
} );
DESCRIPTION
This module auto-indents VHDL source code. It may be extended in
future to do other types of code prettification.
SUBROUTINES
tidy_vhdl
This is the main VHDL-tidying routine. This routine takes its
arguments in the form of a reference to a hash of named arguments - the
required source and destination arguments, and optional settings to
change the style of the tidying. These areguments are:
source
Required argument. This tells the routine where to get the
original VHDL code from. This is actually just passed to
Hardware::Vhdl::Lexer and can therefore take the same types of code
source:
tidy_vhdl( { source => $filehandle_reference, ... } );
To read from a file, pass in the filehandle reference like
this:
use Hardware::Vhdl::Tidy qw( tidy_vhdl );
my $fhi;
open $fhi, '<', $filename || die $!;
tidy_vhdl( { source => $fhi, ... } );
If your source and destination data are both in files, see
"tidy_vhdl_file" for a wrapper function which will open and
close the files for you.
tidy_vhdl( { source => \@array_of_lines, ... } );
tidy_vhdl( { source => \$scalar_containing_vhdl, ... } );
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.
tidy_vhdl( { source => $object_with_get_next_line_method, ... } );
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.
tidy_vhdl( { source => \&subroutine_that_returns_lines, ... } );
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.
destination
Required argument. The tidy_code routine generates tidied code
output line by line, and outputs each line seperately using the
'destination' argument. The types of thing that you can pass as
the destination argument are:
tidy_vhdl( { destination => $filehandle_reference, ... } );
use Hardware::Vhdl::Tidy qw( tidy_vhdl );
my $fho;
open $fho, '>', $output_filename || die $!;
tidy_vhdl( { source => $fho, ... } );
tidy_vhdl( { destination => \@array_of_lines, ... } );
You can pass an array reference as the destination parameter,
in which case each line of tidied VHDL code is appended as a
new element at the end of the referenced array.
tidy_vhdl( { destination => \$scalar_containing_vhdl, ... } );
You can pass an scalar reference as the destination parameter,
in which case each line of tidied VHDL code is appended to the
referenced string.
tidy_vhdl( { destination => \&subroutine_that_accepts_lines, ... }
);
You can pass an subroutine reference as the destination
parameter, in which case the subroutine is called for each line
of tidied VHDL code, with the line of code as the subroutine
parameter.
indent_spaces
This optional argument sets the number of columns per indentation
level (default is 4).
cont_spaces
This optional argument sets the number of extra indentation spaces
applied when a long line is broken. The default is 2, as
illustrated below:
process
begin
wait on foo;
t <= al
-foo*5;
q <= t
+ bar
* x;
end
process
;
tab_spaces
This setting causes the specified number of initial space
characters to be replaced by one tab character. Note that this
setting is completely independent of the value specified for the
indent_spaces parameter. The default value of this setting is 0,
which means that tab characters are not used for indentation.
starting_indentation
If you are tidying a section of VHDL code, rather than a complete
VHDL file, you may want to have the whole tidied section indented
to the right by some amount. This parameter adds a specified
number of indentation levels (not character columns) to all the
tidied output.
preprocessor_prefix
Some people like to use a preprocessor as part of their design
entry system. Preprocessor directives need to be ignored by the
(partial) parser that this module includes to work out indentation.
By default, if a line starts with a '#' character (optionally
preceded by some whitespace) then the line is taken to be a
preprocessor directive, and is ignored by the parser. You can
change the preprocessor directive indicator to a different string
by passing it in as the 'preprocessor_prefix' argument. The way
this is implemented at the moment means that the prefixes that will
work are somewhat limited, but '#' and '@' are known to be OK. If
you want something else, try it - if it doesn't work, let me know.
indent_preprocessor
By default, preprocessor directives are left-aligned. By setting
this argument to a true value, you can request Hardware::Vhdl::Tidy
to give them the same indentation as the previous line.
tidy_vhdl_file
This function acts as a wrapper for "tidy_vhdl" for command-line usage,
converting command-line switches and filenames into function parameters
and dealing with in-place file handling.
The parameter list is the same as for "tidy_vhdl", except that 'source'
and 'destination' are filenames and are optional. If 'source' is not
defined then STDIN is read, and if 'destination' is not defined then
STDOUT is written to.
parse_commandline
This function is provided so that the module can be called from the
command line. It scans @ARGV for switches and filenames and then calls
"tidy_vhdl_file". The tidied output is either sent to STDOUT or is
used to replace the original file. Multiple files may be named in
@ARGV: these are all taken to be input for tidying.
The recognised switches are:
-b If this switch is present in @ARGV and a filename is also present,
then the file is tidied in-place. To do this, the original file is
renamed with an extension of '.bak', and then the tidied output is
written to the original filename.
--bext <string>
You can use this switch to provide an alternative extension to add
to the end of the input filename(s) to make the backup filename(s).
The default is '.bak'.
--indentation <n>
-i <n>
This switch sets the 'indent_spaces' parameter internally: this
sets the number of columns per indentation level (default is 4).
--continuation-indentation <n>
-ci <n>
This switch sets the 'cont_spaces' parameter internally: this sets
the number of extra indentation spaces applied when a long line is
broken. The default is 2.
-t <n>
--tab_spaces <n>
This switch sets the 'tab_spaces' parameter internally: this sets
the number of initial spaces to be replaced by a tab character.
The default is 0, meaning tab characters will not be used for
indentation.
--sil <n>
--starting-indentation-level <n>
This switch sets the 'starting_indentation' parameter internally:
this sets the indentation level used at the start of each file.
The default is 0.
--ppp <string>
--preprocessor-prefix <string>
This switch sets the 'preprocessor_prefix' parameter internally:
this sets the prefix string that identifies preprocessor directive
lines. The default is '#'.
DIAGNOSTICS
"tidy_vhdl 'source' 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.
"tidy_vhdl 'source' 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, or any
other error message not documented above, I would appreciate a bug
report describing how to reproduce the error.
DEPENDENCIES
This module requires the following modules to be available:
· Hardware::Vhdl::Lexer: version 1.00 or later
· Carp: any version
· Exporter: any version
· Getopt::Long: any version
INCOMPATIBILITIES
This module cannot be used with version of Hardware::Vhdl::Lexer before
version 1.00, because the interface to the Lexer module has changed.
BUGS AND LIMITATIONS
· Indenting of preprocessor commands doesn't work correctly with
multi-line preprocessor commands (i.e. where the preprocessor
command is made to continue onto further lines by including a
backslash at the end of the line).
· Not all preprocessor_prefix settings will actually work. Ideally
this should be a regexp, but since the common '#' and '@' prefixes
work this is not a priority to fix at the moment.
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.
Patches are welcome.
AUTHOR
Michael Attenborough, "<michael.attenborough at physics.org>"
LICENCE AND COPYRIGHT
Copyright (c) 2006 Michael Attenborough ("<michael.attenborough at
physics.org>"). All rights reserved.
This module is free software; you can redistribute it and/or modify it
under the same terms as Perl itself. See perlartistic.
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
perl v5.14.1 2007-04-27 Hardware::Vhdl::Tidy(3)
