From d558d3515ab582817f1889a1e0485313645f930b Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 9 Aug 2023 17:49:40 +0200 Subject: [PATCH] cmdline/urls/query.md: document --url-query closes #311 --- SUMMARY.md | 1 + cmdline/urls.md | 1 + cmdline/urls/query.md | 42 +++++++++++++++++++++++++++++++++++++++++ http/post/url-encode.md | 9 +++++---- index-words | 1 + 5 files changed, 50 insertions(+), 4 deletions(-) create mode 100644 cmdline/urls/query.md diff --git a/SUMMARY.md b/SUMMARY.md index 2d514567c4..ab699f54f0 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -57,6 +57,7 @@ * [Host](cmdline/urls/host.md) * [Port number](cmdline/urls/port.md) * [Path](cmdline/urls/path.md) + * [Query](cmdline/urls/query.md) * [FTP type](cmdline/urls/ftptype.md) * [Fragment](cmdline/urls/fragment.md) * [Browsers' address bar](cmdline/urls/browsers.md) diff --git a/cmdline/urls.md b/cmdline/urls.md index 33ca7744aa..8a4b680f4f 100644 --- a/cmdline/urls.md +++ b/cmdline/urls.md @@ -18,6 +18,7 @@ describes how that particular URI format works. * [Host](urls/host.md) * [Port number](urls/port.md) * [Path](urls/path.md) +* [Query](urls/query.md) * [FTP type](urls/ftptype.md) * [Fragment](urls/fragment.md) * [Browsers' address bar](urls/browsers.md) diff --git a/cmdline/urls/query.md b/cmdline/urls/query.md new file mode 100644 index 0000000000..4cf3991075 --- /dev/null +++ b/cmdline/urls/query.md @@ -0,0 +1,42 @@ +# Query + +The query part of a URL is the data that is to the right of a question mark +(`?`) but to the left of the [fragment](fragment.md), which begins with a hash +(`#`). + +The query can be any string of characters really as long as they are URL +encoded. It is a common practice to use a sequence of key/value pairs +separated by ampersands (`&`). Like in +`https://example.com/?name=daniel&tool=curl`. + +To help users create such query sets, properly encoded, curl offers the +command line option `--url-query [content]`. This option adds content, usually +a name + value pair, to the end of the query part of the provided URL. + +When adding query parts, curl adds ampersand separators. + +The syntax is identical to that used `--data-urlencode` with one extension: +the `+` prefix. See below. + + - `content`: This will make curl URL encode the content and add that to the + query. Just be careful so that the content does not contain any `=` or `@` + symbols, as that will then make the syntax match one of the other cases + below! + + - `=content`: This will make curl URL encode the content and add that to the + query. The initial `=` symbol is not included in the data. + + - `name=content`: This will make curl URL encode the content part and add + that to the query. Note that the name part is expected to be URL encoded + already. + + - `@filename`: This will make curl load data from the given file (including + any newlines), URL encode that data and that to the query. + + - `name@filename`: This will make curl load data from the given file + (including any newlines), URL encode that data and add it to the query. + The name part gets an equal sign appended, resulting in + `name=urlencoded-file-content`. Note that the name is expected to be URL + encoded already. + + - `+content`: Add the content to the query without doing any encoding. diff --git a/http/post/url-encode.md b/http/post/url-encode.md index f2aa2e59ca..10c1764c3a 100644 --- a/http/post/url-encode.md +++ b/http/post/url-encode.md @@ -19,11 +19,12 @@ followed by a separator and a content specification. The **data** part can be passed to curl using one of the following syntaxes: - `content`: This will make curl URL encode the content and pass that - on. Just be careful so that the content does not contain any = or @ symbols, - as that will then make the syntax match one of the other cases below! + on. Just be careful so that the content does not contain any `=` or `@` + symbols, as that will then make the syntax match one of the other cases + below! - `=content`: This will make curl URL encode the content and pass that - on. The initial '=' symbol is not included in the data. + on. The initial `=` symbol is not included in the data. - `name=content`: This will make curl URL encode the content part and pass that on. Note that the name part is expected to be URL encoded already. @@ -34,7 +35,7 @@ passed to curl using one of the following syntaxes: - `name@filename`: This will make curl load data from the given file (including any newlines), URL encode that data and pass it on in the POST. The name part gets an equal sign appended, resulting in - name=urlencoded-file-content. Note that the name is expected to be URL + `name=urlencoded-file-content`. Note that the name is expected to be URL encoded already. As an example, you could POST a name to have it encoded by curl: diff --git a/index-words b/index-words index 7c83a17e71..f56beba057 100644 --- a/index-words +++ b/index-words @@ -78,6 +78,7 @@ --trace --trace-ascii --trace-time +--url-query --variable --verbose --version