NAME

       Arch::Name - parse, store and construct an arch name

SYNOPSIS

           use Arch::Name;

           my $version_spec = 'some@hacker.org--pub/bugzilla--main--1.2';
           my $name = Arch::Name->new($version_spec);
           die unless $name eq $version;
           die unless $name - 2 eq 'some@hacker.org--pub/bugzilla';
           die unless $name->branch eq 'main';

           # list other branches (latest versions) in the tree archive
           my $category = Arch::Name->new($tree->get_version)->go_up(2);

           foreach my $branch_str ($session->branches($category)) {
               my $branch = $category->child($branch_str);
               my $latest_version = ($session->versions($branch))[-1];

               print $branch->go_down($latest_version)->to_string, "\n";
           }

           # another way to manipulate it
           my $category = Arch::Name->new($tree->get_version);
           $category->apply([undef, undef]);
           print $category->fqn, "\n", $category->parent->to_hash, "\n";

           # validate arch name from the user input
           # suppose we write a tool that accepts 3 command line args:
           #   * tree directory or branch+ (to get tree)
           #   * fully qualified revision (to get changeset)
           #   * archive+ (fully qualified category is ok too)
           my ($name_or_dir, $rvsn, $archv) = @ARGV;

           my $tree = Arch::Name->is_valid($name_or_dir, "branch+")?
               Arch::Session->new->get_tree($name_or_dir):
               Arch::Tree->new($name_or_dir);
           my $cset = $session->get_revision_changeset($rvsn)
               if Arch::Name->is_valid($rvsn, 'revision');
           my $possibly_archive = Arch::Name->new($archv);
           die "No archive" unless $possibly_archive->is_valid;
           my $archive = $possibly_archive->cast('archive');

DESCRIPTION

       This class represents the Arch name concept and provides useful methods to manipulate it.

       The fully qualified Arch name looks like archive/category--branch--version--revision for
       revisions and some prefix of it for other hierarchy citizens. The branchless names have
       "--branch" part removed.

