Hardware::Vhdl::Tidy - VHDL code prettifier
This documentation refers to Hardware::Vhdl::Tidy version 0.80.
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 } );
This module auto-indents VHDL source code. It may be extended in future to do other types of code prettification.
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:
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:
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_file
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.
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.
get_next_line
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.
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:
use Hardware::Vhdl::Tidy qw( tidy_vhdl ); my $fho; open $fho, '>', $output_filename || die $!; tidy_vhdl( { source => $fho, ... } );
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.
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.
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.
This optional argument sets the number of columns per indentation level (default is 4).
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 ;
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.
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.
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.
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.
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.
tidy_vhdl
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.
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:
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.
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'.
This switch sets the 'indent_spaces' parameter internally: this sets the number of columns per indentation level (default is 4).
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.
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.
This switch sets the 'starting_indentation' parameter internally: this sets the indentation level used at the start of each file. The default is 0.
This switch sets the 'preprocessor_prefix' parameter internally: this sets the prefix string that identifies preprocessor directive lines. The default is '#'.
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.
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.
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.
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
This module cannot be used with version of Hardware::Vhdl::Lexer before version 1.00, because the interface to the Lexer module has changed.
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. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
bug-hardware-vhdl-lexer at rt.cpan.org
Patches are welcome.
Michael Attenborough, <michael.attenborough at physics.org>
<michael.attenborough at physics.org>
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.
To install Hardware::Vhdl::Tidy, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Hardware::Vhdl::Tidy
CPAN shell
perl -MCPAN -e shell install Hardware::Vhdl::Tidy
For more information on module installation, please visit the detailed CPAN module installation guide.