NAME

FindApp::Object::State::Group::State::Dirs - Implement the FindApp group-directory set object

DESCRIPTION

This is the class that each FindApp::Object::State::Group object has three of, one for each of allowed, wanted, found. Each Dirs object represents a set of paths.

Methods

new LIST

Creates, initializes, and returns a Dirs object. The list is a list of filenames. As a class method:

    use  FindApp::Object::State::Group::Dirs;
    my $ob1 = FindApp::Object::State::Group::Dirs->new("lib", "t/lib");

Invoked as an instance method, the old object's contents are added to the set, making it the union of the old object set and the parameter list.

    my $ob2 = $ob1->new("testlib");

Now $ob2->get returns a list of three items: lib, t/lib, and testlib.

If you don't want the old object's contents, don't call it as an object method: use its class instead:

    my $ob3 = $ob2->class->new("bin");

Now $ob3 will hold only the single new item.

copy OLD

Method used to copy an old object into a new one. This sets the new object to be the same set as the old one's only if the old one has anything in its set. So this:

    $new->copy($old);

is like this:

    $new->add($old->get) if $old->count;

This is called implicitly by the new method as just explained.

class

Returns the package of the blessed argument. This is useful for inherited constructors so that you don't need to know the exact class. See "new".

object

Returns the object itself. This is the identity function.

as_number

Overload for comparing whether two objects are truly the same reference. Used by the == and != operators.

as_string

Overload for pretty-printing an object's contents. This is not what is used by the eq and ne operators.

add LIST

Add a list of directories to the object. Duplicates are suppressed.

has LIST

Returns true if the object has all the LIST elements, and false otherwise.

del LIST

Remove all LIST elements from the object, and return those deleted.

count

Report how many elements are in the Dirs set.

first

Return one element, or undef if there isn't one. This should not exist, because these are to be thought of as sets not lists.

get

Return a list of the set contents in list context, and just one of them otherwise.

last

Return one element, or undef if there isn't one. This should not exist, because these are to be thought of as sets not lists.

reset

Clear the set, and return the deleted list.

set LIST

Destructively make the current object equal to the LIST and return the object. One level of array reference will be interpolated.

op_eq

Used to implement the eq operator, this compares contents.

op_equals

Used to implement the == operator, this compares addresses.

op_ne

The opposite of op_eq.

op_notequals

The opposite of op_equals.

ENVIRONMENT

FINDAPP_TRACE

If the FINDAPP_TRACE variable is set to 3 or higher, will trace some method calls.

    tchrist% perl -MFindApp::Object::State::Group::Dirs -E 'say FindApp::Object::State::Group::Dirs->new(<R B G>)->add(<C M Y>)->get'
    BCGMRY

    tchrist% env FINDAPP_TRACE=3 perl -MFindApp::Object::State::Group::Dirs -E 'say FindApp::Object::State::Group::Dirs->new(<R B G>)->add(<C M Y>)->get'
    FindApp::Object::State::Group::Dirs::new FindApp::Object::State::Group::Dirs R B G
    FindApp::Object::State::Group::Dirs::add FindApp::Object::State::Group::Dirs=ARRAY(0x7f9e8b02f780) R B G
    FindApp::Object::State::Group::Dirs::set FindApp::Object::State::Group::Dirs=ARRAY(0x7f9e8b02f780) R B G
    FindApp::Object::State::Group::Dirs::add FindApp::Object::State::Group::Dirs=ARRAY(0x7f9e8b02f780) C M Y
    FindApp::Object::State::Group::Dirs::set FindApp::Object::State::Group::Dirs=ARRAY(0x7f9e8b02f780) B G R C M Y
    BCGMRY

FINDAPP_DEBUG_SHORTEN

If true, this will shorten the trace and debug output by abbreviating package names that start with "FindApp".

    tchrist% FINDAPP_DEBUG_SHORTEN=1 FINDAPP_TRACE=3 perl -MFindApp::Object::State::Group::Dirs -E 'say FindApp::Object::State::Group::Dirs->new(<R B G>)->add(<C M Y>)->get'
    f:o:s:g:Dirs::new f:o:s:Group::Dirs R B G
    f:o:s:g:Dirs::add f:o:s:Group::Dirs=ARRAY(0x7fc00b030738) R B G
    f:o:s:g:Dirs::set f:o:s:Group::Dirs=ARRAY(0x7fc00b030738) R B G
    f:o:s:g:Dirs::add f:o:s:Group::Dirs=ARRAY(0x7fc00b030738) C M Y
    f:o:s:g:Dirs::set f:o:s:Group::Dirs=ARRAY(0x7fc00b030738) B G R C M Y
    BCGMRY

Which is much easier to read. The last two components in the fully-qualfied name are always left as is, with everything else clipped to a single lowercase letter and a single colon instead of a double one for the seprator.

Likewise, instead of this:

    tchrist% perl -MFindApp::Object::State::Group::Dirs -e 'print FindApp::Object::State::Group::Dirs->new(<R B G>)->add(<C M Y>)'
    bless(["B", "C", "G", "M", "R", "Y"], "FindApp::Object::State::Group::Dirs"); # FindApp::Object::State::Group::Dirs=ARRAY(0x7fcaf302f018)

With the shortening, you get this:

    tchrist% FINDAPP_DEBUG_SHORTEN=1 perl -MFindApp::Object::State::Group::Dirs -e 'print FindApp::Object::State::Group::Dirs->new(<R B G>)->add(<C M Y>)'
    bless(["B", "C", "G", "M", "R", "Y"], "f:o:s:Group::Dirs"); # FindApp::Object::State::Group::Dirs=ARRAY(0x7fc79102f030)

The object type in the comment is not subject to shortening.

SEE ALSO

FindApp

CAVEATS AND PROVISOS

Do not rely on the internal representation of these object being an array reference.

AUTHOR

Tom Christiansen <tchrist@perl.com>

LICENCE AND COPYRIGHT

Copyright (c) 2016, Tom Christiansen <tchrist@perl.com>. All Rights Reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.