NAME

FindApp::Utils::Package::Object - FIXME

SYNOPSIS

 use FindApp::Utils::Package::Object;

DESCRIPTION

Public Methods

abbreviate

Returns a string where all package elements but the last two have been abbreviated to a single lowercase letter. Used for debugging output when the FINDAPP_DEBUG_SHORTEN environment variable is true.

    $short = PACKAGE("FindApp::Utils::Package::Object::abbreviate");
    # $short now f:u:p:Object::abbreviate

add(LIST)

Returns a new object with the given arguments added as further components.

    $start = PACKAGE("Three");
    $full  = $start->add("Blind", "Mice");
    # $full now Three::Blind::Mice

OBJ_LIST = $obj->add_all(LIST)

Returns a list of new objects, each with the original plus one element in the argument list appended.

    $pkg = PACKAGE("Spring::Field");
    @pkgs = $pkg->add_all("Ohio", "Iowa", "Maine");
    # Spring::Field::Ohio, Spring::Field::Iowa, Spring::Field::Maine

STR_LIST = $obj->add_all_unblessed(LIST)

Like add_all but returning strings not objects.

aref

Returns a reference to a copy of the object's package components. Does not allow direct access to the original.

as_list

Returns a copy of the object's package components as a list. Does not allow direct access to the original.

This is actually as alias for split.

as_string

Returns a string of the object's package components joined with ::.

This is actually as alias for unbless.

bisect ORDINAL

Return two new objects which represent the original snipped at the given ORDINAL position. The ORDINAL may be either positive or negative, operating symmetrically.

For a positive ORDINAL, count off starting from the right end and then snip, putting everything to the left of however far you got into the left object returned and putting everything past where you got to in the right object returned.

    ($left, $right) = PACKAGE("A::B::C::D::E::F")->bisect(2);
    # $left  is A::B::C::D
    # $right is E::F

    ($left, $right) = PACKAGE("A::B::C::D::E::F")->bisect(4);
    # $left  is A::B
    # $right is C::D::E::F

For a negative ORDINAL, count off starting from the left end and then snip, still putting everything to the left of however far you got into the left object returned and putting everything past where you got to in the right object returned.

    ($left, $right) = PACKAGE("A::B::C::D::E::F")->bisect(-2);
    # $left  is A::B
    # $right is C::D::E::F

    ($left, $right) = PACKAGE("A::B::C::D::E::F")->bisect(-2);
    # $left  is A::B::C::D
    # $right is E::F

Therefore the magnitude of a positive ORDINAL represents how many elements are returned in the right object, while the magnitude of a negative ORDINAL represents how many elements are returned in the left object. If you find this hard to remember or keep straight,

class

Returns the invocant class.

grep CODE_REF

Returns a list of package components for which the code reference expression tests true on as they were each set to $_ in succession.

    say for PACKAGE("Red::Riding::Hood")->grep(sub{/^R/});
  # Red
  # Riding

join STRING

Returns a string with the package elements connected by its argument.

    say PACKAGE("Red::Riding::Hood")->join("!")
    # Red!Riding!Hood

left ORDINAL

Returns a new object that has the leftmost ORDINAL elements in it.

    $head = PACKAGE("A::B::C::D::E::F")->left(2);
    # $head is A::B

If a negative index is supplied, all but that many right elements are returned.

    $tail = PACKAGE("A::B::C::D::E::F")->left(-2);
    # $tail is A::B::C::D

This method have been called first or top or head or even pull or unshift, but left seemed to be the least confusing, especially once negatives are included.

left_and_right ORDINAL

Returns two objects representing the left and right parts of the original.

When ORDINAL is positive, it specifies how many elements will be in the right return object.

When ORDINAL is negative, its magnitude specifies how many elements will be in the left return object.

    ($left, $right) = PACKAGE("A::B::C::D::E::F")->left_and_right(2);
    # $left  is A::B::C::D
    # $right is E::F

    ($left, $right) = PACKAGE("A::B::C::D::E::F")->left_and_right(-2);
    # $left  is A::B
    # $right is C::D::E::F

(Same as bisect, but easier to remember.)

left_but ORDINAL

Returns a new object that has all but the last ORDINAL elements in it. So here you get all left bits but for the last two of them:

    $front = PACKAGE("A::B::C::D::E::F")->left_but(2);
    # $front is A::B::C::D

This method exists so you don't have to remember negatives; it just calls left with the sign of its argument flipped. Negatives therefore work symmetrically:

    $front = PACKAGE("A::B::C::D::E::F")->left_but(-2);
    # $front is A::B

