Skip to content

Commit d558d35

Browse files
committed
cmdline/urls/query.md: document --url-query
closes #311
1 parent c351671 commit d558d35

File tree

5 files changed

+50
-4
lines changed

5 files changed

+50
-4
lines changed

SUMMARY.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,7 @@
5757
* [Host](cmdline/urls/host.md)
5858
* [Port number](cmdline/urls/port.md)
5959
* [Path](cmdline/urls/path.md)
60+
* [Query](cmdline/urls/query.md)
6061
* [FTP type](cmdline/urls/ftptype.md)
6162
* [Fragment](cmdline/urls/fragment.md)
6263
* [Browsers' address bar](cmdline/urls/browsers.md)

cmdline/urls.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ describes how that particular URI format works.
1818
* [Host](urls/host.md)
1919
* [Port number](urls/port.md)
2020
* [Path](urls/path.md)
21+
* [Query](urls/query.md)
2122
* [FTP type](urls/ftptype.md)
2223
* [Fragment](urls/fragment.md)
2324
* [Browsers' address bar](urls/browsers.md)

cmdline/urls/query.md

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# Query
2+
3+
The query part of a URL is the data that is to the right of a question mark
4+
(`?`) but to the left of the [fragment](fragment.md), which begins with a hash
5+
(`#`).
6+
7+
The query can be any string of characters really as long as they are URL
8+
encoded. It is a common practice to use a sequence of key/value pairs
9+
separated by ampersands (`&`). Like in
10+
`https://example.com/?name=daniel&tool=curl`.
11+
12+
To help users create such query sets, properly encoded, curl offers the
13+
command line option `--url-query [content]`. This option adds content, usually
14+
a name + value pair, to the end of the query part of the provided URL.
15+
16+
When adding query parts, curl adds ampersand separators.
17+
18+
The syntax is identical to that used `--data-urlencode` with one extension:
19+
the `+` prefix. See below.
20+
21+
- `content`: This will make curl URL encode the content and add that to the
22+
query. Just be careful so that the content does not contain any `=` or `@`
23+
symbols, as that will then make the syntax match one of the other cases
24+
below!
25+
26+
- `=content`: This will make curl URL encode the content and add that to the
27+
query. The initial `=` symbol is not included in the data.
28+
29+
- `name=content`: This will make curl URL encode the content part and add
30+
that to the query. Note that the name part is expected to be URL encoded
31+
already.
32+
33+
- `@filename`: This will make curl load data from the given file (including
34+
any newlines), URL encode that data and that to the query.
35+
36+
- `name@filename`: This will make curl load data from the given file
37+
(including any newlines), URL encode that data and add it to the query.
38+
The name part gets an equal sign appended, resulting in
39+
`name=urlencoded-file-content`. Note that the name is expected to be URL
40+
encoded already.
41+
42+
- `+content`: Add the content to the query without doing any encoding.

http/post/url-encode.md

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -19,11 +19,12 @@ followed by a separator and a content specification. The **data** part can be
1919
passed to curl using one of the following syntaxes:
2020

2121
- `content`: This will make curl URL encode the content and pass that
22-
on. Just be careful so that the content does not contain any = or @ symbols,
23-
as that will then make the syntax match one of the other cases below!
22+
on. Just be careful so that the content does not contain any `=` or `@`
23+
symbols, as that will then make the syntax match one of the other cases
24+
below!
2425

2526
- `=content`: This will make curl URL encode the content and pass that
26-
on. The initial '=' symbol is not included in the data.
27+
on. The initial `=` symbol is not included in the data.
2728

2829
- `name=content`: This will make curl URL encode the content part and pass
2930
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:
3435
- `name@filename`: This will make curl load data from the given file
3536
(including any newlines), URL encode that data and pass it on in the POST.
3637
The name part gets an equal sign appended, resulting in
37-
name=urlencoded-file-content. Note that the name is expected to be URL
38+
`name=urlencoded-file-content`. Note that the name is expected to be URL
3839
encoded already.
3940

4041
As an example, you could POST a name to have it encoded by curl:

index-words

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -78,6 +78,7 @@
7878
--trace
7979
--trace-ascii
8080
--trace-time
81+
--url-query
8182
--variable
8283
--verbose
8384
--version

0 commit comments

Comments
 (0)