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: when getting contents from a file, you can request to 40get a byte range from it by appending ";[start-end]" to the filename, where 41*start* and *end* are byte offsets to include from the file. For example, 42asking for offset "2-10" means offset two to offset ten, including the byte 43offset 10, meaning 9 bytes in total. "2-2" means a single byte at offset 2. 44Not providing a second number implies to the end of the file. The start offset 45cannot be larger than the end offset. Asking for a range that is outside of 46the file size makes the variable contents empty. 47 48To assign a variable using contents from another variable, use 49--expand-variable. Like for example assigning a new variable using contents 50from two other: 51 52 curl --expand-variable "user={{firstname}} {{lastname}}" 53 54When expanding variables, curl supports a set of functions that can make the 55variable contents more convenient to use. You apply a function to a variable 56expansion by adding a colon and then list the desired functions in a 57comma-separated list that is evaluated in a left-to-right order. Variable 58content holding null bytes that are not encoded when expanded, causes an 59error. 60 61Available functions: 62 63## trim 64removes all leading and trailing white space. 65 66Example: 67 68 curl --expand-url https.//example.com/{{url:trim}} 69 70## json 71outputs the content using JSON string quoting rules. 72 73Example: 74 75 curl --expand-data {{data:json}} https://example.com 76 77## url 78shows the content URL (percent) encoded. 79 80Example: 81 82 curl --expand-url https://example.com/{{path:url}} 83 84## b64 85expands the variable base64 encoded 86 87Example: 88 89 curl --expand-url https://example.com/{{var:b64}} 90
