view release on metacpan or  search on metacpan

lib/Acme/Shotgun.pm  view on Meta::CPAN

    my $r = shift;
    my @patterns = (
        { 0=>[6], 1=>[3,9], 2=>[6], 3=>[3], 4=>[1,6,10], 5=>[4], 6=>[0,7] },
        { 0=>[6], 1=>[3,9], 2=>[6,11], 3=>[3,7,9], 4=>[6,10],
          5=>[4,9], 6=>[7,11] },
        { 0=>[6,9], 1=>[2,4,7], 2=>[5,9], 3=>[1,7], 4=>[6],
          5=>[3,6,9], 6=>[5] },
    );
    return $patterns[$r];
}

1;

__END__

=head1 NAME

Acme::Shotgun - Shoots holes in files

=head1 SYNOPSIS

    use Acme::Shotgun;

    my $gun = Acme::Shotgun->new(
        type  => 'double',   # double | pump
        load  => 'bird',     # bird | buck | slug
        quiet => 0,
        debug => 0,
    );

    $gun->reload();
    $gun->check();
    $gun->fire(target => '/path/to/file.txt');

=head1 DESCRIPTION

Acme::Shotgun is an object-oriented Perl module that shoots holes in plain
text files. Supports double-barrel and pump-action shotgun types, with
birdshot, buckshot, and slug ammunition - each producing a distinct damage
pattern in the target file.

Magazine state is kept in the object itself, so rounds are tracked for the
lifetime of the object.

=head1 METHODS

=head2 new(%args)

Constructs and returns a new Acme::Shotgun object. The gun is automatically
reloaded on construction.

    my $gun = Acme::Shotgun->new(
        type    => 'double',  # 'double' (default) or 'pump'
        load    => 'bird',    # 'bird' (default), 'buck', or 'slug'
        shots   => undef,     # optional: cap the number of rounds loaded
        quiet   => 0,         # suppress all output
        debug   => 0,         # dry-run mode, no file modifications
        verbose => 1,         # verbose output (disabled automatically if quiet)
    );

Dies with an error if an invalid C<type> or C<load> value is given.

=head2 reload()

Loads the magazine for the current shotgun type and ammunition. Default
capacity is 2 rounds for C<double> and 5 rounds for C<pump>. If C<shots>
was set in the constructor and is less than the default capacity, it is
used instead.

Prints a loading message and the resulting mag state when C<verbose> is on.
Returns the object for chaining.

=head2 check()

Prints the current magazine state - shotgun type, ammunition type, and
remaining round count. Returns the object for chaining.

=head2 fire(target => $path)

Fires all remaining rounds at the given target file, shooting holes into
it with each shot. The file must be an existing plain text file under 1 GB.
Each shot prints C<POW!> unless C<quiet> is set.

In C<debug> mode, C<POW!> is still printed but no file modifications are
made. Returns the object for chaining.

=head1 REFERENCE

=head2 Shotgun Types

=over 4

=item B<double>

Double-barrel. Holds 2 rounds by default. This is the default type.

=item B<pump>

Pump-action. Holds 5 rounds by default.

=back

=head2 Ammunition Types

=over 4

=item B<bird>

Birdshot. Sparse, scattered pellet holes spread across the target area.
This is the default ammunition type.

=item B<buck>

Buckshot. Denser, clustered hole patterns - more destructive than birdshot.

=item B<slug>

Slug. A tight, concentrated blast with minimal spread.

=back