NAME

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

SYNOPSIS

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_file(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('123');
my $commits = $project->get_history_by_time(start => 'January 1, 1970',
                                            end   => '2007-01-01');
my ($commit) =
    @{ $project->get_history_by_time(at => 'July 7, 2007 12:01:22 UTC') };

# Other information

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

$repository == $project->repository # True

DESCRIPTION

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

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.

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 one named parameter:

path

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

Returns

A VCI::Abstract::File, or undef if there is no file with that name. (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 a single parameter: $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.

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.

You can either search a range of times using start and end, or you can ask for a specific time using at.

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.

at

A datetime.

Specifies that you want the commits that happened at an exact moment in time.

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

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