[PATCH v3] perl/Git.pm: add parse_rev method

[Lea Wiemann <lewiemann@gmail.com>]

The parse_rev method takes a revision name and returns a SHA1 hash,
like the git-rev-parse command.

Signed-off-by: Lea Wiemann <LeWiemann@gmail.com>
---
Changes since PATCH v2: Updated the documentation (found this while
testing).  Here's the diff excerpt from v2 to v3:

 =item parse_rev ( REVISION_NAME )

 Look up the specified revision name and return the SHA1 hash, or
-return undef if the lookup failed.  See git rev-parse --help, section
-"Specifying Revisions".
+return undef if the lookup failed.  When passed a SHA1 hash, always
+return it even if it doesn't exist in the repository.
+
+See git rev-parse --help, section "Specifying Revisions", for valid
+revision name formats.

 perl/Git.pm |   41 +++++++++++++++++++++++++++++++++++++++++
 1 files changed, 41 insertions(+), 0 deletions(-)

diff --git a/perl/Git.pm b/perl/Git.pm
index d05b633..80f7669 100644
--- a/perl/Git.pm
+++ b/perl/Git.pm
@@ -716,6 +716,47 @@ sub ident_person {
 	return "$ident[0] <$ident[1]>";
 }
 
+=item parse_rev ( REVISION_NAME )
+
+Look up the specified revision name and return the SHA1 hash, or
+return undef if the lookup failed.  When passed a SHA1 hash, always
+return it even if it doesn't exist in the repository.
+
+See git rev-parse --help, section "Specifying Revisions", for valid
+revision name formats.
+
+=cut
+
+sub parse_rev {
+	# We could allow for a list of revisions here.
+	my ($self, $rev_name) = @_;
+
+	my $hash;
+	try {
+		# The --quiet --verify options cause git-rev-parse to fail
+		# with exit status 1 (instead of 128) if the given revision
+		# name is not found, which enables us to distinguish not-found
+		# from serious errors.  The --default option works around
+		# git-rev-parse's lack of support for getopt style "--"
+		# separators (it would fail for tags named "--foo" without
+		# it).
+		$hash = $self->command_oneline("rev-parse", "--verify", "--quiet",
+					       "--default", $rev_name);
+	} catch Git::Error::Command with {
+		my $E = shift;
+		if ($E->value() == 1) {
+			# Revision name not found.
+			$hash = undef;
+		} else {
+			throw $E;
+		}
+	};
+	# Guard against unexpected output.
+	throw Error::Simple(
+		"parse_rev: unexpected output for \"$rev_name\": $hash")
+	    if defined $hash and $hash !~ /^([0-9a-fA-F]{40})$/;
+	return $hash;
+}
 
 =item hash_object ( TYPE, FILENAME )
 
-- 
1.5.5.GIT