[babeltrace.git] / doc / man / common-cmd-params-format.txt

The format of 'PARAMS' is a comma-separated list of 'NAME'='VALUE'
assignments:

[verse]
'NAME'='VALUE'[,'NAME'='VALUE']...

'NAME'::
    Parameter name (C~identifier plus the `:`, `.`, and `-`
    characters).

'VALUE'::
    One of:
+
--
* `null`, `nul`, `NULL`: null value.

* `true`, `TRUE`, `yes`, `YES`: true boolean value.

* `false`, `FALSE`, `no`, `NO`: false boolean value.

* Binary (`0b` prefix), octal (`0` prefix), decimal, or hexadecimal
  (`0x` prefix) unsigned (with `+` prefix) or signed 64-bit integer.

* Double precision floating point number (scientific notation is
  accepted).

* Unquoted string with no special characters, and not matching any of
  the null and boolean value symbols above.

* Double-quoted string (accepts escape characters).

* Array, formatted as an opening `[`, a comma-separated list of 'VALUE',
  and a closing `]`.

* Map, formatted as an opening `{`, a comma-separated list of
  'NAME'='VALUE' assignments, and a closing `}`.

You may put whitespaces around the individual `=` (assignment), `,`
(separator), `[` (array beginning), `]` (array end), `{` (map
beginning), and `}` (map end) characters.
--

Example:

[role="term"]
----
--params='many=null, fresh=yes, condition=false, squirrel=-782329,
          play=+23, observe=3.14, simple=beef,
          needs-quotes="some string",
          escape.chars-are:allowed="a \" quote",
          things=[1, "hello", 2.71828],
          frog={slow=2, bath=[bike, 23], blind=NO}'
----

IMPORTANT: Like in the example above, make sure to single-quote the
whole argument when you run this command from a shell, as it can contain
many special characters.
Commit	Line	Data
e70712b3 PP	1	The format of 'PARAMS' is a comma-separated list of 'NAME'='VALUE'
e70712b3 PP	2	assignments:
0659f3af PP	3
	4	[verse]
	5	'NAME'='VALUE'[,'NAME'='VALUE']...
	6
	7	'NAME'::
e70712b3 PP	8	Parameter name (C~identifier plus the `:`, `.`, and `-`
e70712b3 PP	9	characters).
0659f3af PP	10
	11	'VALUE'::
	12	One of:
	13	+
	14	--
	15	* `null`, `nul`, `NULL`: null value.
	16
	17	* `true`, `TRUE`, `yes`, `YES`: true boolean value.
	18
	19	* `false`, `FALSE`, `no`, `NO`: false boolean value.
	20
	21	* Binary (`0b` prefix), octal (`0` prefix), decimal, or hexadecimal
fdd3a2da	22	(`0x` prefix) unsigned (with `+` prefix) or signed 64-bit integer.
0659f3af PP	23
	24	* Double precision floating point number (scientific notation is
	25	accepted).
	26
	27	* Unquoted string with no special characters, and not matching any of
	28	the null and boolean value symbols above.
	29
	30	* Double-quoted string (accepts escape characters).
	31
e70712b3 PP	32	* Array, formatted as an opening `[`, a comma-separated list of 'VALUE',
e70712b3 PP	33	and a closing `]`.
b25da386	34
e70712b3 PP	35	* Map, formatted as an opening `{`, a comma-separated list of
	36	'NAME'='VALUE' assignments, and a closing `}`.
	37
	38	You may put whitespaces around the individual `=` (assignment), `,`
	39	(separator), `[` (array beginning), `]` (array end), `{` (map
	40	beginning), and `}` (map end) characters.
0659f3af PP	41	--
	42
	43	Example:
	44
e70712b3	45	[role="term"]
0659f3af	46	----
e70712b3 PP	47	--params='many=null, fresh=yes, condition=false, squirrel=-782329,
	48	play=+23, observe=3.14, simple=beef,
	49	needs-quotes="some string",
	50	escape.chars-are:allowed="a \" quote",
	51	things=[1, "hello", 2.71828],
	52	frog={slow=2, bath=[bike, 23], blind=NO}'
0659f3af PP	53	----
	54
	55	IMPORTANT: Like in the example above, make sure to single-quote the
e70712b3 PP	56	whole argument when you run this command from a shell, as it can contain
e70712b3 PP	57	many special characters.