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.