VCI::Abstract::Project - A particular project in the Repository

VCI documentation Contained in the VCI distribution.

Index

Code Index:

NAME

Top

VCI::Abstract::Project - A particular project in the Repository

SYNOPSIS

Top

 my $project = $repository->get_project(name => 'Foo');

 # Getting information about individual files/directories.

 my $file = $project->get_file(path => 'path/to/file.c');
 my $directory = $project->get_directory(path => 'path/to/directory/');

 my $file = $project->get_path(path => 'path/to/file.c');
 my $directory = $project->get_path(path => 'path/to/directory/');

 # Commits

 my $commit = $project->get_commit(revision => '123');
 my $commit = $project->get_commit(time => 'July 7, 2007 12:01:22 UTC');
 my $commit = $project->get_commit(at_or_before => 'July 7, 2007 13:00:00 UTC');
 my $commits = $project->get_history_by_time(start => 'January 1, 1970',
                                             end   => '2007-01-01');
 # Other information

 my $root_directory = $project->root_directory;
 my $history = $project->history;
 my $name = $project->name;

 $repository == $project->repository # True

DESCRIPTION

Top

This represents a Project, something that could be checked out of a Repository.

For example, the Mozilla CVS Repository contains Firefox and Thunderbird as Projects.

METHODS

Top

Accessors

All of these accessors are read-only.

name

The name of the Project, as a string. This is something that you could pass to get_project in VCI::Abstract::Repository to get this Project. Usually this is just the path to the Project's directory, relative to the root of the Repository.

repository

The VCI::Abstract::Repository that this Project is in.

history

The VCI::Abstract::History of this whole Project.

root_directory

The root VCI::Abstract::Directory, containing this project's files and directories.

head_revision

The revision ID that identifies the current "head" of this Project. Usually this will be the ID of the very latest revision.

Files and Directories

Methods to get information about specific files and directories.

Note that paths are case-sensitive in the default implementation of VCI, but particular drivers may be case-insensitive (for example, for version-control systems that are on Windows servers). However, it is best not to rely on case-insensitivity, and always specify your file names assuming that VCI will be case-sensitive.

get_path

Description

When you have a path but you don't know if it's a file or a directory, use this function to get it as an object.

If you know that you want a file, or know that you want a directory, it is recommended that you use get_file or get_directory instead.

Parameters

Takes one named parameter:

path

A Path to the file or directory that you want, relative to the base of the project.

Absolute paths will be interpreted as relative to the base of the project.

If you pass an empty string or "/", you will get the root directory of the Project.

Returns

An object that implements VCI::Abstract::Committable, either a file or a directory.

If there is no object with that path, will return undef. However, if you specify a parent directory that doesn't exist, we will die.

So, for example, if you ask for /path/to/file.c and /path/to/ is a valid directory but doesn't contain file.c, we will return undef. But if /path/to/ is not a valid directory, we will die. Also, if /path is not a valid directory, we will die.

get_directory

Description

Gets a directory from the repository.

Parameters

Takes one named parameter:

path

A Path to the directory that you want, relative to the base of the project.

Absolute paths will be interpreted as relative to the base of the project.

If you pass an empty string or "/", you will get the root directory of the Project.

Returns

A VCI::Abstract::Directory, or undef if there is no directory with that name. (Even if there's a file with that name, if it's not a directory, we will still return undef.)

Also, if any of the parent directories don't exist, we return undef.

get_file

Description

Gets a file from the repository.

Parameters

Takes the following named parameters:

path Required

A Path to the file that you want, relative to the base of the project.

Absolute paths will be interpreted as relative to the base of the project.

This method will throw an error if you pass in an empty string or just "/".

revision

The exact revision that you want of the file. On VCSes where the File revision IDs differ from the Commit revision IDs (like CVS), you should specify the File revision ID here, not the Commit revision ID.

If you specify a valid revision ID but that revision didn't include adding, removing, or modifying this file in any way, you will get undef.

If you don't specify this parameter, you will get the latest revision of the file.

Returns

A VCI::Abstract::File, or undef if there is no file with that name and revision. (Even if there's something with that name, if it's not a file, we will still return undef.)

