Re: [PATCHv3 11/13] strbuf: add strbuf_add*_urlencode
- From
Jeff King <peff@peff.net>
- Date
- Dec 10, 2011, 20:09 UTC
- Message-ID
- <20111210200909.GC17999@sigill.intra.peff.net>
- In-Reply-To
- <m3iplohc6s.fsf@localhost.localdomain>
On Sat, Dec 10, 2011 at 03:57:59AM -0800, Jakub Narebski wrote:
Show 9 quoted lines
> 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.