/ 
Git-Database-0.012
River stage zero No dependents
/ Git::Database::Role::ObjectReader

NAME

Git::Database::Role::ObjectReader - Abstract role for a Git backends that read objects

VERSION

version 0.012

SYNOPSIS

package MyGitBackend;

use Moo;
use namespace::clean;

with
  'Git::Database::Role::Backend',
  'Git::Database::Role::ObjectReader';

# implement the required methods
sub get_object_attributes { ... }
sub all_digests           { ... }

DESCRIPTION

A backend doing the additional Git::Database::Role::ObjectReader role is capable of reading data from a Git repository to produce objects or return information about them.

METHODS

has_object

# assuming 4b825dc642cb6eb9a060e54bf8d69288fbee4904 (the empty tree)
# is in the database and 123456 is not

$kind = $backend->has_object('4b825dc642cb6eb9a060e54bf8d69288fbee4904');  # true ('tree')
$kind = $backend->has_object('4b825d');    # also true ('tree')
$kind = $backend->has_object('123456');    # false ('')

Given a digest value (possibly abbreviated), has_object returns a boolean indicating if the corresponding object is in the database.

As a convenience, if the object exists in the Git database, the true value that is returned is its "kind".

get_object

# a Git::Database::Object::Tree representing the empty tree
$tree = $backend->get_object('4b825dc642cb6eb9a060e54bf8d69288fbee4904');
$tree = $backend->get_object('4b825d');    # idem

# undef
$tree = $backend->get_object('123456');

Given a digest value (possibly abbreviated), get_object returns the full object extracted from the Git database (one of Git::Database::Object::Blob, Git::Database::Object::Tree, Git::Database::Object::Commit, or Git::Database::Object::Tag).

Returns undef if the object is not in the Git database or if the abbreviated digest is ambiguous.

get_object_meta

# ( '4b825dc642cb6eb9a060e54bf8d69288fbee4904', 'tree', 0 );
( $digest, $kind, $size ) = $backend->get_object_meta('4b825d');

# ( '123456', 'missing', undef )
( $digest, $kind, $size ) = $backend->get_object_meta('123456');

Given a digest value (possibly abbreviated), return a list containing the complete digest, the object type and its size (if the requested object is in the database).

Otherwise it returns the requested $digest, the string missing and the undef value.

The default implementation is written using "get_object_attributes". Backend writers may want to implement their own for performance reasons.

REQUIRED METHODS

get_object_attributes

# {
#     kind    => 'tree',
#     size    => 0,
#     content => '',
#     digest  => '4b825dc642cb6eb9a060e54bf8d69288fbee4904',
# }
my $attr = $backend->get_object_attributes('4b825d');

# undef
my $attr = $backend->get_object_attributes('123456');

Given a digest value (possibly abbreviated), return a hash reference with all the attributes needed to create a new object (if the requested object is in the database). This method is typically used by "get_object" to create the actual object instance.

Return undef if the object is not in the Git database or if the abbreviated digest is ambiguous.

The exact content of the hash reference returned by get_object_attributes may vary, but there are certain minimum requirements:

  • The kind key is required.

  • The size key is required, if the backend does not provide its own "get_object_meta" implementation (as the default implementation depends on "get_object_attributes" to obtain the metadata).

  • If present, the digest value must be the full digest (40 hexadecimal digits).

  • Although most backends return the content attribute, it is not strictly required (except for a blob). For a tree, a backend can instead return the directory_entries attribute (a list of Git::Database::DirectoryEntry objects). Likewise, it can also provide commit_info for a commit and tag_info for a tag.

all_digests

# all the digests contained in the Git database
my @sha1 = $backend->all_digests();

# filter by kind
my @trees = $backend->all_digests('tree');

Return all the digests contained in the Git object database. If a kind argument is provided, only return the digests for that specific object kind.

Depending on the underlying implementation, this may return unreachable objects.

AUTHOR

Philippe Bruhat (BooK) <book@cpan.org>.

COPYRIGHT

Copyright 2016 Philippe Bruhat (BooK), all rights reserved.

LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.