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 module libgit2_d.filter;
8 
9 
10 private static import libgit2_d.buffer;
11 private static import libgit2_d.sys.filter;
12 private static import libgit2_d.types;
13 
14 /**
15  * @file git2/filter.h
16  * @brief Git filter APIs
17  *
18  * @ingroup Git
19  * @{
20  */
21 extern (C):
22 nothrow @nogc:
23 public:
24 
25 /**
26  * Filters are applied in one of two directions: smudging - which is
27  * exporting a file from the Git object database to the working directory,
28  * and cleaning - which is importing a file from the working directory to
29  * the Git object database.  These values control which direction of
30  * change is being applied.
31  */
32 enum git_filter_mode_t
33 {
34 	GIT_FILTER_TO_WORKTREE = 0,
35 	GIT_FILTER_SMUDGE = GIT_FILTER_TO_WORKTREE,
36 	GIT_FILTER_TO_ODB = 1,
37 	GIT_FILTER_CLEAN = GIT_FILTER_TO_ODB,
38 }
39 
40 //Declaration name in C language
41 enum
42 {
43 	GIT_FILTER_TO_WORKTREE = .git_filter_mode_t.GIT_FILTER_TO_WORKTREE,
44 	GIT_FILTER_SMUDGE = .git_filter_mode_t.GIT_FILTER_SMUDGE,
45 	GIT_FILTER_TO_ODB = .git_filter_mode_t.GIT_FILTER_TO_ODB,
46 	GIT_FILTER_CLEAN = .git_filter_mode_t.GIT_FILTER_CLEAN,
47 }
48 
49 /**
50  * Filter option flags.
51  */
52 enum git_filter_flag_t
53 {
54 	GIT_FILTER_DEFAULT = 0u,
55 
56 	/**
57 	 * Don't error for `safecrlf` violations, allow them to continue.
58 	 */
59 	GIT_FILTER_ALLOW_UNSAFE = 1u << 0,
60 
61 	/**
62 	 * Don't load `/etc/gitattributes` (or the system equivalent)
63 	 */
64 	GIT_FILTER_NO_SYSTEM_ATTRIBUTES = 1u << 1,
65 
66 	/**
67 	 * Load attributes from `.gitattributes` in the root of HEAD
68 	 */
69 	GIT_FILTER_ATTRIBUTES_FROM_HEAD = 1u << 2,
70 }
71 
72 //Declaration name in C language
73 enum
74 {
75 	GIT_FILTER_DEFAULT = .git_filter_flag_t.GIT_FILTER_DEFAULT,
76 	GIT_FILTER_ALLOW_UNSAFE = .git_filter_flag_t.GIT_FILTER_ALLOW_UNSAFE,
77 	GIT_FILTER_NO_SYSTEM_ATTRIBUTES = .git_filter_flag_t.GIT_FILTER_NO_SYSTEM_ATTRIBUTES,
78 	GIT_FILTER_ATTRIBUTES_FROM_HEAD = .git_filter_flag_t.GIT_FILTER_ATTRIBUTES_FROM_HEAD,
79 }
80 
81 /**
82  * A filter that can transform file data
83  *
84  * This represents a filter that can be used to transform or even replace
85  * file data.  Libgit2 includes one built in filter and it is possible to
86  * write your own (see git2/sys/filter.h for information on that).
87  *
88  * The two builtin filters are:
89  *
90  * * "crlf" which uses the complex rules with the "text", "eol", and
91  *   "crlf" file attributes to decide how to convert between LF and CRLF
92  *   line endings
93  * * "ident" which replaces "$Id$" in a blob with "$Id: <blob OID>$" upon
94  *   checkout and replaced "$Id: <anything>$" with "$Id$" on checkin.
95  */
96 alias git_filter = libgit2_d.sys.filter.git_filter;
97 
98 /**
99  * List of filters to be applied
100  *
101  * This represents a list of filters to be applied to a file / blob.  You
102  * can build the list with one call, apply it with another, and dispose it
103  * with a third.  In typical usage, there are not many occasions where a
104  * git_filter_list is needed directly since the library will generally
105  * handle conversions for you, but it can be convenient to be able to
106  * build and apply the list sometimes.
107  */
108 struct git_filter_list;
109 
110 /**
111  * Load the filter list for a given path.
112  *
113  * This will return 0 (success) but set the output git_filter_list to null
114  * if no filters are requested for the given file.
115  *
116  * Params:
117  *      filters = Output newly created git_filter_list (or null)
118  *      repo = Repository object that contains `path`
119  *      blob = The blob to which the filter will be applied (if known)
120  *      path = Relative path of the file to be filtered
121  *      mode = Filtering direction (WT->ODB or ODB->WT)
122  *      flags = Combination of `git_filter_flag_t` flags
123  *
124  * Returns: 0 on success (which could still return null if no filters are needed for the requested file), <0 on error
125  */
126 //GIT_EXTERN
127 int git_filter_list_load(.git_filter_list** filters, libgit2_d.types.git_repository* repo, libgit2_d.types.git_blob* blob, /* can be null */
128                      const (char)* path, .git_filter_mode_t mode, uint flags);
129 
130 /**
131  * Query the filter list to see if a given filter (by name) will run.
132  * The built-in filters "crlf" and "ident" can be queried, otherwise this
133  * is the name of the filter specified by the filter attribute.
134  *
135  * This will return 0 if the given filter is not in the list, or 1 if
136  * the filter will be applied.
137  *
138  * Params:
139  *      filters = A loaded git_filter_list (or null)
140  *      name = The name of the filter to query
141  *
142  * Returns: 1 if the filter is in the list, 0 otherwise
143  */
144 //GIT_EXTERN
145 int git_filter_list_contains(.git_filter_list* filters, const (char)* name);
146 
147 /**
148  * Apply filter list to a data buffer.
149  *
150  * See `git2/buffer.h` for background on `git_buf` objects.
151  *
152  * If the `in` buffer holds data allocated by libgit2 (i.e. `in_->asize` is
153  * not zero), then it will be overwritten when applying the filters.  If
154  * not, then it will be left untouched.
155  *
156  * If there are no filters to apply (or `filters` is null), then the `out`
157  * buffer will reference the `in` buffer data (with `asize` set to zero)
158  * instead of allocating data.  This keeps allocations to a minimum, but
159  * it means you have to be careful about freeing the `in` data since `out`
160  * may be pointing to it!
161  *
162  * Params:
163  *      out_ = Buffer to store the result of the filtering
164  *      filters = A loaded git_filter_list (or null)
165  *      in_ = Buffer containing the data to filter
166  *
167  * Returns: 0 on success, an error code otherwise
168  */
169 //GIT_EXTERN
170 int git_filter_list_apply_to_data(libgit2_d.buffer.git_buf* out_, .git_filter_list* filters, libgit2_d.buffer.git_buf* in_);
171 
172 /**
173  * Apply a filter list to the contents of a file on disk
174  *
175  * Params:
176  *      out_ = buffer into which to store the filtered file
177  *      filters = the list of filters to apply
178  *      repo = the repository in which to perform the filtering
179  *      path = the path of the file to filter, a relative path will be taken as relative to the workdir
180  */
181 //GIT_EXTERN
182 int git_filter_list_apply_to_file(libgit2_d.buffer.git_buf* out_, .git_filter_list* filters, libgit2_d.types.git_repository* repo, const (char)* path);
183 
184 /**
185  * Apply a filter list to the contents of a blob
186  *
187  * Params:
188  *      out_ = buffer into which to store the filtered file
189  *      filters = the list of filters to apply
190  *      blob = the blob to filter
191  */
192 //GIT_EXTERN
193 int git_filter_list_apply_to_blob(libgit2_d.buffer.git_buf* out_, .git_filter_list* filters, libgit2_d.types.git_blob* blob);
194 
195 /**
196  * Apply a filter list to an arbitrary buffer as a stream
197  *
198  * Params:
199  *      filters = the list of filters to apply
200  *      data = the buffer to filter
201  *      target = the stream into which the data will be written
202  */
203 //GIT_EXTERN
204 int git_filter_list_stream_data(.git_filter_list* filters, libgit2_d.buffer.git_buf* data, libgit2_d.types.git_writestream* target);
205 
206 /**
207  * Apply a filter list to a file as a stream
208  *
209  * Params:
210  *      filters = the list of filters to apply
211  *      repo = the repository in which to perform the filtering
212  *      path = the path of the file to filter, a relative path will be taken as relative to the workdir
213  *      target = the stream into which the data will be written
214  */
215 //GIT_EXTERN
216 int git_filter_list_stream_file(.git_filter_list* filters, libgit2_d.types.git_repository* repo, const (char)* path, libgit2_d.types.git_writestream* target);
217 
218 /**
219  * Apply a filter list to a blob as a stream
220  *
221  * Params:
222  *      filters = the list of filters to apply
223  *      blob = the blob to filter
224  *      target = the stream into which the data will be written
225  */
226 //GIT_EXTERN
227 int git_filter_list_stream_blob(.git_filter_list* filters, libgit2_d.types.git_blob* blob, libgit2_d.types.git_writestream* target);
228 
229 /**
230  * Free a git_filter_list
231  *
232  * Params:
233  *      filters = A git_filter_list created by `git_filter_list_load`
234  */
235 //GIT_EXTERN
236 void git_filter_list_free(.git_filter_list* filters);
237 
238 /** @} */