1MASONTIDY(1)          User Contributed Perl Documentation         MASONTIDY(1)
2
3
4

NAME

6       masontidy - Tidy HTML::Mason / Mason components
7

VERSION

9       version 2.57
10

SYNOPSIS

12           Tidy component, write to standard output:
13
14           % masontidy -m [1|2] file.mc
15
16           Tidy component(s) in place:
17
18           % masontidy -m [1|2] -r file1.mc [file2.mc ...]
19
20           Tidy standard input, write to standard output:
21
22           % masontidy -m [1|2] -p|--pipe < file.mc
23

DESCRIPTION

25       masontidy tidies Mason 1 and Mason 2 components, using perltidy to
26       format the Perl code that can be embedded in various places in the
27       component.  masontidy does not (yet) attempt to tidy the HTML or other
28       non-Perl content in a component.
29
30       For example, this:
31
32           <body>
33           %if($contents||$allow_empty) {
34             <ul>
35           %foreach my $line (@lines) {
36           %chomp($line);
37             <li>
38                 <%2+(3-4)*6%>
39             </li>
40             <li><%  foo($.bar,$.baz,  $.bleah)%></li>
41           %}
42             </ul>
43           %}
44           </body>
45
46           <%init>
47           my @articles = @{Blog::Article::Manager->get_articles(sort_by=>"create_time",limit=>5)};
48           </%init>
49
50       becomes this:
51
52           <body>
53           % if ( $contents || $allow_empty ) {
54             <ul>
55           %     foreach my $line (@lines) {
56           %         chomp($line);
57             <li>
58                 <% 2 + ( 3 - 4 ) * 6 %>
59             </li>
60             <li><% foo( $.bar, $.baz, $.bleah) %></li>
61           %     }
62             </ul>
63           %}
64           </body>
65
66           <%init>
67           my @articles =
68             @{ Blog::Article::Manager->get_articles
69                ( sort_by => "create_time", limit => 5 ) };
70           </%init>
71
72   What gets tidied
73%-lines and "<%perl>" blocks. These are indented relative to each
74           other regardless of intervening non-Perl content, e.g. note the
75           indentation of the "foreach" and "chomp" lines above.
76
77Other code blocks. "<%init>", "<%once>", "<%class>", and
78           "<%filter>" blocks are tidied in isolation from one another.
79
80Perl expressions inside "<% %>" and "<& &>" tags.
81

INVOKING

83       There are three ways of invoking "masontidy":
84
85       •   Specify a single file; the result will be written to standard
86           output.
87
88       •   Specify one or more files with the -r/--replace flag; each file
89           will be tidied in place.
90
91       •   Specify -p/--pipe; content from standard input will be tidied and
92           written to standard output.
93
94       For more advanced options, consider using "masontidy" with tidyall; it
95       will let you write to files with a separate extension, backup files
96       before overwriting, etc.
97

COMMAND-LINE OPTIONS

99       You can specify default options in the "MASONTIDY_OPT" environment
100       variable, e.g.
101
102           MASONTIDY_OPT="-m 2"
103
104       -m, --mason-version
105           Mason major version - 1 or 2. Required. Put this in "MASONTIDY_OPT"
106           if you only ever use one version on your system.
107
108       -r, --replace
109           Modify file(s) in place instead of sending to standard output.
110
111       --indent-perl-block
112           Number of spaces to initially indent all lines inside "<%perl>"
113           blocks.  The default is 2, so as to align with %-lines:
114
115               % my $foo = get_foo();
116               <%perl>
117                 if ($foo) {
118                     $bar = 6;
119                 }
120               </%perl>
121
122           With --indent-perl-block 0:
123
124               % my $foo = get_foo();
125               <%perl>
126               if ($foo) {
127                   $bar = 6;
128               }
129               </%perl>
130
131           Note that this is independent from perltidy's indentation settings.
132
133       --indent-block
134           Number of spaces to initially indent all lines inside code blocks
135           other than "<%perl>" ("<%init>", "<%class>", "<%once>", and
136           "<%filter>").  The default is 0:
137
138               <%init>
139               if ($foo) {
140                   $bar = 6;
141               }
142               </%init>
143
144           With --indent-block 2:
145
146               <%init>
147                 if ($foo) {
148                     $bar = 6;
149                 }
150               </%init>
151
152       --perltidy-argv
153           "perltidy" arguments to use everywhere. e.g.
154
155               --perltidy-argv="-noll -l=78"
156
157           or
158
159               --perltidy-argv " -noll -l=78"
160
161       --perltidy-line-argv
162           Additional "perltidy" arguments to use for Perl lines. "-fnl -fbl"
163           will always be used, to preserve existing newlines.
164
165       --perltidy-block-argv
166           Additional "perltidy" arguments to use for code blocks.
167
168       --perltidy-tag-argv
169           Additional "perltidy" arguments to use for "<% %>" and "<& &>"
170           tags.  "-fnl -fbl" will always be used, to preserve existing
171           newlines.
172
173       -h, --help
174           Print help message
175

ERRORS

177       Will throw a fatal error if a file cannot be tidied, such as when
178       perltidy encounters bad Perl syntax. However, "masontidy" is not
179       intended to be, and should not be considered, a validator; it will
180       remain silent on many syntax errors.
181

LIBRARY API

183       You can use the Mason::Tidy API from inside another Perl script/library
184       instead of calling out to this script.
185

CAVEATS / KNOWN BUGS

187       •   "<%perl>" and "</%perl>" tags must be on their own line, or else
188           their inner content will not be tidied.
189
190       •   "<% %>" tags that span multiple lines are ignored.
191
192       •   The line structure of "%-lines", "<% %>" tags, "<& &>" and
193           "<%perl>" blocks will not be altered; i.e. multiple lines will not
194           be merged and single lines will not be split, regardless of their
195           length.
196

AUTHOR

198       Jonathan Swartz <swartz@pobox.com>
199
201       This software is copyright (c) 2011 by Jonathan Swartz.
202
203       This is free software; you can redistribute it and/or modify it under
204       the same terms as the Perl 5 programming language system itself.
205
206
207
208perl v5.38.0                      2023-07-20                      MASONTIDY(1)
Impressum