trailer: document parse_trailers() usage
Explain how to use parse_trailers(), because earlier we made the trailer_info struct opaque. That is, because clients can no longer peek inside it, we should give them guidance about how the (pointer to the) opaque struct can still be useful to them. Rename "head" struct to "trailer_objects" to make the wording of the new comments a bit easier to read (because "head" itself doesn't really have any domain-specific meaning here). Signed-off-by: Linus Arver <linus@ucla.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Linus Arver committed
May 2, 2024 at 04:54 UTC
5f800603a9fa0cbcca83b3eb56dff893582d0ca7
2 files changed
+54
-5
trailer.c
+4
-4
@@ -1026,12 +1026,12 @@ static struct trailer_info *trailer_info_get(const struct process_trailer_option
1026
}
1027
1028
/*
1029
- * Parse trailers in "str", populating the trailer info and "head"
1029
+ * Parse trailers in "str", populating the trailer info and "trailer_objects"
1030
* linked list structure.
1031
*/
1032
struct trailer_info *parse_trailers(const struct process_trailer_options *opts,
1033
const char *str,
1034
- struct list_head *head)
1034
+ struct list_head *trailer_objects)
1035
{
1036
struct trailer_info *info;
1037
struct strbuf tok = STRBUF_INIT;
@@ -1051,13 +1051,13 @@ struct trailer_info *parse_trailers(const struct process_trailer_options *opts,
1051
separator_pos);
1052
if (opts->unfold)
1053
unfold_value(&val);
1054
- add_trailer_item(head,
1054
+ add_trailer_item(trailer_objects,
1055
strbuf_detach(&tok, NULL),
1056
strbuf_detach(&val, NULL));
1057
} else if (!opts->only_trailers) {
1058
strbuf_addstr(&val, trailer);
1059
strbuf_strip_suffix(&val, "\n");
1060
- add_trailer_item(head,
1060
+ add_trailer_item(trailer_objects,
1061
NULL,
1062
strbuf_detach(&val, NULL));
1063
}
trailer.h
+50
-1
@@ -70,14 +70,63 @@ void parse_trailers_from_command_line_args(struct list_head *arg_head,
70
void process_trailers_lists(struct list_head *head,
71
struct list_head *arg_head);
72
73
+/*
74
+ * Given some input string "str", return a pointer to an opaque trailer_info
75
+ * structure. Also populate the trailer_objects list with parsed trailer
76
+ * objects. Internally this calls trailer_info_get() to get the opaque pointer,
77
+ * but does some extra work to populate the trailer_objects linked list.
78
+ *
79
+ * The opaque trailer_info pointer can be used to check the position of the
80
+ * trailer block as offsets relative to the beginning of "str" in
81
+ * trailer_block_start() and trailer_block_end().
82
+ * blank_line_before_trailer_block() returns 1 if there is a blank line just
83
+ * before the trailer block. All of these functions are useful for preserving
84
+ * the input before and after the trailer block, if we were to write out the
85
+ * original input (but with the trailer block itself modified); see
86
+ * builtin/interpret-trailers.c for an example.
87
+ *
88
+ * For iterating through the parsed trailer block (if you don't care about the
89
+ * position of the trailer block itself in the context of the larger string text
90
+ * from which it was parsed), please see trailer_iterator_init() which uses the
91
+ * trailer_info struct internally.
92
+ *
93
+ * Lastly, callers should call trailer_info_release() when they are done using
94
+ * the opaque pointer.
95
+ *
96
+ * NOTE: Callers should treat both trailer_info and trailer_objects as
97
+ * read-only items, because there is some overlap between the two (trailer_info
98
+ * has "char **trailers" string array, and trailer_objects will have the same
99
+ * data but as a linked list of trailer_item objects). This API does not perform
100
+ * any synchronization between the two. In the future we should be able to
101
+ * reduce the duplication and use just the linked list.
102
+ */
103
struct trailer_info *parse_trailers(const struct process_trailer_options *,
104
const char *str,
75
- struct list_head *head);
105
+ struct list_head *trailer_objects);
106
107
+/*
108
+ * Return the offset of the start of the trailer block. That is, 0 is the start
109
+ * of the input ("str" in parse_trailers()) and some other positive number
110
+ * indicates how many bytes we have to skip over before we get to the beginning
111
+ * of the trailer block.
112
+ */
113
size_t trailer_block_start(struct trailer_info *);
114
+
115
+/*
116
+ * Return the end of the trailer block, again relative to the start of the
117
+ * input.
118
+ */
119
size_t trailer_block_end(struct trailer_info *);
120
+
121
+/*
122
+ * Return 1 if the trailer block had an extra newline (blank line) just before
123
+ * it.
124
+ */
125
int blank_line_before_trailer_block(struct trailer_info *);
126
127
+/*
128
+ * Free trailer_info struct.
129
+ */
130
void trailer_info_release(struct trailer_info *info);
131
132
void trailer_config_init(void);