@leroysheep / Socializer
Code Commits Pulls CI/CD 81,295
bisect
bisect jch maint master next seen test todo
h 235 lines 7.41 KB
Raw
1 #ifndef TRAILER_H
2 #define TRAILER_H
3
4 #include "list.h"
5 #include "strbuf.h"
6
7 struct trailer_block;
8 struct strvec;
9
10 enum trailer_where {
11 WHERE_DEFAULT,
12 WHERE_END,
13 WHERE_AFTER,
14 WHERE_BEFORE,
15 WHERE_START
16 };
17 enum trailer_if_exists {
18 EXISTS_DEFAULT,
19 EXISTS_ADD_IF_DIFFERENT_NEIGHBOR,
20 EXISTS_ADD_IF_DIFFERENT,
21 EXISTS_ADD,
22 EXISTS_REPLACE,
23 EXISTS_DO_NOTHING
24 };
25 enum trailer_if_missing {
26 MISSING_DEFAULT,
27 MISSING_ADD,
28 MISSING_DO_NOTHING
29 };
30
31 int trailer_set_where(enum trailer_where *item, const char *value);
32 int trailer_set_if_exists(enum trailer_if_exists *item, const char *value);
33 int trailer_set_if_missing(enum trailer_if_missing *item, const char *value);
34
35 /*
36 * A list that represents newly-added trailers, such as those provided
37 * with the --trailer command line option of git-interpret-trailers.
38 */
39 struct new_trailer_item {
40 struct list_head list;
41
42 const char *text;
43
44 enum trailer_where where;
45 enum trailer_if_exists if_exists;
46 enum trailer_if_missing if_missing;
47 };
48
49 struct process_trailer_options {
50 int in_place;
51 int trim_empty;
52 int only_trailers;
53 int only_input;
54 int unfold;
55 int no_divider;
56 int key_only;
57 int value_only;
58 const struct strbuf *separator;
59 const struct strbuf *key_value_separator;
60 int (*filter)(const struct strbuf *, void *);
61 void *filter_data;
62 };
63
64 #define PROCESS_TRAILER_OPTIONS_INIT {0}
65
66 void parse_trailers_from_config(struct list_head *config_head);
67
68 void parse_trailers_from_command_line_args(struct list_head *arg_head,
69 struct list_head *new_trailer_head);
70
71 int validate_trailer_args(const struct strvec *cli_args);
72
73 void process_trailers_lists(struct list_head *head,
74 struct list_head *arg_head);
75
76 /*
77 * Given some input string "str", return a pointer to an opaque trailer_block
78 * structure. Also populate the trailer_objects list with parsed trailer
79 * objects. Internally this calls trailer_info_get() to get the opaque pointer,
80 * but does some extra work to populate the trailer_objects linked list.
81 *
82 * The opaque trailer_block pointer can be used to check the position of the
83 * trailer block as offsets relative to the beginning of "str" in
84 * trailer_block_start() and trailer_block_end().
85 * blank_line_before_trailer_block() returns 1 if there is a blank line just
86 * before the trailer block. All of these functions are useful for preserving
87 * the input before and after the trailer block, if we were to write out the
88 * original input (but with the trailer block itself modified); see
89 * builtin/interpret-trailers.c for an example.
90 *
91 * For iterating through the parsed trailer block (if you don't care about the
92 * position of the trailer block itself in the context of the larger string text
93 * from which it was parsed), please see trailer_iterator_init() which uses the
94 * trailer_block struct internally.
95 *
96 * Lastly, callers should call trailer_info_release() when they are done using
97 * the opaque pointer.
98 *
99 * NOTE: Callers should treat both trailer_block and trailer_objects as
100 * read-only items, because there is some overlap between the two (trailer_block
101 * has "char **trailers" string array, and trailer_objects will have the same
102 * data but as a linked list of trailer_item objects). This API does not perform
103 * any synchronization between the two. In the future we should be able to
104 * reduce the duplication and use just the linked list.
105 */
106 struct trailer_block *parse_trailers(const struct process_trailer_options *,
107 const char *str,
108 struct list_head *trailer_objects);
109
110 /*
111 * Return the offset of the start of the trailer block. That is, 0 is the start
112 * of the input ("str" in parse_trailers()) and some other positive number
113 * indicates how many bytes we have to skip over before we get to the beginning
114 * of the trailer block.
115 */
116 size_t trailer_block_start(struct trailer_block *);
117
118 /*
119 * Return the end of the trailer block, again relative to the start of the
120 * input.
121 */
122 size_t trailer_block_end(struct trailer_block *);
123
124 /*
125 * Return 1 if the trailer block had an extra newline (blank line) just before
126 * it.
127 */
128 int blank_line_before_trailer_block(struct trailer_block *);
129
130 /*
131 * Free trailer_block struct.
132 */
133 void trailer_block_release(struct trailer_block *);
134
135 void trailer_config_init(void);
136 void format_trailers(const struct process_trailer_options *,
137 struct list_head *trailers,
138 struct strbuf *out);
139 void free_trailers(struct list_head *);
140
141 /*
142 * Convenience function to format the trailers from the commit msg "msg" into
143 * the strbuf "out". Reuses format_trailers() internally.
144 */
145 void format_trailers_from_commit(const struct process_trailer_options *,
146 const char *msg,
147 struct strbuf *out);
148
149 /*
150 * An interface for iterating over the trailers found in a particular commit
151 * message. Use like:
152 *
153 * struct trailer_iterator iter;
154 * trailer_iterator_init(&iter, msg);
155 * while (trailer_iterator_advance(&iter))
156 * ... do something with iter.key and iter.val ...
157 * trailer_iterator_release(&iter);
158 */
159 struct trailer_iterator {
160 /*
161 * Raw line (e.g., "foo: bar baz") before being parsed as a trailer
162 * key/val pair as part of a trailer block (as the "key" and "val"
163 * fields below). If a line fails to parse as a trailer, then the "key"
164 * will be the entire line and "val" will be the empty string.
165 */
166 const char *raw;
167 struct strbuf key;
168 struct strbuf val;
169
170 /* private */
171 struct {
172 struct trailer_block *trailer_block;
173 size_t cur;
174 } internal;
175 };
176
177 /*
178 * Initialize "iter" in preparation for walking over the trailers in the commit
179 * message "msg". The "msg" pointer must remain valid until the iterator is
180 * released.
181 *
182 * After initializing, note that key/val will not yet point to any trailer.
183 * Call advance() to parse the first one (if any).
184 */
185 void trailer_iterator_init(struct trailer_iterator *iter, const char *msg);
186
187 /*
188 * Advance to the next trailer of the iterator. Returns 0 if there is no such
189 * trailer, and 1 otherwise. The key and value of the trailer can be
190 * fetched from the iter->key and iter->value fields (which are valid
191 * only until the next advance).
192 */
193 int trailer_iterator_advance(struct trailer_iterator *iter);
194
195 /*
196 * Release all resources associated with the trailer iteration.
197 */
198 void trailer_iterator_release(struct trailer_iterator *iter);
199
200 /*
201 * Append trailers specified in trailer_args to buf in-place.
202 *
203 * Each element of trailer_args should be in the same format as the value
204 * accepted by --trailer=<trailer> (i.e., without the --trailer= prefix).
205 */
206 int amend_strbuf_with_trailers(struct strbuf *buf,
207 const struct strvec *trailer_args);
208
209 /*
210 * Augment a file by appending trailers specified in trailer_args.
211 *
212 * Each element of trailer_args should be in the same format as the value
213 * accepted by --trailer=<trailer> (i.e., without the --trailer= prefix).
214 *
215 * Returns 0 on success or a non-zero error code on failure.
216 */
217 int amend_file_with_trailers(const char *path, const struct strvec *trailer_args);
218
219 /*
220 * Create a tempfile ""git-interpret-trailers-XXXXXX" in the same
221 * directory as file.
222 */
223 struct tempfile *trailer_create_in_place_tempfile(const char *file);
224
225 /*
226 * Rewrite the contents of input by processing its trailer block according to
227 * opts and (optionally) appending trailers from new_trailer_head.
228 *
229 * The rewritten message is appended to out (callers should strbuf_reset()
230 * first if needed).
231 */
232 void process_trailers(const struct process_trailer_options *opts,
233 struct list_head *new_trailer_head,
234 struct strbuf *input, struct strbuf *out);
235 #endif /* TRAILER_H */