c2d37463b9
Follow-up to 40c264db61 after discussions on IRC.
The new style is
name[0-99]=contents
and
name[0-99]@filename
A) This does not cause the same problems with old curl versions trying
the new syntax as this way will cause old curls just fail with syntax
error and not risk using the wrong file.
B) Adds the same byte range support for "normal" assigns, which the
previous syntax did not. Thus lets a user get a partial content of a
variable etc.
Added test 790 and 791 to verify non-file assigns with ranges.
Closes #15862
3.2 KiB
| c | SPDX-License-Identifier | Long | Arg | Help | Category | Added | Multi | See-also | Example | ||
|---|---|---|---|---|---|---|---|---|---|---|---|
| Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. | curl | variable | <[%]name=text/@file> | Set variable | curl | 8.3.0 | append |
|
|
--variable
Set a variable with name=content or name@file (where file can be stdin
if set to a single dash (-)). The name is a case sensitive identifier that
must consist of no other letters than a-z, A-Z, 0-9 or underscore. The
specified content is then associated with this identifier.
Setting the same variable name again overwrites the old contents with the new.
The contents of a variable can be referenced in a later command line option
when that option name is prefixed with --expand-, and the name is used as
{{name}}.
--variable can import environment variables into the name space. Opt to either require the environment variable to be set or provide a default value for the variable in case it is not already set.
--variable %name imports the variable called name but exits with an error if
that environment variable is not already set. To provide a default value if
the environment variable is not set, use --variable %name=content or
--variable %name@content. Note that on some systems - but not all -
environment variables are case insensitive.
Added in curl 8.12.0: you can get a byte range from the source by appending
[start-end] to the variable name, where start and end are byte offsets
to include from the contents. For example, asking for offset "2-10" means
offset two to offset ten, inclusive, resulting in 9 bytes in total. 2-2
means a single byte at offset 2. Not providing a second number implies to the
end of data. The start offset cannot be larger than the end offset. Asking for
a range that is outside of the file size makes the variable contents empty.
For example, getting the first one hundred bytes from a given file:
curl --variable "fraction[0-99]@filename"
Given a byte range that has no data results in an empty string. Asking for a range that is larger than the content makes curl use the piece of the data that exists.
To assign a variable using contents from another variable, use --expand-variable. Like for example assigning a new variable using contents from two other:
curl --expand-variable "user={{firstname}} {{lastname}}"
When expanding variables, curl supports a set of functions that can make the variable contents more convenient to use. You apply a function to a variable expansion by adding a colon and then list the desired functions in a comma-separated list that is evaluated in a left-to-right order. Variable content holding null bytes that are not encoded when expanded, causes an error.
Available functions:
trim
removes all leading and trailing white space.
Example:
curl --expand-url https.//example.com/{{url:trim}}
json
outputs the content using JSON string quoting rules.
Example:
curl --expand-data {{data:json}} https://example.com
url
shows the content URL (percent) encoded.
Example:
curl --expand-url https://example.com/{{path:url}}
b64
expands the variable base64 encoded
Example:
curl --expand-url https://example.com/{{var:b64}}