include/git2/sys/filter.h

   1 /*
   2  * Copyright (C) the libgit2 contributors. All rights reserved.
   3  *
   4  * This file is part of libgit2, distributed under the GNU GPL v2 with
   5  * a Linking Exception. For full terms see the included COPYING file.
   6  */
   7 #ifndef INCLUDE_sys_git_config_backend_h__
   8 #define INCLUDE_sys_git_config_backend_h__
   9
  10 #include "git2/filter.h"
  11
  12 /**
  13  * @file git2/sys/filter.h
  14  * @brief Git filter backend and plugin routines
  15  * @defgroup git_backend Git custom backend APIs
  16  * @ingroup Git
  17  * @{
  18  */
  19 GIT_BEGIN_DECL
  20
  21 /**
  22  * Look up a filter by name
  23  *
  24  * @param name The name of the filter
  25  * @return Pointer to the filter object or NULL if not found
  26  */
  27 GIT_EXTERN(git_filter *) git_filter_lookup(const char *name);
  28
  29 #define GIT_FILTER_CRLF "crlf"
  30
  31 /**
  32  * Create a new empty filter list
  33  *
  34  * Normally you won't use this because `git_filter_list_load` will create
  35  * the filter list for you, but you can use this in combination with the
  36  * `git_filter_lookup` and `git_filter_list_push` functions to assemble
  37  * your own chains of filters.
  38  */
  39 GIT_EXTERN(int) git_filter_list_new(
  40         git_filter_list **out, git_repository *repo, git_filter_mode_t mode);
  41
  42 /**
  43  * Add a filter to a filter list with the given payload.
  44  *
  45  * Normally you won't have to do this because the filter list is created
  46  * by calling the "check" function on registered filters when the filter
  47  * attributes are set, but this does allow more direct manipulation of
  48  * filter lists when desired.
  49  *
  50  * Note that normally the "check" function can set up a payload for the
  51  * filter.  Using this function, you can either pass in a payload if you
  52  * know the expected payload format, or you can pass NULL.  Some filters
  53  * may fail with a NULL payload.  Good luck!
  54  */
  55 GIT_EXTERN(int) git_filter_list_push(
  56         git_filter_list *fl, git_filter *filter, void *payload);
  57
  58 /**
  59  * A filter source represents a file/blob to be processed
  60  */
  61 typedef struct git_filter_source git_filter_source;
  62
  63 /**
  64  * Get the repository that the source data is coming from.
  65  */
  66 GIT_EXTERN(git_repository *) git_filter_source_repo(const git_filter_source *src);
  67
  68 /**
  69  * Get the path that the source data is coming from.
  70  */
  71 GIT_EXTERN(const char *) git_filter_source_path(const git_filter_source *src);
  72
  73 /**
  74  * Get the file mode of the source file
  75  * If the mode is unknown, this will return 0
  76  */
  77 GIT_EXTERN(uint16_t) git_filter_source_filemode(const git_filter_source *src);
  78
  79 /**
  80  * Get the OID of the source
  81  * If the OID is unknown (often the case with GIT_FILTER_CLEAN) then
  82  * this will return NULL.
  83  */
  84 GIT_EXTERN(const git_oid *) git_filter_source_id(const git_filter_source *src);
  85
  86 /**
  87  * Get the git_filter_mode_t to be applied
  88  */
  89 GIT_EXTERN(git_filter_mode_t) git_filter_source_mode(const git_filter_source *src);
  90
  91 /*
  92  * struct git_filter
  93  *
  94  * The filter lifecycle:
  95  * - initialize - first use of filter
  96  * - shutdown   - filter removed/unregistered from system
  97  * - check      - considering for file
  98  * - apply      - applied to file
  99  * - cleanup    - done with file
 100  */
 101
 102 /**
 103  * Initialize callback on filter
 104  */
 105 typedef int (*git_filter_init_fn)(git_filter *self);
 106
 107 /**
 108  * Shutdown callback on filter
 109  */
 110 typedef void (*git_filter_shutdown_fn)(git_filter *self);
 111
 112 /**
 113  * Callback to decide if a given source needs this filter
 114  */
 115 typedef int (*git_filter_check_fn)(
 116         git_filter        *self,
 117         void              **payload, /* points to NULL ptr on entry, may be set */
 118         const git_filter_source *src,
 119         const char        **attr_values);
 120
 121 /**
 122  * Callback to actually perform the data filtering
 123  */
 124 typedef int (*git_filter_apply_fn)(
 125         git_filter        *self,
 126         void              **payload, /* may be read and/or set */
 127         git_buffer        *to,
 128         const git_buffer  *from,
 129         const git_filter_source *src);
 130
 131 /**
 132  * Callback to clean up after filtering has been applied
 133  */
 134 typedef void (*git_filter_cleanup_fn)(
 135         git_filter *self,
 136         void       *payload);
 137
 138 /**
 139  * Filter structure used to register a new filter.
 140  *
 141  * To associate extra data with a filter, simply allocate extra data
 142  * and put the `git_filter` struct at the start of your data buffer,
 143  * then cast the `self` pointer to your larger structure when your
 144  * callback is invoked.
 145  *
 146  * `version` should be set to GIT_FILTER_VERSION
 147  *
 148  * `attributes` is a whitespace-separated list of attribute names to check
 149  * for this filter (e.g. "eol crlf text").  If the attribute name is bare,
 150  * it will be simply loaded and passed to the `check` callback.  If it has
 151  * a value (i.e. "name=value"), the attribute must match that value for
 152  * the filter to be applied.
 153  *
 154  * `initialize` is an optional callback invoked before a filter is first
 155  * used.  It will be called once at most.
 156  *
 157  * `shutdown` is an optional callback invoked when the filter is
 158  * unregistered or when libgit2 is shutting down.  It will be called once
 159  * at most and should free any memory as needed.
 160  *
 161  * `check` is an optional callback that checks if filtering is needed for
 162  * a given source.  It should return 0 if the filter should be applied
 163  * (i.e. success), GIT_ENOTFOUND if the filter should not be applied, or
 164  * an other error code to fail out of the filter processing pipeline and
 165  * return to the caller.
 166  *
 167  * `apply` is the callback that actually filters data.  If it successfully
 168  * writes the output, it should return 0.  Like `check`, it can return
 169  * GIT_ENOTFOUND to indicate that the filter doesn't actually want to run.
 170  * Other error codes will stop filter processing and return to the caller.
 171  *
 172  * `cleanup` is an optional callback that is made after the filter has
 173  * been applied.  Both the `check` and `apply` callbacks are able to
 174  * allocate a `payload` to keep per-source filter state, and this callback
 175  * is given that value and can clean up as needed.
 176  */
 177 struct git_filter {
 178         unsigned int           version;
 179
 180         const char            *attributes;
 181
 182         git_filter_init_fn     initialize;
 183         git_filter_shutdown_fn shutdown;
 184         git_filter_check_fn    check;
 185         git_filter_apply_fn    apply;
 186         git_filter_cleanup_fn  cleanup;
 187 };
 188
 189 #define GIT_FILTER_VERSION 1
 190
 191 /**
 192  * Register a filter under a given name with a given priority.
 193  *
 194  * If non-NULL, the filter's initialize callback will be invoked before
 195  * the first use of the filter, so you can defer expensive operations (in
 196  * case libgit2 is being used in a way that doesn't need the filter).
 197  *
 198  * A filter's attribute checks and `check` and `apply` callbacks will be
 199  * issued in order of `priority` on smudge (to workdir), and in reverse
 200  * order of `priority` on clean (to odb).
 201  *
 202  * One filter will be preregistered with libgit2:
 203  * - GIT_FILTER_CRLF with priority of 0.
 204  *
 205  * Currently the filter registry is not thread safe, so any registering or
 206  * deregistering of filters must be done outside of any possible usage of
 207  * the filters (i.e. during application setup or shutdown).
 208  */
 209 GIT_EXTERN(int) git_filter_register(
 210         const char *name, git_filter *filter, int priority);
 211
 212 /**
 213  * Remove the filter with the given name
 214  *
 215  * It is not allowed to remove the builtin libgit2 filters.
 216  *
 217  * Currently the filter registry is not thread safe, so any registering or
 218  * deregistering of filters must be done outside of any possible usage of
 219  * the filters (i.e. during application setup or shutdown).
 220  */
 221 GIT_EXTERN(int) git_filter_unregister(const char *name);
 222
 223 /** @} */
 224 GIT_END_DECL
 225 #endif