Arch::Name(3pm)

📦 version 0.5.2, in ubuntu jammy

🌸 Arch::Name 🌸

okay bestie, welcome to Arch::Name(3pm) from the User Contributed Perl Documentation — it's giving "tiny module, huge power" and I'm obsessed 💅

✨ 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 💖

So this class is the whole Arch name concept, wrapped in a cute little object, and it comes with a bunch of methods to mess with it 🎀

The fully qualified Arch name looks like this:

archive/category--branch--version--revision

…for revisions, and some prefix of that for all the other hierarchy citizens 👑 And listen — the branchless names have the --branch part removed, no cap.

🧚 METHODS 🧚

Here are all the class methods you get, bestie:

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] — builds the Arch::Name instanse 🫶 If you pass the optional init parameter, then set gets called with that parameter on the brand-new instanse.

By default (no init), you get the empty name, and lowkey that one does not pass the is_valid check 🙈

If on_error is set and positive, then it dies on any initialization error — like when only a partial name got parsed, or when no name components were given at all. By default an object representing a partial name is returned instead, and you can use error to peek at what went wrong. If on_error is set and negative, then don't set any error, periodt.

not me warning you about this one: passing an Arch::Name object as the parameter does not construct a new instance — it just returns the object you passed in 💀 Use clone if you actually want a clone, or call set explicitly.

🌟 set 🌟

set object
set string
set arrayref
set hashref

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

🦋 clone 🦋

clone [init ..] — creates and returns a new Arch::Name instanse that stores the same logical arch name 💜 If the optional init parameter(s) are given, then the apply method gets called with these parameters on the newly created instanse.

🎀 apply 🎀

apply hashref
apply [reversed_arrayref] [subname ..]

Similar to set, but it lets you apply a partial change, which is the icon of it all. 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 🌈

go_up [level=1] — removes one dimension (aka 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 🫶

go_down string .. — adds one more dimension (aka a new component string) to the name, and multiple new dimentions are supported, because we're generous like that 💖 This is effectivelly just an alias for apply(string, .. ).

👑 parent 👑

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

🌸 child 🌸

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

⭐ to_string ⭐

to_string — returns the fully qualified name.

💜 to_nonarch_string 💜

to_nonarch_string — returns the nonarch name (that is, the fully qualified name without the archive/ part).

🍓 to_array 🍓

to_array — returns 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 an empty string.

Returns array or arrayref depending on context ✨

🧚 to_hash 🧚

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

Returns hash or hashref depending on context 💫

🌟 fqn 🌟

fqn — This is an alias for to_string.

🌟 nan 🌟

nan — This is an alias for to_nonarch_string.

🌟 get 🌟

get — This is an alias for to_array.

💅 archive 💅

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

💅 category 💅

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

💅 branch 💅

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

💅 version 💅

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

💅 revision 💅

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

😭 error 😭

error — returns the last error string or undef. Some errors are fatal (like passing an unexiting [elem] parameter to is_valid), and then the module straight-up dies 💀 Some errors are however not fatal (like setting a malformed fully qualified name, or setting the revision part when no version part is set). In that case the name is set to something adequate (usually the 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 🔥

level [stringify-flag] — returns 0 if the name is not valid (empty). Returns an 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 🎀

cast elem — similar to parent or clone, but it requires an 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 fewer components than requested, then undef is returned 🫶

✨ is_valid ✨

is_valid [elem] — returns 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 💫

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

🌈 OVERLOADED OPERATORS 🌈

These operators are overloaded, and honestly? iconic:

""    # 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.

and that's the whole page, bestie 🎀 it's perl v5.20.2, dated 2005-01-09, and it's literally serving Arch::Name(3pm) realness. go forth and parse those arch names 💖✨

📦 where this page comes from

ubuntu jammy: libarch-perl 0.5.2-2 · GPL-2.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms