From: Stefan Beller <sbeller@google.com>
To: gitster@pobox.com
Cc: git@vger.kernel.org, bmwill@google.com, pclouds@gmail.com,
Stefan Beller <sbeller@google.com>
Subject: [PATCH 14/28] attr: retire git_check_attrs() API
Date: Mon, 10 Oct 2016 17:21:01 -0700 [thread overview]
Message-ID: <20161011002115.23312-15-sbeller@google.com> (raw)
In-Reply-To: <20161011002115.23312-1-sbeller@google.com>
From: Junio C Hamano <gitster@pobox.com>
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>
---
Documentation/technical/api-gitattributes.txt | 82 ++++++++++++++++++---------
attr.c | 3 +-
attr.h | 2 -
3 files changed, 56 insertions(+), 31 deletions(-)
diff --git a/Documentation/technical/api-gitattributes.txt b/Documentation/technical/api-gitattributes.txt
index 2602668..92fc32a 100644
--- 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()`.
+`struct git_attr_check_elem`::
+
+ This structure represents one attribute and its value.
+
`struct git_attr_check`::
- This structure represents a set of attributes to check in a call
- to `git_check_attr()` function, and receives the results.
+ This structure represents a collection of `git_attr_check_elem`.
+ It is passed to `git_check_attr()` function, specifying the
+ attributes to check, and receives their values.
Attribute Values
@@ -48,49 +53,51 @@ value of the attribute for the path.
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 git_attr_check` using git_attr_check_initl()
+ function, enumerating the names of attributes whose values you are
+ interested in, terminated with a NULL pointer. Alternatively, an
+ empty `struct git_attr_check` can be prepared by calling
+ `git_attr_check_alloc()` function and then attributes you want to
+ ask about can be added to it with `git_attr_check_append()`
+ function.
* 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 `git_attr_check` structure to see how each of the
+ attribute in the array is defined for the path.
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 git_attr_check` with two elements (because
+ we are checking two attributes):
------------
-static struct git_attr_check check[2];
+static struct git_attr_check *check;
static void setup_check(void)
{
- if (check[0].attr)
+ if (check)
return; /* already done */
- check[0].attr = git_attr("crlf");
- check[1].attr = git_attr("ident");
+ check = git_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 git_attr_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->check[]`:
------------
- const char *value = check[0].value;
+ const char *value = check->check[0].value;
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 git_attr_check *check;
+static void setup_check(const char **argv)
+{
+ check = git_attr_check_alloc();
+ while (*argv) {
+ struct git_attr *attr = git_attr(*argv);
+ git_attr_check_append(check, attr);
+ argv++;
+ }
+}
+------------
+
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 `git_attr_check` structure by calling
+ `git_attr_check_alloc()`.
+
+* Call `git_all_attrs()`, which populates the `git_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 `git_attr_check.check[]` array to examine
+ the attribute names and values. The name of the attribute
+ described by a `git_attr_check.check[]` object can be retrieved via
+ `git_attr_name(check->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.)
-* Free the `git_array_check` array.
+* Free the `git_array_check` by calling `git_attr_check_free()`.
diff --git a/attr.c b/attr.c
index 76f0d6b..d427798 100644
--- a/attr.c
+++ b/attr.c
@@ -778,7 +778,8 @@ static void collect_some_attrs(const char *path, int num,
rem = fill(path, pathlen, basename_offset, stk, rem);
}
-int git_check_attrs(const char *path, int num, struct git_attr_check_elem *check)
+static int git_check_attrs(const char *path, int num,
+ struct git_attr_check_elem *check)
{
int i;
diff --git a/attr.h b/attr.h
index 0d94077..506db0c 100644
--- a/attr.h
+++ b/attr.h
@@ -52,8 +52,6 @@ extern void git_attr_check_free(struct git_attr_check *);
*/
extern const char *git_attr_name(const struct git_attr *);
-int git_check_attrs(const char *path, int, struct git_attr_check_elem *);
-
/*
* Retrieve all attributes that apply to the specified path.
* check holds the attributes and their values.
--
2.10.1.382.ga23ca1b.dirty
next prev parent reply other threads:[~2016-10-11 0:21 UTC|newest]
Thread overview: 44+ messages / expand[flat|nested] mbox.gz Atom feed top
2016-10-11 0:20 [PATCH 00/28] Revamping the attr subsystem! Stefan Beller
2016-10-11 0:20 ` [PATCH 01/28] commit.c: use strchrnul() to scan for one line Stefan Beller
2016-10-11 0:20 ` [PATCH 02/28] attr.c: " Stefan Beller
2016-10-11 0:20 ` [PATCH 03/28] attr.c: update a stale comment on "struct match_attr" Stefan Beller
2016-10-11 0:20 ` [PATCH 04/28] attr.c: explain the lack of attr-name syntax check in parse_attr() Stefan Beller
2016-10-11 0:20 ` [PATCH 05/28] attr.c: complete a sentence in a comment Stefan Beller
2016-10-11 0:20 ` [PATCH 06/28] attr.c: mark where #if DEBUG ends more clearly Stefan Beller
2016-10-11 0:20 ` [PATCH 07/28] attr.c: simplify macroexpand_one() Stefan Beller
2016-10-11 0:20 ` [PATCH 08/28] attr.c: tighten constness around "git_attr" structure Stefan Beller
2016-10-11 0:20 ` [PATCH 09/28] attr.c: plug small leak in parse_attr_line() Stefan Beller
2016-10-11 0:20 ` [PATCH 10/28] attr: rename function and struct related to checking attributes Stefan Beller
2016-10-11 0:20 ` [PATCH 11/28] attr: (re)introduce git_check_attr() and struct git_attr_check Stefan Beller
2016-10-11 16:59 ` Brandon Williams
2016-10-11 17:42 ` Junio C Hamano
2016-10-11 0:20 ` [PATCH 12/28] attr: convert git_all_attrs() to use "struct git_attr_check" Stefan Beller
2016-10-11 0:21 ` [PATCH 13/28] attr: convert git_check_attrs() callers to use the new API Stefan Beller
2016-10-11 0:21 ` Stefan Beller [this message]
2016-10-11 0:21 ` [PATCH 15/28] attr: add counted string version of git_check_attr() Stefan Beller
2016-10-11 0:21 ` [PATCH 16/28] attr: add counted string version of git_attr() Stefan Beller
2016-10-11 0:21 ` [PATCH 17/28] attr: expose validity check for attribute names Stefan Beller
2016-10-11 17:28 ` Brandon Williams
2016-10-11 18:28 ` Stefan Beller
2016-10-11 18:40 ` Brandon Williams
2016-10-11 18:44 ` Stefan Beller
2016-10-11 18:49 ` Brandon Williams
2016-10-11 0:21 ` [PATCH 18/28] attr: support quoting pathname patterns in C style Stefan Beller
2016-10-11 0:21 ` [PATCH 19/28] attr.c: add push_stack() helper Stefan Beller
2016-10-11 0:21 ` [PATCH 20/28] attr.c: pass struct git_attr_check down the callchain Stefan Beller
2016-10-11 0:21 ` [PATCH 21/28] attr.c: rename a local variable check Stefan Beller
2016-10-11 0:21 ` [PATCH 22/28] attr.c: correct ugly hack for git_all_attrs() Stefan Beller
2016-10-11 0:21 ` [PATCH 23/28] attr.c: introduce empty_attr_check_elems() Stefan Beller
2016-10-11 0:21 ` [PATCH 24/28] attr.c: always pass check[] to collect_some_attrs() Stefan Beller
2016-10-11 0:21 ` [PATCH 25/28] attr.c: outline the future plans by heavily commenting Stefan Beller
2016-10-11 0:21 ` [PATCH 26/28] attr: make git_attr_counted static Stefan Beller
2016-10-11 17:37 ` Brandon Williams
2016-10-11 21:53 ` Stefan Beller
2016-10-11 0:21 ` [PATCH 27/28] attr: make git_check_attr_counted static Stefan Beller
2016-10-11 0:21 ` [PATCH 28/28] attr: convert to new threadsafe API Stefan Beller
2016-10-11 17:40 ` Junio C Hamano
2016-10-11 17:56 ` Stefan Beller
2016-10-11 18:23 ` Junio C Hamano
2016-10-11 18:56 ` Stefan Beller
2016-10-11 19:47 ` Junio C Hamano
2016-10-11 17:45 ` Brandon Williams
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20161011002115.23312-15-sbeller@google.com \
--to=sbeller@google.com \
--cc=bmwill@google.com \
--cc=git@vger.kernel.org \
--cc=gitster@pobox.com \
--cc=pclouds@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).