Svn.pl

#!/usr/bin/perl
#
# blah blah... license info blah blah seems most other source files have this header comment format
#
# The Original Code was written for:
#     Delta Debugging Framework.
#
# The Initial Developer of the Original Code:
#     Richard Chu
#
# Contributor(s):
#     Elizabeth Chak - Documentation
#
# Date Created: October 09, 2006
# Date Last Modified: October 24, 2006
#
# Version: 0.03
#
# Description:
# Light Wrapper around SVN commands used to manage, update, manipulate the SVN source repository.
# The wrapper assumes the most common usage of each command. It can perform the following commands:
#     svn checkout
#     svn update
#     svn commit
#     svn diff
#
# One thing I haven't figured out yet is if the svn commands return a return code to indicate
# whether or not the command executed successfully or not. If the svn commands do, then I
# would probably perform a check on whether or not the commands executed successfully or not.
#
# NOTE/FIXME: Currently (Oct. 24, 2006 version), the subroutines that take in revision numbers
#               (update, diff) require that the argument be numerical. There is no support for
#               revision keywords (HEAD, BASE, COMMITED, PREV), or revision dates as described
#               here: http://svnbook.red-bean.com/nightly/en/svn.tour.revs.html
#
# Change History:
#     October 09, 2006:
#         - svn class created. Initial support for most common usage of checkout, update, and commit commands
#
#     October 15, 2006:
#         - added support for most common usage of diff command.
#         - updated the update subroutine to receive another parameter for file/directory path.
#           arguments in update subroutine are all optional now. 1st argument default is "HEAD".
#
#     October 24, 2006:
#         - fixed conditional statement in diff subroutine from < $nRevisions to <= $nRevisions
#
###############################################################################

use warnings;
use strict;
package RCS::SVN;

####
# Create an generic RCS element. The hash ($self) holds the values for svn
# url, username and password passed into the subroutine. Data type of 
# hash is then changed to $class.  
# @param url       svn url
# @param username  svn username
# @param password  svn password
#
# Developer's comments: 
# I think this class should ideally be designed as a singleton but I haven't figured
# out how to do that in Perl. Yet.
####
sub new ($$$) {
    my $class = shift; # first element in @_ is class name
    my ($url, $username, $password) = @_; # the rest are arguments passed in to subroutine
    my $self = {
        _url => $url,
        _username => $username,
        _password => $password
    };
    bless ($self, $class);
    return $self;
};

####
# This is the destructor. It deletes the class variables that
# consist of svn url, svn username and svn password
####
sub destroy () {
    my $self = shift;
    delete $self->{_url};
    delete $self->{_username};
    delete $self->{_password};
}

####
# Checkout subroutine checks out the source tree from the svn source repository.
#
# 
# @param directory	Optional; Allows you to change the top-level directory of your
#                       working copy to be different than that in the SVN repository.
#                       The value must be relative position from your present working directory
#                       If it is undefined, it will default to empty string (top-level directory 
#                       of working copy same as repository)
#
# Some interesting values:
#   "." 		will make the top-level directory your present working directory
#   "../" 		will make the top-level directory the parent directory of your present working directory.
#   "C:\<directory>" 	will not work as expected as the value must be relative to present working directory.
####
sub checkout (;$) {
    my $self = shift;
    my $directory = pop(@_);

    if (defined($self->{_url})) {
        if (!defined($directory)) {
            $directory = "";
        }
        my $rc = `svn checkout $self->{_url} $directory`;
    }
}

####
# Commit subroutine that commits changes to the source repository if the
# class variables for the svn username and svn password are defined.
# Argument passed in is the svn log message; can be an empty string but it's 
# not recommended for logging purposes.
# 
# @param message     svn log message, describing the change 
####
sub commit ($) {
    my $message = pop(@_);
    my $self = shift;

    if (defined($self->{_username}) && defined($self->{_password})) {
        my $rc = `svn commit -m \"$message\" --username $self->{_username} --password $self->{_password}`;
    }
    else {
        print "No username or password defined.";
    }
}

