trailer.h

   1 #ifndef TRAILER_H
   2 #define TRAILER_H
   3
   4 #include "list.h"
   5 #include "strbuf.h"
   6
   7 struct strvec;
   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 struct trailer_info {
  35         /*
  36          * True if there is a blank line before the location pointed to by
  37          * trailer_block_start.
  38          */
  39         int blank_line_before_trailer;
  40
  41         /*
  42          * Offsets to the trailer block start and end positions in the input
  43          * string. If no trailer block is found, these are both set to the
  44          * "true" end of the input (find_end_of_log_message()).
  45          */
  46         size_t trailer_block_start, trailer_block_end;
  47
  48         /*
  49          * Array of trailers found.
  50          */
  51         char **trailers;
  52         size_t trailer_nr;
  53 };
  54
  55 /*
  56  * A list that represents newly-added trailers, such as those provided
  57  * with the --trailer command line option of git-interpret-trailers.
  58  */
  59 struct new_trailer_item {
  60         struct list_head list;
  61
  62         const char *text;
  63
  64         enum trailer_where where;
  65         enum trailer_if_exists if_exists;
  66         enum trailer_if_missing if_missing;
  67 };
  68
  69 struct process_trailer_options {
  70         int in_place;
  71         int trim_empty;
  72         int only_trailers;
  73         int only_input;
  74         int unfold;
  75         int no_divider;
  76         int key_only;
  77         int value_only;
  78         const struct strbuf *separator;
  79         const struct strbuf *key_value_separator;
  80         int (*filter)(const struct strbuf *, void *);
  81         void *filter_data;
  82 };
  83
  84 #define PROCESS_TRAILER_OPTIONS_INIT {0}
  85
  86 void parse_trailers_from_config(struct list_head *config_head);
  87
  88 void parse_trailers_from_command_line_args(struct list_head *arg_head,
  89                                            struct list_head *new_trailer_head);
  90
  91 void process_trailers_lists(struct list_head *head,
  92                             struct list_head *arg_head);
  93
  94 void parse_trailers(const struct process_trailer_options *,
  95                     struct trailer_info *,
  96                     const char *str,
  97                     struct list_head *head);
  98
  99 void trailer_info_get(const struct process_trailer_options *,
 100                       const char *str,
 101                       struct trailer_info *);
 102
 103 void trailer_info_release(struct trailer_info *info);
 104
 105 void trailer_config_init(void);
 106 void format_trailers(const struct process_trailer_options *,
 107                      struct list_head *trailers,
 108                      struct strbuf *out);
 109 void free_trailers(struct list_head *);
 110
 111 /*
 112  * Convenience function to format the trailers from the commit msg "msg" into
 113  * the strbuf "out". Reuses format_trailers() internally.
 114  */
 115 void format_trailers_from_commit(const struct process_trailer_options *,
 116                                  const char *msg,
 117                                  struct strbuf *out);
 118
 119 /*
 120  * An interface for iterating over the trailers found in a particular commit
 121  * message. Use like:
 122  *
 123  *   struct trailer_iterator iter;
 124  *   trailer_iterator_init(&iter, msg);
 125  *   while (trailer_iterator_advance(&iter))
 126  *      ... do something with iter.key and iter.val ...
 127  *   trailer_iterator_release(&iter);
 128  */
 129 struct trailer_iterator {
 130         struct strbuf key;
 131         struct strbuf val;
 132
 133         /* private */
 134         struct {
 135                 struct trailer_info info;
 136                 size_t cur;
 137         } internal;
 138 };
 139
 140 /*
 141  * Initialize "iter" in preparation for walking over the trailers in the commit
 142  * message "msg". The "msg" pointer must remain valid until the iterator is
 143  * released.
 144  *
 145  * After initializing, note that key/val will not yet point to any trailer.
 146  * Call advance() to parse the first one (if any).
 147  */
 148 void trailer_iterator_init(struct trailer_iterator *iter, const char *msg);
 149
 150 /*
 151  * Advance to the next trailer of the iterator. Returns 0 if there is no such
 152  * trailer, and 1 otherwise. The key and value of the trailer can be
 153  * fetched from the iter->key and iter->value fields (which are valid
 154  * only until the next advance).
 155  */
 156 int trailer_iterator_advance(struct trailer_iterator *iter);
 157
 158 /*
 159  * Release all resources associated with the trailer iteration.
 160  */
 161 void trailer_iterator_release(struct trailer_iterator *iter);
 162
 163 /*
 164  * Augment a file to add trailers to it by running git-interpret-trailers.
 165  * This calls run_command() and its return value is the same (i.e. 0 for
 166  * success, various non-zero for other errors). See run-command.h.
 167  */
 168 int amend_file_with_trailers(const char *path, const struct strvec *trailer_args);
 169
 170 #endif /* TRAILER_H */