diff options
author | Edward Thomson <ethomson@edwardthomson.com> | 2021-05-12 22:13:12 +0100 |
---|---|---|
committer | Edward Thomson <ethomson@edwardthomson.com> | 2021-08-27 15:06:32 -0400 |
commit | a9a7bfb506ee4db156abf1ba55cda9de86c18fdb (patch) | |
tree | 8068fb78d25892b1d87e756e6a5d16f9b7b570a8 | |
parent | 45489a119467964b641515735b216a1eff12dd6d (diff) | |
download | libgit2-a9a7bfb506ee4db156abf1ba55cda9de86c18fdb.tar.gz |
filter: add docs for `git_filter_stream_fn`
-rw-r--r-- | include/git2/sys/filter.h | 69 |
1 files changed, 41 insertions, 28 deletions
diff --git a/include/git2/sys/filter.h b/include/git2/sys/filter.h index e43fde55c..098f8f7d3 100644 --- a/include/git2/sys/filter.h +++ b/include/git2/sys/filter.h @@ -167,16 +167,16 @@ typedef void GIT_CALLBACK(git_filter_shutdown_fn)(git_filter *self); * * 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 `apply` callback. Note that the value should be heap - * allocated (not stack), so that it doesn't go away before the `apply` + * 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, /* points to NULL ptr on entry, may be set */ + git_filter *self, + void **payload, /* NULL on entry, may be set */ const git_filter_source *src, - const char **attr_values); + const char **attr_values); /** * Callback to actually perform the data filtering @@ -191,30 +191,40 @@ typedef int GIT_CALLBACK(git_filter_check_fn)( * `check` callback. It may be read from or written to as needed. */ 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, + git_filter *self, + void **payload, /* may be read and/or set */ + git_buf *to, + const git_buf *from, const git_filter_source *src); +/** + * 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, + git_writestream **out, + git_filter *self, + void **payload, const git_filter_source *src, - git_writestream *next); + 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` or `apply` callbacks - * allocated a `payload` to keep per-source filter state, use this - * callback to free that payload and release resources as required. + * 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); + git_filter *self, + void *payload); /** * Filter structure used to register custom filters. @@ -248,21 +258,24 @@ struct git_filter { /** * Called to determine whether the filter should be invoked for a * given file. If this function returns `GIT_PASSTHROUGH` then the - * `apply` function will not be invoked and the contents will be passed - * through unmodified. + * `stream` or `apply` functions will not be invoked and the + * contents will be passed through unmodified. */ git_filter_check_fn check; /** - * Called to actually apply the filter to file contents. If this - * function returns `GIT_PASSTHROUGH` then the contents will be passed - * through unmodified. + * Provided for backward compatibility; this will apply the + * filter to the given contents in a `git_buf`. Callers should + * provide a `stream` function instead. */ git_filter_apply_fn apply; /** - * Called to apply the filter in a streaming manner. If this is not - * specified then the system will call `apply` with the whole buffer. + * Called to apply the filter, 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. */ git_filter_stream_fn stream; @@ -289,9 +302,9 @@ GIT_EXTERN(int) git_filter_init(git_filter *filter, unsigned int version); * As mentioned elsewhere, the initialize callback will not be invoked * immediately. It is deferred until the filter is used in some way. * - * A filter's attribute checks and `check` and `apply` callbacks will be - * issued in order of `priority` on smudge (to workdir), and in reverse - * order of `priority` on clean (to odb). + * A filter's attribute checks and `check` and `stream` (or `apply`) + * callbacks will be issued in order of `priority` on smudge (to + * workdir), and in reverse order of `priority` on clean (to odb). * * Two filters are preregistered with libgit2: * - GIT_FILTER_CRLF with priority 0 |