attr: retire git_check_attrs() API
Since nobody uses the old API, make it file-scope static, and update the documentation to describe the new API. Signed-off-by: Junio C Hamano <gitster@pobox.com> Signed-off-by: Stefan Beller <sbeller@google.com> Signed-off-by: Brandon Williams <bmwill@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Junio C Hamano committed
Jan 27, 2017 at 18:01 UTC
1295c2152457c2267d605d353332ae4b3e5e5d5c
3 files changed
+58
-32
Documentation/technical/api-gitattributes.txt
+56
-30
@@ -16,10 +16,15 @@ Data Structure
16
of no interest to the calling programs. The name of the
17
attribute can be retrieved by calling `git_attr_name()`.
18
19
-`struct git_attr_check`::
19
+`struct attr_check_item`::
20
21
- This structure represents a set of attributes to check in a call
22
- to `git_check_attr()` function, and receives the results.
21
+ This structure represents one attribute and its value.
22
+
23
+`struct attr_check`::
24
+
25
+ This structure represents a collection of `attr_check_item`.
26
+ It is passed to `git_check_attr()` function, specifying the
27
+ attributes to check, and receives their values.
28
29
30
Attribute Values
@@ -27,7 +32,7 @@ Attribute Values
32
33
An attribute for a path can be in one of four states: Set, Unset,
34
Unspecified or set to a string, and `.value` member of `struct
30
-git_attr_check` records it. There are three macros to check these:
35
+attr_check_item` records it. There are three macros to check these:
36
37
`ATTR_TRUE()`::
38
@@ -48,49 +53,51 @@ value of the attribute for the path.
53
Querying Specific Attributes
54
----------------------------
55
51
-* Prepare an array of `struct git_attr_check` to define the list of
52
- attributes you would want to check. To populate this array, you would
53
- need to define necessary attributes by calling `git_attr()` function.
56
+* Prepare `struct attr_check` using attr_check_initl()
57
+ function, enumerating the names of attributes whose values you are
58
+ interested in, terminated with a NULL pointer. Alternatively, an
59
+ empty `struct attr_check` can be prepared by calling
60
+ `attr_check_alloc()` function and then attributes you want to
61
+ ask about can be added to it with `attr_check_append()`
62
+ function.
63
64
* Call `git_check_attr()` to check the attributes for the path.
65
57
-* Inspect `git_attr_check` structure to see how each of the attribute in
58
- the array is defined for the path.
66
+* Inspect `attr_check` structure to see how each of the
67
+ attribute in the array is defined for the path.
68
69
70
Example
71
-------
72
64
-To see how attributes "crlf" and "indent" are set for different paths.
73
+To see how attributes "crlf" and "ident" are set for different paths.
74
66
-. Prepare an array of `struct git_attr_check` with two elements (because
67
- we are checking two attributes). Initialize their `attr` member with
68
- pointers to `struct git_attr` obtained by calling `git_attr()`:
75
+. Prepare a `struct attr_check` with two elements (because
76
+ we are checking two attributes):
77
78
------------
71
-static struct git_attr_check check[2];
79
+static struct attr_check *check;
80
static void setup_check(void)
81
{
74
- if (check[0].attr)
82
+ if (check)
83
return; /* already done */
76
- check[0].attr = git_attr("crlf");
77
- check[1].attr = git_attr("ident");
84
+ check = attr_check_initl("crlf", "ident", NULL);
85
}
86
------------
87
81
-. Call `git_check_attr()` with the prepared array of `struct git_attr_check`:
88
+. Call `git_check_attr()` with the prepared `struct attr_check`:
89
90
------------
91
const char *path;
92
93
setup_check();
87
- git_check_attr(path, ARRAY_SIZE(check), check);
94
+ git_check_attr(path, check);
95
------------
96
90
-. Act on `.value` member of the result, left in `check[]`:
97
+. Act on `.value` member of the result, left in `check->items[]`:
98
99
------------
93
- const char *value = check[0].value;
100
+ const char *value = check->items[0].value;
101
102
if (ATTR_TRUE(value)) {
103
The attribute is Set, by listing only the name of the
@@ -109,20 +116,39 @@ static void setup_check(void)
116
}
117
------------
118
119
+To see how attributes in argv[] are set for different paths, only
120
+the first step in the above would be different.
121
+
122
+------------
123
+static struct attr_check *check;
124
+static void setup_check(const char **argv)
125
+{
126
+ check = attr_check_alloc();
127
+ while (*argv) {
128
+ struct git_attr *attr = git_attr(*argv);
129
+ attr_check_append(check, attr);
130
+ argv++;
131
+ }
132
+}
133
+------------
134
+
135
136
Querying All Attributes
137
-----------------------
138
139
To get the values of all attributes associated with a file:
140
118
-* Call `git_all_attrs()`, which returns an array of `git_attr_check`
119
- structures.
141
+* Prepare an empty `attr_check` structure by calling
142
+ `attr_check_alloc()`.
143
+
144
+* Call `git_all_attrs()`, which populates the `attr_check`
145
+ with the attributes attached to the path.
146
121
-* Iterate over the `git_attr_check` array to examine the attribute
122
- names and values. The name of the attribute described by a
123
- `git_attr_check` object can be retrieved via
124
- `git_attr_name(check[i].attr)`. (Please note that no items will be
125
- returned for unset attributes, so `ATTR_UNSET()` will return false
126
- for all returned `git_array_check` objects.)
147
+* Iterate over the `attr_check.items[]` array to examine
148
+ the attribute names and values. The name of the attribute
149
+ described by a `attr_check.items[]` object can be retrieved via
150
+ `git_attr_name(check->items[i].attr)`. (Please note that no items
151
+ will be returned for unset attributes, so `ATTR_UNSET()` will return
152
+ false for all returned `attr_check.items[]` objects.)
153
128
-* Free the `git_array_check` array.
154
+* Free the `attr_check` struct by calling `attr_check_free()`.
attr.c
+2
-1
@@ -890,7 +890,8 @@ static void collect_some_attrs(const char *path, int num,
890
rem = fill(path, pathlen, basename_offset, stk, rem);
891
}
892
893
-int git_check_attrs(const char *path, int num, struct attr_check_item *check)
893
+static int git_check_attrs(const char *path, int num,
894
+ struct attr_check_item *check)
895
{
896
int i;
897
attr.h
-1
@@ -52,7 +52,6 @@ extern void attr_check_free(struct attr_check *check);
52
*/
53
extern const char *git_attr_name(const struct git_attr *);
54
55
-int git_check_attrs(const char *path, int, struct attr_check_item *);
55
extern int git_check_attr(const char *path, struct attr_check *check);
56
57
/*