1Hardware::Vhdl::Tidy(3)User Contributed Perl DocumentatioHnardware::Vhdl::Tidy(3)
2
3
4

NAME

6       Hardware::Vhdl::Tidy - VHDL code prettifier
7

VERSION

9       This documentation refers to Hardware::Vhdl::Tidy version 0.80.
10

SYNOPSIS

12       Command-line call to make a tidied version of a VHDL file:
13
14           perl -MHardware::Vhdl::Tidy -e "Hardware::Vhdl::Tidy::parse_commandline" < messy.vhd > tidied.vhd
15           # or:
16           perl -MHardware::Vhdl::Tidy -e "Hardware::Vhdl::Tidy::parse_commandline" messy.vhd > tidied.vhd
17
18       Command-line call for an in-place tidy of one or more VHDL files:
19
20           perl -MHardware::Vhdl::Tidy -e "Hardware::Vhdl::Tidy::parse_commandline" -- -b <filenames...>
21
22       To tidy a VHDL file from a perl script:
23
24           use Hardware::Vhdl::Tidy qw/ tidy_vhdl_file /;
25           tidy_vhdl_file( {
26               source => $infile,
27               destination => $outfile,
28               # the following args are optional, and the values shown are the defaults:
29               indent_spaces        => 4, # integer value, >= 0
30               cont_spaces          => 2, # integer value, >= 0
31               tab_spaces           => 0, # integer value, >= 0
32               starting_indentation => 0, # integer value, >= 0
33               preprocessor_prefix  => '#', # string
34               indent_preprocessor  => 0, # boolean
35           } );
36
37       To tidy some stored VHDL code in a perl script:
38
39           use Hardware::Vhdl::Tidy qw/ tidy_vhdl /;
40           tidy_vhdl( {
41               source => $souce_thing, # a scalar, array ref, filehandle ref, object...
42               destination => $dest_thing,  # a scalar, array ref, filehandle ref, object...
43               # options can be set here, as for tidy_vhdl_file
44           } );
45

DESCRIPTION

47       This module auto-indents VHDL source code.  It may be extended in
48       future to do other types of code prettification.
49

SUBROUTINES