If the parent directory doesn't exist, or any of the parent directories don't exist, this will throw an error (identically to how get_path works).

Commits to the Project

get_commit

Description

Gets a particular commit from the Project by its unique identifier.

Parameters

Takes one (and only one) of the following named parameters:

revision

The unique identifier of the commit that you want, as a string.

See revision in VCI::Abstract::Commit for a discussion of exactly what a revision identifier is.

time

A datetime.

Specifies that you want the commit that happened at an exact moment in time. Note that some VCSes may track commits down to the microsecond, and in this case, your time must be accurate down to the same microsecond.

(If you want to be less accurate, use get_history_by_time or the at_or_before argument instead.)

In extremely rare cases, VCSes may have two commits that happen at the exact same time. In this case VCI will print a warning and you will get the commit that the VCS considers to have happened "first" (that is, it will have the lower revision number or come "logically" before the other commit).

at_or_before

A datetime.

Specifies that you want the commit right before or exactly at this time.

Note that if the earliest commit is after this time, you will get undef.

Returns

The VCI::Abstract::Commit that you asked for, or undef if there is no commit with that ID in this Project.

get_history_by_time

Description

Get a section of the Project's history based on times.

Parameters

Takes the following named parameters. At least one of them must be specified.

start

A datetime.

The earliest revision you want returned. (Search is "inclusive", so if the time of the commit matches start exactly, it will be returned.)

If you specify start without end, we search from start to the most recent commit.

end

A datetime.

The latest revision you want returned. (Search is "inclusive", so if the time of the commit matches end exactly, it will be returned.)

If you specify end without start, we search from the beginning of time to end.

Returns

A VCI::Abstract::History for the project representing the times that you asked for. If there were no commits matching your criteria, the History's "commits" will be an empty arrayref.

CLASS METHODS

Top

Constructors

Usually you won't construct an instance of this class directly, but instead, use get_project in VCI::Abstract::Repository or projects in VCI::Abstract::Repository.

new

Takes all Accessors of this class as named parameters. The following fields are required: name and repository.

VCI documentation Contained in the VCI distribution. 
package VCI::Abstract::Project;
use Moose;
use MooseX::Method;

use VCI::Util qw(CLASS_METHODS);

has 'name'       => (is => 'ro', isa => 'Str', required => 1);
has 'repository' => (is => 'ro', isa => 'VCI::Abstract::Repository',
                     required => 1, handles => ['vci', CLASS_METHODS]);
has 'history'    => (is => 'ro', isa => 'VCI::Abstract::History', lazy_build => 1);
has 'head_revision' => (is => 'ro', isa => 'Str', lazy_build => 1);
has 'root_directory' => (is => 'ro', isa => 'VCI::Abstract::Directory',
                         lazy_build => 1);

# This is handy for people who want to override get_commit.
use constant get_commit_prototype => (
    revision => { isa => 'Str' },
    time     => { isa => 'VCI::Type::DateTime', coerce => 1 },
    at_or_before => { isa => 'VCI::Type::DateTime', coerce => 1 },
);
method 'get_commit' => named (get_commit_prototype) => sub {
    my ($self, $params) = @_;

    # MooseX::Method always has a hash key for each parameter, even if they
    # weren't passed by the caller.
    delete $params->{$_} foreach (grep { !defined $params->{$_} } keys %$params);
    
    if (!keys %$params) {
        confess("You must specify at least one argument for get_commit");
    }
    elsif (scalar(keys %$params) > 1) {
        confess("You must specify only one argument to get_commit."
                . " You specified the following arguments: "
                . join(', ', keys %$params));
    }    
    
    my ($key) = keys %$params;
    my $value = $params->{$key};

    if ($key eq 'at_or_before') {
        my @commits = @{$self->history->commits};
        # If there are no commits, or the first commit is later than our
        # at_or_before, we return undef.
        return undef if !@commits || $commits[0]->time > $value;
        my $last_commit;
        
        # Cycle through the commits until we find a commit whose time
        # is too late. That means the commit before that one is the one
        # we want.
        foreach my $commit (@commits) {
            last if $commit->time > $value;
            $last_commit = $commit;
        }
        return $last_commit;
    }

    my @items = grep { $_->$key eq $value } @{$self->history->commits};
    warn "More than one commit found with $key '$value'" if scalar @items > 1;
    return $items[0];
};

