From 63b76948e1d211ad4a95c3a9c7a0087fe6a1e371 Mon Sep 17 00:00:00 2001 From: Stephen Boyd Date: Thu, 17 Dec 2009 16:05:28 -0800 Subject: api-strbuf.txt: fix typos and document launch_editor() Signed-off-by: Stephen Boyd Signed-off-by: Junio C Hamano --- Documentation/technical/api-strbuf.txt | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) (limited to 'Documentation/technical/api-strbuf.txt') diff --git a/Documentation/technical/api-strbuf.txt b/Documentation/technical/api-strbuf.txt index 7438149249..a0e0f850f8 100644 --- a/Documentation/technical/api-strbuf.txt +++ b/Documentation/technical/api-strbuf.txt @@ -12,7 +12,7 @@ strbuf API actually relies on the string being free of NULs. strbufs has some invariants that are very important to keep in mind: -. The `buf` member is never NULL, so you it can be used in any usual C +. The `buf` member is never NULL, so it can be used in any usual C string operations safely. strbuf's _have_ to be initialized either by `strbuf_init()` or by `= STRBUF_INIT` before the invariants, though. + @@ -55,7 +55,7 @@ Data structures * `struct strbuf` -This is string buffer structure. The `len` member can be used to +This is the string buffer structure. The `len` member can be used to determine the current length of the string, and `buf` member provides access to the string itself. @@ -253,3 +253,9 @@ same behaviour as well. comments are considered contents to be removed or not. `launch_editor`:: + + Launch the user preferred editor to edit a file and fill the buffer + with the file's contents upon the user completing their editing. The + third argument can be used to set the environment which the editor is + run in. If the buffer is NULL the editor is launched as usual but the + file's contents are not read into the buffer upon completion. -- cgit v1.2.3 From 0a0416a34a7ef5c64f4e0226371e4cab8c1ba982 Mon Sep 17 00:00:00 2001 From: Jeff King Date: Wed, 13 Jan 2010 12:35:31 -0500 Subject: strbuf_expand: convert "%%" to "%" The only way to safely quote arbitrary text in a pretty-print user format is to replace instances of "%" with "%x25". This is slightly unreadable, and many users would expect "%%" to produce a single "%", as that is what printf format specifiers do. This patch converts "%%" to "%" for all users of strbuf_expand(): (1) git-daemon interpolated paths (2) pretty-print user formats (3) merge driver command lines Case (1) was already doing the conversion itself outside of strbuf_expand(). Case (2) is the intended beneficiary of this patch. Case (3) users probably won't notice, but as this is user-facing behavior, consistently providing the quoting mechanism makes sense. Signed-off-by: Jeff King Signed-off-by: Junio C Hamano --- Documentation/technical/api-strbuf.txt | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'Documentation/technical/api-strbuf.txt') diff --git a/Documentation/technical/api-strbuf.txt b/Documentation/technical/api-strbuf.txt index a0e0f850f8..3b1da10f26 100644 --- a/Documentation/technical/api-strbuf.txt +++ b/Documentation/technical/api-strbuf.txt @@ -199,6 +199,10 @@ character if the letter `n` appears after a `%`. The function returns the length of the placeholder recognized and `strbuf_expand()` skips over it. + +The format `%%` is automatically expanded to a single `%` as a quoting +mechanism; callers do not need to handle the `%` placeholder themselves, +and the callback function will not be invoked for this placeholder. ++ All other characters (non-percent and not skipped ones) are copied verbatim to the strbuf. If the callback returned zero, meaning that the placeholder is unknown, then the percent sign is copied, too. -- cgit v1.2.3 From 361df5df77255321b2ca409d892b4c24b7b0441d Mon Sep 17 00:00:00 2001 From: Jeff King Date: Wed, 13 Jan 2010 12:36:42 -0500 Subject: strbuf: add strbuf_addbuf_percentquote This is handy for creating strings which will be fed to printf() or strbuf_expand(). Signed-off-by: Jeff King Signed-off-by: Junio C Hamano --- Documentation/technical/api-strbuf.txt | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'Documentation/technical/api-strbuf.txt') diff --git a/Documentation/technical/api-strbuf.txt b/Documentation/technical/api-strbuf.txt index 3b1da10f26..afe2759951 100644 --- a/Documentation/technical/api-strbuf.txt +++ b/Documentation/technical/api-strbuf.txt @@ -218,6 +218,13 @@ which can be used by the programmer of the callback as she sees fit. placeholder and replacement string. The array needs to be terminated by an entry with placeholder set to NULL. +`strbuf_addbuf_percentquote`:: + + Append the contents of one strbuf to another, quoting any + percent signs ("%") into double-percents ("%%") in the + destination. This is useful for literal data to be fed to either + strbuf_expand or to the *printf family of functions. + `strbuf_addf`:: Add a formatted string to the buffer. -- cgit v1.2.3