view release on metacpan or  search on metacpan

deps/libgit2/include/git2/sys/filter.h  view on Meta::CPAN

 * will be called once at most and should release resources as needed.
 * This may be called even if the `initialize` callback was not made.
 *
 * Typically this function will free the `git_filter` object itself.
 */
typedef void GIT_CALLBACK(git_filter_shutdown_fn)(git_filter *self);

/**
 * Callback to decide if a given source needs this filter
 *
 * Specified as `filter.check`, this is an optional callback that checks
 * if filtering is needed for a given source.
 *
 * It should return 0 if the filter should be applied (i.e. success),
 * GIT_PASSTHROUGH if the filter should not be applied, or an error code
 * to fail out of the filter processing pipeline and return to the caller.
 *
 * The `attr_values` will be set to the values of any attributes given in
 * the filter definition.  See `git_filter` below for more detail.
 *
 * The `payload` will be a pointer to a reference payload for the filter.
 * This will start as NULL, but `check` can assign to this pointer for
 * later use by the `stream` callback.  Note that the value should be heap
 * allocated (not stack), so that it doesn't go away before the `stream`
 * callback can use it.  If a filter allocates and assigns a value to the
 * `payload`, it will need a `cleanup` callback to free the payload.
 */
typedef int GIT_CALLBACK(git_filter_check_fn)(
	git_filter              *self,
	void                   **payload, /* NULL on entry, may be set */
	const git_filter_source *src,
	const char             **attr_values);

#ifndef GIT_DEPRECATE_HARD
/**
 * Callback to actually perform the data filtering
 *
 * Specified as `filter.apply`, this is the callback that actually filters
 * data.  If it successfully writes the output, it should return 0.  Like
 * `check`, it can return GIT_PASSTHROUGH to indicate that the filter
 * doesn't want to run.  Other error codes will stop filter processing and
 * return to the caller.
 *
 * The `payload` value will refer to any payload that was set by the
 * `check` callback.  It may be read from or written to as needed.
 *
 * @deprecated use git_filter_stream_fn
 */
typedef int GIT_CALLBACK(git_filter_apply_fn)(
	git_filter              *self,
	void                   **payload, /* may be read and/or set */
	git_buf                 *to,
	const git_buf           *from,
	const git_filter_source *src);
#endif

/**
 * Callback to perform the data filtering.
 *
 * Specified as `filter.stream`, this is a callback that filters data
 * in a streaming manner.  This function will provide a
 * `git_writestream` that will the original data will be written to;
 * with that data, the `git_writestream` will then perform the filter
 * translation and stream the filtered data out to the `next` location.
 */
typedef int GIT_CALLBACK(git_filter_stream_fn)(
	git_writestream        **out,
	git_filter              *self,
	void                   **payload,
	const git_filter_source *src,
	git_writestream         *next);

/**
 * Callback to clean up after filtering has been applied
 *
 * Specified as `filter.cleanup`, this is an optional callback invoked
 * after the filter has been applied.  If the `check`, `apply`, or
 * `stream` callbacks allocated a `payload` to keep per-source filter
 * state, use this callback to free that payload and release resources
 * as required.
 */
typedef void GIT_CALLBACK(git_filter_cleanup_fn)(
	git_filter              *self,
	void                    *payload);

/**
 * Filter structure used to register custom filters.
 *
 * To associate extra data with a filter, allocate extra data and put the
 * `git_filter` struct at the start of your data buffer, then cast the
 * `self` pointer to your larger structure when your callback is invoked.
 */
struct git_filter {
	/** The `version` field should be set to `GIT_FILTER_VERSION`. */
	unsigned int           version;

 	/**
	 * A whitespace-separated list of attribute names to check for this
	 * filter (e.g. "eol crlf text").  If the attribute name is bare, it
	 * will be simply loaded and passed to the `check` callback.  If it
	 * has a value (i.e. "name=value"), the attribute must match that
	 * value for the filter to be applied.  The value may be a wildcard
	 * (eg, "name=*"), in which case the filter will be invoked for any
	 * value for the given attribute name.  See the attribute parameter
	 * of the `check` callback for the attribute value that was specified.
	 */
	const char            *attributes;

	/** Called when the filter is first used for any file. */
	git_filter_init_fn     initialize;

	/** Called when the filter is removed or unregistered from the system. */
	git_filter_shutdown_fn shutdown;

	/**
	 * Called to determine whether the filter should be invoked for a
	 * given file.  If this function returns `GIT_PASSTHROUGH` then the
	 * `stream` or `apply` functions will not be invoked and the
	 * contents will be passed through unmodified.
	 */
	git_filter_check_fn    check;