/*

 * Copyright (C) the libgit2 contributors. All rights reserved.

 *

 * This file is part of libgit2, distributed under the GNU GPL v2 with

 * a Linking Exception. For full terms see the included COPYING file.

 */

#ifndef INCLUDE_git_object_h__

#define INCLUDE_git_object_h__

#include "common.h"

#include "types.h"

#include "oid.h"

#include "buffer.h"

/**

 * @file git2/object.h

 * @brief Git revision object management routines

 * @defgroup git_object Git revision object management routines

 * @ingroup Git

 * @{

 */

GIT_BEGIN_DECL

/**

 * Lookup a reference to one of the objects in a repository.

 *

 * The generated reference is owned by the repository and

 * should be closed with the `git_object_free` method

 * instead of free'd manually.

 *

 * The 'type' parameter must match the type of the object

 * in the odb; the method will fail otherwise.

 * The special value 'GIT_OBJ_ANY' may be passed to let

 * the method guess the object's type.

 *

 * @param object pointer to the looked-up object

 * @param repo the repository to look up the object

 * @param id the unique identifier for the object

 * @param type the type of the object

 * @return 0 or an error code

 */

GIT_EXTERN(int) git_object_lookup(

		git_object **object,

		git_repository *repo,

		const git_oid *id,

		git_otype type);

/**

 * Lookup a reference to one of the objects in a repository,

 * given a prefix of its identifier (short id).

 *

 * The object obtained will be so that its identifier

 * matches the first 'len' hexadecimal characters

 * (packets of 4 bits) of the given 'id'.

 * 'len' must be at least GIT_OID_MINPREFIXLEN, and

 * long enough to identify a unique object matching

 * the prefix; otherwise the method will fail.

 *

 * The generated reference is owned by the repository and

 * should be closed with the `git_object_free` method

 * instead of free'd manually.

 *

 * The 'type' parameter must match the type of the object

 * in the odb; the method will fail otherwise.

 * The special value 'GIT_OBJ_ANY' may be passed to let

 * the method guess the object's type.

 *

 * @param object_out pointer where to store the looked-up object

 * @param repo the repository to look up the object

 * @param id a short identifier for the object

 * @param len the length of the short identifier

 * @param type the type of the object

 * @return 0 or an error code

 */

GIT_EXTERN(int) git_object_lookup_prefix(

		git_object **object_out,

		git_repository *repo,

		const git_oid *id,

		size_t len,

		git_otype type);

/**

 * Lookup an object that represents a tree entry.

 *

 * @param out buffer that receives a pointer to the object (which must be freed

 *            by the caller)

 * @param treeish root object that can be peeled to a tree

 * @param path relative path from the root object to the desired object

 * @param type type of object desired

 * @return 0 on success, or an error code

 */

GIT_EXTERN(int) git_object_lookup_bypath(

		git_object **out,

		const git_object *treeish,

		const char *path,

		git_otype type);

/**

 * Get the id (SHA1) of a repository object

 *

 * @param obj the repository object

 * @return the SHA1 id

 */

GIT_EXTERN(const git_oid *) git_object_id(const git_object *obj);

/**

 * Get a short abbreviated OID string for the object

 *

 * This starts at the "core.abbrev" length (default 7 characters) and

 * iteratively extends to a longer string if that length is ambiguous.

 * The result will be unambiguous (at least until new objects are added to

 * the repository).

 *

 * @param out Buffer to write string into

 * @param obj The object to get an ID for

 * @return 0 on success, <0 for error

 */

GIT_EXTERN(int) git_object_short_id(git_buf *out, const git_object *obj);

/**

 * Get the object type of an object

 *

 * @param obj the repository object

 * @return the object's type

 */

GIT_EXTERN(git_otype) git_object_type(const git_object *obj);

/**

 * Get the repository that owns this object

 *

 * Freeing or calling `git_repository_close` on the

 * returned pointer will invalidate the actual object.

 *

 * Any other operation may be run on the repository without

 * affecting the object.

 *

 * @param obj the object

 * @return the repository who owns this object

 */

GIT_EXTERN(git_repository *) git_object_owner(const git_object *obj);

/**

 * Close an open object

 *

 * This method instructs the library to close an existing

 * object; note that git_objects are owned and cached by the repository

 * so the object may or may not be freed after this library call,

 * depending on how aggressive is the caching mechanism used

 * by the repository.

 *

 * IMPORTANT:

 * It *is* necessary to call this method when you stop using

 * an object. Failure to do so will cause a memory leak.

 *

 * @param object the object to close

 */

GIT_EXTERN(void) git_object_free(git_object *object);

/**

 * Convert an object type to its string representation.

 *

 * The result is a pointer to a string in static memory and

 * should not be free()'ed.

 *

 * @param type object type to convert.

 * @return the corresponding string representation.

 */

GIT_EXTERN(const char *) git_object_type2string(git_otype type);

/**

 * Convert a string object type representation to it's git_otype.

 *

 * @param str the string to convert.

 * @return the corresponding git_otype.

 */

GIT_EXTERN(git_otype) git_object_string2type(const char *str);

/**

 * Determine if the given git_otype is a valid loose object type.

 *

 * @param type object type to test.

 * @return true if the type represents a valid loose object type,

 * false otherwise.

 */

GIT_EXTERN(int) git_object_typeisloose(git_otype type);

/**

 * Get the size in bytes for the structure which

 * acts as an in-memory representation of any given

 * object type.

 *

 * For all the core types, this would the equivalent

 * of calling `sizeof(git_commit)` if the core types

 * were not opaque on the external API.

 *

 * @param type object type to get its size

 * @return size in bytes of the object

 */

GIT_EXTERN(size_t) git_object__size(git_otype type);

/**

 * Recursively peel an object until an object of the specified type is met.

 *

 * If the query cannot be satisfied due to the object model,

 * GIT_EINVALIDSPEC will be returned (e.g. trying to peel a blob to a

 * tree).

 *

 * If you pass `GIT_OBJ_ANY` as the target type, then the object will

 * be peeled until the type changes. A tag will be peeled until the

 * referenced object is no longer a tag, and a commit will be peeled

 * to a tree. Any other object type will return GIT_EINVALIDSPEC.

 *

 * If peeling a tag we discover an object which cannot be peeled to

 * the target type due to the object model, GIT_EPEEL will be

 * returned.

 *

 * You must free the returned object.

 *

 * @param peeled Pointer to the peeled git_object

 * @param object The object to be processed

 * @param target_type The type of the requested object (a GIT_OBJ_ value)

 * @return 0 on success, GIT_EINVALIDSPEC, GIT_EPEEL, or an error code

 */

GIT_EXTERN(int) git_object_peel(

	git_object **peeled,

	const git_object *object,

	git_otype target_type);

/**

 * Create an in-memory copy of a Git object. The copy must be

 * explicitly free'd or it will leak.

 *

 * @param dest Pointer to store the copy of the object

 * @param source Original object to copy

 */

GIT_EXTERN(int) git_object_dup(git_object **dest, git_object *source);

/** @} */

GIT_END_DECL

#endif