freshlybakedca.ke
Git fork
1#ifndef TRAILER_H
2#define TRAILER_H
3
4#include "list.h"
5#include "strbuf.h"
6
7struct trailer_block;
8struct strvec;
9
10enum trailer_where {
11 WHERE_DEFAULT,
12 WHERE_END,
13 WHERE_AFTER,
14 WHERE_BEFORE,
15 WHERE_START
16};
17enum 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};
25enum trailer_if_missing {
26 MISSING_DEFAULT,
27 MISSING_ADD,
28 MISSING_DO_NOTHING
29};
30
31int trailer_set_where(enum trailer_where *item, const char *value);
32int trailer_set_if_exists(enum trailer_if_exists *item, const char *value);
33int 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 */
39struct 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
49struct 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
66void parse_trailers_from_config(struct list_head *config_head);
67
68void parse_trailers_from_command_line_args(struct list_head *arg_head,
69 struct list_head *new_trailer_head);
70
71void process_trailers_lists(struct list_head *head,
72 struct list_head *arg_head);
73
74/*
75 * Given some input string "str", return a pointer to an opaque trailer_block
76 * structure. Also populate the trailer_objects list with parsed trailer
77 * objects. Internally this calls trailer_info_get() to get the opaque pointer,
78 * but does some extra work to populate the trailer_objects linked list.
79 *
80 * The opaque trailer_block pointer can be used to check the position of the
81 * trailer block as offsets relative to the beginning of "str" in
82 * trailer_block_start() and trailer_block_end().
83 * blank_line_before_trailer_block() returns 1 if there is a blank line just
84 * before the trailer block. All of these functions are useful for preserving
85 * the input before and after the trailer block, if we were to write out the
86 * original input (but with the trailer block itself modified); see
87 * builtin/interpret-trailers.c for an example.
88 *
89 * For iterating through the parsed trailer block (if you don't care about the
90 * position of the trailer block itself in the context of the larger string text
91 * from which it was parsed), please see trailer_iterator_init() which uses the
92 * trailer_block struct internally.
93 *
94 * Lastly, callers should call trailer_info_release() when they are done using
95 * the opaque pointer.
96 *
97 * NOTE: Callers should treat both trailer_block and trailer_objects as
98 * read-only items, because there is some overlap between the two (trailer_block
99 * has "char **trailers" string array, and trailer_objects will have the same
100 * data but as a linked list of trailer_item objects). This API does not perform
101 * any synchronization between the two. In the future we should be able to
102 * reduce the duplication and use just the linked list.
103 */
104struct trailer_block *parse_trailers(const struct process_trailer_options *,
105 const char *str,
106 struct list_head *trailer_objects);
107
108/*
109 * Return the offset of the start of the trailer block. That is, 0 is the start
110 * of the input ("str" in parse_trailers()) and some other positive number
111 * indicates how many bytes we have to skip over before we get to the beginning
112 * of the trailer block.
113 */
114size_t trailer_block_start(struct trailer_block *);
115
116/*
117 * Return the end of the trailer block, again relative to the start of the
118 * input.
119 */
120size_t trailer_block_end(struct trailer_block *);
121
122/*
123 * Return 1 if the trailer block had an extra newline (blank line) just before
124 * it.
125 */
126int blank_line_before_trailer_block(struct trailer_block *);
127
128/*
129 * Free trailer_block struct.
130 */
131void trailer_block_release(struct trailer_block *);
132
133void trailer_config_init(void);
134void format_trailers(const struct process_trailer_options *,
135 struct list_head *trailers,
136 struct strbuf *out);
137void free_trailers(struct list_head *);
138
139/*
140 * Convenience function to format the trailers from the commit msg "msg" into
141 * the strbuf "out". Reuses format_trailers() internally.
142 */
143void format_trailers_from_commit(const struct process_trailer_options *,
144 const char *msg,
145 struct strbuf *out);
146
147/*
148 * An interface for iterating over the trailers found in a particular commit
149 * message. Use like:
150 *
151 * struct trailer_iterator iter;
152 * trailer_iterator_init(&iter, msg);
153 * while (trailer_iterator_advance(&iter))
154 * ... do something with iter.key and iter.val ...
155 * trailer_iterator_release(&iter);
156 */
157struct trailer_iterator {
158 /*
159 * Raw line (e.g., "foo: bar baz") before being parsed as a trailer
160 * key/val pair as part of a trailer block (as the "key" and "val"
161 * fields below). If a line fails to parse as a trailer, then the "key"
162 * will be the entire line and "val" will be the empty string.
163 */
164 const char *raw;
165 struct strbuf key;
166 struct strbuf val;
167
168 /* private */
169 struct {
170 struct trailer_block *trailer_block;
171 size_t cur;
172 } internal;
173};
174
175/*
176 * Initialize "iter" in preparation for walking over the trailers in the commit
177 * message "msg". The "msg" pointer must remain valid until the iterator is
178 * released.
179 *
180 * After initializing, note that key/val will not yet point to any trailer.
181 * Call advance() to parse the first one (if any).
182 */
183void trailer_iterator_init(struct trailer_iterator *iter, const char *msg);
184
185/*
186 * Advance to the next trailer of the iterator. Returns 0 if there is no such
187 * trailer, and 1 otherwise. The key and value of the trailer can be
188 * fetched from the iter->key and iter->value fields (which are valid
189 * only until the next advance).
190 */
191int trailer_iterator_advance(struct trailer_iterator *iter);
192
193/*
194 * Release all resources associated with the trailer iteration.
195 */
196void trailer_iterator_release(struct trailer_iterator *iter);
197
198/*
199 * Augment a file to add trailers to it by running git-interpret-trailers.
200 * This calls run_command() and its return value is the same (i.e. 0 for
201 * success, various non-zero for other errors). See run-command.h.
202 */
203int amend_file_with_trailers(const char *path, const struct strvec *trailer_args);
204
205#endif /* TRAILER_H */