]>
Commit | Line | Data |
---|---|---|
b1d78d77 CC |
1 | #ifndef TRAILER_H |
2 | #define TRAILER_H | |
3 | ||
51166b87 | 4 | #include "list.h" |
f0939a0e | 5 | #include "strbuf.h" |
ef3ca954 | 6 | |
c1e4b2b1 | 7 | struct trailer_info; |
4a861878 JP |
8 | struct strvec; |
9 | ||
52fc319d | 10 | enum trailer_where { |
0ea5292e | 11 | WHERE_DEFAULT, |
52fc319d PB |
12 | WHERE_END, |
13 | WHERE_AFTER, | |
14 | WHERE_BEFORE, | |
15 | WHERE_START | |
16 | }; | |
17 | enum trailer_if_exists { | |
0ea5292e | 18 | EXISTS_DEFAULT, |
52fc319d PB |
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 { | |
0ea5292e | 26 | MISSING_DEFAULT, |
52fc319d PB |
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 | ||
51166b87 PB |
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; | |
0ea5292e PB |
43 | |
44 | enum trailer_where where; | |
45 | enum trailer_if_exists if_exists; | |
46 | enum trailer_if_missing if_missing; | |
51166b87 PB |
47 | }; |
48 | ||
8abc8980 JK |
49 | struct process_trailer_options { |
50 | int in_place; | |
51 | int trim_empty; | |
56c493ed | 52 | int only_trailers; |
fdbdb64f | 53 | int only_input; |
00002396 | 54 | int unfold; |
1688c9a4 | 55 | int no_divider; |
9d87d5ae | 56 | int key_only; |
d9b936db | 57 | int value_only; |
0b691d86 | 58 | const struct strbuf *separator; |
058761f1 | 59 | const struct strbuf *key_value_separator; |
250bea0c AW |
60 | int (*filter)(const struct strbuf *, void *); |
61 | void *filter_data; | |
8abc8980 JK |
62 | }; |
63 | ||
64 | #define PROCESS_TRAILER_OPTIONS_INIT {0} | |
65 | ||
ae0ec2e0 LA |
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 | void process_trailers_lists(struct list_head *head, | |
72 | struct list_head *arg_head); | |
73 | ||
5f800603 LA |
74 | /* |
75 | * Given some input string "str", return a pointer to an opaque trailer_info | |
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_info 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_info 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_info and trailer_objects as | |
98 | * read-only items, because there is some overlap between the two (trailer_info | |
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 | */ | |
24a25c63 LA |
104 | struct trailer_info *parse_trailers(const struct process_trailer_options *, |
105 | const char *str, | |
5f800603 | 106 | struct list_head *trailer_objects); |
24a25c63 | 107 | |
5f800603 LA |
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 | */ | |
655eb65d | 114 | size_t trailer_block_start(struct trailer_info *); |
5f800603 LA |
115 | |
116 | /* | |
117 | * Return the end of the trailer block, again relative to the start of the | |
118 | * input. | |
119 | */ | |
655eb65d | 120 | size_t trailer_block_end(struct trailer_info *); |
b1d78d77 | 121 | |
5f800603 LA |
122 | /* |
123 | * Return 1 if the trailer block had an extra newline (blank line) just before | |
124 | * it. | |
125 | */ | |
655eb65d | 126 | int blank_line_before_trailer_block(struct trailer_info *); |
e8c352c3 | 127 | |
5f800603 LA |
128 | /* |
129 | * Free trailer_info struct. | |
130 | */ | |
e8c352c3 JT |
131 | void trailer_info_release(struct trailer_info *info); |
132 | ||
ae0ec2e0 | 133 | void trailer_config_init(void); |
3452d173 | 134 | void format_trailers(const struct process_trailer_options *, |
bf35e0a0 LA |
135 | struct list_head *trailers, |
136 | struct strbuf *out); | |
ae0ec2e0 LA |
137 | void free_trailers(struct list_head *); |
138 | ||
a388b10f | 139 | /* |
3452d173 LA |
140 | * Convenience function to format the trailers from the commit msg "msg" into |
141 | * the strbuf "out". Reuses format_trailers() internally. | |
a388b10f | 142 | */ |
3452d173 | 143 | void format_trailers_from_commit(const struct process_trailer_options *, |
0383dc56 LA |
144 | const char *msg, |
145 | struct strbuf *out); | |
a388b10f | 146 | |
f0939a0e JK |
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 | */ | |
157 | struct trailer_iterator { | |
3be65e6e LA |
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; | |
f0939a0e JK |
165 | struct strbuf key; |
166 | struct strbuf val; | |
167 | ||
168 | /* private */ | |
13211ae2 | 169 | struct { |
24a25c63 | 170 | struct trailer_info *info; |
13211ae2 LA |
171 | size_t cur; |
172 | } internal; | |
f0939a0e JK |
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 | */ | |
183 | void 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 | */ | |
191 | int trailer_iterator_advance(struct trailer_iterator *iter); | |
192 | ||
193 | /* | |
194 | * Release all resources associated with the trailer iteration. | |
195 | */ | |
196 | void trailer_iterator_release(struct trailer_iterator *iter); | |
197 | ||
4a861878 JP |
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 | */ | |
203 | int amend_file_with_trailers(const char *path, const struct strvec *trailer_args); | |
204 | ||
b1d78d77 | 205 | #endif /* TRAILER_H */ |