METHODS

       The following class methods are available:

       new, set, clone, apply, go_up, go_down, parent, child, to_string, to_nonarch_string,
       to_array, to_hash, fqn, nan, get, archive, category, branch, version, revision, error,
       level, cast, is_valid.

       new
       new init [on_error=0]
           Construct the "Arch::Name" instanse. If the optional init parameter is given, then set
           method is called with this parameter on the newly created instanse.

           By default (without init), the empty name is created that does not pass is_valid
           check.

           If on_error is set and positive, then die on any initialization error, i.e. when only
           a partial name is parsed or no name components are given.  By default an object
           representing a partial name is returning, and error may be used. If on_error is set
           and is negative, then don't set any error.

           Please note, that passing "Arch::Name" object as the parameter does not construct a
           new instance, but returns this passed object. Use clone instead if you want to clone
           the passed object. Or explicitly call set.

       set object
       set string
       set arrayref
       set hashref
           Store the new content. Multiple argument types supported. object is another reference
           object of type "Arch::Name". string is fully qualified name.  arrayref contains
           subnames, like the ones returned by to_array method.  hashref is hash with some or all
           keys archive, category, branch, version and revision, like the ones returned by
           to_hash method.

       clone [init ..]
           Create and return a new "Arch::Name" instanse that stores the same logical arch name.
           If the optional init parameter(s) given, then apply method is called with these
           parameters on the newly created instanse.

       apply hashref
       apply [reversed_arrayref] [subname ..]
           Similar to set, but enables to apply a partial change. For example:

               my $name = Arch::Name->new("user@host--arch/cat--felix--1.2.3");

               $name->apply([ '1.2.4', 'leo' ]);        # ok, new branch-version
           or:
               $name->apply({ branch => 'leo', version => '1.2.4' });  # ditto
           or:
               $name->apply([ 'panther' ]);             # error, invalid version
           or:
               $name->apply([ undef, 'panther' ]);      # ok, it is branch now
           or:
               $name->apply({ category => 'dog' });     # ok, it is category now
           or:
               $name->apply({ branch => 'leo' });       # ok, == [undef, 'leo']
           or:
               $name->apply({ version => undef });      # ok, it is branch now
           or:
               $name->apply({ revision => 'patch-6' }); # ok, it is revision now
           or:
               $name->apply([], 'patch-6');             # ditto
           or:
               $name->apply([ '1.2.4' ], 'patch-6');    # ditto with new version
           or:
               $branch->apply([], '0', 'base-0');       # ok, go import revision
           or:
               $branch->apply('0', 'base-0') ;          # ditto

       go_up [level=1]
           Remove one dimension (i.e. the last component) from the name, or more than one
           dimension if level is given. This is effectivelly just a convenient shortcut for
           "apply([ (undef) x level ])".

       go_down string ..
           Add one more dimension (i.e. new component string) to the name.  Multiple new
           dimentions are supported. This is effectivelly just an alias for "apply(string, .. )".

       parent [level=1]
           Return object representing the parent arch name. This is just a shortcut for
           "clone->go_up(level)".

       child string ..
           Return object representing the child arch name. This is just a shortcut for
           "clone->go_down(string)".

       to_string
           Return the fully qualified name.

       to_nonarch_string
           Return the nonarch name (that is the fully qualified name without archive/ part).

       to_array
           Return the components of the name starting from archive to revision.  The returned
           array may contain 0 to 5 strings; the branch in branchless names is represented by
           empty string.

           Returns array or arrayref depending on context.

       to_hash
           Return the hash containing the components of the name with keys: archive, category,
           branch, version and revision.

           Returns hash or hashref depending on context.

       fqn This is an alias for to_string.

       nan This is an alias for to_nonarch_string.

       get This is an alias for to_array.

       archive [archive]
           Get or set the archive component only (the string). See also, to_array (getter) and
           apply (setter).

       category [category]
           Get or set the category component only (the string). See also, to_array (getter) and
           apply (setter).

       branch [branch]
           Get or set the branch component only (the string). See also, to_array (getter) and
           apply (setter).

       version [version]
           Get or set the version component only (the string). See also, to_array (getter) and
           apply (setter).

       revision [revision]
           Get or set the revision component only (the string). See also, to_array (getter) and
           apply (setter).

       error
           Return the last error string or undef. Some errors are fatal (like passing unexiting
           [elem] parameter to is_valid), then the module dies. Some errors are however not fatal
           (like setting malformed fully qualified name, or setting revision part when no version
           part is set). In this case the name is set to something adequate (usually empty name),
           and this method may be used to get the error message.

           This last error string is class global and it is (un)set on every set or apply method.

       level [stringify-flag]
           Return 0 if the name is not valid (empty).  Return integer [1 .. 5] if the name is
           archive, category, branch, version and revision correspondingly.

           If stringify-flag is set, then return the same as a text, i.e. one of the values:
           "none", "archive", "category", "branch", "version", "revision".

       cast elem
           Similar to parent or clone, but requires argument that is one of the values that level
           returns (i.e. either integers 0 .. 5 or strings "none" .. "revision"). The returned
           cloned object contains only the number of components specified by elem.

           If the original object contains less components than requested, then undef if
           returned.

       is_valid [elem]
           Return true if the object contains the valid arch name (i.e. at least one component).

           If elem is given that is one of the strings "archive", "category", "branch", "version"
           and "revision", then return true if the object represents the given element (for
           example, category), and false otherwise.

           If elem is given that is one of the strings "archive+", "category+", "branch+",
           "version+" and "revision+", then return true if the object represents at least the
           given element, and false otherwise.

       Arch::Name->is_valid name [elem]
           This class method does two things, first constructs the "Arch::Name" object with name
           as the constructor parameter, and then calls the is_valid method on this created
           object with optional elem passed.

OVERLOADED OPERATORS

       The following operators are overloaded:

           ""    # to_string
           0+    # level
           bool  # is_valid
           =     # clone
           +     # child
           -     # parent
           +=    # go_down
           -=    # go_up

BUGS

       No known bugs.

       "man perl | grep more"

AUTHORS

       Mikhael Goikhman (migo@homemail.com--Perl-GPL/arch-perl--devel).

SEE ALSO

       For more information, see tla, Arch::Session, Arch::Library, Arch::Tree.