VCI::Abstract::Project - A particular project in the Repository
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
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.
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.
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
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.
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.
"/"
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.
undef
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
Gets a directory from the repository.
A Path to the directory that you want, relative to the base of the project.
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
Gets a file from the repository.
Takes the following named parameters:
A Path to the file that you want, 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.
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).
get_commit
Gets a particular commit from the Project by its unique identifier.
Takes one (and only one) of the following named parameters:
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
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.
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
Get a section of the Project's history based on times.
Takes the following named parameters. At least one of them must be specified.
start
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
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.
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.
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".
To install VCI, copy and paste the appropriate command in to your terminal.
cpanm
cpanm VCI
CPAN shell
perl -MCPAN -e shell install VCI
For more information on module installation, please visit the detailed CPAN module installation guide.