include/git2/filter.h - third_party/libgit2 - Git at Google

 /*
  * 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_filter_h__
 #define INCLUDE_git_filter_h__

 #include "common.h"
 #include "types.h"
 #include "oid.h"
 #include "buffer.h"

 /**
  * @file git2/filter.h
  * @brief Git filter APIs
  *
  * @ingroup Git
  * @{
  */
 GIT_BEGIN_DECL

 /**
  * Filters are applied in one of two directions: smudging - which is
  * exporting a file from the Git object database to the working directory,
  * and cleaning - which is importing a file from the working directory to
  * the Git object database.  These values control which direction of
  * change is being applied.
  */
 typedef enum {
 	GIT_FILTER_TO_WORKTREE = 0,
 	GIT_FILTER_SMUDGE = GIT_FILTER_TO_WORKTREE,
 	GIT_FILTER_TO_ODB = 1,
 	GIT_FILTER_CLEAN = GIT_FILTER_TO_ODB,
 } git_filter_mode_t;

 /**
  * Filter option flags.
  */
 typedef enum {
 	GIT_FILTER_DEFAULT = 0u,
 	GIT_FILTER_ALLOW_UNSAFE = (1u << 0),
 } git_filter_flag_t;

 /**
  * A filter that can transform file data
  *
  * This represents a filter that can be used to transform or even replace
  * file data.  Libgit2 includes one built in filter and it is possible to
  * write your own (see git2/sys/filter.h for information on that).
  *
  * The two builtin filters are:
  *
  * * "crlf" which uses the complex rules with the "text", "eol", and
  *   "crlf" file attributes to decide how to convert between LF and CRLF
  *   line endings
  * * "ident" which replaces "$Id$" in a blob with "$Id: <blob OID>$" upon
  *   checkout and replaced "$Id: <anything>$" with "$Id$" on checkin.
  */
 typedef struct git_filter git_filter;

 /**
  * List of filters to be applied
  *
  * This represents a list of filters to be applied to a file / blob.  You
  * can build the list with one call, apply it with another, and dispose it
  * with a third.  In typical usage, there are not many occasions where a
  * git_filter_list is needed directly since the library will generally
  * handle conversions for you, but it can be convenient to be able to
  * build and apply the list sometimes.
  */
 typedef struct git_filter_list git_filter_list;

 /**
  * Load the filter list for a given path.
  *
  * This will return 0 (success) but set the output git_filter_list to NULL
  * if no filters are requested for the given file.
  *
  * @param filters Output newly created git_filter_list (or NULL)
  * @param repo Repository object that contains `path`
  * @param blob The blob to which the filter will be applied (if known)
  * @param path Relative path of the file to be filtered
  * @param mode Filtering direction (WT->ODB or ODB->WT)
  * @param flags Combination of `git_filter_flag_t` flags
  * @return 0 on success (which could still return NULL if no filters are
  *         needed for the requested file), <0 on error
  */
 GIT_EXTERN(int) git_filter_list_load(
 	git_filter_list **filters,
 	git_repository *repo,
 	git_blob *blob, /* can be NULL */
 	const char *path,
 	git_filter_mode_t mode,
 	uint32_t flags);

 /**
  * Query the filter list to see if a given filter (by name) will run.
  * The built-in filters "crlf" and "ident" can be queried, otherwise this
  * is the name of the filter specified by the filter attribute.
  *
  * This will return 0 if the given filter is not in the list, or 1 if
  * the filter will be applied.
  *
  * @param filters A loaded git_filter_list (or NULL)
  * @param name The name of the filter to query
  * @return 1 if the filter is in the list, 0 otherwise
  */
 GIT_EXTERN(int) git_filter_list_contains(
 	git_filter_list *filters,
 	const char *name);

 /**
  * Apply filter list to a data buffer.
  *
  * See `git2/buffer.h` for background on `git_buf` objects.
  *
  * If the `in` buffer holds data allocated by libgit2 (i.e. `in->asize` is
  * not zero), then it will be overwritten when applying the filters.  If
  * not, then it will be left untouched.
  *
  * If there are no filters to apply (or `filters` is NULL), then the `out`
  * buffer will reference the `in` buffer data (with `asize` set to zero)
  * instead of allocating data.  This keeps allocations to a minimum, but
  * it means you have to be careful about freeing the `in` data since `out`
  * may be pointing to it!
  *
  * @param out Buffer to store the result of the filtering
  * @param filters A loaded git_filter_list (or NULL)
  * @param in Buffer containing the data to filter
  * @return 0 on success, an error code otherwise
  */
 GIT_EXTERN(int) git_filter_list_apply_to_data(
 	git_buf *out,
 	git_filter_list *filters,
 	git_buf *in);

 /**
  * Apply a filter list to the contents of a file on disk
  *
  * @param out buffer into which to store the filtered file
  * @param filters the list of filters to apply
  * @param repo the repository in which to perform the filtering
  * @param path the path of the file to filter, a relative path will be
  * taken as relative to the workdir
  */
 GIT_EXTERN(int) git_filter_list_apply_to_file(
 	git_buf *out,
 	git_filter_list *filters,
 	git_repository *repo,
 	const char *path);

 /**
  * Apply a filter list to the contents of a blob
  *
  * @param out buffer into which to store the filtered file
  * @param filters the list of filters to apply
  * @param blob the blob to filter
  */
 GIT_EXTERN(int) git_filter_list_apply_to_blob(
 	git_buf *out,
 	git_filter_list *filters,
 	git_blob *blob);

 /**
  * Apply a filter list to an arbitrary buffer as a stream
  *
  * @param filters the list of filters to apply
  * @param data the buffer to filter
  * @param target the stream into which the data will be written
  */
 GIT_EXTERN(int) git_filter_list_stream_data(
 	git_filter_list *filters,
 	git_buf *data,
 	git_writestream *target);

 /**
  * Apply a filter list to a file as a stream
  *
  * @param filters the list of filters to apply
  * @param repo the repository in which to perform the filtering
  * @param path the path of the file to filter, a relative path will be
  * taken as relative to the workdir
  * @param target the stream into which the data will be written
  */
 GIT_EXTERN(int) git_filter_list_stream_file(
 	git_filter_list *filters,
 	git_repository *repo,
 	const char *path,
 	git_writestream *target);

 /**
  * Apply a filter list to a blob as a stream
  *
  * @param filters the list of filters to apply
  * @param blob the blob to filter
  * @param target the stream into which the data will be written
  */
 GIT_EXTERN(int) git_filter_list_stream_blob(
 	git_filter_list *filters,
 	git_blob *blob,
 	git_writestream *target);

 /**
  * Free a git_filter_list
  *
  * @param filters A git_filter_list created by `git_filter_list_load`
  */
 GIT_EXTERN(void) git_filter_list_free(git_filter_list *filters);


 GIT_END_DECL

 /** @} */

 #endif
	/*
	* 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_filter_h__
	#define INCLUDE_git_filter_h__

	#include "common.h"
	#include "types.h"
	#include "oid.h"
	#include "buffer.h"

	/**
	* @file git2/filter.h
	* @brief Git filter APIs
	*
	* @ingroup Git
	* @{
	*/
	GIT_BEGIN_DECL

	/**
	* Filters are applied in one of two directions: smudging - which is
	* exporting a file from the Git object database to the working directory,
	* and cleaning - which is importing a file from the working directory to
	* the Git object database. These values control which direction of
	* change is being applied.
	*/
	typedef enum {
	GIT_FILTER_TO_WORKTREE = 0,
	GIT_FILTER_SMUDGE = GIT_FILTER_TO_WORKTREE,
	GIT_FILTER_TO_ODB = 1,
	GIT_FILTER_CLEAN = GIT_FILTER_TO_ODB,
	} git_filter_mode_t;

	/**
	* Filter option flags.
	*/
	typedef enum {
	GIT_FILTER_DEFAULT = 0u,
	GIT_FILTER_ALLOW_UNSAFE = (1u << 0),
	} git_filter_flag_t;

	/**
	* A filter that can transform file data
	*
	* This represents a filter that can be used to transform or even replace
	* file data. Libgit2 includes one built in filter and it is possible to
	* write your own (see git2/sys/filter.h for information on that).
	*
	* The two builtin filters are:
	*
	* * "crlf" which uses the complex rules with the "text", "eol", and
	* "crlf" file attributes to decide how to convert between LF and CRLF
	* line endings
	* * "ident" which replaces "$Id$" in a blob with "$Id: <blob OID>$" upon
	* checkout and replaced "$Id: <anything>$" with "$Id$" on checkin.
	*/
	typedef struct git_filter git_filter;

	/**
	* List of filters to be applied
	*
	* This represents a list of filters to be applied to a file / blob. You
	* can build the list with one call, apply it with another, and dispose it
	* with a third. In typical usage, there are not many occasions where a
	* git_filter_list is needed directly since the library will generally
	* handle conversions for you, but it can be convenient to be able to
	* build and apply the list sometimes.
	*/
	typedef struct git_filter_list git_filter_list;

	/**
	* Load the filter list for a given path.
	*
	* This will return 0 (success) but set the output git_filter_list to NULL
	* if no filters are requested for the given file.
	*
	* @param filters Output newly created git_filter_list (or NULL)
	* @param repo Repository object that contains `path`
	* @param blob The blob to which the filter will be applied (if known)
	* @param path Relative path of the file to be filtered
	* @param mode Filtering direction (WT->ODB or ODB->WT)
	* @param flags Combination of `git_filter_flag_t` flags
	* @return 0 on success (which could still return NULL if no filters are
	* needed for the requested file), <0 on error
	*/
	GIT_EXTERN(int) git_filter_list_load(
	git_filter_list **filters,
	git_repository *repo,
	git_blob blob, / can be NULL */
	const char *path,
	git_filter_mode_t mode,
	uint32_t flags);

	/**
	* Query the filter list to see if a given filter (by name) will run.
	* The built-in filters "crlf" and "ident" can be queried, otherwise this
	* is the name of the filter specified by the filter attribute.
	*
	* This will return 0 if the given filter is not in the list, or 1 if
	* the filter will be applied.
	*
	* @param filters A loaded git_filter_list (or NULL)
	* @param name The name of the filter to query
	* @return 1 if the filter is in the list, 0 otherwise
	*/
	GIT_EXTERN(int) git_filter_list_contains(
	git_filter_list *filters,
	const char *name);

	/**
	* Apply filter list to a data buffer.
	*
	* See `git2/buffer.h` for background on `git_buf` objects.
	*
	* If the `in` buffer holds data allocated by libgit2 (i.e. `in->asize` is
	* not zero), then it will be overwritten when applying the filters. If
	* not, then it will be left untouched.
	*
	* If there are no filters to apply (or `filters` is NULL), then the `out`
	* buffer will reference the `in` buffer data (with `asize` set to zero)
	* instead of allocating data. This keeps allocations to a minimum, but
	* it means you have to be careful about freeing the `in` data since `out`
	* may be pointing to it!
	*
	* @param out Buffer to store the result of the filtering
	* @param filters A loaded git_filter_list (or NULL)
	* @param in Buffer containing the data to filter
	* @return 0 on success, an error code otherwise
	*/
	GIT_EXTERN(int) git_filter_list_apply_to_data(
	git_buf *out,
	git_filter_list *filters,
	git_buf *in);

	/**
	* Apply a filter list to the contents of a file on disk
	*
	* @param out buffer into which to store the filtered file
	* @param filters the list of filters to apply
	* @param repo the repository in which to perform the filtering
	* @param path the path of the file to filter, a relative path will be
	* taken as relative to the workdir
	*/
	GIT_EXTERN(int) git_filter_list_apply_to_file(
	git_buf *out,
	git_filter_list *filters,
	git_repository *repo,
	const char *path);

	/**
	* Apply a filter list to the contents of a blob
	*
	* @param out buffer into which to store the filtered file
	* @param filters the list of filters to apply
	* @param blob the blob to filter
	*/
	GIT_EXTERN(int) git_filter_list_apply_to_blob(
	git_buf *out,
	git_filter_list *filters,
	git_blob *blob);

	/**
	* Apply a filter list to an arbitrary buffer as a stream
	*
	* @param filters the list of filters to apply
	* @param data the buffer to filter
	* @param target the stream into which the data will be written
	*/
	GIT_EXTERN(int) git_filter_list_stream_data(
	git_filter_list *filters,
	git_buf *data,
	git_writestream *target);

	/**
	* Apply a filter list to a file as a stream
	*
	* @param filters the list of filters to apply
	* @param repo the repository in which to perform the filtering
	* @param path the path of the file to filter, a relative path will be
	* taken as relative to the workdir
	* @param target the stream into which the data will be written
	*/
	GIT_EXTERN(int) git_filter_list_stream_file(
	git_filter_list *filters,
	git_repository *repo,
	const char *path,
	git_writestream *target);

	/**
	* Apply a filter list to a blob as a stream
	*
	* @param filters the list of filters to apply
	* @param blob the blob to filter
	* @param target the stream into which the data will be written
	*/
	GIT_EXTERN(int) git_filter_list_stream_blob(
	git_filter_list *filters,
	git_blob *blob,
	git_writestream *target);

	/**
	* Free a git_filter_list
	*
	* @param filters A git_filter_list created by `git_filter_list_load`
	*/
	GIT_EXTERN(void) git_filter_list_free(git_filter_list *filters);


	GIT_END_DECL

	/** @} */

	#endif