NAME

Brick::Bucket - The thing that keeps everything straight

SYNOPSIS

        use Brick::Bucket;

        my $bucket = Brick::Bucket->new();

DESCRIPTION

Class methods

new()

Creates a new bucket to store Brick constraints

entry_class

Although this is really a class method, it's also an object method because Perl doesn't know the difference. The return value, however, isn't designed to be mutable. You may want to change it in a subclass, but the entire system still needs to agree on what it is. Since I don't need to change it (although I don't want to hard code it either), I have a method for it. If you need something else, figure out the consequences and see if this could work another way.

Object methods

add_to_bucket( HASHREF )

add_to_pool # DEPRECATED

You can pass these entries in the HASHREF:

        code        - the coderef to add to the bucket
        name        - a name for the entry, which does not have to be unique
        description - explain what this coderef does
        args        - a reference to the arguments that the coderef closes over
        fields      - the input field names the coderef references
        unique      - this name has to be unique

If you pass a true value for the unique value, then there can't be any other brick with that name already, or a later brick which tries to use the same name will fail.

The method adds these fields to the entry:

        gv          - a GV reference from B::svref_2object($sub), useful for
                                finding where an anonymous coderef came from

        created_by  - the name of the routine that added the entry to the bucket

It returns the subroutine reference.

get_from_bucket( CODEREF )

Gets the entry for the specified CODEREF. If the CODEREF is not in the bucket, it returns false.

The return value is an entry instance.

get_brick_by_name( NAME )

Gets the code references for the bricks with the name NAME. Since bricks don't have to have a unique name, it might return more than one.

In list context return the bricks with NAMe, In scalar context returns the number of bricks it found.

get_all_keys

Returns an unordered list of the keys (entry IDs) in the bucket. Although you probably know that the bucket is a hash, use this just in case the data structure changes.

comprise( COMPOSED_CODEREF, THE_OTHER_CODEREFS )

Tell the bucket that the COMPOSED_CODEREF is made up of THE_OTHER_CODEREFS.

        $bucket->comprise( $sub, @component_subs );

dump_bucket

Show the names and descriptions of the entries in the bucket. This is mostly a debugging tool.

Field labels

The bucket can store a dictionary that maps field names to arbitrary strings. This way, a brick can translate and input parameter name (e.g. a CGI input field name) into a more pleasing string for humans for its error messages. By providing methods in the bucket class, every brick has a chance to call them.

use_field_labels( HASHREF )

Set the hash that get_field_label uses to map field names to field labels.

This method croaks if its argument isn't a hash reference.

get_field_label( FIELD )

Retrieve the label for FIELD.

set_field_label( FIELD, VALUE )

Set the label for FIELD to VALUE. It returns VALUE.

Brick::Bucket::Entry

my $entry = Brick::Bucket::Entry->new( HASHREF )

$entry->get_gv()

Get the GV object associated with the entry. The GV object comes from the svref_2object(SVREF) function in the B module. Use it to get information about the coderef's creation.

        my $entry = $bucket->get_entry( $coderef );
        my $gv    = $entry->get_gv;

        printf "$coderef comes from %s line %s\n",
                map { $gv->$_ } qw( FILE LINE );

The B documentation explains what you can do with the GV object.

$entry->get_name()

Get the name for the entry.

$entry->get_description()

Get the description for the entry.

$entry->get_coderef()

Get the coderef for the entry. This is the actual reference that you can execute, not the string form used for the bucket key.

$entry->get_comprises()

Get the subroutines that this entry composes. A coderef might simply combine other code refs, and this part gives the map. Use it recursively to get the tree of code refs that make up this entry.

$entry->get_created_by()

Get the name of the routine that added the entry to the bucket. This is handy for tracing the flow of code refs around the program. Different routines my make coderefs with the same name, so you also want to know who created it. You can use this with get_gv to get file and line numbers too.

$entry->get_fields()

$entry->set_name( SCALAR )

Set the entry's name. Usually this happens when you add the object to the bucket, but you might want to update it to show more specific or higher level information. For instance, if you added the code ref with a low level routine that named the entry "check_number", a higher order routine might want to reuse the same entry but pretend it created it by setting the name to "check_integer", a more specific sort of check.

$entry->set_description( SCALAR )

Set the entry's description. Usually this happens when you add the object to the bucket, but you might want to update it to show more specific or higher level information. See get_name.

$entry->set_gv( SCALAR )

Set the GV object for the entry. You probably don't want to do this yourself. The bucket does it for you when it adds the object.

$entry->add_bit( CODEREFS )

I hate this name, but this is the part that adds the CODEREFS to the entry that composes it.

$entry->dump

Print a text version of the entry.

$entry->applies_to_fields

Return a list of fields the brick applies to.

I don't think I've really figured this out, but the composers should be the ones to figure it out and add this stuff to the information that the bucket tracks.

TO DO

TBA

SEE ALSO

TBA

SOURCE AVAILABILITY

This source is in Github:

        https://github.com/briandfoy/brick

AUTHOR

brian d foy, <bdfoy@cpan.org>

COPYRIGHT

Copyright (c) 2007-2014, brian d foy, All Rights Reserved.

You may redistribute this under the same terms as Perl itself.