/ 
Mason-Tidy-2.50
River stage one • 1 direct dependent • 1 total dependent
/ masontidy

NAME

masontidy - Tidy HTML::Mason / Mason components

VERSION

version 2.50

SYNOPSIS

Tidy component, write to standard output:

% masontidy file.mc

Process component(s) in place:

% masontidy -r file1.mc [file2.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) {
  <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) {
  <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>

This shows the three main categories of Perl in a component that can be tidied:

  • Perl blocks. <%init>, <%perl>, etc. These are tidied in isolation from one another.

  • %-lines. These are indented relative to each other regardless of intervening non-Perl content, e.g. in the example above, the foreach is indented inside the if.

    By default, Perl lines are indented with 2 spaces instead of the normal 4 spaces. This can be overriden with "--perltidy-line-argv".

    A single space is inserted after the '%'.

  • Perl expressions inside <% %> and <& &> tags. A single space is inserted before and after the tidied expression if there isn't one already.

INVOKING

There are two ways to invoke 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.

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

COMMAND-LINE OPTIONS

-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 a block of Perl. The default is 2, e.g.

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

If you set this to 0, you'll get

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

Note that this is independent from perltidy's indentation (in this case the default, 4 spaces).

--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. Defaults to "-i=2" (indent 2 characters instead of the usual 4). You can pass "-i=4" or " " (a string with just a space) to eliminate this exception.

--perltidy-line-argv "-i=4"
--perltidy-line-argv " "
--perltidy-block-argv

Additional perltidy arguments to use for Perl blocks.

--perltidy-tag-argv

Additional perltidy arguments to use for substitution tags.

-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

  • A %-line or <% %> tag will never be split up into multiple lines regardless of how long it is.

  • <% %> tags that span multiple lines are ignored.

  • Blocks that begin and end on the same line are ignored.

AUTHOR

Jonathan Swartz <swartz@pobox.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2011 by Jonathan Swartz.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.