method 'get_history_by_time' => named (
    start => { isa => 'VCI::Type::DateTime', coerce => 1 },
    end   => { isa => 'VCI::Type::DateTime', coerce => 1 },
) => sub {
    my ($self, $params) = @_;
    my $start = $params->{start};
    my $end   = $params->{end};
    my $at    = $params->{at};
    
    if ( !(defined $start || defined $end || defined $at) ) {
        confess("Either 'start' or 'end', must be passed to"
                . " get_history_by_time");
    }
    
    my @commits = grep { (!$start || $_->time >= $start)
                         && (!$end || $_->time <= $end) }
                       @{$self->history->commits};

    my $vci = $self->vci;
    return $vci->history_class->new(commits => \@commits, project => $self);
};

# XXX All these methods will need "revision" and "at_or_before".

method 'get_directory' => named (
    path => { isa => 'VCI::Type::Path', coerce => 1, required => 1 },
) => sub {
    my ($self, $params) = @_;
    my $path = $params->{path};
    
    my $root = $self->root_directory;
    return $root if $path->is_empty;
    
    my @dirs = $path->list;
    my $current_dir = $root;
    while (my $dir_name = shift @dirs) {
        my $contents = $current_dir->contents;
        my @matches = grep { $_->isa('VCI::Abstract::Directory')
                             && $_->name eq $dir_name } @$contents;
        
        return undef if !@matches;
        warn("More than one directory in " . $current_dir->path
             . " is called '$dir_name'") if scalar @matches > 1;
        $current_dir = $matches[0];
    }

    return $current_dir;
};

method 'get_file' => named (
    path     => { isa => 'VCI::Type::Path', coerce => 1, required => 1 },
    revision => { isa => 'Str' },
) => sub {
    my ($self, $params) = @_;
    my $path = $params->{path};
    my $rev  = $params->{revision};
    
    confess("Empty path name passed to get_file") if $path->is_empty;
    
    if (defined $rev) {
        # This won't work in VCSes like CVS where the File revision IDs are
        # different from the Commit revision IDs.
        my $commit = $self->get_commit(revision => $rev);
        confess("No commit with revision $rev") if !$commit;
        my ($file) = grep { $_->path->stringify eq $path->stringify }
                          @{ $commit->contents };
        return $file;
    }
    
    my $dir = $self->get_directory(path => $path->parent);
    confess("No directory named " . $path->parent) if !$dir;
    
    my $filename = $path->last;
    
    my @matches = grep { $_->isa('VCI::Abstract::File')
                         && $_->name eq $filename } @{$dir->contents};
    
    return undef if !@matches;
    warn("More than one file in " . $dir->path . " is called '$filename'.")
        if scalar @matches > 1;
    return $matches[0];
};

method 'get_path' => named (
    path => { isa => 'VCI::Type::Path', coerce => 1, required => 1 },
) => sub {
    my ($self, $params) = @_;
    my $path = $params->{path};

    return $self->root_directory if $path->is_empty;

    my $dir = $self->get_directory(path => $path->parent);
    confess("No directory named " . $path->parent) if !$dir;

    my $name = $path->last;
    my @matches = grep { $_->name eq $name } @{$dir->contents};
    return undef if !@matches;
    warn("More than one item in " . $dir->path . " is called '$name'.")
        if scalar @matches > 1;
    return $matches[0];
};

sub _build_root_directory {
    my $self = shift;
    return $self->directory_class->new(path => '',
                                                        project => $self);
}

sub _build_head_revision {
    my $self = shift;
    my $last_commit = $self->history->commits->[-1];
    return undef if !$last_commit;
    return $last_commit->revision;
}

####################
# Subclass Helpers #
####################

# For use in BUILD
sub _name_never_ends_with_slash   { $_[0]->{name} =~ s|/+\s*$|| }
sub _name_never_starts_with_slash { $_[0]->{name} =~ s|^\s*/+|| }

__PACKAGE__->meta->make_immutable;

1;

__END__