####
# Update subroutine that updates your working copy to the source repository to receive changes 
# made by other developers since your last update. An update will take files/ directories etc. 
# on the server and copy it to your local copy. Update is only done if the username and password
# are defined and if revision numbers are not out of range. Otherwise, the user will be alerted about
# the error.
#
# @param revision    Specified by argument passed in as long as it's valid (default is HEAD revision)
#                    Possible revision keywords: HEAD, (BASE?, COMMITTED?, PREV?) and numbers 
#                    The number has to be less or equal to the number of revisions in the SVN source repository
#                    and can be acquired through getNumberOfRevisions() subroutine
#       
#                    Revision keywords and definitions:
#
#                    HEAD
#
#                      The latest (or "youngest") revision in the repository.
#
#                    BASE
#
#                      The revision number of an item in a working copy. If the item has been locally modified, the 
#                      "BASE version" refers to the way the item appears without those local modifications.
#
#                    COMMITTED
#
#                      The most recent revision prior to, or equal to, BASE, in which an item changed.
#
#                    PREV
#
#                       The revision immediately before the last revision in which an item changed. 
#                      (Technically, COMMITTED - 1.)
#
#                    NOTE: PREV, BASE, and COMMITTED can be used to refer to local paths, but not to URLs.
#
# @param file        Specified by second argument; file or directory is only updated if defined.
# @return rc         svn update command
####
sub update (;$$) {
    my $self = shift;
    my ($revision, $file) = @_;

    if (!defined($revision)) { $revision = "HEAD"; }
    if (!defined($file)) { $file = ""; }

    my $nRevisions = $self->getNumberOfRevisions();

    if (defined($self->{_username}) && defined($self->{_password})
        && ($revision eq "HEAD" ||
            $revision eq "BASE" ||
            $revision eq "COMMITTED" ||
            $revision eq "PREV" ||
           ($revision > 0 && $revision <= $nRevisions))) {
        my $rc = `svn update -r $revision  --username $self->{"_username"} --password $self->{"_password"} $file`;
    }
    else {
        print "username or password undefined or revision number out of range. Must be between 1 and $nRevisions";
    }
}

####
# Diff subroutine gets the differences between two paths ; optionally takes 3 parameters. 
# If no arguments are given, then the user's working copy will be compared with the latest revision.
# If one argument is given (a revision number), then the working copy is compared with the passed in revision.
# If two arguments are given (2 revision numbers), then the first and second revision numbers passed in are compared.
# If a third option is given, then the differences between the file given is returned.
# The svn diff command will only perform if the username and password are defined.
#
# @param rev1        Revision number, working copy is compared with the passed in revision, has to be more than 0 and
#                    less or equal to the revision number retrieved from the number of revisions in the SVN source 
#                    repository retrieved from getNumberOfRevisions subroutine
# @param rev2        Second revision number, first and second revision numbers passed in are compared, has to be more 
#                    than 0 and less or equal to the revision number retrieved from the number of revisions in the SVN 
#                    source repository retrieved from getNumberOfRevisions subroutine
# @param file        Filename, differences between the file given is returned if this is defined
# @return rc	     svn diff command
####
sub diff (;$$$) {
    my $self = shift;
    my ($rev1, $rev2, $file) = @_;
    my $rc;

    my $nRevisions = $self->getNumberOfRevisions();

    if (!defined($rev1)) { $rev1 = ""; }
    if (!defined($rev2)) { $rev2 = ""; }
    if (!defined($file)) { $file = ""; }

    if (defined($self->{_username}) && defined($self->{_password})
        && ($rev1 eq "" || ($rev1 > 0 && $rev1 <= $nRevisions))
        && ($rev2 eq "" || ($rev2 > 0 && $rev2 <= $nRevisions))) {

        if ($rev2 ne "") { $rev2 = ":" . $rev2; }

        $rc = `svn diff -r $rev1$rev2 --username $self->{_username} --password $self->{_password} $file`;
    }
    else {
        print "No username or password defined. Or revision number out of range.";
    }

    return $rc;
}

####
# getNumberOfRevisions subroutine returns the number of revisions in the SVN source repository
# if the class variables username and password are defined
#
# @return rc    number of revisions in the SVN source repository
#
# Comments from developer:
# Did not find an svn command that returns the number of revisions so this is
# like a work around. May not be the best way but it is one way.
# This is supposed to be a private method. However, I have not figured out how to
# properly create private methods in perl (if it's even possible). Yet.
####
sub getNumberOfRevisions () {
    my $self = shift;
    my $rc = -1;

    if (defined($self->{_username}) && defined($self->{_password})) {

        my $log = `svn log -r HEAD --username $self->{"_username"} --password $self->{"_password"}`;

        $log =~ m/r[0-9]+/;

        my $r = $&;

        $r =~ m/[0-9]+/;
        $rc = $&;

    }

    return $rc;
}

1; # last expression of file must return true