1Hardware::Vhdl::Tidy(3)User Contributed Perl DocumentatioHnardware::Vhdl::Tidy(3)
2
6 Hardware::Vhdl::Tidy - VHDL code prettifier
7
9 This documentation refers to Hardware::Vhdl::Tidy version 0.80.
10
12 Command-line call to make a tidied version of a VHDL file:
13 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 Command-line call for an in-place tidy of one or more VHDL files:
19 perl -MHardware::Vhdl::Tidy -e "Hardware::Vhdl::Tidy::parse_commandline" -- -b <filenames...>
21 To tidy a VHDL file from a perl script:
23 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 To tidy some stored VHDL code in a perl script:
38 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
47 This module auto-indents VHDL source code. It may be extended in
48 future to do other types of code prettification.
49
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 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 tidy_vhdl( { source => $filehandle_reference, ... } );
64 To read from a file, pass in the filehandle reference like
65 this:
66 use Hardware::Vhdl::Tidy qw( tidy_vhdl );
68 my $fhi;
69 open $fhi, '<', $filename || die $!;
70 tidy_vhdl( { source => $fhi, ... } );
71 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 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 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 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 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 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 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 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 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 indent_spaces
124 This optional argument sets the number of columns per indentation
125 level (default is 4).
126 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 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 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 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 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 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 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 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 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 The recognised switches are:
194 -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 --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 --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 --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 -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 --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 --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
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 "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 "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
258 This module requires the following modules to be available:
259 • Hardware::Vhdl::Lexer: version 1.00 or later
261 • Carp: any version
263 • Exporter: any version
265 • Getopt::Long: any version
267
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
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 • 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 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 Patches are welcome.
289
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 This module is free software; you can redistribute it and/or modify it
298 under the same terms as Perl itself. See perlartistic.
299 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.
303perl v5.32.1 2021-01-27 Hardware::Vhdl::Tidy(3)