trailer.h

   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 void 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  */
 104 struct 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  */
 114 size_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  */
 120 size_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  */
 126 int blank_line_before_trailer_block(struct trailer_block *);
 127
 128 /*
 129  * Free trailer_block struct.
 130  */
 131 void trailer_block_release(struct trailer_block *);
 132
 133 void trailer_config_init(void);
 134 void format_trailers(const struct process_trailer_options *,
 135                      struct list_head *trailers,
 136                      struct strbuf *out);
 137 void 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  */
 143 void 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  */
 157 struct 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  */
 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
 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
 205 #endif /* TRAILER_H */