Michael Attenborough > Hardware-Vhdl-Tidy > Hardware::Vhdl::Tidy

Download:
Hardware-Vhdl-Tidy-0.8.tar.gz

Dependencies

Annotate this POD (1)

View/Report Bugs
Module Version: 0.8   Source  

NAME ^

Hardware::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:

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 ^

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.

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.

syntax highlighting: