Arch::Storage - abstract class to access arch archives

Arch documentation Contained in the Arch distribution.

Index

Code Index:

NAME

Top

Arch::Storage - abstract class to access arch archives

SYNOPSIS

Top

    use base 'Arch::Storage';

    # see synopsis of concrete classes

DESCRIPTION

Top

Arch::Storage provides some common methods to query content of arch archive.

The methods usually return arrayref if not otherwise specified, and are not affected by the list context (except for working_names).

METHODS

Top

The following (implemented and pure virtual) methods are common to subclasses:

new, init, working_name, working_names, fixup_name_alias, is_archive_managed, expanded_revisions.

archives, categories, branches, versions, revisions, get_revision_descs, expanded_archive_info, get_revision_changeset, get_changeset, get_revision_log, get_log.

new [%args]

Create a new instance of the concrete subclass (i.e. Arch::Session or Arch::Library).

instance

Alternative constructor. Return the last created instance of the concrete subclass (i.e. Arch::Session or Arch::Library) or create a new one.

The purpose of this alternative constructor is to allow the singleton behaviour as well as certain Aspect Oriented Programming practices.

Theoretical note: this design is acceptably good, and mixing new and instance constructors in the code usually does what is intended. However, if someone actually creates more than one object of any subclass, he has two choices to enforce correctness. Either only use instance method in the code (singleton pattern), or alternatively create a temporary new object before calling methods of other classes that internally use instance to work with this subclass.

init %args

Initialize or reset the object state.

working_name [name]

Set or get the default working operand for other methods.

The argument may be anything that Arch::Name constructor accepts, i.e. fully qualified string, arrayref, hashref or Arch::Name instance. If needed, name is converted to Arch::Name instance, and this is what is returned. Note that this object behaves as fully qualified name in string context.

working_names [archive ..]

Similar to working_name, but accepts and returns a list of name components, from archive to revision.

This method is provided for convenience and backward compatibility only. You may as well use working_name instead, just enclose the argument list into arrayref, and call to_array on the returned object.

fixup_name_alias

Replace (if needed) the "FIRST" and "LATEST" components of the working name's version and revision with the actual values by querying the storage.

is_archive_managed [archive]

Return true or false depending on whether the archive is known to the storage.

If given, the argument is used instead of the default working_name.

expanded_revisions

Return all revisions in all archives, each revision is Arch::Name object.

archives

Return all registered (or otherwise known) archives.

categories [archive]
branches [category]
versions [branch]
revisions [version]

Return all categories, branches, versions or revisions respectively in the immediate parent, similarly to the corresponding tla commands.

If given, the argument is used instead of the default working_name.

get_revision_descs [version]

Return describing hash for every revision in the version.

If given, the argument is used instead of the default working_name.

The revision hashes have the following fields:

name

The revision name (i.e. base-0, patch-X, version-0 or versionfix-X)

summary

The revision's commit log's summary line

creator

The name part of the committers tla my-id (i.e. John Hacker)

email

The email address part of the committers tla my-id (i.e. jhacker@nowhere.org)

date

The revisions commit date in %Y-%m-%d %H:%M:%S %Z format (see strftime(3))

kind

The kind of revision (i.e. one of tag, import, cset or unknown)

expanded_archive_info [archive]

Returns a tree of categories, branches and versions in the archive. The archive defaults to working_names.

