view release on metacpan or  search on metacpan

lib/Algorithm/Gutter/Cell.pod  view on Meta::CPAN

=head1 NAME

Algorithm::Gutter::Cell - cellular automata to simulate rain in a gutter

=head1 DESCRIPTION

This module provides cells that can populate a L<Algorithm::Gutter>
gutter array reference, or the caller could instead provide their own
object that conforms to the same interface as this module.

Cells may contain some amount of fluid, may have a hole in them that
drains some amount of the fluid at some threshold, and the hole may or
may not be enabled. An update code reference should be supplied that
will trigger when fluid drains from the cell.

=head1 FIELDS

Note that mutator methods must be written as C<<$cell->enabled = 1>> and
not C<<$cell->enabled(1)>>.

=over 4

=item B<amount>

Mutator for the amount of fluid present in the cell, by default C<0>.

=item B<context>

Mutator for a user-supplied scalar that can contain additional state for
the cell.

=item B<enabled>

Mutator for whether the cell's hole is enabled, or not. Cells are not
enabled by default.

=item B<id>

Reader for a user-supplied ID (C<0> by default) for the object. Could be
set to the gutter array index to help track down where an otherwise
unknown cell reference lives.

=item B<threshold>

Mutator for the threshold at which the cell drains, by default a very
large integer. Cells with actual holes in them should probably set the
threshold to a much smaller non-negative integer value. And one may also
want to sometimes B<enable> the cell so that it can drain.

=item B<update>

Mutator for a code reference that will be called when the B<drain>
method in L<Algorithm::Gutter> calculates that this cell's fluid
drains. The reference is called with the cell object, cell index in the
gutter list, how much fluid drained, and an optional I<stash> provided
by the caller.

The caller is responsible for the return value, which will be
accumulated by the parent B<drain> method and returned to the caller as
a list. For example, the B<update> code could return MIDI events, the
amount of fluid drained, both, neither, or other values as need be.

Failing to set an update callback for a cell that triggers will result
in an exception.

=back

=head1 METHODS

=over 4

=item B<new> [ I<fields ...> ]

Constructor.

=back

=head1 BUGS

These probably should be called errors, not bugs.

=head1 SEE ALSO

L<Object::Pad>

=head1 AUTHOR

Jeremy Mates

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2024 by Jeremy Mates

This module is distributed under the (Revised) BSD License.

=cut