l10n: bg.po: Updated Bulgarian translation (4839t)
[git] / attr.h
1 #ifndef ATTR_H
2 #define ATTR_H
3
4 /**
5  * gitattributes mechanism gives a uniform way to associate various attributes
6  * to set of paths.
7  *
8  *
9  * Querying Specific Attributes
10  * ----------------------------
11  *
12  * - Prepare `struct attr_check` using attr_check_initl() function, enumerating
13  *   the names of attributes whose values you are interested in, terminated with
14  *   a NULL pointer.  Alternatively, an empty `struct attr_check` can be
15  *   prepared by calling `attr_check_alloc()` function and then attributes you
16  *   want to ask about can be added to it with `attr_check_append()` function.
17  *
18  * - Call `git_check_attr()` to check the attributes for the path.
19  *
20  * - Inspect `attr_check` structure to see how each of the attribute in the
21  *   array is defined for the path.
22  *
23  *
24  * Example
25  * -------
26  *
27  * To see how attributes "crlf" and "ident" are set for different paths.
28  *
29  * - Prepare a `struct attr_check` with two elements (because we are checking
30  *   two attributes):
31  *
32  * ------------
33  * static struct attr_check *check;
34  * static void setup_check(void)
35  * {
36  *      if (check)
37  *              return; // already done
38  * check = attr_check_initl("crlf", "ident", NULL);
39  * }
40  * ------------
41  *
42  * - Call `git_check_attr()` with the prepared `struct attr_check`:
43  *
44  * ------------
45  * const char *path;
46  *
47  * setup_check();
48  * git_check_attr(path, check);
49  * ------------
50  *
51  * - Act on `.value` member of the result, left in `check->items[]`:
52  *
53  * ------------
54  * const char *value = check->items[0].value;
55  *
56  * if (ATTR_TRUE(value)) {
57  * The attribute is Set, by listing only the name of the
58  * attribute in the gitattributes file for the path.
59  * } else if (ATTR_FALSE(value)) {
60  * The attribute is Unset, by listing the name of the
61  *         attribute prefixed with a dash - for the path.
62  * } else if (ATTR_UNSET(value)) {
63  * The attribute is neither set nor unset for the path.
64  * } else if (!strcmp(value, "input")) {
65  * If none of ATTR_TRUE(), ATTR_FALSE(), or ATTR_UNSET() is
66  *         true, the value is a string set in the gitattributes
67  * file for the path by saying "attr=value".
68  * } else if (... other check using value as string ...) {
69  * ...
70  * }
71  * ------------
72  *
73  * To see how attributes in argv[] are set for different paths, only
74  * the first step in the above would be different.
75  *
76  * ------------
77  * static struct attr_check *check;
78  * static void setup_check(const char **argv)
79  * {
80  *     check = attr_check_alloc();
81  *     while (*argv) {
82  *         struct git_attr *attr = git_attr(*argv);
83  *         attr_check_append(check, attr);
84  *         argv++;
85  *     }
86  * }
87  * ------------
88  *
89  *
90  * Querying All Attributes
91  * -----------------------
92  *
93  * To get the values of all attributes associated with a file:
94  *
95  * - Prepare an empty `attr_check` structure by calling `attr_check_alloc()`.
96  *
97  * - Call `git_all_attrs()`, which populates the `attr_check` with the
98  * attributes attached to the path.
99  *
100  * - Iterate over the `attr_check.items[]` array to examine the attribute
101  * names and values. The name of the attribute described by an
102  * `attr_check.items[]` object can be retrieved via
103  * `git_attr_name(check->items[i].attr)`. (Please note that no items will be
104  * returned for unset attributes, so `ATTR_UNSET()` will return false for all
105  * returned `attr_check.items[]` objects.)
106  *
107  * - Free the `attr_check` struct by calling `attr_check_free()`.
108  */
109
110 struct index_state;
111
112 /**
113  * An attribute is an opaque object that is identified by its name. Pass the
114  * name to `git_attr()` function to obtain the object of this type.
115  * The internal representation of this structure is of no interest to the
116  * calling programs. The name of the attribute can be retrieved by calling
117  * `git_attr_name()`.
118  */
119 struct git_attr;
120
121 /* opaque structures used internally for attribute collection */
122 struct all_attrs_item;
123 struct attr_stack;
124 struct index_state;
125
126 /*
127  * Given a string, return the gitattribute object that
128  * corresponds to it.
129  */
130 const struct git_attr *git_attr(const char *);
131
132 /* Internal use */
133 extern const char git_attr__true[];
134 extern const char git_attr__false[];
135
136 /**
137  * Attribute Values
138  * ----------------
139  *
140  * An attribute for a path can be in one of four states: Set, Unset, Unspecified
141  * or set to a string, and `.value` member of `struct attr_check_item` records
142  * it. The three macros check these, if none of them returns true, `.value`
143  * member points at a string value of the attribute for the path.
144  */
145
146 /* Returns true if the attribute is Set for the path. */
147 #define ATTR_TRUE(v) ((v) == git_attr__true)
148
149 /* Returns true if the attribute is Unset for the path. */
150 #define ATTR_FALSE(v) ((v) == git_attr__false)
151
152 /* Returns true if the attribute is Unspecified for the path. */
153 #define ATTR_UNSET(v) ((v) == NULL)
154
155 /* This structure represents one attribute and its value. */
156 struct attr_check_item {
157         const struct git_attr *attr;
158         const char *value;
159 };
160
161 /**
162  * This structure represents a collection of `attr_check_item`. It is passed to
163  * `git_check_attr()` function, specifying the attributes to check, and
164  * receives their values.
165  */
166 struct attr_check {
167         int nr;
168         int alloc;
169         struct attr_check_item *items;
170         int all_attrs_nr;
171         struct all_attrs_item *all_attrs;
172         struct attr_stack *stack;
173 };
174
175 struct attr_check *attr_check_alloc(void);
176 struct attr_check *attr_check_initl(const char *, ...);
177 struct attr_check *attr_check_dup(const struct attr_check *check);
178
179 struct attr_check_item *attr_check_append(struct attr_check *check,
180                                           const struct git_attr *attr);
181
182 void attr_check_reset(struct attr_check *check);
183 void attr_check_clear(struct attr_check *check);
184 void attr_check_free(struct attr_check *check);
185
186 /*
187  * Return the name of the attribute represented by the argument.  The
188  * return value is a pointer to a null-delimited string that is part
189  * of the internal data structure; it should not be modified or freed.
190  */
191 const char *git_attr_name(const struct git_attr *);
192
193 void git_check_attr(const struct index_state *istate,
194                     const char *path, struct attr_check *check);
195
196 /*
197  * Retrieve all attributes that apply to the specified path.
198  * check holds the attributes and their values.
199  */
200 void git_all_attrs(const struct index_state *istate,
201                    const char *path, struct attr_check *check);
202
203 enum git_attr_direction {
204         GIT_ATTR_CHECKIN,
205         GIT_ATTR_CHECKOUT,
206         GIT_ATTR_INDEX
207 };
208 void git_attr_set_direction(enum git_attr_direction new_direction);
209
210 void attr_start(void);
211
212 #endif /* ATTR_H */