MASONTIDY(1)

📦
version 2.57 · 2 versions
, in fedora 43

💖 MASONTIDY 💖

okay bestie, sit down, hydrate, because i'm about to put you onto masontidy, and honestly? it's giving organized. it tidies your HTML::Mason / Mason components. yes, the version is 2.57. yes, that matters. moving on. 🎀

✨ SYNOPSIS ✨

Tidy a component, write it 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 🌸

so masontidy tidies Mason 1 and Mason 2 components, and it does that by handing the Perl code — wherever it's hiding inside your component — off to perltidy to get formatted. periodt. 💅

but bestie, listen: masontidy does not (yet) attempt to tidy the HTML or other non-Perl content in a component. not its job. not today. 🙈

like, 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>

look at that glow-up. i'm obsessed. 😭✨

🦋 What gets tidied

  • %-lines and <%perl> blocks. these get indented relative to each other, no matter how much non-Perl content is chillin' in between — like, notice the indentation of the foreach and chomp lines up there. iykyk.
  • Other code blocks. <%init>, <%once>, <%class>, and <%filter> blocks get tidied in isolation from one another. separate vibes, separate treatments.
  • Perl expressions inside <% %> and <& &> tags. yes, those too.

👑 INVOKING 👑

there are exactly three ways of invoking masontidy, bestie, pick your fighter:

  • 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.

and 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. main character tooling fr fr. 🫶

💅 COMMAND-LINE OPTIONS 💅

you can specify default options in the MASONTIDY_OPT environment variable, like:

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, so you never have to think about it again. 💖
  • -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. two different girls, two different jobs. 💁

  • --indent-block — number of spaces to initially indent all lines inside code blocks other than <%perl> (so: <%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. not up for debate. ✋
  • --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. same rule, different tag. 💜
  • -h, --help — print help message.

💀 ERRORS 💀

masontidy will throw a fatal error if a file cannot be tidied — like when perltidy encounters bad Perl syntax. no cap, it will simply pass away.

however, masontidy is not intended to be, and should not be considered, a validator; it will remain silent on many syntax errors. it's a stylist, not a bouncer. do not trust it to catch your crimes. 🙈

🌈 LIBRARY API 🌈

you can use the Mason::Tidy API from inside another Perl script/library instead of calling out to this script. yes, you can just import the whole vibe. ✨

😭 CAVEATS / KNOWN BUGS 😭

the fine print, bestie, read it:

  • <%perl> and </%perl> tags must be on their own line, or else their inner content will not be tidied. no line, no service. 💔
  • <% %> 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. so if your line is 400 characters long, that's between you and your line. 🔥

🎀 AUTHOR 🎀

Jonathan Swartz <swartz@pobox.com>

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.

and that's the whole page, bestie — brought to you by perl v5.42.0, dated 2025-07-25, from the MASONTIDY(1) era of User Contributed Perl Documentation. go forth and tidy. you got this. 💖🦋🌸

📦 where this page comes from