51   tidy_vhdl
52       This is the main VHDL-tidying routine.  This routine takes its
53       arguments in the form of a reference to a hash of named arguments - the
54       required source and destination arguments, and optional settings to
55       change the style of the tidying.  These areguments are:
56
57       source
58           Required argument.  This tells the routine where to get the
59           original VHDL code from.  This is actually just passed to
60           Hardware::Vhdl::Lexer and can therefore take the same types of code
61           source:
62
63           tidy_vhdl( { source => $filehandle_reference, ... } );
64               To read from a file, pass in the filehandle reference like
65               this:
66
67                   use Hardware::Vhdl::Tidy qw( tidy_vhdl );
68                   my $fhi;
69                   open $fhi, '<', $filename || die $!;
70                   tidy_vhdl( { source => $fhi, ... } );
71
72               If your source and destination data are both in files, see
73               "tidy_vhdl_file" for a wrapper function which will open and
74               close the files for you.
75
76           tidy_vhdl( { source => \@array_of_lines, ... } );
77           tidy_vhdl( { source => \$scalar_containing_vhdl, ... } );
78               To read VHDL source that is already in program memory, the
79               linesource argument can be a reference to either an array of
80               lines or a single string which can have embedded newlines.
81
82           tidy_vhdl( { source => $object_with_get_next_line_method, ... } );
83               The linesource argument can be an object with a "get_next_line"
84               method.  This method must return undef when there are no more
85               lines to read.
86
87           tidy_vhdl( { source => \&subroutine_that_returns_lines, ... } );
88               If none of the above input methods suits your needs, you can
89               give a subroutine reference and wrap whatever code you need to
90               get the VHDL source.  When called, this subroutine must return
91               each line of source code in turn, and then return undef when
92               there are no more lines.
93
94       destination
95           Required argument.  The tidy_code routine generates tidied code
96           output line by line, and outputs each line seperately using the
97           'destination' argument.  The types of thing that you can pass as
98           the destination argument are:
99
100           tidy_vhdl( { destination => $filehandle_reference, ... } );
101                   use Hardware::Vhdl::Tidy qw( tidy_vhdl );
102                   my $fho;
103                   open $fho, '>', $output_filename || die $!;
104                   tidy_vhdl( { source => $fho, ... } );
105
106           tidy_vhdl( { destination => \@array_of_lines, ... } );
107               You can pass an array reference as the destination parameter,
108               in which case each line of tidied VHDL code is appended as a
109               new element at the end of the referenced array.
110
111           tidy_vhdl( { destination => \$scalar_containing_vhdl, ... } );
112               You can pass an scalar reference as the destination parameter,
113               in which case each line of tidied VHDL code is appended to the
114               referenced string.
115
116           tidy_vhdl( { destination => \&subroutine_that_accepts_lines, ... }
117           );
118               You can pass an subroutine reference as the destination
119               parameter, in which case the subroutine is called for each line
120               of tidied VHDL code, with the line of code as the subroutine
121               parameter.
122
123       indent_spaces
124           This optional argument sets the number of columns per indentation
125           level (default is 4).
126
127       cont_spaces
128           This optional argument sets the number of extra indentation spaces
129           applied when a long line is broken.  The default is 2, as
130           illustrated below:
131
132               process
133               begin
134                   wait on foo;
135                   t <= al
136                     -foo*5;
137                   q <= t
138                     + bar
139                     * x;
140               end
141                 process
142                 ;
143
144       tab_spaces
145           This setting causes the specified number of initial space
146           characters to be replaced by one tab character.  Note that this
147           setting is completely independent of the value specified for the
148           indent_spaces parameter.  The default value of this setting is 0,
149           which means that tab characters are not used for indentation.
150
151       starting_indentation
152           If you are tidying a section of VHDL code, rather than a complete
153           VHDL file, you may want to have the whole tidied section indented
154           to the right by some amount.  This parameter adds a specified
155           number of indentation levels (not character columns) to all the
156           tidied output.
157
158       preprocessor_prefix
159           Some people like to use a preprocessor as part of their design
160           entry system.  Preprocessor directives need to be ignored by the
161           (partial) parser that this module includes to work out indentation.
162           By default, if a line starts with a '#' character (optionally
163           preceded by some whitespace) then the line is taken to be a
164           preprocessor directive, and is ignored by the parser.  You can
165           change the preprocessor directive indicator to a different string
166           by passing it in as the 'preprocessor_prefix' argument.  The way
167           this is implemented at the moment means that the prefixes that will
168           work are somewhat limited, but '#' and '@' are known to be OK.  If
169           you want something else, try it - if it doesn't work, let me know.
170
171       indent_preprocessor
172           By default, preprocessor directives are left-aligned.  By setting
173           this argument to a true value, you can request Hardware::Vhdl::Tidy
174           to give them the same indentation as the previous line.
175
176   tidy_vhdl_file
177       This function acts as a wrapper for "tidy_vhdl" for command-line usage,
178       converting command-line switches and filenames into function parameters
179       and dealing with in-place file handling.
180
181       The parameter list is the same as for "tidy_vhdl", except that 'source'
182       and 'destination' are filenames and are optional.  If 'source' is not
183       defined then STDIN is read, and if 'destination' is not defined then
184       STDOUT is written to.
185
186   parse_commandline
187       This function is provided so that the module can be called from the
188       command line.  It scans @ARGV for switches and filenames and then calls
189       "tidy_vhdl_file".  The tidied output is either sent to STDOUT or is
190       used to replace the original file.  Multiple files may be named in
191       @ARGV: these are all taken to be input for tidying.
192
193       The recognised switches are:
194
195       -b  If this switch is present in @ARGV and a filename is also present,
196           then the file is tidied in-place.  To do this, the original file is
197           renamed with an extension of '.bak', and then the tidied output is
198           written to the original filename.
199
200       --bext <string>
201           You can use this switch to provide an alternative extension to add
202           to the end of the input filename(s) to make the backup filename(s).
203           The default is '.bak'.
204
205       --indentation <n>
206       -i <n>
207           This switch sets the 'indent_spaces' parameter internally: this
208           sets the number of columns per indentation level (default is 4).
209
210       --continuation-indentation <n>
211       -ci <n>
212           This switch sets the 'cont_spaces' parameter internally: this sets
213           the number of extra indentation spaces applied when a long line is
214           broken.  The default is 2.
215
216       -t <n>
217       --tab_spaces <n>
218           This switch sets the 'tab_spaces' parameter internally: this sets
219           the number of initial spaces to be replaced by a tab character.
220           The default is 0, meaning tab characters will not be used for
221           indentation.
222
223       --sil <n>
224       --starting-indentation-level <n>
225           This switch sets the 'starting_indentation' parameter internally:
226           this sets the indentation level used at the start of each file.
227           The default is 0.
228
229       --ppp <string>
230       --preprocessor-prefix <string>
231           This switch sets the 'preprocessor_prefix' parameter internally:
232           this sets the prefix string that identifies preprocessor directive
233           lines.  The default is '#'.
234

