File Coverage

blib/lib/Git/Database/Role/ObjectReader.pm
Criterion Covered Total %
statement 25 25 100.0
branch 4 4 100.0
condition 2 3 66.6
subroutine 8 8 100.0
pod 3 3 100.0
total 42 43 97.6


line stmt bran cond sub pod time code
1             package Git::Database::Role::ObjectReader;
2             $Git::Database::Role::ObjectReader::VERSION = '0.012';
3 7     7   6766 use Git::Database::Object::Blob;
  7         32  
  7         279  
4 7     7   54 use Git::Database::Object::Tree;
  7         34  
  7         240  
5 7     7   51 use Git::Database::Object::Commit;
  7         24  
  7         231  
6 7     7   52 use Git::Database::Object::Tag;
  7         25  
  7         250  
7              
8 7     7   55 use Moo::Role;
  7         15  
  7         53  
9              
10             requires
11             'get_object_attributes',
12             'all_digests',
13             ;
14              
15             sub has_object {
16 231     231 1 1264505 my ( $self, $digest ) = @_;
17 231         2707 my ( $sha1, $kind, $size ) = $self->get_object_meta($digest);
18 231 100       10277 return $kind eq 'missing' ? '' : $kind;
19             }
20              
21             sub get_object_meta {
22 171     171 1 689 my ( $self, $digest ) = @_;
23              
24 171         1167 my $attr = $self->get_object_attributes($digest);
25             return $attr
26 171 100       1475 ? ( @{$attr}{qw( digest kind size )} )
  72         661  
27             : ( $digest, 'missing', undef );
28             }
29              
30             sub get_object {
31 574     574 1 331757 my ( $self, $digest ) = @_;
32 574         5852 my $attr = $self->get_object_attributes($digest);
33 574   66     36432 return $attr
34             && "Git::Database::Object::\u$attr->{kind}"
35             ->new( %$attr, backend => $self );
36             }
37              
38             1;
39              
40             __END__
41              
42             =pod
43              
44             =head1 NAME
45              
46             Git::Database::Role::ObjectReader - Abstract role for a Git backends that read objects
47              
48             =head1 VERSION
49              
50             version 0.012
51              
52             =head1 SYNOPSIS
53              
54             package MyGitBackend;
55              
56             use Moo;
57             use namespace::clean;
58              
59             with
60             'Git::Database::Role::Backend',
61             'Git::Database::Role::ObjectReader';
62              
63             # implement the required methods
64             sub get_object_attributes { ... }
65             sub all_digests { ... }
66              
67             =head1 DESCRIPTION
68              
69             A L<backend|Git::Database::Role::Backend> doing the additional
70             Git::Database::Role::ObjectReader role is capable of reading data from
71             a Git repository to produce L<objects|Git::Database::Role::Object> or
72             return information about them.
73              
74             =head1 METHODS
75              
76             =head2 has_object
77              
78             # assuming 4b825dc642cb6eb9a060e54bf8d69288fbee4904 (the empty tree)
79             # is in the database and 123456 is not
80              
81             $kind = $backend->has_object('4b825dc642cb6eb9a060e54bf8d69288fbee4904'); # true ('tree')
82             $kind = $backend->has_object('4b825d'); # also true ('tree')
83             $kind = $backend->has_object('123456'); # false ('')
84              
85             Given a digest value (possibly abbreviated), C<has_object> returns a
86             boolean indicating if the corresponding object is in the database.
87              
88             As a convenience, if the object exists in the Git database, the true
89             value that is returned is its "kind".
90              
91             =head2 get_object
92              
93             # a Git::Database::Object::Tree representing the empty tree
94             $tree = $backend->get_object('4b825dc642cb6eb9a060e54bf8d69288fbee4904');
95             $tree = $backend->get_object('4b825d'); # idem
96              
97             # undef
98             $tree = $backend->get_object('123456');
99              
100             Given a digest value (possibly abbreviated), C<get_object>
101             returns the full object extracted from the Git database (one of
102             L<Git::Database::Object::Blob>, L<Git::Database::Object::Tree>,
103             L<Git::Database::Object::Commit>, or L<Git::Database::Object::Tag>).
104              
105             Returns C<undef> if the object is not in the Git database or if the
106             abbreviated digest is ambiguous.
107              
108             =head2 get_object_meta
109              
110             # ( '4b825dc642cb6eb9a060e54bf8d69288fbee4904', 'tree', 0 );
111             ( $digest, $kind, $size ) = $backend->get_object_meta('4b825d');
112              
113             # ( '123456', 'missing', undef )
114             ( $digest, $kind, $size ) = $backend->get_object_meta('123456');
115              
116             Given a digest value (possibly abbreviated), return a list containing
117             the complete digest, the object type and its size (if the requested
118             object is in the database).
119              
120             Otherwise it returns the requested C<$digest>, the string C<missing>
121             and the C<undef> value.
122              
123             The default implementation is written using L</get_object_attributes>.
124             Backend writers may want to implement their own for performance reasons.
125              
126             =head1 REQUIRED METHODS
127              
128             =head2 get_object_attributes
129              
130             # {
131             # kind => 'tree',
132             # size => 0,
133             # content => '',
134             # digest => '4b825dc642cb6eb9a060e54bf8d69288fbee4904',
135             # }
136             my $attr = $backend->get_object_attributes('4b825d');
137              
138             # undef
139             my $attr = $backend->get_object_attributes('123456');
140              
141             Given a digest value (possibly abbreviated), return a hash reference with
142             all the attributes needed to create a new object (if the requested object
143             is in the database). This method is typically used by L</get_object>
144             to create the actual object instance.
145              
146             Return C<undef> if the object is not in the Git database or if the
147             abbreviated digest is ambiguous.
148              
149             The exact content of the hash reference returned by C<get_object_attributes>
150             may vary, but there are certain minimum requirements:
151              
152             =over 4
153              
154             =item *
155              
156             The C<kind> key is B<required>.
157              
158             =item *
159              
160             The C<size> key is B<required>, if the backend does not provide its own
161             L</get_object_meta> implementation (as the default implementation depends
162             on L</get_object_attributes> to obtain the metadata).
163              
164             =item *
165              
166             If present, the C<digest> value B<must> be the full digest (40 hexadecimal
167             digits).
168              
169             =item *
170              
171             Although most backends return the C<content> attribute, it is not strictly
172             required (except for a blob). For a tree, a backend can instead return
173             the L<directory_entries|Git::Database::Object::Tree/directory_entries>
174             attribute (a list of L<Git::Database::DirectoryEntry> objects). Likewise,
175             it can also provide L<commit_info|Git::Database::Object::Commit/commit_info>
176             for a commit and L<tag_info|Git::Database::Object::Tag/tag_info> for a tag.
177              
178             =back
179              
180             =head2 all_digests
181              
182             # all the digests contained in the Git database
183             my @sha1 = $backend->all_digests();
184              
185             # filter by kind
186             my @trees = $backend->all_digests('tree');
187              
188             Return all the digests contained in the Git object database.
189             If a L<kind|Git::Database::Role::Object/kind> argument is provided,
190             only return the digests for that specific object kind.
191              
192             Depending on the underlying implementation, this may return unreachable
193             objects.
194              
195             =head1 AUTHOR
196              
197             Philippe Bruhat (BooK) <book@cpan.org>.
198              
199             =head1 COPYRIGHT
200              
201             Copyright 2016 Philippe Bruhat (BooK), all rights reserved.
202              
203             =head1 LICENSE
204              
205             This program is free software; you can redistribute it and/or modify it
206             under the same terms as Perl itself.
207              
208             =cut