|
Packit |
ae235b |
|
|
Packit |
ae235b |
<html>
|
|
Packit |
ae235b |
<head>
|
|
Packit |
ae235b |
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
|
|
Packit |
ae235b |
<title>GVariant Text Format: GLib Reference Manual</title>
|
|
Packit |
ae235b |
<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
|
|
Packit |
ae235b |
<link rel="home" href="index.html" title="GLib Reference Manual">
|
|
Packit |
ae235b |
<link rel="up" href="glib-data-types.html" title="GLib Data Types">
|
|
Packit |
ae235b |
<link rel="prev" href="gvariant-format-strings.html" title="GVariant Format Strings">
|
|
Packit |
ae235b |
<link rel="next" href="deprecated.html" title="Deprecated APIs">
|
|
Packit |
ae235b |
<meta name="generator" content="GTK-Doc V1.27 (XML mode)">
|
|
Packit |
ae235b |
<link rel="stylesheet" href="style.css" type="text/css">
|
|
Packit |
ae235b |
</head>
|
|
Packit |
ae235b |
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
GVariant Text Format
|
|
Packit |
ae235b |
GVariant Text Format — textual representation of GVariants
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
GVariant Text Format
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
This page attempts to document the GVariant text format as produced by
|
|
Packit |
ae235b |
g_variant_print() and parsed by the
|
|
Packit |
ae235b |
g_variant_parse() family of functions. In most
|
|
Packit |
ae235b |
cases the style closely resembles the formatting of literals in Python but there are some additions and
|
|
Packit |
ae235b |
exceptions.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
The functions that deal with GVariant text format absolutely always deal in utf-8. Conceptually, GVariant
|
|
Packit |
ae235b |
text format is a string of Unicode characters -- not bytes. Non-ASCII but otherwise printable Unicode
|
|
Packit |
ae235b |
characters are not treated any differently from normal ASCII characters.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
The parser makes two passes. The purpose of the first pass is to determine the type of the value being
|
|
Packit |
ae235b |
parsed. The second pass does the actual parsing. Based on the fact that all elements in an array have to
|
|
Packit |
ae235b |
have the same type, GVariant is able to make some deductions that would not otherwise be possible. As an
|
|
Packit |
ae235b |
example:
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
1
|
|
Packit |
ae235b |
[[1, 2, 3], [4, 5, 6]]
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
is parsed as an array of arrays of integers (type 'aai'), but
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
1
|
|
Packit |
ae235b |
[[1, 2, 3], [4, 5, 6.0]]
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
is parsed as a array of arrays of doubles (type 'aad').
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
As another example, GVariant is able to determine that
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
1
|
|
Packit |
ae235b |
["hello", nothing]
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
is an array of maybe strings (type 'ams').
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
What the parser accepts as valid input is dependent on context. The API permits for out-of-band type
|
|
Packit |
ae235b |
information to be supplied to the parser (which will change its behaviour). This can be seen in the
|
|
Packit |
ae235b |
GSettings and GDBus command line utilities where the type information is available from the schema or the
|
|
Packit |
ae235b |
remote introspection information. The additional information can cause parses to succeed when they would not
|
|
Packit |
ae235b |
otherwise have been able to (by resolving ambiguous type information) or can cause them to fail (due to
|
|
Packit |
ae235b |
conflicting type information). Unless stated otherwise, the examples given in this section assume that no
|
|
Packit |
ae235b |
out-of-band type data has been given to the parser.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Syntax Summary
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
The following table describes the rough meaning of symbols that may appear inside GVariant text format.
|
|
Packit |
ae235b |
Each symbol is described in detail in its own section, including usage examples.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Symbol
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Meaning
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
true,
|
|
Packit |
ae235b |
false
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Booleans.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
"",
|
|
Packit |
ae235b |
''
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
String literal. See Strings below.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
numbers
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
See Numbers below.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
()
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Tuples.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
[]
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Arrays.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
{}
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Dictionaries and Dictionary Entries.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
<>
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Variants.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
just,
|
|
Packit |
ae235b |
nothing
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Maybe Types.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
@
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Type Annotations.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
type keywords
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
boolean,
|
|
Packit |
ae235b |
byte,
|
|
Packit |
ae235b |
int16,
|
|
Packit |
ae235b |
uint16,
|
|
Packit |
ae235b |
int32,
|
|
Packit |
ae235b |
uint32,
|
|
Packit |
ae235b |
handle,
|
|
Packit |
ae235b |
int64,
|
|
Packit |
ae235b |
uint64,
|
|
Packit |
ae235b |
double,
|
|
Packit |
ae235b |
string,
|
|
Packit |
ae235b |
objectpath,
|
|
Packit |
ae235b |
signature
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
See Type Annotations below.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
b"",
|
|
Packit |
ae235b |
b''
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Bytestrings.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
%
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Positional Parameters.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Booleans
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
The strings true and false are parsed as booleans. This is the only
|
|
Packit |
ae235b |
way to specify a boolean value.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Strings
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Strings literals must be quoted using "" or ''. The two are
|
|
Packit |
ae235b |
completely equivalent (except for the fact that each one is unable to contain itself unescaped).
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Strings are Unicode strings with no particular encoding. For example, to specify the character
|
|
Packit |
ae235b |
é, you just write 'é'. You could also give the Unicode codepoint of
|
|
Packit |
ae235b |
that character (U+E9) as the escape sequence '\u00e9'. Since the strings are pure
|
|
Packit |
ae235b |
Unicode, you should not attempt to encode the utf-8 byte sequence corresponding to the string using escapes;
|
|
Packit |
ae235b |
it won't work and you'll end up with the individual characters corresponding to each byte.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Unicode escapes of the form \uxxxx and \Uxxxxxxxx are supported, in
|
|
Packit |
ae235b |
hexidecimal. The usual control sequence escapes \a, \b,
|
|
Packit |
ae235b |
\f, \n, \r, \t and
|
|
Packit |
ae235b |
\v are supported. Additionally, a \ before a newline character causes
|
|
Packit |
ae235b |
the newline to be ignored. Finally, any other character following \ is copied literally
|
|
Packit |
ae235b |
(for example, \" or \\) but for forwards compatibility with future
|
|
Packit |
ae235b |
additions you should only use this feature when necessary for escaping backslashes or quotes.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
The usual octal and hexidecimal escapes \0nnn and \xnn are not
|
|
Packit |
ae235b |
supported here. Those escapes are used to encode byte values and GVariant strings are Unicode.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Single-character strings are not interpreted as bytes. Bytes must be specified by their numerical value.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Numbers
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Numbers are given by default as decimal values. Octal and hex values can be given in the usual way (by
|
|
Packit |
ae235b |
prefixing with 0 or 0x). Note that GVariant considers bytes to be
|
|
Packit |
ae235b |
unsigned integers and will print them as a two digit hexidecimal number by default.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Floating point numbers can also be given in the usual ways, including scientific and hexidecimal notations.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
For lack of additional information, integers will be parsed as int32 values by default. If the number has a
|
|
Packit |
ae235b |
point or an 'e' in it, then it will be parsed as a double precision floating point number by default. If
|
|
Packit |
ae235b |
type information is available (either explicitly or inferred) then that type will be used instead.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Some examples:
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
5 parses as the int32 value five.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
37.5 parses as a floating point value.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
3.75e1 parses the same as the value above.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
uint64 7 parses seven as a uint64.
|
|
Packit |
ae235b |
See Type Annotations.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Tuples
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Tuples are formed using the same syntax as Python. Here are some examples:
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
() parses as the empty tuple.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
(5,) is a tuple containing a single value.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
("hello", 42) is a pair. Note that values of different types are permitted.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Arrays
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Arrays are formed using the same syntax as Python uses for lists (which is arguably the term that GVariant
|
|
Packit |
ae235b |
should have used). Note that, unlike Python lists, GVariant arrays are statically typed. This has two
|
|
Packit |
ae235b |
implications.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
First, all items in the array must have the same type. Second, the type of the array must be known, even in
|
|
Packit |
ae235b |
the case that it is empty. This means that (unless there is some other way to infer it) type information
|
|
Packit |
ae235b |
will need to be given explicitly for empty arrays.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
The parser is able to infer some types based on the fact that all items in an array must have the same type.
|
|
Packit |
ae235b |
See the examples below:
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
[1] parses (without additional type information) as a one-item array of signed integers.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
[1, 2, 3] parses (similarly) as a three-item array.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
[1, 2, 3.0] parses as an array of doubles. This is the most simple case of the type
|
|
Packit |
ae235b |
inferencing in action.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
[(1, 2), (3, 4.0)] causes the 2 to also be parsed as a double (but the 1 and 4 are still
|
|
Packit |
ae235b |
integers).
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
["", nothing] parses as an array of maybe strings. The presence of
|
|
Packit |
ae235b |
"nothing" clearly implies that the array elements are nullable.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
[[], [""]] will parse properly because the type of the first (empty) array can be
|
|
Packit |
ae235b |
inferred to be equal to the type of the second array (both are arrays of strings).
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
[b'hello', []] looks odd but will parse properly.
|
|
Packit |
ae235b |
See Bytestrings
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
And some examples of errors:
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
["hello", 42] fails to parse due to conflicting types.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
[] will fail to parse without additional type information.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Dictionaries and Dictionary Entries
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Dictionaries and dictionary entries are both specified using the {} characters.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
The dictionary syntax is more commonly used. This is what the printer elects to use in the normal case of
|
|
Packit |
ae235b |
dictionary entries appearing in an array (aka "a dictionary"). The separate syntax for dictionary entries
|
|
Packit |
ae235b |
is typically only used for when the entries appear on their own, outside of an array (which is valid but
|
|
Packit |
ae235b |
unusual). Of course, you are free to use the dictionary entry syntax within arrays but there is no good
|
|
Packit |
ae235b |
reason to do so (and the printer itself will never do so). Note that, as with arrays, the type of empty
|
|
Packit |
ae235b |
dictionaries must be established (either explicitly or through inference).
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
The dictionary syntax is the same as Python's syntax for dictionaries. Some examples:
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
@a{sv} {} parses as the empty dictionary of everyone's favourite type.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
@a{sv} [] is the same as above (owing to the fact that dictionaries are really arrays).
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
{1: "one", 2: "two", 3: "three"} parses as a dictionary mapping integers to strings.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
The dictionary entry syntax looks just like a pair (2-tuple) that uses braces instead of parens. The
|
|
Packit |
ae235b |
presence of a comma immediately following the key differentiates it from the dictionary syntax (which
|
|
Packit |
ae235b |
features a colon after the first key). Some examples:
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
{1, "one"} is a free-standing dictionary entry that can be parsed on its own or as part
|
|
Packit |
ae235b |
of another container value.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
[{1, "one"}, {2, "two"}, {3, "three"}] is exactly equivalent to the dictionary example
|
|
Packit |
ae235b |
given above.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Variants
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Variants are denoted using angle brackets (aka "XML brackets"), <>. They may not
|
|
Packit |
ae235b |
be omitted.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Using <> effectively disrupts the type inferencing that occurs between array
|
|
Packit |
ae235b |
elements. This can have positive and negative effects.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
[<"hello">, <42>] will parse whereas ["hello", 42] would
|
|
Packit |
ae235b |
not.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
[<['']>, <[]>] will fail to parse even though [[''], []]
|
|
Packit |
ae235b |
parses successfully. You would need to specify [<['']>, <@as []>].
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
{"title": <"frobit">, "enabled": <true>, width: <800>} is an example of
|
|
Packit |
ae235b |
perhaps the most pervasive use of both dictionaries and variants.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Maybe Types
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
The syntax for specifying maybe types is inspired by Haskell.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
The null case is specified using the keyword nothing and the non-null case is explicitly
|
|
Packit |
ae235b |
specified using the keyword just. GVariant allows just to be omitted
|
|
Packit |
ae235b |
in every case that it is able to unambiguously determine the intention of the writer. There are two cases
|
|
Packit |
ae235b |
where it must be specified:
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
when using nested maybes, in order to specify the just nothing case
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
to establish the nullability of the type of a value without explicitly specifying its full type
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Some examples:
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
just 'hello' parses as a non-null nullable string.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
@ms 'hello' is the same (demonstrating how just can be dropped if the type is already
|
|
Packit |
ae235b |
known).
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
nothing will not parse wtihout extra type information.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
@ms nothing parses as a null nullable string.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
[just 3, nothing] is an array of nullable integers
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
[3, nothing] is the same as the above (demonstrating another place were
|
|
Packit |
ae235b |
just can be dropped).
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
[3, just nothing] parses as an array of maybe maybe integers (type
|
|
Packit |
ae235b |
'ammi').
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Type Annotations
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Type annotations allow additional type information to be given to the parser. Depending on the context,
|
|
Packit |
ae235b |
this type information can change the output of the parser, cause an error when parsing would otherwise have
|
|
Packit |
ae235b |
succeeded or resolve an error when parsing would have otherwise failed.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Type annotations come in two forms: type codes and type keywords.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Type keywords can be seen as more verbose (and more legible) versions of a common subset of the type codes.
|
|
Packit |
ae235b |
The type keywords boolean, byte, int16,
|
|
Packit |
ae235b |
uint16, int32, uint32, handle,
|
|
Packit |
ae235b |
int64, uint64, double, string,
|
|
Packit |
ae235b |
objectpath and literal signature are each exactly equivalent to their
|
|
Packit |
ae235b |
corresponding type code.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Type codes are an @ ("at" sign) followed by a definite GVariant type string. Some
|
|
Packit |
ae235b |
examples:
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
uint32 5 causes the number to be parsed unsigned instead of signed (the default).
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
@u 5 is the same
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
objectpath "/org/gnome/xyz" creates an object path instead of a normal string
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
@au [] specifies the type of the empty array (which would not parse otherwise)
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
@ms "" indicates that a string value is meant to have a maybe type
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Bytestrings
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
The bytestring syntax is a piece of syntactic sugar meant to complement the bytestring APIs in GVariant. It
|
|
Packit |
ae235b |
constructs arrays of non-nul bytes (type 'ay') with a nul terminator at the end.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Bytestrings are specified with either b"" or b''. As with strings,
|
|
Packit |
ae235b |
there is no fundamental difference between the two different types of quotes.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Bytestrings support the full range of escapes that you would expect (ie: those supported by
|
|
Packit |
ae235b |
g_strcompress(). This includes the normal control
|
|
Packit |
ae235b |
sequence escapes (as mentioned in the section on strings) as well as octal and hexidecimal escapes of the
|
|
Packit |
ae235b |
forms \0nnn and \xnn.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
b'abc' is equivalent to [byte 0x97, 0x98, 0x99, 0].
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
When formatting arrays of bytes, the printer will choose to display the array as a bytestring if it contains
|
|
Packit |
ae235b |
a nul character at the end and no other nul bytes within. Otherwise, it is formatted as a normal array.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Positional Parameters
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Positional parameters are not a part of the normal GVariant text format, but they are mentioned here because
|
|
Packit |
ae235b |
they can be used with g_variant_new_parsed().
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
A positional parameter is indicated with a % followed by any valid
|
|
Packit |
ae235b |
GVariant Format String. Variable arguments are collected as
|
|
Packit |
ae235b |
specified by the format string and the resulting value is inserted at the current position.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
This feature is best explained by example:
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
1
|
|
Packit |
ae235b |
2
|
|
Packit |
ae235b |
3
|
|
Packit |
ae235b |
4
|
|
Packit |
ae235b |
5
|
|
Packit |
ae235b |
char *t = "xyz";
|
|
Packit |
ae235b |
gboolean en = false;
|
|
Packit |
ae235b |
GVariant *value;
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
value = g_variant_new_parsed ("{'title': <%s>, 'enabled': <%b>}", t, en);
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
This constructs a dictionary mapping strings to variants (type 'a{sv}') with two items in
|
|
Packit |
ae235b |
it. The key names are parsed from the string and the values for those keys are taken as variable arguments
|
|
Packit |
ae235b |
parameters.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
The arguments are always collected in the order that they appear in the string to be parsed. Format strings
|
|
Packit |
ae235b |
that collect multiple arguments are permitted, so you may require more varargs parameters than the number of
|
|
Packit |
ae235b |
% signs that appear. You can also give format strings that collect no arguments, but
|
|
Packit |
ae235b |
there's no good reason to do so.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Generated by GTK-Doc V1.27
|
|
Packit |
ae235b |
</body>
|
|
Packit |
ae235b |
</html>
|