trailer.h

   1 #ifndef TRAILER_H
   2 #define TRAILER_H
   3
   4 #include "list.h"
   5 #include "strbuf.h"
   6
   7 struct trailer_info;
   8
   9 enum trailer_where {
  10         WHERE_DEFAULT,
  11         WHERE_END,
  12         WHERE_AFTER,
  13         WHERE_BEFORE,
  14         WHERE_START
  15 };
  16 enum trailer_if_exists {
  17         EXISTS_DEFAULT,
  18         EXISTS_ADD_IF_DIFFERENT_NEIGHBOR,
  19         EXISTS_ADD_IF_DIFFERENT,
  20         EXISTS_ADD,
  21         EXISTS_REPLACE,
  22         EXISTS_DO_NOTHING
  23 };
  24 enum trailer_if_missing {
  25         MISSING_DEFAULT,
  26         MISSING_ADD,
  27         MISSING_DO_NOTHING
  28 };
  29
  30 int trailer_set_where(enum trailer_where *item, const char *value);
  31 int trailer_set_if_exists(enum trailer_if_exists *item, const char *value);
  32 int trailer_set_if_missing(enum trailer_if_missing *item, const char *value);
  33
  34 /*
  35  * A list that represents newly-added trailers, such as those provided
  36  * with the --trailer command line option of git-interpret-trailers.
  37  */
  38 struct new_trailer_item {
  39         struct list_head list;
  40
  41         const char *text;
  42
  43         enum trailer_where where;
  44         enum trailer_if_exists if_exists;
  45         enum trailer_if_missing if_missing;
  46 };
  47
  48 struct process_trailer_options {
  49         int in_place;
  50         int trim_empty;
  51         int only_trailers;
  52         int only_input;
  53         int unfold;
  54         int no_divider;
  55         int key_only;
  56         int value_only;
  57         const struct strbuf *separator;
  58         const struct strbuf *key_value_separator;
  59         int (*filter)(const struct strbuf *, void *);
  60         void *filter_data;
  61 };
  62
  63 #define PROCESS_TRAILER_OPTIONS_INIT {0}
  64
  65 void parse_trailers_from_config(struct list_head *config_head);
  66
  67 void parse_trailers_from_command_line_args(struct list_head *arg_head,
  68                                            struct list_head *new_trailer_head);
  69
  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,
 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);
 133 void format_trailers(const struct process_trailer_options *,
 134                      struct list_head *trailers,
 135                      struct strbuf *out);
 136 void free_trailers(struct list_head *);
 137
 138 /*
 139  * Convenience function to format the trailers from the commit msg "msg" into
 140  * the strbuf "out". Reuses format_trailers() internally.
 141  */
 142 void format_trailers_from_commit(const struct process_trailer_options *,
 143                                  const char *msg,
 144                                  struct strbuf *out);
 145
 146 /*
 147  * An interface for iterating over the trailers found in a particular commit
 148  * message. Use like:
 149  *
 150  *   struct trailer_iterator iter;
 151  *   trailer_iterator_init(&iter, msg);
 152  *   while (trailer_iterator_advance(&iter))
 153  *      ... do something with iter.key and iter.val ...
 154  *   trailer_iterator_release(&iter);
 155  */
 156 struct trailer_iterator {
 157         /*
 158          * Raw line (e.g., "foo: bar baz") before being parsed as a trailer
 159          * key/val pair as part of a trailer block (as the "key" and "val"
 160          * fields below). If a line fails to parse as a trailer, then the "key"
 161          * will be the entire line and "val" will be the empty string.
 162          */
 163         const char *raw;
 164         struct strbuf key;
 165         struct strbuf val;
 166
 167         /* private */
 168         struct {
 169                 struct trailer_info *info;
 170                 size_t cur;
 171         } internal;
 172 };
 173
 174 /*
 175  * Initialize "iter" in preparation for walking over the trailers in the commit
 176  * message "msg". The "msg" pointer must remain valid until the iterator is
 177  * released.
 178  *
 179  * After initializing, note that key/val will not yet point to any trailer.
 180  * Call advance() to parse the first one (if any).
 181  */
 182 void trailer_iterator_init(struct trailer_iterator *iter, const char *msg);
 183
 184 /*
 185  * Advance to the next trailer of the iterator. Returns 0 if there is no such
 186  * trailer, and 1 otherwise. The key and value of the trailer can be
 187  * fetched from the iter->key and iter->value fields (which are valid
 188  * only until the next advance).
 189  */
 190 int trailer_iterator_advance(struct trailer_iterator *iter);
 191
 192 /*
 193  * Release all resources associated with the trailer iteration.
 194  */
 195 void trailer_iterator_release(struct trailer_iterator *iter);
 196
 197 #endif /* TRAILER_H */