view release on metacpan or  search on metacpan

perllib/Arch/Name.pm  view on Meta::CPAN

	'-='   => sub { $_[0]->go_up($_[1]) },
	'fallback' => 1;

1;

__END__

=head1 NAME

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

=head1 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');

=head1 DESCRIPTION

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

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

=head1 METHODS

The following class methods are available:

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

=over 4

=item B<new>

=item B<new> I<init> [I<on_error>=0]

Construct the C<Arch::Name> instanse. If the optional I<init> parameter is
given, then B<set> method is called with this parameter on the newly created
instanse.

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

If I<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 B<error>
may be used. If I<on_error> is set and is negative, then don't set any error.

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

=item B<set> I<object>

=item B<set> I<string>

=item B<set> I<arrayref>