DIAGNOSTICS

236       "tidy_vhdl 'source' parameter is not of a valid type (it is not a
237       reference)"
238           The linesource parameter needs to be a reference to something.  If
239           your VHDL code to be passed is in a scalar string, you need to pass
240           in a reference to the string, not the string itself.
241
242       "tidy_vhdl 'source' parameter is not of a valid type (type is
243       '<type>')"
244           The linesource parameter that you have passed to new() does not
245           appear to be a reference to a scalar, a list, a filehandle, a
246           subroutine or an object with a get_next_line method.  You have
247           passed a reference to something (otherwise you would see the
248           previous message) and the error message will tell you what it
249           appears to be a reference to.
250
251       "Internal error (token failed to match anything)"
252           This is a "this should never happen" type of error, and is a sign
253           that I have included a bug.  If you ever see this error, or any
254           other error message not documented above, I would appreciate a bug
255           report describing how to reproduce the error.
256

DEPENDENCIES

258       This module requires the following modules to be available:
259
260       ·   Hardware::Vhdl::Lexer: version 1.00 or later
261
262       ·   Carp: any version
263
264       ·   Exporter: any version
265
266       ·   Getopt::Long: any version
267

INCOMPATIBILITIES

269       This module cannot be used with version of Hardware::Vhdl::Lexer before
270       version 1.00, because the interface to the Lexer module has changed.
271

BUGS AND LIMITATIONS

273       ·   Indenting of preprocessor commands doesn't work correctly with
274           multi-line preprocessor commands (i.e. where the preprocessor
275           command is made to continue onto further lines by including a
276           backslash at the end of the line).
277
278       ·   Not all preprocessor_prefix settings will actually work.  Ideally
279           this should be a regexp, but since the common '#' and '@' prefixes
280           work this is not a priority to fix at the moment.
281
282       Please report any bugs or feature requests to "bug-hardware-vhdl-lexer
283       at rt.cpan.org", or through the web interface at
284       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Hardware-Vhdl-Lexer>.
285       I will be notified, and then you'll automatically be notified of
286       progress on your bug as I make changes.
287
288       Patches are welcome.
289

AUTHOR

291       Michael Attenborough, "<michael.attenborough at physics.org>"
292
294       Copyright (c) 2006 Michael Attenborough ("<michael.attenborough at
295       physics.org>"). All rights reserved.
296
297       This module is free software; you can redistribute it and/or modify it
298       under the same terms as Perl itself. See perlartistic.
299
300       This program is distributed in the hope that it will be useful, but
301       WITHOUT ANY WARRANTY; without even the implied warranty of
302       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
303
304
305
306perl v5.30.1                      2020-01-30           Hardware::Vhdl::Tidy(3)
Impressum