Returns a reference to a list of categories. Every category is a list consisting of the category name and a list of branches. Every branch is a list consisting of the branch name and a list of versions. Every version is list consisting of the version number and the first and last revision name.

    [
      [ "category1", [
        [ "branch1", [
          [ "version1", "first_revision1", "last_revision1" ],
          [ "version2", "first_revision2", "last_revision2" ],
          ...
        ],
        ...
      ],
      ...
    ]
get_revision_changeset revision [dir]
get_changeset [dir]

Fetches the changeset for revision or working_name and returns an Arch::Changeset for it. If dir is specified, it will be used to store the contents of the changeset. Otherwise a new temporary directory will be created.

get_revision_log revision
get_log

Fetch the log for the revision or working_name. Returns an Arch::Log object.

BUGS

Top

No known bugs.

AUTHORS

Top

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

Enno Cramer (uebergeek@web.de--2003/arch-perl--devel).

SEE ALSO

Top

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

Arch documentation Contained in the Arch distribution. 
# Arch Perl library, Copyright (C) 2004 Mikhael Goikhman
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

use 5.005;
use strict;

package Arch::Storage;

use Arch::Name;

sub new ($%) {
	my $class = shift;
	my %init = @_;

	my $self = { $class->_default_fields };
	bless $self, $class;
	$self->init(%init);

	no strict 'refs';
	${"${class}::global_instance"} = $self;
	return $self;
}

sub instance ($) {
	my $class = shift;

	no strict 'refs';
	return ${"${class}::global_instance"} || $class->new;
}

sub init ($%) {
	my $self = shift;
	my %init = @_;
	while (my ($name, $value) = each %init) {
		die ref($self) . "::init: Option $name is unknown.\n"
			unless exists $self->{$name};
		$self->{$name} = $value;
	}
	return $self;
}

sub _default_fields ($) {
	my $this = shift;
	return (
		name => Arch::Name->new,
	);
}

sub working_name ($;$) {
	my $self = shift;
	if (@_) {
		$self->{name} = Arch::Name->new(shift);
		$self->fixup_name_alias;
	}
	return $self->{name};
}

sub working_names ($;$@) {
	my $self = shift;
	if (@_) {
		$self->{name} = Arch::Name->new(ref($_[0])? $_[0]: [ @_ ]);
	}
	return $self->{name}->get;
}

sub fixup_name_alias ($) {
	my $self = shift;
	$self->{name_alias} = 0;
	$self->{version_alias} = undef;
	$self->{revision_alias} = undef;

	my $name = $self->{name};
	my ($version, $revision) = ($name->get)[3, 4];
	foreach (
		[ qw(version versions branch), $version ],
		[ qw(revision revisions version), $revision ]
	) {
		my ($element, $method, $parent, $alias) = @$_;
		if (defined $alias && $alias =~ /^FIRST|LATEST$/) {
			$name->$element(undef);
			my $values = $self->$method($name);
			die "There is no any $element in this $parent, so $name--$alias alias is invalid\n"
				unless @$values;
			my $value = $values->[$alias eq "FIRST"? 0: -1];
			$value =~ s/^.*--//;
			$name->$element($value);
			$name->revision($revision) unless $element eq 'revision';
			$self->{name_alias} = 1;
			$self->{"${element}_alias"} = $alias;
		}
	}
}

sub _name_operand ($$;$) {
	my $self = shift;
	my $arg  = shift;
	my $elem = shift;
	my $func = (caller(1))[3];

	my $name = $arg? Arch::Name->new($arg): $self->{name};
	die "$func: no working name and no argument given\n" unless $name;
	if ($elem) {
		my $enclosing = $name->cast($elem);
		die "$func: operand '$name' is not $elem\n" unless $enclosing;
		$name = $enclosing;
	}
	return $name;
}

sub is_archive_managed ($;$) {
	my $self = shift;
	my $archive = $self->_name_operand(shift, 'archive');

	unless ($self->{archives_presence}) {
		my $archives_hash = {};
		$archives_hash->{$_} = 1 foreach @{$self->archives};
		$self->{archives_presence} = $archives_hash;
	}
	return $self->{archives_presence}->{$archive};
}

sub expanded_revisions ($) {
	my $self = shift;

	my $all_revisions = [];
	my $archives = $self->archives;
	foreach my $archive (@$archives) {
		my $category_infos = $self->expanded_archive_info($archive, 1);
		foreach my $category_info (@$category_infos) {
			my ($category, $branch_infos) = @$category_info;
			foreach my $branch_info (@$branch_infos) {
				my ($branch, $version_infos) = @$branch_info;
				foreach my $version_info (@$version_infos) {
					my ($version, @revisions) = @$version_info;
					foreach my $revision (@revisions) {
						my $name = Arch::Name->new([
							$archive, $category, $branch, $version, $revision,
						]);
						die $name->error .
							"\n\t($archive, $category, $branch, $version, $revision)\n"
							if $name->error;
						push @$all_revisions, $name;
					}
				}
			}
		}
	}

	return $all_revisions;
}

1;

__END__