1--- 2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. 3SPDX-License-Identifier: curl 4Long: variable 5Arg: <[%]name=text/@file> 6Help: Set variable 7Category: curl 8Added: 8.3.0 9Multi: append 10See-also: 11 - config 12Example: 13 - --variable name=smith --expand-url "$URL/{{name}}" 14--- 15 16# `--variable` 17 18Set a variable with `name=content` or `name@file` (where `file` can be stdin 19if set to a single dash (`-`)). The name is a case sensitive identifier that 20must consist of no other letters than a-z, A-Z, 0-9 or underscore. The 21specified content is then associated with this identifier. 22 23Setting the same variable name again overwrites the old contents with the new. 24 25The contents of a variable can be referenced in a later command line option 26when that option name is prefixed with `--expand-`, and the name is used as 27`{{name}}`. 28 29--variable can import environment variables into the name space. Opt to either 30require the environment variable to be set or provide a default value for the 31variable in case it is not already set. 32 33--variable %name imports the variable called `name` but exits with an error if 34that environment variable is not already set. To provide a default value if 35the environment variable is not set, use --variable %name=content or 36--variable %name@content. Note that on some systems - but not all - 37environment variables are case insensitive. 38 39Added in curl 8.12.0: you can get a byte range from the source by appending 40`[start-end]` to the variable name, where *start* and *end* are byte offsets 41to include from the contents. For example, asking for offset "2-10" means 42offset two to offset ten, inclusive, resulting in 9 bytes in total. `2-2` 43means a single byte at offset 2. Not providing a second number implies to the 44end of data. The start offset cannot be larger than the end offset. Asking for 45a range that is outside of the file size makes the variable contents empty. 46For example, getting the first one hundred bytes from a given file: 47 48 curl --variable "fraction[0-99]@filename" 49 50Given a byte range that has no data results in an empty string. Asking for a 51range that is larger than the content makes curl use the piece of the data 52that exists. 53 54To assign a variable using contents from another variable, use 55--expand-variable. Like for example assigning a new variable using contents 56from two other: 57 58 curl --expand-variable "user={{firstname}} {{lastname}}" 59 60When expanding variables, curl supports a set of functions that can make the 61variable contents more convenient to use. You apply a function to a variable 62expansion by adding a colon and then list the desired functions in a 63comma-separated list that is evaluated in a left-to-right order. Variable 64content holding null bytes that are not encoded when expanded, causes an 65error. 66 67Available functions: 68 69## trim 70removes all leading and trailing white space. 71 72Example: 73 74 curl --expand-url https.//example.com/{{url:trim}} 75 76## json 77outputs the content using JSON string quoting rules. 78 79Example: 80 81 curl --expand-data {{data:json}} https://example.com 82 83## url 84shows the content URL (percent) encoded. 85 86Example: 87 88 curl --expand-url https://example.com/{{path:url}} 89 90## b64 91expands the variable base64 encoded 92 93Example: 94 95 curl --expand-url https://example.com/{{var:b64}} 96