masontidy - Man Page

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:

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

Author

Jonathan Swartz <swartz@pobox.com>

Info

2024-07-19 perl v5.40.0 User Contributed Perl Documentation