/*

 * 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