[glib] GVariant: doc the format of g_variant_parse/print
- From: Ryan Lortie <ryanl src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [glib] GVariant: doc the format of g_variant_parse/print
- Date: Fri, 11 Feb 2011 18:54:55 +0000 (UTC)
commit ea4e3ea1cb7d3264cb4c84d0b257e886a2be88e8
Author: Ryan Lortie <desrt desrt ca>
Date: Fri Feb 11 10:27:44 2011 -0500
GVariant: doc the format of g_variant_parse/print
docs/reference/glib/Makefile.am | 3 +-
docs/reference/glib/glib-docs.sgml | 1 +
docs/reference/glib/gvariant-text.xml | 615 +++++++++++++++++++++++++++++++++
glib/gvariant-parser.c | 2 +
glib/gvariant.c | 2 +
5 files changed, 622 insertions(+), 1 deletions(-)
---
diff --git a/docs/reference/glib/Makefile.am b/docs/reference/glib/Makefile.am
index 27fdf0b..4372db5 100644
--- a/docs/reference/glib/Makefile.am
+++ b/docs/reference/glib/Makefile.am
@@ -66,7 +66,8 @@ content_files = \
glib-gettextize.xml \
gtester.xml \
gtester-report.xml \
- gvariant-varargs.xml
+ gvariant-varargs.xml \
+ gvariant-text.xml
# Extra options to supply to gtkdoc-fixref
FIXXREF_OPTIONS=
diff --git a/docs/reference/glib/glib-docs.sgml b/docs/reference/glib/glib-docs.sgml
index 9474af9..f3197d9 100644
--- a/docs/reference/glib/glib-docs.sgml
+++ b/docs/reference/glib/glib-docs.sgml
@@ -125,6 +125,7 @@ synchronize their operation.
<xi:include href="xml/gvarianttype.xml"/>
<xi:include href="xml/gvariant.xml"/>
<xi:include href="gvariant-varargs.xml"/>
+ <xi:include href="gvariant-text.xml"/>
</chapter>
<chapter id="tools">
diff --git a/docs/reference/glib/gvariant-text.xml b/docs/reference/glib/gvariant-text.xml
new file mode 100644
index 0000000..6c60683
--- /dev/null
+++ b/docs/reference/glib/gvariant-text.xml
@@ -0,0 +1,615 @@
+<?xml version='1.0' encoding='utf-8'?>
+
+<refentry id='gvariant-text'>
+ <refmeta>
+ <refentrytitle>GVariant Text Format</refentrytitle>
+ </refmeta>
+
+ <refsect1>
+ <title>GVariant Text Format</title>
+
+ <para>
+ This page attempts to document the GVariant text format as produced by
+ <link linkend='g-variant-print'><function>g_variant_print()</function></link> and parsed by the
+ <link linkend='g-variant-parse'><function>g_variant_parse()</function></link> family of functions. In most
+ cases the style closely resembles the formatting of literals in Python but there are some additions and
+ exceptions.
+ </para>
+
+ <para>
+ The functions that deal with GVariant text format absolutely always deal in utf-8. Conceptually, GVariant
+ text format is a string of unicode characters -- not bytes. Non-ASCII but otherwise printable unicode
+ characters are not treated any differently from normal ASCII characters.
+ </para>
+
+ <para>
+ The parser makes two passes. The purpose of the first pass is to determine the type of the value being
+ parsed. The second pass does the actual parsing. Based on the fact that all elements in an array have to
+ have the same type, GVariant is able to make some deductions that would not otherwise be possible. As an
+ example:
+
+ <informalexample><programlisting>[[1, 2, 3], [4, 5, 6]]</programlisting></informalexample>
+
+ is parsed as an array of arrays of integers (type '<literal>aai</literal>'), but
+
+ <informalexample><programlisting>[[1, 2, 3], [4, 5, 6.0]]</programlisting></informalexample>
+
+ is parsed as a array of arrays of doubles (type '<literal>aad</literal>').
+ </para>
+
+ <para>
+ As another example, GVariant is able to determine that
+
+ <informalexample><programlisting>["hello", nothing]</programlisting></informalexample>
+
+ is an array of maybe strings (type '<literal>ams</literal>').
+ </para>
+
+ <para>
+ What the parser accepts as valid input is dependent on context. The API permits for out-of-band type
+ information to be supplied to the parser (which will change its behaviour). This can be seen in the
+ GSettings and GDBus command line utilities where the type information is available from the schema or the
+ remote introspection information. The additional information can cause parses to succeed when they would not
+ otherwise have been able to (by resolving ambiguous type information) or can cause them to fail (due to
+ conflicting type information). Unless stated otherwise, the examples given in this section assume that no
+ out-of-band type data has been given to the parser.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Syntax Summary</title>
+
+ <para>
+ The following table describes the rough meaning of symbols that may appear inside GVariant text format.
+ Each symbol is described in detail in its own section, including usage examples.
+ </para>
+
+ <informaltable>
+ <tgroup cols='2'>
+ <colspec colname='col_0'/>
+ <colspec colname='col_1'/>
+ <tbody>
+
+ <row rowsep='1'>
+ <entry colsep='1' rowsep='1'>
+ <para>
+ <emphasis role='strong'>Symbol</emphasis>
+ </para>
+ </entry>
+ <entry colsep='1' rowsep='1'>
+ <para>
+ <emphasis role='strong'>Meaning</emphasis>
+ </para>
+ </entry>
+ </row>
+
+ <row rowsep='1'>
+ <entry colsep='1' rowsep='1'>
+ <para>
+ <emphasis role='strong'><literal>true</literal></emphasis>,
+ <emphasis role='strong'><literal>false</literal></emphasis>
+ </para>
+ </entry>
+ <entry colsep='1' rowsep='1'>
+ <para>
+ <link linkend='gvariant-text-booleans'>Booleans</link>.
+ </para>
+ </entry>
+ </row>
+
+ <row rowsep='1'>
+ <entry colsep='1' rowsep='1'>
+ <para>
+ <emphasis role='strong'><literal>""</literal></emphasis>,
+ <emphasis role='strong'><literal>''</literal></emphasis>
+ </para>
+ </entry>
+ <entry colsep='1' rowsep='1'>
+ <para>
+ String literal. See <link linkend='gvariant-text-strings'>Strings</link> below.
+ </para>
+ </entry>
+ </row>
+
+ <row rowsep='1'>
+ <entry colsep='1' rowsep='1'>
+ <para>
+ numbers
+ </para>
+ </entry>
+ <entry colsep='1' rowsep='1'>
+ <para>
+ See <link linkend='gvariant-text-numbers'>Numbers</link> below.
+ </para>
+ </entry>
+ </row>
+
+ <row rowsep='1'>
+ <entry colsep='1' rowsep='1'>
+ <para>
+ <emphasis role='strong'><literal>()</literal></emphasis>
+ </para>
+ </entry>
+ <entry colsep='1' rowsep='1'>
+ <para>
+ <link linkend='gvariant-text-tuples'>Tuples</link>.
+ </para>
+ </entry>
+ </row>
+
+ <row rowsep='1'>
+ <entry colsep='1' rowsep='1'>
+ <para>
+ <emphasis role='strong'><literal>[]</literal></emphasis>
+ </para>
+ </entry>
+ <entry colsep='1' rowsep='1'>
+ <para>
+ <link linkend='gvariant-text-arrays'>Arrays</link>.
+ </para>
+ </entry>
+ </row>
+
+ <row rowsep='1'>
+ <entry colsep='1' rowsep='1'>
+ <para>
+ <emphasis role='strong'><literal>{}</literal></emphasis>
+ </para>
+ </entry>
+ <entry colsep='1' rowsep='1'>
+ <para>
+ <link linkend='gvariant-text-dictionaries'>Dictionaries and Dictionary Entries</link>.
+ </para>
+ </entry>
+ </row>
+
+ <row rowsep='1'>
+ <entry colsep='1' rowsep='1'>
+ <para>
+ <emphasis role='strong'><literal><></literal></emphasis>
+ </para>
+ </entry>
+ <entry colsep='1' rowsep='1'>
+ <para>
+ <link linkend='gvariant-text-variants'>Variants</link>.
+ </para>
+ </entry>
+ </row>
+
+ <row rowsep='1'>
+ <entry colsep='1' rowsep='1'>
+ <para>
+ <emphasis role='strong'><literal>just</literal></emphasis>,
+ <emphasis role='strong'><literal>nothing</literal></emphasis>
+ </para>
+ </entry>
+ <entry colsep='1' rowsep='1'>
+ <para>
+ <link linkend='gvariant-text-maybe-types'>Maybe Types</link>.
+ </para>
+ </entry>
+ </row>
+
+ <row rowsep='1'>
+ <entry colsep='1' rowsep='1'>
+ <para>
+ <emphasis role='strong'><literal>@</literal></emphasis>
+ </para>
+ </entry>
+ <entry colsep='1' rowsep='1'>
+ <para>
+ <link linkend='gvariant-text-type-annotations'>Type Annotations</link>.
+ </para>
+ </entry>
+ </row>
+
+ <row rowsep='1'>
+ <entry colsep='1' rowsep='1'>
+ <para>
+ type keywords
+ </para>
+ </entry>
+ <entry colsep='1' rowsep='1'>
+ <para>
+ <literal>boolean</literal>,
+ <literal>byte</literal>,
+ <literal>int16</literal>,
+ <literal>uint16</literal>,
+ <literal>int32</literal>,
+ <literal>uint32</literal>,
+ <literal>handle</literal>,
+ <literal>int64</literal>,
+ <literal>uint64</literal>,
+ <literal>double</literal>,
+ <literal>string</literal>,
+ <literal>objectpath</literal>,
+ <literal>signature</literal>
+ </para>
+ <para>
+ See <link linkend='gvariant-text-type-annotations'>Type Annotations</link> below.
+ </para>
+ </entry>
+ </row>
+
+ <row rowsep='1'>
+ <entry colsep='1' rowsep='1'>
+ <para>
+ <emphasis role='strong'><literal>b""</literal></emphasis>,
+ <emphasis role='strong'><literal>b''</literal></emphasis>
+ </para>
+ </entry>
+ <entry colsep='1' rowsep='1'>
+ <para>
+ <link linkend='gvariant-text-bytestrings'>Bytestrings</link>.
+ </para>
+ </entry>
+ </row>
+
+ <row rowsep='1'>
+ <entry colsep='1' rowsep='1'>
+ <para>
+ <emphasis role='strong'><literal>%</literal></emphasis>
+ </para>
+ </entry>
+ <entry colsep='1' rowsep='1'>
+ <para>
+ <link linkend='gvariant-text-positional'>Positional Parameters</link>.
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <refsect2 id='gvariant-text-booleans'>
+ <title>Booleans</title>
+ <para>
+ The strings <literal>true</literal> and <literal>false</literal> are parsed as booleans. This is the only
+ way to specify a boolean value.
+ </para>
+ </refsect2>
+
+ <refsect2 id='gvariant-text-strings'>
+ <title>Strings</title>
+ <para>
+ Strings literals must be quoted using <literal>""</literal> or <literal>''</literal>. The two are
+ completely equivalent (except for the fact that each one is unable to contain itself unescaped).
+ </para>
+ <para>
+ Strings are unicode strings with no particular encoding. For example, to specify the character
+ <literal>é</literal>, you just write <literal>'é'</literal>. You could also give the unicode codepoint of
+ that character (U+E9) as the escape sequence <literal>'\u00e9'</literal>. Since the strings are pure
+ unicode, you should not attempt to encode the utf-8 byte sequence corresponding to the string using escapes;
+ it won't work and you'll end up with the individual characters corresponding to each byte.
+ </para>
+ <para>
+ Unicode escapes of the form <literal>\uxxxx</literal> and <literal>\Uxxxxxxxx</literal> are supported, in
+ hexidecimal. The usual control sequence escapes <literal>\a</literal>, <literal>\b</literal>,
+ <literal>\f</literal>, <literal>\n</literal>, <literal>\r</literal>, <literal>\t</literal> and
+ <literal>\v</literal> are supported. Additionally, a <literal>\</literal> before a newline character causes
+ the newline to be ignored. Finally, any other character following <literal>\</literal> is copied literally
+ (for example, <literal>\"</literal> or <literal>\\</literal>) but for forwards compatibility with future
+ additions you should only use this feature when necessary for escaping backslashes or quotes.
+ </para>
+ <para>
+ The usual octal and hexidecimal escapes <literal>\0nnn</literal> and <literal>\xnn</literal> are not
+ supported here. Those escapes are used to encode byte values and GVariant strings are unicode.
+ </para>
+ <para>
+ Single-character strings are not interpreted as bytes. Bytes must be specified by their numerical value.
+ </para>
+ </refsect2>
+
+ <refsect2 id='gvariant-text-numbers'>
+ <title>Numbers</title>
+ <para>
+ Numbers are given by default as decimal values. Octal and hex values can be given in the usual way (by
+ prefixing with <literal>0</literal> or <literal>0x</literal>). Note that GVariant considers bytes to be
+ unsigned integers and will print them as a two digit hexidecimal number by default.
+ </para>
+ <para>
+ Floating point numbers can also be given in the usual ways, including scientific and hexidecimal notations.
+ </para>
+ <para>
+ For lack of additional information, integers will be parsed as int32 values by default. If the number has a
+ point or an 'e' in it, then it will be parsed as a double precision floating point number by default. If
+ type information is available (either explicitly or inferred) then that type will be used instead.
+ </para>
+ <para>
+ Some examples:
+ </para>
+ <para>
+ <literal>5</literal> parses as the int32 value five.
+ </para>
+ <para>
+ <literal>37.5</literal> parses as a floating point value.
+ </para>
+ <para>
+ <literal>3.75e1</literal> parses the same as the value above.
+ </para>
+ <para>
+ <literal>uint32 7</literal> parses seven as a uint64.
+ See <link linkend='gvariant-text-type-annotations'>Type Annotations</link>.
+ </para>
+ </refsect2>
+
+ <refsect2 id='gvariant-text-tuples'>
+ <title>Tuples</title>
+ <para>
+ Tuples are formed using the same syntax as Python. Here are some examples:
+ </para>
+ <para>
+ <literal>()</literal> parses as the empty tuple.
+ </para>
+ <para>
+ <literal>(5,)</literal> is a tuple containing a single value.
+ </para>
+ <para>
+ <literal>("hello", 42)</literal> is a pair. Note that values of different types are permitted.
+ </para>
+ </refsect2>
+
+ <refsect2 id='gvariant-text-arrays'>
+ <title>Arrays</title>
+ <para>
+ Arrays are formed using the same syntax as Python uses for lists (which is arguably the term that GVariant
+ should have used). Note that, unlike Python lists, GVariant arrays are statically typed. This has two
+ implications.
+ </para>
+ <para>
+ First, all items in the array must have the same type. Second, the type of the array must be known, even in
+ the case that it is empty. This means that (unless there is some other way to infer it) type information
+ will need to be given explicitly for empty arrays.
+ </para>
+ <para>
+ The parser is able to infer some types based on the fact that all items in an array must have the same type.
+ See the examples below:
+ </para>
+ <para>
+ <literal>[1]</literal> parses (without additional type information) as a one-item array of signed integers.
+ </para>
+ <para>
+ <literal>[1, 2, 3]</literal> parses (similarly) as a three-item array.
+ </para>
+ <para>
+ <literal>[1, 2, 3.0]</literal> parses as an array of doubles. This is the most simple case of the type
+ inferencing in action.
+ </para>
+ <para>
+ <literal>[(1, 2), (3, 4.0)]</literal> causes the 2 to also be parsed as a double (but the 1 and 4 are still
+ integers).
+ </para>
+ <para>
+ <literal>["", nothing]</literal> parses as an array of maybe strings. The presence of
+ "<literal>nothing</literal>" clearly implies that the array elements are nullable.
+ </para>
+ <para>
+ <literal>[[], [""]]</literal> will parse properly because the type of the first (empty) array can be
+ inferred to be equal to the type of the second array (both are arrays of strings).
+ </para>
+ <para>
+ <literal>[b'hello', []]</literal> looks odd but will parse properly.
+ See <link linkend='gvariant-text-bytestrings'>Bytestrings</link>
+ </para>
+ <para>
+ And some examples of errors:
+ </para>
+ <para>
+ <literal>["hello", 42]</literal> fails to parse due to conflicting types.
+ </para>
+ <para>
+ <literal>[]</literal> will fail to parse without additional type information.
+ </para>
+ </refsect2>
+
+ <refsect2 id='gvariant-text-dictionaries'>
+ <title>Dictionaries and Dictionary Entries</title>
+ <para>
+ Dictionaries and dictionary entries are both specified using the <literal>{}</literal> characters.
+ </para>
+ <para>
+ The dictionary syntax is more commonly used. This is what the printer elects to use in the normal case of
+ dictionary entries appearing in an array (aka "a dictionary"). The separate syntax for dictionary entries
+ is typically only used for when the entries appear on their own, outside of an array (which is valid but
+ unusual). Of course, you are free to use the dictionary entry syntax within arrays but there is no good
+ reason to do so (and the printer itself will never do so). Note that, as with arrays, the type of empty
+ dictionaries must be established (either explicitly or through inference).
+ </para>
+ <para>
+ The dictionary syntax is the same as Python's syntax for dictionaries. Some examples:
+ </para>
+ <para>
+ <literal>@a{sv} {}</literal> parses as the empty dictionary of everyone's favourite type.
+ </para>
+ <para>
+ <literal>@a{sv} []</literal> is the same as above (owing to the fact that dictionaries are really arrays).
+ </para>
+ <para>
+ <literal>{1: "one", 2: "two", 3: "three"}</literal> parses as a dictionary mapping integers to strings.
+ </para>
+ <para>
+ The dictionary entry syntax looks just like a pair (2-tuple) that uses braces instead of parens. The
+ presence of a comma immediately following the key differentiates it from the dictionary syntax (which
+ features a colon after the first key). Some examples:
+ </para>
+ <para>
+ <literal>{1, "one"}</literal> is a free-standing dictionary entry that can be parsed on its own or as part
+ of another container value.
+ </para>
+ <para>
+ <literal>[{1, "one"}, {2, "two"}, {3, "three"}]</literal> is exactly equivalent to the dictionary example
+ given above.
+ </para>
+ </refsect2>
+
+ <refsect2 id='gvariant-text-variants'>
+ <title>Variants</title>
+ <para>
+ Variants are denoted using angle brackets (aka "XML brackets"), <literal><></literal>. They may not
+ be omitted.
+ </para>
+ <para>
+ Using <literal><></literal> effectively disrupts the type inferencing that occurs between array
+ elements. This can have positive and negative effects.
+ </para>
+ <para>
+ <literal>[<"hello">, <42>]</literal> will parse whereas <literal>["hello", 42]</literal> would
+ not.
+ </para>
+ <para>
+ <literal>[<['']>, <[]>]</literal> will fail to parse even though <literal>[[''], []]</literal>
+ parses successfully. You would need to specify <literal>[<['']>, <@as []>]</literal>.
+ </para>
+ <para>
+ <literal>{"title": <"frobit">, "enabled": <true>, width: <800>}</literal> is an example of
+ perhaps the most pervasive use of both dictionaries and variants.
+ </para>
+ </refsect2>
+
+ <refsect2 id='gvariant-text-maybe-types'>
+ <title>Maybe Types</title>
+ <para>
+ The syntax for specifying maybe types is inspired by Haskell.
+ </para>
+ <para>
+ The null case is specified using the keyword <literal>nothing</literal> and the non-null case is explicitly
+ specified using the keyword <literal>just</literal>. GVariant allows <literal>just</literal> to be omitted
+ in every case that it is able to unambiguously determine the intention of the writer. There are two cases
+ where it must be specified:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>when using nested maybes, in order to specify the <literal>just nothing</literal> case</para>
+ </listitem>
+ <listitem>
+ <para>
+ to establish the nullability of the type of a value without explicitly specifying its full type
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ Some examples:
+ </para>
+ <para>
+ <literal>just 'hello'</literal> parses as a non-null nullable string.
+ </para>
+ <para>
+ <literal>@ms 'hello'</literal> is the same (demonstrating how <literal>just</literal> can be dropped if the type is already
+ known).
+ </para>
+ <para>
+ <literal>nothing</literal> will not parse wtihout extra type information.
+ </para>
+ <para>
+ <literal>@ms nothing</literal> parses as a null nullable string.
+ </para>
+ <para>
+ <literal>[just 3, nothing]</literal> is an array of nullable integers
+ </para>
+ <para>
+ <literal>[3, nothing]</literal> is the same as the above (demonstrating another place were
+ <literal>just</literal> can be dropped).
+ </para>
+ <para>
+ <literal>[3, just nothing]</literal> parses as an array of maybe maybe integers (type
+ <literal>'ammi'</literal>).
+ </para>
+ </refsect2>
+
+ <refsect2 id='gvariant-text-type-annotations'>
+ <title>Type Annotations</title>
+ <para>
+ Type annotations allow additional type information to be given to the parser. Depending on the context,
+ this type information can change the output of the parser, cause an error when parsing would otherwise have
+ succeeded or resolve an error when parsing would have otherwise failed.
+ </para>
+ <para>
+ Type annotations come in two forms: type codes and type keywords.
+ </para>
+ <para>
+ Type keywords can be seen as more verbose (and more legible) versions of a common subset of the type codes.
+ The type keywords <literal>boolean</literal>, <literal>byte</literal>, <literal>int16</literal>,
+ <literal>uint16</literal>, <literal>int32</literal>, <literal>uint32</literal>, <literal>handle</literal>,
+ <literal>int64</literal>, <literal>uint64</literal>, <literal>double</literal>, <literal>string</literal>,
+ <literal>objectpath</literal> and literal <literal>signature</literal> are each exactly equivalent to their
+ corresponding type code.
+ </para>
+ <para>
+ Type codes are an <literal>@</literal> ("at" sign) followed by a definite GVariant type string. Some
+ examples:
+ </para>
+ <para>
+ <literal>uint32 5</literal> causes the number to be parsed unsigned instead of signed (the default).
+ </para>
+ <para>
+ <literal>@u 5</literal> is the same
+ </para>
+ <para>
+ <literal>objectpath "/org/gnome/xyz"</literal> creates an object path instead of a normal string
+ </para>
+ <para>
+ <literal>@au []</literal> specifies the type of the empty array (which would not parse otherwise)
+ </para>
+ <para>
+ <literal>@ms ""</literal> indicates that a string value is meant to have a maybe type
+ </para>
+ </refsect2>
+
+ <refsect2 id='gvariant-text-bytestrings'>
+ <title>Bytestrings</title>
+ <para>
+ The bytestring syntax is a piece of syntactic sugar meant to complement the bytestring APIs in GVariant. It
+ constructs arrays of non-nul bytes (type '<literal>ay</literal>') with a nul terminator at the end.
+ </para>
+ <para>
+ Bytestrings are specified with either <literal>b""</literal> or <literal>b''</literal>. As with strings,
+ there is no fundamental difference between the two different types of quotes.
+ </para>
+ <para>
+ Bytestrings support the full range of escapes that you would expect (ie: those supported by
+ <link linkend='g-strcompress'><function>g_strcompress()</function></link>. This includes the normal control
+ sequence escapes (as mentioned in the section on strings) as well as octal and hexidecimal escapes of the
+ forms <literal>\0nnn</literal> and <literal>\xnn</literal>.
+ </para>
+ <para>
+ <literal>b'abc'</literal> is equivalent to <literal>[byte 0x97, 0x98, 0x99, 0]</literal>.
+ </para>
+ <para>
+ When formatting arrays of bytes, the printer will choose to display the array as a bytestring if it contains
+ a nul character at the end and no other nul bytes within. Otherwise, it is formatted as a normal array.
+ </para>
+ </refsect2>
+
+ <refsect2 id='gvariant-text-positional'>
+ <title>Positional Parameters</title>
+ <para>
+ Positional parameters are not a part of the normal GVariant text format, but they are mentioned here because
+ they can be used with <link linkend='g-variant-new-parsed'><function>g_variant_new_parsed()</function></link>.
+ </para>
+ <para>
+ A positional parameter is indicated with a <literal>%</literal> followed by any valid
+ <link linkend='gvariant-format-strings'>GVariant Format String</link>. Variable arguments are collected as
+ specified by the format string and the resulting value is inserted at the current position.
+ </para>
+ <para>
+ This feature is best explained by example:
+ </para>
+ <informalexample><programlisting><![CDATA[char *t = "xyz";
+gboolean en = false;
+GVariant *value;
+
+value = g_variant_new_parsed ("{'title': <%s>, 'enabled': <%b>}", t, en);]]></programlisting></informalexample>
+ <para>
+ This constructs a dictionary mapping strings to variants (type '<literal>a{sv}</literal>') with two items in
+ it. The key names are parsed from the string and the values for those keys are taken as variable arguments
+ parameters.
+ </para>
+ <para>
+ The arguments are always collected in the order that they appear in the string to be parsed. Format strings
+ that collect multiple arguments are permitted, so you may require more varargs parameters than the number of
+ <literal>%</literal> signs that appear. You can also give format strings that collect no arguments, but
+ there's no good reason to do so.
+ </para>
+ </refsect2>
+ </refsect1>
+</refentry>
diff --git a/glib/gvariant-parser.c b/glib/gvariant-parser.c
index ca69dfb..7cd424b 100644
--- a/glib/gvariant-parser.c
+++ b/glib/gvariant-parser.c
@@ -2290,6 +2290,8 @@ parse (TokenStream *stream,
*
* A single #GVariant is parsed from the content of @text.
*
+ * The format is described <link linkend='gvariant-text'>here</link>.
+ *
* The memory at @limit will never be accessed and the parser behaves as
* if the character at @limit is the nul terminator. This has the
* effect of bounding @text.
diff --git a/glib/gvariant.c b/glib/gvariant.c
index 6bfc900..fc74611 100644
--- a/glib/gvariant.c
+++ b/glib/gvariant.c
@@ -2234,6 +2234,8 @@ g_variant_print_string (GVariant *value,
*
* Pretty-prints @value in the format understood by g_variant_parse().
*
+ * The format is described <link linkend='gvariant-text'>here</link>.
+ *
* If @type_annotate is %TRUE, then type information is included in
* the output.
*/
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
