Re: [PATCHv3 11/13] strbuf: add strbuf_add*_urlencode

[Jeff King <peff@peff.net>]

On Sat, Dec 10, 2011 at 03:57:59AM -0800, Jakub Narebski wrote:

> Jeff King <peff@peff.net> writes:
> 
> > +void strbuf_add_urlencode(struct strbuf *sb, const char *s, size_t len,
> > +			  int reserved)
> > +{
> > +	strbuf_grow(sb, len);
> 
> What is this `reserved` flag for, and when should one use it?
> It would be nice to have a short comment...

It indicates whether one should encode rfc3986 reserved characters. You
want to use it when encoding the host, username, and password portions
of a URL (i.e., before the "/"), but not the path (since you don't want
to encode all of the slashes). If you were breaking down the path more
(e.g., into a "query" and "fragment" portion), you would care about more
specific quoting there, but we don't; we treat everything after the
slash as an opaque blob of path.

Patch to the strbuf api documentation is below. I think it should be
squashed into patch 12/13.

> BTW. was it meant to be aligned like this?
> 
> > +void strbuf_add_urlencode(struct strbuf *sb, const char *s, size_t len,
> > +			     int reserved)

It is aligned correctly. When you ident by tabs, the "+" of the diff
gets soaked in the first tabstop, so it is off-by-one with respect to
non-tabbed input (it is off even more in the quoted section above,
because "> > +" gets soaked into the first tabstop). You can see your
version above also is misaligned when I quote it. :)

If you apply the diff, the result is as you expected.

-Peff

---
diff --git a/Documentation/technical/api-strbuf.txt b/Documentation/technical/api-strbuf.txt
index afe2759..e1ab6c5 100644
--- a/Documentation/technical/api-strbuf.txt
+++ b/Documentation/technical/api-strbuf.txt
@@ -270,3 +270,14 @@ same behaviour as well.
 	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.
+
+`strbuf_add_urlencode`::
+
+	Copy data to the end of the buffer, percent-encoding it as per
+	rfc3986. If the reserved flag is non-zero, then characters in
+	the rfc3986 reserved list are percent-encoded; otherwise, they
+	are copied literally. Characters in the rfc3986 unreserved list
+	are always copied literally. All other characters are
+	percent-encoded. Typically, one would use the reserved flag for
+	the host and user-info sections of a URL, but leave special
+	characters in the path untouched.