masontidy man page

masontidy — Tidy HTML::Mason / Mason components

Version

version 2.57

Synopsis

Tidy component, write to standard output:
% masontidy -m [1|2] file.mc
Tidy component(s) in place:
% masontidy -m [1|2] -r file1.mc [file2.mc ...]
Tidy standard input, write to standard output:
% masontidy -m [1|2] -p|--pipe < file.mc

Description

masontidy tidies Mason 1 and Mason 2 components, using perltidy to format the Perl code that can be embedded in various places in the component. masontidy does not (yet) attempt to tidy the HTML or other non-Perl content in a component.

For example, this:

<body>
%if($contents||$allow_empty) {
  <ul>
%foreach my $line (@lines) {
%chomp($line);
  <li>
      <%2+(3-4)*6%>
  </li>
  <li><%  foo($.bar,$.baz,  $.bleah)%></li>
%}
  </ul>
%}
</body>

<%init>
my @articles = @{Blog::Article::Manager->get_articles(sort_by=>"create_time",limit=>5)};
</%init>

becomes this:

<body>
% if ( $contents || $allow_empty ) {
  <ul>
%     foreach my $line (@lines) {
%         chomp($line);
  <li>
      <% 2 + ( 3 - 4 ) * 6 %>
  </li>
  <li><% foo( $.bar, $.baz, $.bleah) %></li>
%     }
  </ul>
%}
</body>
<%init>
my @articles =
  @{ Blog::Article::Manager->get_articles
     ( sort_by => "create_time", limit => 5 ) };
</%init>

What gets tidied

·
%-lines and "<%perl>" blocks. These are indented relative to each other regardless of intervening non-Perl content, e.g. note the indentation of the "foreach" and "chomp" lines above.
·
Other code blocks. "<%init>", "<%once>", "<%class>", and "<%filter>" blocks are tidied in isolation from one another.
·
Perl expressions inside "<% %>" and "<& &>" tags.

Invoking

There are three ways of invoking "masontidy":

·
Specify a single file; the result will be written to standard output.
·
Specify one or more files with the -r/--replace flag; each file will be tidied in place.
·
Specify -p/--pipe; content from standard input will be tidied and written to standard output.

For more advanced options, consider using "masontidy" with tidyall; it will let you write to files with a separate extension, backup files before overwriting, etc.

Command-Line Options

You can specify default options in the "MASONTIDY_OPT" environment variable, e.g.

MASONTIDY_OPT="-m 2"
-m, --mason-version
Mason major version - 1 or 2. Required. Put this in "MASONTIDY_OPT" if you only ever use one version on your system.
-r, --replace
Modify file(s) in place instead of sending to standard output.
--indent-perl-block

Number of spaces to initially indent all lines inside "<%perl>" blocks. The default is 2, so as to align with %-lines:

% my $foo = get_foo();
<%perl>
  if ($foo) {
      $bar = 6;
  }
</%perl>

With --indent-perl-block 0:

% my $foo = get_foo();
<%perl>
if ($foo) {
    $bar = 6;
}
</%perl>

Note that this is independent from perltidy's indentation settings.

--indent-block

Number of spaces to initially indent all lines inside code blocks other than "<%perl>" ("<%init>", "<%class>", "<%once>", and "<%filter>"). The default is 0:

<%init>
if ($foo) {
    $bar = 6;
}
</%init>

With --indent-block 2:

<%init>
  if ($foo) {
      $bar = 6;
  }
</%init>
--perltidy-argv

"perltidy" arguments to use everywhere. e.g.

--perltidy-argv="-noll -l=78"

or

--perltidy-argv " -noll -l=78"
--perltidy-line-argv
Additional "perltidy" arguments to use for Perl lines. "-fnl -fbl" will always be used, to preserve existing newlines.
--perltidy-block-argv
Additional "perltidy" arguments to use for code blocks.
--perltidy-tag-argv
Additional "perltidy" arguments to use for "<% %>" and "<& &>" tags. "-fnl -fbl" will always be used, to preserve existing newlines.
-h, --help
Print help message

Errors

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

Library API

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

Caveats / Known Bugs

·
"<%perl>" and "</%perl>" tags must be on their own line, or else their inner content will not be tidied.
·
"<% %>" tags that span multiple lines are ignored.
·
The line structure of "%-lines", "<% %>" tags, "<& &>" and "<%perl>" blocks will not be altered; i.e. multiple lines will not be merged and single lines will not be split, regardless of their length.

Author

Jonathan Swartz <swartz@pobox.com>

Info

2012-10-07 perl v5.24.0 User Contributed Perl Documentation