/ 
File-Find-Mason-0.0.4
River stage zero No dependents
/ File::Find::Mason

NAME

File::Find::Mason - Find files that contain Mason components

VERSION

Version 0.0.3

SYNOPSIS

use File::Find::Mason;

my @files = File::Find::Mason::find(\%options, @directories);
my $is_mason = File::Find::Mason::wanted(\%options, $filename);

DESCRIPTION

Mason templates may have multiple extensions depending on their use, particularly for HTTP APIs. Some Mason templates may be very brief and contain only static HTML, whereas others may contain only a single Mason component or comment indicating their purpose. This module should aide quickly finding all or some such Mason file.

Basic usage

Usage follows the patterns of File::Find.

File::Find::Mason::find(\%options, @directories)

When provided with no wanted option, find() searches the given directories using File::Find::find for Mason-like files and returns them as a list. If a wanted callback is provided in %options, it is invoked for every matching file.

The %options are passed directly to File::Find::find except for the wanted handler.

File::Find::Mason::wanted(\%options, $filename)

When provided with no $options{wanted}, the function will return true when $filename is a Mason file, based on the options passed for detection. If a wanted function is passed with the options, it will be invoked as a callback for every matching filename.

Mason file identification

A file is consider a valid Mason file when:

  • There is no shebang line.

  • The file contains one of the configured Mason components (default %args, %once, %perl).

  • The file contains a balanced component call line of the form <&.*&>.

  • The file contains a terminal modeline of the form %#.*mason.

Options

The following options are supported.

wanted

When provided to wanted, this should be a callback of the form function(filename).

When provided to find, this can be a standard File::Find wanted function using $File::Find::name and other variables as provided.

args
once
perl
call

Enabled by default, any of these can be set to false to prevent matching a file with the equivalent Mason component, of the form <%args> etcetera.

shebang

By default, shebang matching skips any file with a shebang line. If false, shebang skipping is disabled.

modeline

When true, modeline enables matching of a vim-style modeline, namely a Mason-comment line containing a Perl comment character (#) and the string mason. The line can appear anywhere in the file.

verbose

If files are not found or not readable, an error will be given when verbose is true.

BUGS

  • Shebangs/modelines match the beginning of the line anywhere in the file.