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>

diff --git a/Documentation/technical/api-gitattributes.txt b/Documentation/technical/api-gitattributes.txt
index 260266867768a549e58e540eaa95d3bbe422e5c0..e7cbb7c13adf2f7ea3b15279a17f1a06da859cbc 100644 (file)
--- a/Documentation/technical/api-gitattributes.txt
+++ b/Documentation/technical/api-gitattributes.txt
@@ -16,10 +16,15 @@ Data Structure
        of no interest to the calling programs.  The name of the
        attribute can be retrieved by calling `git_attr_name()`.
 
        of no interest to the calling programs.  The name of the
        attribute can be retrieved by calling `git_attr_name()`.
 

-`struct git_attr_check`::
+`struct attr_check_item`::

 
 

-       This structure represents a set of attributes to check in a call
-       to `git_check_attr()` function, and receives the results.
+       This structure represents one attribute and its value.
+
+`struct attr_check`::
+
+       This structure represents a collection of `attr_check_item`.
+       It is passed to `git_check_attr()` function, specifying the
+       attributes to check, and receives their values.

 
 
 Attribute Values
 
 
 Attribute Values


@@ -27,7 +32,7 @@ Attribute Values
 
 An attribute for a path can be in one of four states: Set, Unset,
 Unspecified or set to a string, and `.value` member of `struct
 
 An attribute for a path can be in one of four states: Set, Unset,
 Unspecified or set to a string, and `.value` member of `struct

-git_attr_check` records it.  There are three macros to check these:
+attr_check_item` records it.  There are three macros to check these:

 
 `ATTR_TRUE()`::
 
 
 `ATTR_TRUE()`::
 


@@ -48,49 +53,51 @@ value of the attribute for the path.
 Querying Specific Attributes
 ----------------------------
 
 Querying Specific Attributes
 ----------------------------
 

-* Prepare an array of `struct git_attr_check` to define the list of
-  attributes you would want to check.  To populate this array, you would
-  need to define necessary attributes by calling `git_attr()` function.
+* Prepare `struct attr_check` using attr_check_initl()
+  function, enumerating the names of attributes whose values you are
+  interested in, terminated with a NULL pointer.  Alternatively, an
+  empty `struct attr_check` can be prepared by calling
+  `attr_check_alloc()` function and then attributes you want to
+  ask about can be added to it with `attr_check_append()`
+  function.

 
 * Call `git_check_attr()` to check the attributes for the path.
 
 
 * Call `git_check_attr()` to check the attributes for the path.
 

-* Inspect `git_attr_check` structure to see how each of the attribute in
-  the array is defined for the path.
+* Inspect `attr_check` structure to see how each of the
+  attribute in the array is defined for the path.

 
 
 Example
 -------
 
 
 
 Example
 -------
 

-To see how attributes "crlf" and "indent" are set for different paths.
+To see how attributes "crlf" and "ident" are set for different paths.

 
 

-. Prepare an array of `struct git_attr_check` with two elements (because
-  we are checking two attributes).  Initialize their `attr` member with
-  pointers to `struct git_attr` obtained by calling `git_attr()`:
+. Prepare a `struct attr_check` with two elements (because
+  we are checking two attributes):

 
 ------------
 
 ------------

-static struct git_attr_check check[2];
+static struct attr_check *check;

 static void setup_check(void)
 {
 static void setup_check(void)
 {

-       if (check[0].attr)
+       if (check)

                return; /* already done */
                return; /* already done */

-       check[0].attr = git_attr("crlf");
-       check[1].attr = git_attr("ident");
+       check = attr_check_initl("crlf", "ident", NULL);

 }
 ------------
 
 }
 ------------
 

-. Call `git_check_attr()` with the prepared array of `struct git_attr_check`:
+. Call `git_check_attr()` with the prepared `struct attr_check`:

 
 ------------
        const char *path;
 
        setup_check();
 
 ------------
        const char *path;
 
        setup_check();

