fix typos
[notmuch] / tag-util.h
1 #ifndef _TAG_UTIL_H
2 #define _TAG_UTIL_H
3
4 #include "notmuch-client.h"
5
6 typedef struct _tag_operation_t tag_operation_t;
7 typedef struct _tag_op_list_t tag_op_list_t;
8
9 /* Use powers of 2 */
10 typedef enum {
11     TAG_FLAG_NONE = 0,
12
13     /* Operations are synced to maildir, if possible.
14      */
15     TAG_FLAG_MAILDIR_SYNC = (1 << 0),
16
17     /* Remove all tags from message before applying list.
18      */
19     TAG_FLAG_REMOVE_ALL = (1 << 1),
20
21     /* Don't try to avoid database operations. Useful when we
22      * know that message passed needs these operations.
23      */
24     TAG_FLAG_PRE_OPTIMIZED = (1 << 2),
25
26     /* Accept strange tags that might be user error;
27      * intended for use by notmuch-restore.
28      */
29     TAG_FLAG_BE_GENEROUS = (1 << 3)
30
31 } tag_op_flag_t;
32
33 /* These should obey the convention that fatal errors are negative,
34  * skipped lines are positive.
35  */
36 typedef enum {
37     TAG_PARSE_OUT_OF_MEMORY = -1,
38
39     /* Line parsed successfully. */
40     TAG_PARSE_SUCCESS = 0,
41
42     /* Line has a syntax error */
43     TAG_PARSE_INVALID = 1,
44
45     /* Line was blank or a comment */
46     TAG_PARSE_SKIPPED = 2
47
48 } tag_parse_status_t;
49
50 /* Parse a string of the following format:
51  *
52  * +<tag>|-<tag> [...] [--] <search-terms>
53  *
54  * Each line is interpreted similarly to "notmuch tag" command line
55  * arguments. The delimiter is one or more spaces ' '. Any characters
56  * in <tag> and <search-terms> MAY be hex encoded with %NN where NN is
57  * the hexadecimal value of the character. Any ' ' and '%' characters
58  * in <tag> and <search-terms> MUST be hex encoded (using %20 and %25,
59  * respectively). Any characters that are not part of <tag> or
60  * <search-terms> MUST NOT be hex encoded.
61  *
62  * Leading and trailing space ' ' is ignored. Empty lines and lines
63  * beginning with '#' are ignored.
64  *
65  *
66  * Output Parameters:
67  *      ops     contains a list of tag operations
68  *      query_str the search terms.
69  */
70 tag_parse_status_t
71 parse_tag_line (void *ctx, char *line,
72                 tag_op_flag_t flags,
73                 char **query_str, tag_op_list_t *ops);
74
75
76
77 /* Parse a command line of the following format:
78  *
79  * +<tag>|-<tag> [...] [--] <search-terms>
80  *
81  * Output Parameters:
82  *      ops     contains a list of tag operations
83  *      query_str the search terms.
84  *
85  * The ops argument is not cleared.
86  */
87
88 tag_parse_status_t
89 parse_tag_command_line (void *ctx, int argc, char **argv,
90                         char **query_str, tag_op_list_t *ops);
91
92 /*
93  * Test tags for some forbidden cases.
94  *
95  * Relax the checks if 'remove' is true to allow removal of previously
96  * added forbidden tags.
97  *
98  * return: NULL if OK,
99  *         explanatory message otherwise.
100  */
101 const char *
102 illegal_tag (const char *tag, bool remove);
103
104 /*
105  * Create an empty list of tag operations
106  *
107  * ctx is passed to talloc
108  */
109
110 tag_op_list_t *
111 tag_op_list_create (void *ctx);
112
113 /*
114  * Add a tag operation (delete iff remove == true) to a list.
115  * The list is expanded as necessary.
116  */
117
118 int
119 tag_op_list_append (tag_op_list_t *list,
120                     const char *tag,
121                     bool remove);
122
123 /*
124  * Apply a list of tag operations, in order, to a given message.
125  *
126  * Flags can be bitwise ORed; see enum above for possibilies.
127  */
128
129 notmuch_status_t
130 tag_op_list_apply (notmuch_message_t *message,
131                    tag_op_list_t *tag_ops,
132                    tag_op_flag_t flags);
133
134 /*
135  * Return the number of operations in a list
136  */
137
138 size_t
139 tag_op_list_size (const tag_op_list_t *list);
140
141 /*
142  * Reset a list to contain no operations
143  */
144
145 void
146 tag_op_list_reset (tag_op_list_t *list);
147
148
149 /*
150  *   return the i'th tag in the list
151  */
152
153 const char *
154 tag_op_list_tag (const tag_op_list_t *list, size_t i);
155
156 /*
157  *   Is the i'th tag operation a remove?
158  */
159
160 bool
161 tag_op_list_isremove (const tag_op_list_t *list, size_t i);
162
163 #endif