perl/Git/Object.pm

   1 =head1 NAME
   2
   3 Git::Object - Object-oriented interface to Git objects (base class).
   4
   5 =head1 DESCRIPTION
   6
   7 Git::Object is a base class that provides access to commit, tag and
   8 (unimplemented) tree objects.  See L<Git::Commit> and L<Git::Tag>.
   9
  10 Objects are loaded lazily, and hence instantiation is free.
  11 Git::Object instances stringify to their SHA1s.
  12
  13 =cut
  14
  15
  16 use strict;
  17 use warnings;
  18
  19
  20 package Git::Object;
  21
  22 use Encode qw(decode);
  23
  24 use base qw(Exporter);
  25
  26 our @EXPORT = qw();
  27 our @EXPORT_OK = qw();
  28
  29 use overload
  30     '""' => \&sha1;
  31
  32 =head1 METHODS
  33
  34 =over
  35
  36 =item Git::Object->new($repo, $sha1)
  37
  38 Return a new Git::Object instance for the object with $sha1 in the
  39 repository $repo (a Git::Repo instance).
  40
  41 Note that this method does not check whether the object exists in the
  42 repository.  Trying to accessing its properties through a subclass
  43 will fail if the object doesn't exist, however.
  44
  45 =cut
  46
  47 sub new {
  48         my ($class, $repo, $sha1) = @_;
  49         die "$repo is not a Git::Repo instance" unless $repo->isa('Git::Repo');
  50         my $self = {repo => $repo, sha1 => $sha1};
  51         return bless $self, $class;
  52 }
  53
  54 =item $obj->repo
  55
  56 Return the Git::Repo instance this object was instantiated with.
  57
  58 =cut
  59
  60 sub repo {
  61         shift->{repo}
  62 }
  63
  64 =item $obj->sha1
  65
  66 Return the SHA1 of this object.
  67
  68 =cut
  69
  70 sub sha1 {
  71         shift->{sha1}
  72 }
  73
  74 # Helper method: Decode the given octets into a Unicode string, trying
  75 # the $self->{encoding} encoding first, if defined, then trying UTF-8,
  76 # then falling back to Latin 1.
  77
  78 sub _decode {
  79         my ($self, $octets) = @_;
  80         my $string;
  81         # Try $self->{encoding}:
  82         eval { $string = decode($self->{encoding}, $octets, Encode::FB_CROAK) }
  83             if $self->{encoding};
  84         # ... else try UTF-8:
  85         eval { $string = decode('utf-8', $octets, Encode::FB_CROAK) }
  86             unless defined $string;
  87         # ... else fall back to Latin 1 (the first 256 Unicode code
  88         # points coincide with Latin 1):
  89         $string = $octets unless defined $string;
  90         return $string;
  91 }
  92
  93
  94 1;