-       git_check_attr(path, ARRAY_SIZE(check), check);
+       git_check_attr(path, check);

 ------------
 
 ------------
 

-. Act on `.value` member of the result, left in `check[]`:
+. Act on `.value` member of the result, left in `check->items[]`:

 
 ------------
 
 ------------

-       const char *value = check[0].value;
+       const char *value = check->items[0].value;

 
        if (ATTR_TRUE(value)) {
                The attribute is Set, by listing only the name of the
 
        if (ATTR_TRUE(value)) {
                The attribute is Set, by listing only the name of the


@@ -109,20 +116,39 @@ static void setup_check(void)
        }
 ------------
 
        }
 ------------
 

+To see how attributes in argv[] are set for different paths, only
+the first step in the above would be different.
+
+------------
+static struct attr_check *check;
+static void setup_check(const char **argv)
+{
+       check = attr_check_alloc();
+       while (*argv) {
+               struct git_attr *attr = git_attr(*argv);
+               attr_check_append(check, attr);
+               argv++;
+       }
+}
+------------
+

 
 Querying All Attributes
 -----------------------
 
 To get the values of all attributes associated with a file:
 
 
 Querying All Attributes
 -----------------------
 
 To get the values of all attributes associated with a file:
 

-* Call `git_all_attrs()`, which returns an array of `git_attr_check`
-  structures.
+* Prepare an empty `attr_check` structure by calling
+  `attr_check_alloc()`.
+
+* Call `git_all_attrs()`, which populates the `attr_check`
+  with the attributes attached to the path.

 
 

-* Iterate over the `git_attr_check` array to examine the attribute
-  names and values.  The name of the attribute described by a
-  `git_attr_check` object can be retrieved via
-  `git_attr_name(check[i].attr)`.  (Please note that no items will be
-  returned for unset attributes, so `ATTR_UNSET()` will return false
-  for all returned `git_array_check` objects.)
+* Iterate over the `attr_check.items[]` array to examine
+  the attribute names and values.  The name of the attribute
+  described by a  `attr_check.items[]` object can be retrieved via
+  `git_attr_name(check->items[i].attr)`.  (Please note that no items
+  will be returned for unset attributes, so `ATTR_UNSET()` will return
+  false for all returned `attr_check.items[]` objects.)

 
 

-* Free the `git_array_check` array.
+* Free the `attr_check` struct by calling `attr_check_free()`.

diff --git a/attr.c b/attr.c
index 40818246f34c5b7b3a2d003fe94021c7fa8a54a1..c0e7893b5fa9ff0ffa1d22c6f2195334913bc3e3 100644 (file)
--- a/attr.c
+++ b/attr.c
@@ -890,7 +890,8 @@ static void collect_some_attrs(const char *path, int num,
                rem = fill(path, pathlen, basename_offset, stk, rem);
 }
 
                rem = fill(path, pathlen, basename_offset, stk, rem);
 }
 

-int git_check_attrs(const char *path, int num, struct attr_check_item *check)
+static int git_check_attrs(const char *path, int num,
+                          struct attr_check_item *check)

 {
        int i;
 
 {
        int i;
 

diff --git a/attr.h b/attr.h
index 9f2729842d0dc65cdad519c99d1a304fea4ee728..b2cfd8550962935a0587325136d2fcaa9e3d506c 100644 (file)
--- a/attr.h
+++ b/attr.h
@@ -52,7 +52,6 @@ extern void attr_check_free(struct attr_check *check);
  */
 extern const char *git_attr_name(const struct git_attr *);
 
  */
 extern const char *git_attr_name(const struct git_attr *);
 

-int git_check_attrs(const char *path, int, struct attr_check_item *);

 extern int git_check_attr(const char *path, struct attr_check *check);
 
 /*
 extern int git_check_attr(const char *path, struct attr_check *check);
 
 /*