Negative ordinals mean to keep only that many rather than to discard that many:

    $front = PACKAGE("A::B::C::D::E::F")->left_but(-2);
    # $front is A::B

The left_but(N) method is really the left(-N) method so that you don't have to think about negative ordinals.

length

Returns the number of package elements.

    $count = PACKAGE("A::B::C::D::E::F")->length;
    # $count is now 6.

This is the method used for the 0+ operator overload.

map CODE_REF

Returns a new object each of whose path components is the result of running the given code against.

    $small = PACKAGE("A::B::C")->map(sub{lc});
    # $small is a::b::c

new LIST

This is the general class constructor.

    $class = "FindApp::Utils::Package::Object";
    $ob = $class->new("A::B::C");
    # $ob now has length 3

If multiple arguments are given, they concatenate:

    $ob = $class->new("A" .. Z");
    # $ob has length 26

The single-quote version of the package separator is tolerated on input, but the canonical form is always produced on output:

    $ob = $class->new("you", "shouldn't've");
    # $ob is now you::shouldn::t::ve

Because the package name FindApp::Utils::Package::Object is so long, the PACKAGE alias for the constructor is normally used.

object

Returns the invocant.

op_cmp

This is the method used for the overloaded cmp operator. It runs a normal cmp operation on each element left to right. That means that "AB::CD::EF" will sort earlier than "ABC::DEF" because "AB" sorts before "ABC". The first element that differs is what counts.

See the op_spaceship method if you want it to work the other way.

In other words, it only uses the real cmp operator on each element iteratively until one fails. It does not compare the entire package as one string.

op_eq

This is the method used for the overloaded eq operator. It compares the two strings in full using the regular eq.

op_equals

This is the method used for the overloaded == operator. It is used for checking whether two objects are the same object by comparing their reference's addresses numerically. It returns true if their refaddrs are the same.

It's really the method of that name imported from FindApp::Utils::Objects.

op_minus

This is the method used for the overloaded binary - operator, the infix one. It is the same as calling the super method with its numeric argument, so throws away that many elements from the right and returns a new object.

    $ob = PACKAGE("usr::bin::perl");
    print $ob - 1;
    # prints usr::bin

This is also used for derived -= and -- operators.

op_ne

This is the method used for the overloaded ne operator. It is simply the reverse of the eq operator.

op_neg

This is the method used for the overloaded unary - operator, the prefix one. It's a quick way to get the leftmost element.

    $ob = PACKAGE("usr::bin::perl");
    print -$ob;
    # prints "usr"

op_notequals

This is the method used for the overloaded != operator. It is used for checking whether two objects are different objects by comparing their reference's addresses numerically. It returns true if their refaddrs are not the same number.

It's really the method of that name imported from FindApp::Utils::Objects.

op_plus

This is the method used for the overloaded binary + operator. As you might expect, it returns a new object that has the right operand concatenated to the end of the left operand in that order.

    print PACKAGE("A::B") + PACKAGE("X::Y");
    # prints A::B::X::Y

It is not associative, since ordering matters.

op_spaceship

This is the method used for the overloaded <=> operator.

It first compares the numbers of elements in each operand as numbers, and only if those are the same does it then go on compare the respective pieces as strings. That means that shorter package counts sort earlier even if they have later letters. So all one-element packages would sort before all two-element ones, and so on.

    PACKAGE("AB::CD::EF") <=> PACKAGE("ABC::DEF") # 1

That returns 1 because the first has three elements and the second has two. See the op_cmp method if you want it to work the other way by comparing "AB" with "ABC".

Another way to think of it is that $a <=> $b is that is works like

    $a->length <=> $b->length
               ||
            $a cmp $b

In other words, the real <=> operator is used only for comparing lengths. If the lengths are the same, then cmp operator is used one package element at a time.

pmpath

This method converts the package object into a path sting by swapping the double colons out for slashes and appending ".pm" to the end. It's just there to give a name to this simple operation:

    $obj->join("/").".pm"

reverse

Returns a new object with all its elements laid out the other direction.

    PACKAGE("AB::CD::EF")->reverse
    # produces ED::CD::AB

right ORDINAL

Returns a new object that has the rightmost ORDINAL elements in it.

    $tail = PACKAGE("A::B::C::D::E::F")->right(2);
    # $head is E::F

If a negative index is supplied, all but that many left elements are returned.

    $head = PACKAGE("A::B::C::D::E::F")->right(-2);
    # $tail is A::B::C::D

This method have been called last or pop or tail.

right_and_left ORDINAL

Returns two objects representing the left and right parts of the original, in that order. When ORDINAL is positive, it specifies how many elements will be in the left return object. When ORDINAL is negative, its magnitude specifies how many elements will be in the right return object.

    ($left, $right) = PACKAGE("A::B::C::D::E::F")->right_and_left(2);
    # $left  is A::B
    # $right is C::D::E::F

    ($left, $right) = PACKAGE("A::B::C::D::E::F")->right_and_left(-2);
    # $left  is A::B::C::D
    # $right is E::F

This method exists so you don't have to think about negative ordinals, but it is potentially confusing because you get back the left first and the right second even though those words occur in the opposite order in the name of the method. Just remember that whichever word has the number near it is how many of that you get.

right_but ORDINAL

Returns a new object that has all but the first ORDINAL elements in it. So here you get all the right bits but for the first two of them:

    $back = PACKAGE("A::B::C::D::E::F")->right_but(2);
    # $back is C::D::E::F

Negative ordinals keep only that many rather than to discard that many:

    $back = PACKAGE("A::B::C::D::E::F")->right_but(-2);
    # $back is E::F

The right_but(N) method is really the right(-N) method so that you don't have to think about negative ordinals.

self

Returns the object itself. Dies if invoked on a class.

sib NAME

Returns a new object which is the named "sibling" package of the one specified. So for example if your package is A::B::C, then your super is A::B and represents your parent, and if you had a sibling named J, that would be A::B::J.

    $sib = PACKAGE("A::B::C")->sib("J");
    # $sub is A::B::J

It only returns one result no matter how many arguments you supply; if you pass more than one NAME, these are each separate elements in the one return object:

    $sib = PACKAGE("A::B::C")->sib("J","K");
    $ $sib is A::B::J::K.

slice INDICES

Returns a new object selecting only those elements whose ordinals you specify in the argument list. Positive ordinals count from the left and negatives ones from the right.

    $class   = "FindApp::Utils::Package::Object";
    $abc_obj = $class->new("A" .. "Z");
    # $abc_obj is A::B::C::D::E::F::G::H::I::J::K::L::M::N::O::P::Q::R::S::T::U::V::W::X::Y::Z

    print $abc_obj->slice(1,3,-3,-1);
    # prints A::C::X::Z

snip START, END

Returns a new object formed by joining portion to left of the START ordinal to the portion to the right of the END ordinal in the original package elements.

span START, END

Returns a new object consisting of a span of all the original package elements starting with the START ordinal and ending with the END ordinal. The second argument must not be less than the first argument.

    $class   = "FindApp::Utils::Package::Object";
    $abc_obj = $class->new("A" .. "Z");
    # $abc_obj is A::B::C::D::E::F::G::H::I::J::K::L::M::N::O::P::Q::R::S::T::U::V::W::X::Y::Z

    print $abc_obj->span(1, 4);
    # prints A::B::C::D

    print $abc_obj->span(-4, -1);
    # prints W::X::Y::Z

    print $abc_obj->span(4, 8);
    # prints D::E::F::G::H

As a special dispensation for a common mistake, if both arguments are negative but the second is greater than the first, then you must have reversed the arguments by accident and so the method flips them back as though you had written them correctly.

    #         means span(-4, -1)
    print $abc_obj->span(-1, -4);
    # prints W::X::Y::Z

splice START, END

splice START

Returns a new object with everything between START and END deleted. If END is omitted, everything till the end is deleted.

split

stash

super

unbless

Exports

PACKAGE(;$)

UNPACKAGE(_)

Sorting

resorting the dict-sorted ABBA AB::CD A::B::C::D::E::F A::B::CD::EF A::B::CDEF A::BC::D::EF A::BCD::E::F AB::CD::EF ABC::DEF sort {cmp} packages: A::B::C::D::E::F A::B::CD::EF A::B::CDEF A::BC::D::EF A::BCD::E::F AB::CD AB::CD::EF ABBA ABC::DEF sort {<=>} packages: ABBA AB::CD ABC::DEF A::B::CDEF AB::CD::EF A::B::CD::EF A::BC::D::EF A::BCD::E::F A::B::C::D::E::F

EXAMPLES

ENVIRONMENT

SEE ALSO

FindApp

CAVEATS AND PROVISOS

BUGS AND LIMITATIONS

HISTORY

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.

cpanm FindApp

perl -MCPAN -e shell
install FindApp