-image: fedora:31
+image: fedora:34
stages:
- build
+ - docs
+ - deploy
-before_script:
- - dnf install -y gcc gettext glib2-devel gobject-introspection-devel gtk-doc meson ninja-build redhat-rpm-config
-
-build-json-glib:
- stage: build
+.build-default:
+ before_script:
+ - dnf install -y ${FEDORA_DEPS}
+ - pip3 install --user meson==${MESON_VERSION}
+ - export PATH="$PATH:$HOME/.local/bin"
script:
- - meson --prefix /usr -Dman=true _build .
- - cd _build
- - ninja
- - meson test
- except:
- - tags
+ - meson setup ${MESON_EXTRA_FLAGS} --prefix /usr _build .
+ - meson compile -C _build
+ - meson test -C _build
+ - meson install -C _build
artifacts:
- when: on_failure
+ when: always
name: "json-glib-${CI_COMMIT_REF_NAME}"
paths:
- "${CI_PROJECT_DIR}/_build/meson-logs"
-dist-json-glib:
+fedora-x86_64:
+ extends: .build-default
stage: build
- only:
- - tags
+ needs: []
+ variables:
+ FEDORA_DEPS:
+ gcc
+ gettext
+ git
+ glib2-devel
+ gobject-introspection-devel
+ ninja-build
+ python3
+ python3-pip
+ python3-wheel
+ redhat-rpm-config
+ MESON_VERSION: "0.55.3"
+ MESON_EXTRA_FLAGS: "--buildtype=debug --default-library=both -Dwerror=true -Dglib:werror=false -Dintrospection=enabled"
+
+reference:
+ extends: .build-default
+ stage: docs
+ needs: []
+ variables:
+ FEDORA_DEPS:
+ docbook-style-xsl
+ gcc
+ gettext
+ git
+ glib2-devel
+ gobject-introspection-devel
+ graphviz
+ ninja-build
+ python3
+ python3-jinja2
+ python3-markdown
+ python3-markupsafe
+ python3-pip
+ python3-pygments
+ python3-toml
+ python3-typogrify
+ python3-wheel
+ redhat-rpm-config
+ libxslt
+ MESON_VERSION: "0.55.3"
+ MESON_EXTRA_FLAGS: "-Dgtk_doc=enabled -Dman=true -Dintrospection=enabled"
+ after_script:
+ - mkdir _reference
+ - mv _build/doc/json-glib-1.0/ _reference/
+ artifacts:
+ paths:
+ - _reference
+
+pages:
+ stage: deploy
+ needs: ['reference']
script:
- - meson --prefix /usr --buildtype release -Dman=true -Ddocs=true _build .
- - cd _build
- - ninja dist
- - ninja json-glib-doc
- - tar -c -f "json-glib-docs-${CI_COMMIT_TAG}.tar.xz" -C docs html
+ - mv _reference public
artifacts:
paths:
- - "${CI_PROJECT_DIR}/_build/json-glib-docs-${CI_COMMIT_TAG}.tar.xz"
- - "${CI_PROJECT_DIR}/_build/meson-dist/json-glib-*.tar.xz"
+ - public
+ only:
+ - master
--- /dev/null
+# Contributing
+
+If you find a bug in JSON-GLib, please file an issue on the
+[Issues page][gitlab-issues].
+
+Required information:
+
+ * the version of JSON-GLib
+ * if it is a development version, the branch of the git repository
+ * the JSON data that produced the bug (if any)
+ * a small, self-contained test case, if none of the test units exhibit the
+ buggy behaviour
+ * in case of a segmentation fault, a full stack trace with debugging
+ symbols obtained through gdb is greatly appreaciated
+
+JSON-GLib is developed mainly inside a GIT repository available at:
+
+ https://gitlab.gnome.org/GNOME/json-glib/
+
+You can clone the GIT repository with:
+
+ git clone https://gitlab.gnome.org/GNOME/json-glib.git
+
+If you want to contribute functionality or bug fixes to JSON-GLib you should
+fork the json-glib repository, work on a separate branch, and then open a
+merge request on Gitlab:
+
+ https://gitlab.gnome.org/GNOME/json-glib/merge_requests/new
+
+Please, try to conform to the coding style used by JSON-GLib, which is the same
+used by projects like GLib, [GTK][gtk-coding-style], and Clutter. Coding style
+conformance is a requirement for upstream acceptance.
+
+Make sure you always run the test suite when you are fixing bugs. New features
+should come with a test unit. Functionality that regress the test suite will be
+rejected.
• Fix build reproducibility [!33, Alexander Kanavin]
• #26 - Fix parsing of UTF-16 surrogate pairs [James Westman]
• #56 - Ignore UTF-8 BOM [Jan-Michael Brummer]
+• Discover linker flags on all toolchains
+• #58 - Fix memory leak [Richard Hughes]
+• Use gi-docgen instead of gtk-doc for generating the API reference
+• Build against newer versions of GLib
Overview of changes for 1.4
==============================
developers.
GObject is a library providing a run-time Object Oriented type system for C
-developers. GLib and GObject are extensively used by the GTK+ toolkit and by the
+developers. GLib and GObject are extensively used by the GTK toolkit and by the
[GNOME][gnome] project.
For more information, see:
* [ninja](http://ninja-build.org)
* [meson](http://mesonbuild.com)
* pkg-config
- * gtk-doc ≥ 1.13 (optional)
- * GLib, GIO ≥ 2.38
- * GObject-Introspection ≥ 1.38 (optional)
+ * GLib, GIO ≥ 2.54
+ * GObject-Introspection ≥ 1.54 (optional)
Build and installation
--------------------------------------------------------------------------------
```sh
$ meson _build .
- $ ninja -C _build
+ $ meson -C _build
$ meson test -C _build
- $ sudo ninja -C _build install
+ $ meson install -C _build
```
See the [Meson documentation](http://mesonbuild.com) for more information.
-Contributing
---------------------------------------------------------------------------------
-If you find a bug in JSON-GLib, please file an issue on the
-[Issues page][gitlab-issues].
-
-Required information:
-
- * the version of JSON-GLib
- * if it is a development version, the branch of the git repository
- * the JSON data that produced the bug (if any)
- * a small, self-contained test case, if none of the test units exhibit the
- buggy behaviour
- * in case of a segmentation fault, a full stack trace with debugging
- symbols obtained through gdb is greatly appreaciated
-
-JSON-GLib is developed mainly inside a GIT repository available at:
-
- https://gitlab.gnome.org/GNOME/json-glib/
-
-You can clone the GIT repository with:
-
- git clone https://gitlab.gnome.org/GNOME/json-glib.git
-
-If you want to contribute functionality or bug fixes to JSON-GLib you should
-fork the json-glib repository, work on a separate branch, and then open a
-merge request on Gitlab:
-
- https://gitlab.gnome.org/GNOME/json-glib/merge_requests/new
-
-Please, try to conform to the coding style used by JSON-GLib, which is the same
-used by projects like GLib, [GTK+][gtk-coding-style], and Clutter. Coding style
-conformance is a requirement for upstream acceptance.
-
-Make sure you always run the test suite when you are fixing bugs. New features
-should come with a test unit. Patches that regress the test suite will be
-rejected.
-
Release notes
--------------------------------------------------------------------------------
* Prior to JSON-GLib 0.10, a JsonSerializable implementation could
Copyright 2009, 2010, 2011, 2012 Intel Corp.
Copyright 2013 Emmanuele Bassi
-[json]: http://www.json.org "JSON"
-[glib]: http://www.gtk.org "GTK+"
-[json-glib]: https://wiki.gnome.org/Projects/JsonGlib "JSON-GLib wiki"
+[json]: https://www.json.org "JSON"
+[glib]: https://www.gtk.org "GTK"
+[json-glib]: https://gnome.pages.gitlab.gnome.org/json-glib/json-glib-1.0/
[gnome]: https://www.gnome.org "GNOME"
[gitlab-issues]: https://gitlab.gnome.org/GNOME/json-glib/issues
-[gtk-coding-style]: https://git.gnome.org/browse/gtk+/tree/docs/CODING-STYLE
+[gtk-coding-style]: https://gitlab.gnome.org/GNOME/gtk/-/blob/HEAD/docs/CODING-STYLE.md
--- /dev/null
+Title: Serializing GBoxed Types
+
+# Serializing GBoxed Types
+
+GLib's `GBoxed` type is a generic wrapper for arbitrary C structures.
+
+JSON-GLib allows serialization and deserialization of a boxed type
+by registering functions mapping a [enum@Json.NodeType] to a specific
+`GType`.
+
+When registering a boxed type you should also register the
+corresponding transformation functions, e.g.:
+
+```c
+GType
+my_struct_get_type (void)
+{
+ static GType boxed_type = 0;
+
+ if (boxed_type == 0)
+ {
+ boxed_type =
+ g_boxed_type_register_static (g_intern_static_string ("MyStruct"),
+ (GBoxedCopyFunc) my_struct_copy,
+ (GBoxedFreeFunc) my_struct_free);
+
+ json_boxed_register_serialize_func (boxed_type, JSON_NODE_OBJECT,
+ my_struct_serialize);
+ json_boxed_register_deserialize_func (boxed_type, JSON_NODE_OBJECT,
+ my_struct_deserialize);
+ }
+
+ return boxed_type;
+}
+```
+
+The serialization function will be invoked by [func@Json.boxed_serialize]:
+it will be passed a pointer to the C structure and it must return a
+[struct@Json.Node]. The deserialization function will be invoked by
+[func@Json.boxed_deserialize]: it will be passed a `JsonNode` for the
+declared type and it must return a newly allocated C structure.
+
+It is possible to check whether a boxed type can be deserialized
+from a specific `JsonNodeType`, and whether a boxed can be serialized
+and to which specific `JsonNodeType`.
+++ /dev/null
-<?xml version="1.0"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
- "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
-[
- <!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
- <!ENTITY % gtkdocentities SYSTEM "xml/gtkdocentities.ent">
- %gtkdocentities;
-]>
-
-<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
- <bookinfo>
- <title>&package_name; Reference Manual</title>
- <releaseinfo>
- <para>This document is the API reference for for &package_name; &package_version;.</para>
- <para>
- The latest version of this API reference is also available
- <ulink role="online-location" url="https://developer.gnome.org/json-glib/">online</ulink>.
- </para>
- <para>
- If you find any issues in this API reference, please report it
- using <ulink type="http" url="&package_bugreport;">the online
- bug reporting tool</ulink> at bugzilla.gnome.org.
- </para>
- </releaseinfo>
-
- <copyright>
- <year>2007, 2008</year>
- <holder>OpenedHand LTD</holder>
- </copyright>
-
- <copyright>
- <year>2009, 2010, 2011</year>
- <holder>Intel Corporation</holder>
- </copyright>
-
- <legalnotice>
- <para>
- Permission is granted to copy, distribute and/or modify this
- document under the terms of the <citetitle>GNU Free
- Documentation License</citetitle>, Version 1.1 or any later
- version published by the Free Software Foundation with no
- Invariant Sections, no Front-Cover Texts, and no Back-Cover
- Texts. You may obtain a copy of the <citetitle>GNU Free
- Documentation License</citetitle> from the Free Software
- Foundation by visiting <ulink type="http"
- url="http://www.fsf.org">their Web site</ulink> or by writing
- to:
-
- <address>
- The Free Software Foundation, Inc.,
- <street>59 Temple Place</street> - Suite 330,
- <city>Boston</city>, <state>MA</state> <postcode>02111-1307</postcode>,
- <country>USA</country>
- </address>
- </para>
- </legalnotice>
-
- </bookinfo>
-
- <part id="json-overview">
- <title>JSON-GLib Overview</title>
-
- <partintro>
-
- <para>
- JSON-GLib is a library aimed at providing an API for efficient parsing
- and writing of JSON (JavaScript Object Notation) streams, using GLib's
- data types and API.
- </para>
-
- <para>
- JSON (JavaScript Object Notation) is a lightweight data-interchange
- format. More information on the grammar is <ulink type="http"
- url="http://json.org">available on json.org</ulink>.
- </para>
-
- </partintro>
-
- </part>
-
- <part id="json-base">
- <title>JSON-GLib Reference</title>
-
- <partintro>
-
- <para>
- JSON-GLib provides wrappers around the complex data types defined
- by the JSON specification. The fundamental types are handled using
- the Generic Value container (GValue) provided by GLib.
- </para>
-
- <para>
- JSON complex data types are either arrays (a n-tuple of items)
- or objects (a mapping between a string and a value); arrays and
- objects can contain multiple values, including other arrays and
- objects.
- </para>
-
- </partintro>
-
- <chapter>
- <title>Data Types</title>
- <xi:include href="xml/json-node.xml"/>
- <xi:include href="xml/json-array.xml"/>
- <xi:include href="xml/json-object.xml"/>
- </chapter>
-
- </part>
-
- <part id="json-streams">
- <title>Reading and writing</title>
-
- <partintro>
-
- <para>
- JSON-GLib provides a parser object to read any valid JSON data
- stream and build the data object model in memory.
- </para>
-
- </partintro>
-
- <chapter>
- <title>Parser</title>
- <xi:include href="xml/json-parser.xml"/>
- <xi:include href="xml/json-reader.xml"/>
- <xi:include href="xml/json-path.xml"/>
- </chapter>
-
- <chapter>
- <title>Generator</title>
- <xi:include href="xml/json-generator.xml"/>
- <xi:include href="xml/json-builder.xml"/>
- </chapter>
-
- <chapter>
- <title>General Purpose API</title>
- <xi:include href="xml/json-utils.xml"/>
- </chapter>
-
- </part>
-
- <part id="json-advanced">
- <title>JSON-GLib Advanced API</title>
-
- <xi:include href="xml/json-gobject.xml"/>
- <xi:include href="xml/json-serializable.xml"/>
- <xi:include href="xml/json-gboxed.xml"/>
- <xi:include href="xml/json-gvariant.xml"/>
- <xi:include href="xml/json-version.xml"/>
- </part>
-
- <part id="json-tools">
- <title>JSON-GLib Additional Reference</title>
-
- <chapter id="tools">
- <title>JSON-GLib Tools</title>
- <xi:include href="json-glib-format.xml"/>
- <xi:include href="json-glib-validate.xml"/>
- </chapter>
-
- <chapter>
- <title>Object Hierarchy</title>
- <xi:include href="xml/tree_index.sgml"/>
- </chapter>
-
- </part>
-
- <index>
- <title>Index</title>
- <xi:include href="xml/api-index-full.xml"><xi:fallback/></xi:include>
- </index>
-
- <index role="deprecated">
- <title>Index of deprecated symbols</title>
- <xi:include href="xml/api-index-deprecated.xml"><xi:fallback/></xi:include>
- </index>
-
- <index role="0.4">
- <title>Index of new symbols in 0.4</title>
- <xi:include href="xml/api-index-0.4.xml"><xi:fallback/></xi:include>
- </index>
-
- <index role="0.6">
- <title>Index of new symbols in 0.6</title>
- <xi:include href="xml/api-index-0.6.xml"><xi:fallback/></xi:include>
- </index>
-
- <index role="0.8">
- <title>Index of new symbols in 0.8</title>
- <xi:include href="xml/api-index-0.8.xml"><xi:fallback/></xi:include>
- </index>
-
- <index role="0.10">
- <title>Index of new symbols in 0.10</title>
- <xi:include href="xml/api-index-0.10.xml"><xi:fallback/></xi:include>
- </index>
-
- <index role="0.12">
- <title>Index of new symbols in 0.12</title>
- <xi:include href="xml/api-index-0.12.xml"><xi:fallback/></xi:include>
- </index>
-
- <index role="0.14">
- <title>Index of new symbols in 0.14</title>
- <xi:include href="xml/api-index-0.14.xml"><xi:fallback/></xi:include>
- </index>
-
- <index role="0.16">
- <title>Index of new symbols in 0.16</title>
- <xi:include href="xml/api-index-0.16.xml"><xi:fallback/></xi:include>
- </index>
-
- <index role="1.0">
- <title>Index of new symbols in 1.0</title>
- <xi:include href="xml/api-index-1.0.xml"><xi:fallback/></xi:include>
- </index>
-
- <index role="1.2">
- <title>Index of new symbols in 1.2</title>
- <xi:include href="xml/api-index-1.2.xml"><xi:fallback/></xi:include>
- </index>
-
- <index role="1.4">
- <title>Index of new symbols in 1.4</title>
- <xi:include href="xml/api-index-1.4.xml"><xi:fallback/></xi:include>
- </index>
-
- <index role="1.6">
- <title>Index of new symbols in 1.6</title>
- <xi:include href="xml/api-index-1.6.xml"><xi:fallback/></xi:include>
- </index>
-
- <xi:include href="xml/annotation-glossary.xml"><xi:fallback/></xi:include>
-
- <appendix id="license">
- <title>License</title>
-
- <para>
- This library is free software; you can redistribute it and/or
- modify it under the terms of the <citetitle>GNU Library General
- Public License</citetitle> as published by the Free Software
- Foundation; either version 2 of the License, or (at your option)
- any later version.
- </para>
-
- <para>
- This library is distributed in the hope that it will be useful,
- but WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- <citetitle>GNU Library General Public License</citetitle> for
- more details.
- </para>
-
- <para>
- You may obtain a copy of the <citetitle>GNU Library General
- Public License</citetitle> from the Free Software Foundation by
- visiting <ulink type="http" url="http://www.fsf.org">their Web
- site</ulink> or by writing to:
-
- <address>
- Free Software Foundation, Inc.
- <street>59 Temple Place</street> - Suite 330
- <city>Boston</city>, <state>MA</state> <postcode>02111-1307</postcode>
- <country>USA</country>
- </address>
- </para>
- </appendix>
-
-</book>
+++ /dev/null
-<MACRO>
-<NAME>JSON_MAJOR_VERSION</NAME>
-#define JSON_MAJOR_VERSION
-</MACRO>
-
-<MACRO>
-<NAME>JSON_MINOR_VERSION</NAME>
-#define JSON_MINOR_VERSION
-</MACRO>
-
-<MACRO>
-<NAME>JSON_MICRO_VERSION</NAME>
-#define JSON_MICRO_VERSION
-</MACRO>
+++ /dev/null
-<INCLUDE>json-glib/json-glib.h</INCLUDE>
-
-<SECTION>
-<FILE>json-object</FILE>
-<TITLE>JSON Object</TITLE>
-JsonObject
-json_object_new
-json_object_ref
-json_object_unref
-json_object_seal
-json_object_is_immutable
-json_object_hash
-json_object_equal
-
-<SUBSECTION>
-json_object_add_member
-json_object_set_member
-json_object_has_member
-json_object_get_member
-json_object_dup_member
-json_object_get_members
-json_object_get_values
-json_object_get_size
-json_object_remove_member
-JsonObjectForeach
-json_object_foreach_member
-JsonObjectIter
-json_object_iter_init
-json_object_iter_next
-json_object_iter_init_ordered
-json_object_iter_next_ordered
-
-<SUBSECTION>
-json_object_set_array_member
-json_object_get_array_member
-json_object_set_object_member
-json_object_get_object_member
-json_object_set_null_member
-json_object_get_null_member
-json_object_set_boolean_member
-json_object_get_boolean_member
-json_object_get_boolean_member_with_default
-json_object_set_double_member
-json_object_get_double_member
-json_object_get_double_member_with_default
-json_object_set_int_member
-json_object_get_int_member
-json_object_get_int_member_with_default
-json_object_set_string_member
-json_object_get_string_member
-json_object_get_string_member_with_default
-
-<SUBSECTION Private>
-JSON_TYPE_OBJECT
-json_object_get_type
-</SECTION>
-
-<SECTION>
-<FILE>json-array</FILE>
-<TITLE>JSON Array</TITLE>
-JsonArray
-json_array_new
-json_array_sized_new
-json_array_ref
-json_array_unref
-json_array_seal
-json_array_is_immutable
-json_array_hash
-json_array_equal
-
-<SUBSECTION>
-json_array_add_element
-json_array_get_element
-json_array_dup_element
-json_array_get_elements
-json_array_get_length
-json_array_remove_element
-JsonArrayForeach
-json_array_foreach_element
-
-<SUBSECTION>
-json_array_add_array_element
-json_array_get_array_element
-json_array_add_boolean_element
-json_array_get_boolean_element
-json_array_add_double_element
-json_array_get_double_element
-json_array_add_int_element
-json_array_get_int_element
-json_array_add_null_element
-json_array_get_null_element
-json_array_add_object_element
-json_array_get_object_element
-json_array_add_string_element
-json_array_get_string_element
-
-<SUBSECTION Private>
-JSON_TYPE_ARRAY
-json_array_get_type
-</SECTION>
-
-<SECTION>
-<FILE>json-node</FILE>
-<TITLE>JSON Node</TITLE>
-JsonNodeType
-JsonNode
-JSON_NODE_TYPE
-JSON_NODE_HOLDS
-JSON_NODE_HOLDS_VALUE
-JSON_NODE_HOLDS_OBJECT
-JSON_NODE_HOLDS_ARRAY
-JSON_NODE_HOLDS_NULL
-json_node_alloc
-json_node_init
-json_node_init_int
-json_node_init_double
-json_node_init_boolean
-json_node_init_string
-json_node_init_null
-json_node_init_object
-json_node_init_array
-json_node_new
-json_node_copy
-json_node_free
-json_node_ref
-json_node_unref
-json_node_is_immutable
-json_node_seal
-json_node_hash
-json_node_equal
-
-<SUBSECTION>
-json_node_set_array
-json_node_take_array
-json_node_get_array
-json_node_dup_array
-
-<SUBSECTION>
-json_node_set_object
-json_node_take_object
-json_node_get_object
-json_node_dup_object
-
-<SUBSECTION>
-json_node_set_value
-json_node_get_value
-json_node_set_boolean
-json_node_get_boolean
-json_node_set_double
-json_node_get_double
-json_node_set_int
-json_node_get_int
-json_node_set_string
-json_node_get_string
-json_node_dup_string
-
-<SUBSECTION>
-json_node_set_parent
-json_node_get_parent
-json_node_type_name
-json_node_get_value_type
-json_node_get_node_type
-json_node_is_null
-
-<SUBSECTION>
-json_string_hash
-json_string_equal
-json_string_compare
-
-<SUBSECTION Private>
-JSON_DEPRECATED
-JSON_DEPRECATED_FOR
-JSON_TYPE_NODE
-json_node_get_type
-</SECTION>
-
-<SECTION>
-<FILE>json-parser</FILE>
-<TITLE>JsonParser</TITLE>
-JsonParserError
-
-<SUBSECTION>
-JsonParser
-JsonParserClass
-json_parser_new
-json_parser_new_immutable
-json_parser_load_from_file
-json_parser_load_from_mapped_file
-json_parser_load_from_data
-json_parser_load_from_stream
-json_parser_load_from_stream_async
-json_parser_load_from_stream_finish
-
-<SUBSECTION>
-json_parser_get_root
-json_parser_steal_root
-
-<SUBSECTION>
-json_parser_get_current_line
-json_parser_get_current_pos
-json_parser_has_assignment
-
-<SUBSECTION Standard>
-JSON_TYPE_PARSER
-JSON_PARSER
-JSON_IS_PARSER
-JSON_PARSER_CLASS
-JSON_IS_PARSER_CLASS
-JSON_PARSER_ERROR
-JSON_PARSER_GET_CLASS
-
-<SUBSECTION Private>
-JsonParserPrivate
-json_parser_get_type
-json_parser_error_quark
-</SECTION>
-
-<SECTION>
-<FILE>json-generator</FILE>
-<TITLE>JsonGenerator</TITLE>
-<SUBSECTION>
-JsonGenerator
-JsonGeneratorClass
-json_generator_new
-json_generator_set_root
-json_generator_get_root
-json_generator_set_pretty
-json_generator_get_pretty
-json_generator_set_indent
-json_generator_get_indent
-json_generator_set_indent_char
-json_generator_get_indent_char
-
-<SUBSECTION>
-json_generator_to_file
-json_generator_to_data
-json_generator_to_gstring
-json_generator_to_stream
-
-<SUBSECTION Standard>
-JSON_TYPE_GENERATOR
-JSON_GENERATOR
-JSON_IS_GENERATOR
-JSON_GENERATOR_CLASS
-JSON_IS_GENERATOR_CLASS
-JSON_GENERATOR_GET_CLASS
-
-<SUBSECTION Private>
-JsonGeneratorPrivate
-json_generator_get_type
-</SECTION>
-
-<SECTION>
-<FILE>json-serializable</FILE>
-<TITLE>Serializable Interface</TITLE>
-JsonSerializableIface
-json_serializable_serialize_property
-json_serializable_deserialize_property
-json_serializable_find_property
-json_serializable_get_property
-json_serializable_list_properties
-json_serializable_set_property
-
-<SUBSECTION>
-json_serializable_default_serialize_property
-json_serializable_default_deserialize_property
-
-<SUBSECTION Standard>
-JSON_TYPE_SERIALIZABLE
-JSON_SERIALIZABLE
-JSON_IS_SERIALIZABLE
-JSON_SERIALIZABLE_GET_IFACE
-
-<SUBSECTION Private>
-JsonSerializable
-json_serializable_get_type
-</SECTION>
-
-<SECTION>
-<FILE>json-gboxed</FILE>
-<TITLE>Boxed Types Serialization</TITLE>
-JsonBoxedSerializeFunc
-JsonBoxedDeserializeFunc
-json_boxed_register_serialize_func
-json_boxed_register_deserialize_func
-
-<SUBSECTION>
-json_boxed_can_serialize
-json_boxed_can_deserialize
-json_boxed_serialize
-json_boxed_deserialize
-</SECTION>
-
-<SECTION>
-<FILE>json-gobject</FILE>
-<TITLE>GObject Serialization</TITLE>
-json_gobject_serialize
-json_gobject_deserialize
-json_gobject_to_data
-json_gobject_from_data
-
-<SUBSECTION>
-json_construct_gobject
-json_serialize_gobject
-</SECTION>
-
-<SECTION>
-<FILE>json-gvariant</FILE>
-
-<SUBSECTION>
-json_gvariant_serialize
-json_gvariant_serialize_data
-json_gvariant_deserialize
-json_gvariant_deserialize_data
-</SECTION>
-
-<SECTION>
-<FILE>json-version</FILE>
-<TITLE>Versioning information</TITLE>
-JSON_MAJOR_VERSION
-JSON_MINOR_VERSION
-JSON_MICRO_VERSION
-
-<SUBSECTION>
-JSON_VERSION
-JSON_VERSION_S
-JSON_VERSION_HEX
-
-<SUBSECTION>
-JSON_CHECK_VERSION
-JSON_VERSION_MIN_REQUIRED
-JSON_VERSION_MAX_ALLOWED
-
-<SUBSECTION Standard>
-JSON_VERSION_CUR_STABLE
-JSON_VERSION_PREV_STABLE
-JSON_VERSION_1_0
-JSON_AVAILABLE_IN_1_0
-JSON_DEPRECATED_IN_1_0
-JSON_DEPRECATED_IN_1_0_FOR
-JSON_VERSION_1_2
-JSON_AVAILABLE_IN_1_2
-JSON_DEPRECATED_IN_1_2
-JSON_DEPRECATED_IN_1_2_FOR
-JSON_VERSION_1_4
-JSON_AVAILABLE_IN_1_4
-JSON_DEPRECATED_IN_1_4
-JSON_DEPRECATED_IN_1_4_FOR
-JSON_VERSION_1_6
-JSON_AVAILABLE_IN_1_6
-JSON_DEPRECATED_IN_1_6
-JSON_DEPRECATED_IN_1_6_FOR
-
-<SUBSECTION Private>
-JSON_ENCODE_VERSION
-JSON_DEPRECATED
-JSON_DEPRECATED_FOR
-JSON_UNAVAILABLE
-_JSON_EXTERN
-</SECTION>
-
-<SECTION>
-<FILE>json-builder</FILE>
-JsonBuilder
-JsonBuilderClass
-json_builder_new
-json_builder_new_immutable
-json_builder_get_root
-json_builder_reset
-<SUBSECTION>
-json_builder_begin_array
-json_builder_end_array
-json_builder_begin_object
-json_builder_set_member_name
-json_builder_end_object
-<SUBSECTION>
-json_builder_add_value
-json_builder_add_int_value
-json_builder_add_double_value
-json_builder_add_boolean_value
-json_builder_add_string_value
-json_builder_add_null_value
-<SUBSECTION Standard>
-JSON_TYPE_BUILDER
-JSON_BUILDER
-JSON_BUILDER_CLASS
-JSON_IS_BUILDER
-JSON_IS_BUILDER_CLASS
-JSON_BUILDER_GET_CLASS
-<SUBSECTION Private>
-JsonBuilderPrivate
-json_builder_get_type
-</SECTION>
-
-<SECTION>
-<FILE>json-reader</FILE>
-JsonReader
-JsonReaderClass
-json_reader_new
-json_reader_set_root
-<SUBSECTION>
-json_reader_read_element
-json_reader_end_element
-json_reader_is_array
-json_reader_count_elements
-<SUBSECTION>
-json_reader_read_member
-json_reader_end_member
-json_reader_is_object
-json_reader_count_members
-json_reader_list_members
-json_reader_get_member_name
-<SUBSECTION>
-json_reader_is_value
-json_reader_get_value
-json_reader_get_int_value
-json_reader_get_double_value
-json_reader_get_string_value
-json_reader_get_boolean_value
-json_reader_get_null_value
-<SUBSECTION>
-JsonReaderError
-JSON_READER_ERROR
-json_reader_get_error
-<SUBSECTION Standard>
-JSON_READER
-JSON_READER_CLASS
-JSON_IS_READER
-JSON_IS_READER_CLASS
-JSON_READER_GET_CLASS
-JSON_TYPE_READER
-<SUBSECTION Private>
-JsonReaderPrivate
-json_reader_get_type
-json_reader_error_quark
-</SECTION>
-
-<SECTION>
-<FILE>json-path</FILE>
-JsonPath
-JsonPathClass
-json_path_new
-JSON_PATH_ERROR
-JsonPathError
-json_path_compile
-json_path_match
-<SUBSECTION>
-json_path_query
-<SUBSECTION Standard>
-JSON_TYPE_PATH
-JSON_PATH
-JSON_IS_PATH
-<SUBSECTION Private>
-json_path_get_type
-json_path_error_quark
-</SECTION>
-
-<SECTION>
-<FILE>json-utils</FILE>
-json_from_string
-json_to_string
-</SECTION>
--- /dev/null
+[library]
+namespace = "Json"
+version = "@JSON_VERSION@"
+browse_url = "https://gitlab.gnome.org/GNOME/json-glib/"
+repository_url = "https://gitlab.gnome.org/GNOME/json-glib.git"
+authors = "Emmanuele Bassi"
+license = "LGPL-2.1-or-later"
+description = "JSON parser and generator"
+dependencies = [ "GObject-2.0", "Gio-2.0" ]
+devhelp = true
+search_index = true
+
+ [dependencies."GObject-2.0"]
+ name = "GObject"
+ description = "The base type system library"
+ docs_url = "https://developer.gnome.org/gobject/stable"
+
+ [dependencies."Gio-2.0"]
+ name = "Gio"
+ description = "GObject interfaces and objects"
+ docs_url = "https://developer.gnome.org/gio/stable"
+
+[theme]
+name = "basic"
+show_index_summary = true
+show_class_hierarchy = true
+
+[source-location]
+base_url = "https://gitlab.gnome.org/GNOME/json-glib/-/blob/master/"
+
+[extra]
+content_files = [
+ 'json-gboxed.md',
+ 'json-gobject.md',
+ 'json-gvariant.md',
+]
+
+[[object]]
+pattern = "DEPRECATED_IN_*"
+hidden = true
+
+[[object]]
+name = "DEPRECATED_FOR"
+hidden = true
+
+[[object]]
+name = "UNAVAILABLE"
+hidden = true
+
+[[object]]
+name = "ParserError"
+ [[object.function]]
+ name = "quark"
+ check_ignore = true
+
+
+[[object]]
+name = "PathError"
+ [[object.function]]
+ name = "quark"
+ check_ignore = true
+
+[[object]]
+name = "ReaderError"
+ [[object.function]]
+ name = "quark"
+ check_ignore = true
--- /dev/null
+Title: Serializing GObject Types
+
+# Serializing GObject Types
+
+JSON-GLib provides API for serializing and deserializing `GObject` instances
+to and from JSON data streams.
+
+Simple `GObject` classes can be (de)serialized into JSON objects, if the
+properties have compatible types with the native JSON types (integers,
+booleans, strings, string vectors). If the class to be (de)serialized has
+complex data types for properties (like boxed types or other objects) then
+the class should implement the provided [iface@Json.Serializable] interface
+and its virtual functions.
--- /dev/null
+Title: Serializing GVariants
+
+# Serializing GVariants
+
+`GVariant` is a serialization format mainly used as the wire data for D-Bus,
+as well as storing values in GSettings. JSON-GLib provides utility functions
+to serialize and deserialize `GVariant` data to and from JSON.
+
+Use [`func@Json.gvariant_serialize`] and [`func@Json.gvariant_serialize_data`] to
+convert from any `GVariant` value to a [struct@Json.Node] tree or its string
+representation.
+
+Use [`func@Json.gvariant_deserialize`] and [`func@Json.gvariant_deserialize_data`]
+to obtain the `GVariant` value from a `JsonNode` tree or directly from a JSON
+string.
+
+Since many `GVariant` data types cannot be directly represented as
+JSON, a `GVariant` type string (signature) should be provided to these
+methods in order to obtain a correct, type-contrained result.
+If no signature is provided, conversion can still be done, but the
+resulting `GVariant` value will be "guessed" from the JSON data types
+using the following rules:
+
+Strings:
+ A JSON string maps to a GVariant string `(s)`.
+
+Integers:
+ A JSON integer maps to a GVariant 64-bit integer `(x)`.
+
+Booleans:
+ A JSON boolean maps to a GVariant boolean `(b)`.
+
+Numbers:
+ A JSON number maps to a GVariant double `(d)`.
+
+Arrays:
+ A JSON array maps to a GVariant array of variants `(av)`.
+
+Objects:
+ A JSON object maps to a GVariant dictionary of string to variants `(a{sv})`.
+
+`NULL` values:
+ A JSON `null` value maps to a GVariant "maybe" variant `(mv)`.
-if find_program('gtkdoc-scan', required : get_option('gtk_doc')).found()
- subdir('xml')
+if get_option('gtk_doc').enabled() and get_option('introspection').enabled()
+ dependency('gi-docgen', version: '>= 2021.6',
+ fallback: ['gi-docgen', 'dummy_dep'],
+ )
- private_headers = [
- 'config.h',
+ gidocgen = find_program('gi-docgen', required: get_option('gtk_doc'))
- 'json-debug.h',
- 'json-enum-types.h',
- 'json-glib.h',
- 'json-gobject-private.h',
- 'json-marshal.h',
- 'json-private.h',
- 'json-scanner.h',
- 'json-types-private.h',
+ json_docdir = json_datadir / 'doc'
- 'tests/json-test-utils.h',
- ]
+ toml_conf = configuration_data()
+ toml_conf.set('JSON_VERSION', meson.project_version())
- glib_prefix = dependency('glib-2.0').get_pkgconfig_variable('prefix')
- glib_docpath = join_paths(glib_prefix, 'share', 'gtk-doc', 'html')
- docpath = join_paths(json_datadir, 'gtk-doc', 'html')
+ json_toml = configure_file(
+ input: 'json-glib.toml.in',
+ output: 'json-glib.toml',
+ configuration: toml_conf,
+ )
- gnome.gtkdoc(
- 'json-glib',
- main_xml: 'json-glib-docs.xml',
- src_dir: include_directories('../json-glib'),
- dependencies: json_glib_dep,
- gobject_typesfile: 'json-glib.types',
- scan_args: [
- '--rebuild-types',
- '--ignore-decorators=_JSON_EXTERN',
- '--ignore-headers=' + ' '.join(private_headers),
- ],
- fixxref_args: [
- '--html-dir=@0@'.format(docpath),
- '--extra-dir=@0@'.format(join_paths(glib_docpath, 'glib')),
- '--extra-dir=@0@'.format(join_paths(glib_docpath, 'gobject')),
- '--extra-dir=@0@'.format(join_paths(glib_docpath, 'gio')),
+ json_content_files = [
+ 'json-gboxed.md',
+ 'json-gobject.md',
+ 'json-gvariant.md',
+ ]
+
+ custom_target('json-glib-doc',
+ input: json_glib_gir[0],
+ output: 'json-glib-1.0',
+ command: [
+ gidocgen,
+ 'generate',
+ '--quiet',
+ '--fatal-warnings',
+ '--add-include-path=@0@'.format(meson.current_build_dir() / '../json-glib'),
+ '--config', json_toml,
+ '--output-dir=@OUTPUT@',
+ '--no-namespace-dir',
+ '--content-dir=@0@'.format(meson.current_source_dir()),
+ '@INPUT@',
],
+ depend_files: [ json_toml, json_content_files ],
+ build_by_default: true,
install: true,
+ install_dir: json_docdir,
)
+
+ if get_option('tests')
+ test('doc-check',
+ gidocgen,
+ args: [
+ 'check',
+ '--config', json_toml,
+ '--add-include-path=@0@'.format(meson.current_build_dir() / '../json-glib'),
+ json_glib_gir[0],
+ ],
+ depends: json_glib_gir[0],
+ suite: ['docs'],
+ )
+ endif
+
endif
xsltproc = find_program('xsltproc', required: false)
+++ /dev/null
-<!ENTITY package "@PACKAGE@">
-<!ENTITY package_bugreport "@PACKAGE_BUGREPORT@">
-<!ENTITY package_name "@PACKAGE_NAME@">
-<!ENTITY package_string "@PACKAGE_STRING@">
-<!ENTITY package_tarname "@PACKAGE_TARNAME@">
-<!ENTITY package_url "@PACKAGE_URL@">
-<!ENTITY package_version "@PACKAGE_VERSION@">
-<!ENTITY package_api_version "@PACKAGE_API_VERSION@">
+++ /dev/null
-ent_conf = configuration_data()
-ent_conf.set('PACKAGE', 'JSON-GLib')
-ent_conf.set('PACKAGE_BUGREPORT', 'https://bugzilla.gnome.org/enter_bug.cgi?product=json-glib')
-ent_conf.set('PACKAGE_NAME', 'JSON-GLib')
-ent_conf.set('PACKAGE_STRING', meson.project_name())
-ent_conf.set('PACKAGE_TARNAME', '@0@-@1@'.format(meson.project_name(), meson.project_version()))
-ent_conf.set('PACKAGE_URL', 'http://wiki.gnome.org/Project/JsonGlib')
-ent_conf.set('PACKAGE_VERSION', meson.project_version())
-ent_conf.set('PACKAGE_API_VERSION', json_api_version)
-configure_file(input: 'gtkdocentities.ent.in', output: 'gtkdocentities.ent', configuration: ent_conf)
-
#include "json-types-private.h"
/**
- * SECTION:json-array
- * @short_description: a JSON array representation
+ * JsonArray:
*
- * #JsonArray is the representation of the array type inside JSON. It contains
- * #JsonNode elements, which may contain fundamental types, other arrays or
- * objects.
+ * `JsonArray` is the representation of the array type inside JSON.
*
- * Since arrays can be expensive, they are reference counted. You can control
- * the lifetime of a #JsonArray using json_array_ref() and json_array_unref().
+ * A `JsonArray` contains [struct@Json.Node] elements, which may contain
+ * fundamental types, other arrays or objects.
*
- * To append an element, use json_array_add_element().
- * To extract an element at a given index, use json_array_get_element().
- * To retrieve the entire array in list form, use json_array_get_elements().
- * To retrieve the length of the array, use json_array_get_length().
+ * Since arrays can be arbitrarily big, copying them can be expensive; for
+ * this reason, they are reference counted. You can control the lifetime of
+ * a `JsonArray` using [method@Json.Array.ref] and [method@Json.Array.unref].
+ *
+ * To append an element, use [method@Json.Array.add_element].
+ *
+ * To extract an element at a given index, use [method@Json.Array.get_element].
+ *
+ * To retrieve the entire array in list form, use [method@Json.Array.get_elements].
+ *
+ * To retrieve the length of the array, use [method@Json.Array.get_length].
*/
G_DEFINE_BOXED_TYPE (JsonArray, json_array, json_array_ref, json_array_unref);
/**
* json_array_new: (constructor)
*
- * Creates a new #JsonArray.
+ * Creates a new array.
*
- * Return value: (transfer full): the newly created #JsonArray
+ * Return value: (transfer full): the newly created array
*/
JsonArray *
json_array_new (void)
* json_array_sized_new: (constructor)
* @n_elements: number of slots to pre-allocate
*
- * Creates a new #JsonArray with @n_elements slots already allocated.
+ * Creates a new array with `n_elements` slots already allocated.
*
- * Return value: (transfer full): the newly created #JsonArray
+ * Return value: (transfer full): the newly created array
*/
JsonArray *
json_array_sized_new (guint n_elements)
/**
* json_array_ref:
- * @array: a #JsonArray
+ * @array: the array to reference
*
- * Increase by one the reference count of a #JsonArray.
+ * Acquires a reference on the given array.
*
- * Return value: (transfer none): the passed #JsonArray, with the reference count
- * increased by one.
+ * Return value: (transfer none): the passed array, with the reference count
+ * increased by one
*/
JsonArray *
json_array_ref (JsonArray *array)
/**
* json_array_unref:
- * @array: a #JsonArray
+ * @array: the array to unreference
*
- * Decreases by one the reference count of a #JsonArray. If the
- * reference count reaches zero, the array is destroyed and all
+ * Releases a reference on the given array.
+ *
+ * If the reference count reaches zero, the array is destroyed and all
* its allocated resources are freed.
*/
void
/**
* json_array_seal:
- * @array: a #JsonArray
+ * @array: the array to seal
+ *
+ * Seals the given array, making it immutable to further changes.
*
- * Seals the #JsonArray, making it immutable to further changes. This will
- * recursively seal all elements in the array too.
+ * This function will recursively seal all elements in the array too.
*
- * If the @array is already immutable, this is a no-op.
+ * If the `array` is already immutable, this is a no-op.
*
* Since: 1.2
*/
/**
* json_array_is_immutable:
- * @array: a #JsonArray
+ * @array: a JSON array
*
- * Check whether the given @array has been marked as immutable by calling
- * json_array_seal() on it.
+ * Check whether the given `array` has been marked as immutable by calling
+ * [method@Json.Array.seal] on it.
*
* Since: 1.2
- * Returns: %TRUE if the @array is immutable
+ * Returns: %TRUE if the array is immutable
*/
gboolean
json_array_is_immutable (JsonArray *array)
/**
* json_array_get_elements:
- * @array: a #JsonArray
+ * @array: a JSON array
*
- * Gets the elements of a #JsonArray as a list of #JsonNode instances.
+ * Retrieves all the elements of an array as a list of nodes.
*
- * Return value: (element-type JsonNode) (transfer container): a #GList
- * containing the elements of the array. The contents of the list are
- * owned by the array and should never be modified or freed. Use
- * g_list_free() on the returned list when done using it
+ * Return value: (element-type JsonNode) (transfer container) (nullable): the elements
+ * of the array
*/
GList *
json_array_get_elements (JsonArray *array)
/**
* json_array_dup_element:
- * @array: a #JsonArray
+ * @array: a JSON array
* @index_: the index of the element to retrieve
*
- * Retrieves a copy of the #JsonNode containing the value of the
- * element at @index_ inside a #JsonArray
+ * Retrieves a copy of the element at the given position in the array.
*
- * Return value: (transfer full): a copy of the #JsonNode at the requested
- * index. Use json_node_unref() when done.
+ * Return value: (transfer full): a copy of the element at the given position
*
* Since: 0.6
*/
/**
* json_array_get_element:
- * @array: a #JsonArray
+ * @array: a JSON array
* @index_: the index of the element to retrieve
- *
- * Retrieves the #JsonNode containing the value of the element at @index_
- * inside a #JsonArray.
*
- * Return value: (transfer none): a pointer to the #JsonNode at the requested index
+ * Retrieves the element at the given position in the array.
+ *
+ * Return value: (transfer none): the element at the given position
*/
JsonNode *
json_array_get_element (JsonArray *array,
/**
* json_array_get_int_element:
- * @array: a #JsonArray
+ * @array: a JSON array
* @index_: the index of the element to retrieve
*
- * Conveniently retrieves the integer value of the element at @index_
- * inside @array
+ * Conveniently retrieves the integer value of the element at the given
+ * position inside an array.
*
- * See also: json_array_get_element(), json_node_get_int()
+ * See also: [method@Json.Array.get_element], [method@Json.Node.get_int]
*
* Return value: the integer value
*
/**
* json_array_get_double_element:
- * @array: a #JsonArray
+ * @array: a JSON array
* @index_: the index of the element to retrieve
*
* Conveniently retrieves the floating point value of the element at
- * @index_ inside @array
+ * the given position inside an array.
*
- * See also: json_array_get_element(), json_node_get_double()
+ * See also: [method@Json.Array.get_element], [method@Json.Node.get_double]
*
* Return value: the floating point value
*
/**
* json_array_get_boolean_element:
- * @array: a #JsonArray
+ * @array: a JSON array
* @index_: the index of the element to retrieve
*
- * Conveniently retrieves the boolean value of the element at @index_
- * inside @array
+ * Conveniently retrieves the boolean value of the element at the given
+ * position inside an array.
*
- * See also: json_array_get_element(), json_node_get_boolean()
+ * See also: [method@Json.Array.get_element], [method@Json.Node.get_boolean]
*
- * Return value: the integer value
+ * Return value: the boolean value
*
* Since: 0.8
*/
/**
* json_array_get_string_element:
- * @array: a #JsonArray
+ * @array: a JSON array
* @index_: the index of the element to retrieve
*
- * Conveniently retrieves the string value of the element at @index_
- * inside @array
+ * Conveniently retrieves the string value of the element at the given
+ * position inside an array.
*
- * See also: json_array_get_element(), json_node_get_string()
+ * See also: [method@Json.Array.get_element], [method@Json.Node.get_string]
*
- * Return value: the string value; the returned string is owned by
- * the #JsonArray and should not be modified or freed
+ * Return value: (transfer none): the string value
*
* Since: 0.8
*/
/**
* json_array_get_null_element:
- * @array: a #JsonArray
+ * @array: a JSON array
* @index_: the index of the element to retrieve
*
- * Conveniently retrieves whether the element at @index_ is set to null
+ * Conveniently checks whether the element at the given position inside the
+ * array contains a `null` value.
*
- * See also: json_array_get_element(), JSON_NODE_TYPE(), %JSON_NODE_NULL
+ * See also: [method@Json.Array.get_element], [method@Json.Node.is_null]
*
- * Return value: %TRUE if the element is null
+ * Return value: `TRUE` if the element is `null`
*
* Since: 0.8
*/
/**
* json_array_get_array_element:
- * @array: a #JsonArray
+ * @array: a JSON array
* @index_: the index of the element to retrieve
*
- * Conveniently retrieves the array from the element at @index_
- * inside @array
+ * Conveniently retrieves the array at the given position inside an array.
*
- * See also: json_array_get_element(), json_node_get_array()
+ * See also: [method@Json.Array.get_element], [method@Json.Node.get_array]
*
* Return value: (transfer none): the array
*
/**
* json_array_get_object_element:
- * @array: a #JsonArray
+ * @array: a JSON array
* @index_: the index of the element to retrieve
*
- * Conveniently retrieves the object from the element at @index_
- * inside @array
+ * Conveniently retrieves the object at the given position inside an array.
*
- * See also: json_array_get_element(), json_node_get_object()
+ * See also: [method@Json.Array.get_element], [method@Json.Node.get_object]
*
* Return value: (transfer none): the object
*
/**
* json_array_get_length:
- * @array: a #JsonArray
+ * @array: a JSON array
*
- * Retrieves the length of a #JsonArray
+ * Retrieves the length of the given array
*
* Return value: the length of the array
*/
/**
* json_array_add_element:
- * @array: a #JsonArray
- * @node: (transfer full): a #JsonNode
+ * @array: a JSON array
+ * @node: (transfer full): the element to add
*
- * Appends @node inside @array. The array will take ownership of the
- * #JsonNode.
+ * Appends the given `node` inside an array.
*/
void
json_array_add_element (JsonArray *array,
/**
* json_array_add_int_element:
- * @array: a #JsonArray
- * @value: an integer value
+ * @array: a JSON array
+ * @value: the integer value to add
*
- * Conveniently adds an integer @value into @array
+ * Conveniently adds the given integer value into an array.
*
- * See also: json_array_add_element(), json_node_set_int()
+ * See also: [method@Json.Array.add_element], [method@Json.Node.set_int]
*
* Since: 0.8
*/
/**
* json_array_add_double_element:
- * @array: a #JsonArray
- * @value: a floating point value
+ * @array: a JSON array
+ * @value: the floating point value to add
*
- * Conveniently adds a floating point @value into @array
+ * Conveniently adds the given floating point value into an array.
*
- * See also: json_array_add_element(), json_node_set_double()
+ * See also: [method@Json.Array.add_element], [method@Json.Node.set_double]
*
* Since: 0.8
*/
/**
* json_array_add_boolean_element:
- * @array: a #JsonArray
- * @value: a boolean value
+ * @array: a JSON array
+ * @value: the boolean value to add
*
- * Conveniently adds a boolean @value into @array
+ * Conveniently adds the given boolean value into an array.
*
- * See also: json_array_add_element(), json_node_set_boolean()
+ * See also: [method@Json.Array.add_element], [method@Json.Node.set_boolean]
*
* Since: 0.8
*/
/**
* json_array_add_string_element:
- * @array: a #JsonArray
- * @value: a string value
+ * @array: a JSON array
+ * @value: the string value to add
*
- * Conveniently adds a string @value into @array
+ * Conveniently adds the given string value into an array.
*
- * See also: json_array_add_element(), json_node_set_string()
+ * See also: [method@Json.Array.add_element], [method@Json.Node.set_string]
*
* Since: 0.8
*/
/**
* json_array_add_null_element:
- * @array: a #JsonArray
+ * @array: a JSON array
*
- * Conveniently adds a null element into @array
+ * Conveniently adds a `null` element into an array
*
- * See also: json_array_add_element(), %JSON_NODE_NULL
+ * See also: [method@Json.Array.add_element], `JSON_NODE_NULL`
*
* Since: 0.8
*/
/**
* json_array_add_array_element:
- * @array: a #JsonArray
- * @value: (allow-none) (transfer full): a #JsonArray
+ * @array: a JSON array
+ * @value: (nullable) (transfer full): the array to add
+ *
+ * Conveniently adds an array element into an array.
*
- * Conveniently adds an array into @array. The @array takes ownership
- * of the newly added #JsonArray
+ * If `value` is `NULL`, a `null` element will be added instead.
*
- * See also: json_array_add_element(), json_node_take_array()
+ * See also: [method@Json.Array.add_element], [method@Json.Node.take_array]
*
* Since: 0.8
*/
/**
* json_array_add_object_element:
- * @array: a #JsonArray
- * @value: (transfer full): a #JsonObject
+ * @array: a JSON array
+ * @value: (transfer full) (nullable): the object to add
*
- * Conveniently adds an object into @array. The @array takes ownership
- * of the newly added #JsonObject
+ * Conveniently adds an object into an array.
*
- * See also: json_array_add_element(), json_node_take_object()
+ * If `value` is `NULL`, a `null` element will be added instead.
+ *
+ * See also: [method@Json.Array.add_element], [method@Json.Node.take_object]
*
* Since: 0.8
*/
/**
* json_array_remove_element:
- * @array: a #JsonArray
+ * @array: a JSON array
* @index_: the position of the element to be removed
*
- * Removes the #JsonNode inside @array at @index_ freeing its allocated
- * resources.
+ * Removes the element at the given position inside an array.
+ *
+ * This function will release the reference held on the element.
*/
void
json_array_remove_element (JsonArray *array,
/**
* json_array_foreach_element:
- * @array: a #JsonArray
+ * @array: a JSON array
* @func: (scope call): the function to be called on each element
* @data: (closure): data to be passed to the function
*
- * Iterates over all elements of @array and calls @func on
+ * Iterates over all elements of an array, and calls a function on
* each one of them.
*
- * It is safe to change the value of a #JsonNode of the @array
- * from within the iterator @func, but it is not safe to add or
- * remove elements from the @array.
+ * It is safe to change the value of an element of the array while
+ * iterating over it, but it is not safe to add or remove elements
+ * from the array.
*
* Since: 0.8
*/
/**
* json_array_hash:
- * @key: (type JsonArray): a JSON array to hash
+ * @key: (type JsonArray) (not nullable): a JSON array to hash
*
- * Calculate a hash value for the given @key (a #JsonArray).
+ * Calculates a hash value for the given `key`.
*
- * The hash is calculated over the array and all its elements, recursively. If
- * the array is immutable, this is a fast operation; otherwise, it scales
+ * The hash is calculated over the array and all its elements, recursively.
+ *
+ * If the array is immutable, this is a fast operation; otherwise, it scales
* proportionally with the length of the array.
*
- * Returns: hash value for @key
+ * Returns: hash value for the key
* Since: 1.2
*/
guint
/**
* json_array_equal:
- * @a: (type JsonArray): a JSON array
- * @b: (type JsonArray): another JSON array
+ * @a: (type JsonArray) (not nullable): a JSON array
+ * @b: (type JsonArray) (not nullable): another JSON array
+ *
+ * Check whether two arrays are equal.
+ *
+ * Equality is defined as:
*
- * Check whether @a and @b are equal #JsonArrays, meaning they have the same
- * number of elements, and the values of elements in corresponding positions
- * are equal.
+ * - the array have the same number of elements
+ * - the values of elements in corresponding positions are equal
*
- * Returns: %TRUE if @a and @b are equal; %FALSE otherwise
+ * Returns: `TRUE` if the arrays are equal, and `FALSE` otherwise
* Since: 1.2
*/
gboolean
*/
/**
- * SECTION:json-builder
- * @Title: JsonBuilder
- * @short_description: Generates JSON trees
- * @See_Also: JsonGenerator
+ * JsonBuilder:
*
- * #JsonBuilder provides an object for generating a JSON tree.
- * You can generate only one tree with one #JsonBuilder instance.
+ * `JsonBuilder` provides an object for generating a JSON tree.
*
- * The root of the JSON tree can be either a #JsonObject or a #JsonArray.
+ * The root of the JSON tree can be either a [struct@Json.Object] or a [struct@Json.Array].
* Thus the first call must necessarily be either
- * json_builder_begin_object() or json_builder_begin_array().
+ * [method@Json.Builder.begin_object] or [method@Json.Builder.begin_array].
*
- * For convenience to language bindings, #JsonBuilder returns itself from
- * most of functions, making it easy to chain function calls.
+ * For convenience to language bindings, most `JsonBuilder` method return the
+ * instance, making it easy to chain function calls.
+ *
+ * ## Using `JsonBuilder`
+ *
+ * ```c
+ * g_autoptr(JsonBuilder) builder = json_builder_new ();
+ *
+ * json_builder_begin_object (builder);
+ *
+ * json_builder_set_member_name (builder, "url");
+ * json_builder_add_string_value (builder, "http://www.gnome.org/img/flash/two-thirty.png");
+ *
+ * json_builder_set_member_name (builder, "size");
+ * json_builder_begin_array (builder);
+ * json_builder_add_int_value (builder, 652);
+ * json_builder_add_int_value (builder, 242);
+ * json_builder_end_array (builder);
+ *
+ * json_builder_end_object (builder);
+ *
+ * g_autoptr(JsonNode) root root = json_builder_get_root (builder);
+ *
+ * g_autoptr(JsonGenerator) gen = json_generator_new ();
+ * json_generator_set_root (gen, root);
+ * g_autofree char *str = json_generator_to_data (gen, NULL);
+ *
+ * // str now contains the following JSON data
+ * // { "url" : "http://www.gnome.org/img/flash/two-thirty.png", "size" : [ 652, 242 ] }
+ * ```
*/
#include "config.h"
/**
* JsonBuilder:immutable:
*
- * Whether the #JsonNode tree built by the #JsonBuilder should be immutable
- * when created. Making the output immutable on creation avoids the expense
+ * Whether the tree should be immutable when created.
+ *
+ * Making the output immutable on creation avoids the expense
* of traversing it to make it immutable later.
*
* Since: 1.2
/**
* json_builder_new:
*
- * Creates a new #JsonBuilder. You can use this object to generate a
- * JSON tree and obtain the root #JsonNode.
+ * Creates a new `JsonBuilder`.
+ *
+ * You can use this object to generate a JSON tree and obtain the root node.
*
- * Return value: the newly created #JsonBuilder instance
+ * Return value: the newly created builder instance
*/
JsonBuilder *
json_builder_new (void)
/**
* json_builder_new_immutable: (constructor)
*
- * Creates a new #JsonBuilder instance with its #JsonBuilder:immutable property
- * set to %TRUE to create immutable output trees.
+ * Creates a new, immutable `JsonBuilder` instance.
+ *
+ * It is equivalent to setting the [property@Json.Builder:immutable] property
+ * set to `TRUE` at construction time.
*
* Since: 1.2
- * Returns: (transfer full): a new #JsonBuilder
+ * Returns: (transfer full): the newly create builder instance
*/
JsonBuilder *
json_builder_new_immutable (void)
/**
* json_builder_get_root:
- * @builder: a #JsonBuilder
+ * @builder: a builder
*
- * Returns the root of the current constructed tree, if the build is complete
- * (ie: all opened objects, object members and arrays are being closed).
+ * Returns the root of the currently constructed tree.
*
- * Return value: (nullable) (transfer full): the #JsonNode, or %NULL if the
- * build is not complete. Free the returned value with json_node_unref().
+ * if the build is incomplete (ie: if there are any opened objects, or any
+ * open object members and array elements) then this function will return
+ * `NULL`.
+ *
+ * Return value: (nullable) (transfer full): the root node
*/
JsonNode *
json_builder_get_root (JsonBuilder *builder)
/**
* json_builder_reset:
- * @builder: a #JsonBuilder
+ * @builder: a builder
*
- * Resets the state of the @builder back to its initial state.
+ * Resets the state of the builder back to its initial state.
*/
void
json_builder_reset (JsonBuilder *builder)
/**
* json_builder_begin_object:
- * @builder: a #JsonBuilder
+ * @builder: a builder
+ *
+ * Opens an object inside the given builder.
+ *
+ * You can add a new member to the object by using [method@Json.Builder.set_member_name],
+ * followed by [method@Json.Builder.add_value].
*
- * Opens a subobject inside the given @builder. When done adding members to
- * the subobject, json_builder_end_object() must be called.
+ * Once you added all members to the object, you must call [method@Json.Builder.end_object]
+ * to close the object.
*
- * Can be called for first or only if the call is associated to an object member
- * or an array element.
+ * If the builder is in an inconsistent state, this function will return `NULL`.
*
- * Return value: (nullable) (transfer none): the #JsonBuilder, or %NULL if the
- * call was inconsistent
+ * Return value: (nullable) (transfer none): the builder instance
*/
JsonBuilder *
json_builder_begin_object (JsonBuilder *builder)
/**
* json_builder_end_object:
- * @builder: a #JsonBuilder
+ * @builder: a builder
*
- * Closes the subobject inside the given @builder that was opened by the most
- * recent call to json_builder_begin_object().
+ * Closes the object inside the given builder that was opened by the most
+ * recent call to [method@Json.Builder.begin_object].
*
- * Cannot be called after json_builder_set_member_name().
+ * This function cannot be called after [method@Json.Builder.set_member_name].
*
- * Return value: (nullable) (transfer none): the #JsonBuilder, or %NULL if the
- * call was inconsistent
+ * Return value: (nullable) (transfer none): the builder instance
*/
JsonBuilder *
json_builder_end_object (JsonBuilder *builder)
/**
* json_builder_begin_array:
- * @builder: a #JsonBuilder
+ * @builder: a builder
*
- * Opens a subarray inside the given @builder. When done adding members to
- * the subarray, json_builder_end_array() must be called.
+ * Opens an array inside the given builder.
*
- * Can be called for first or only if the call is associated to an object member
- * or an array element.
+ * You can add a new element to the array by using [method@Json.Builder.add_value].
*
- * Return value: (nullable) (transfer none): the #JsonBuilder, or %NULL if the
- * call was inconsistent
+ * Once you added all elements to the array, you must call
+ * [method@Json.Builder.end_array] to close the array.
+ *
+ * Return value: (nullable) (transfer none): the builder instance
*/
JsonBuilder *
json_builder_begin_array (JsonBuilder *builder)
/**
* json_builder_end_array:
- * @builder: a #JsonBuilder
+ * @builder: a builder
*
- * Closes the subarray inside the given @builder that was opened by the most
- * recent call to json_builder_begin_array().
+ * Closes the array inside the given builder that was opened by the most
+ * recent call to [method@Json.Builder.begin_array].
*
- * Cannot be called after json_builder_set_member_name().
+ * This function cannot be called after [method@Json.Builder.set_member_name].
*
- * Return value: (nullable) (transfer none): the #JsonBuilder, or %NULL if the
- * call was inconsistent
+ * Return value: (nullable) (transfer none): the builder instance
*/
JsonBuilder *
json_builder_end_array (JsonBuilder *builder)
/**
* json_builder_set_member_name:
- * @builder: a #JsonBuilder
+ * @builder: a builder
* @member_name: the name of the member
*
- * Set the name of the next member in an object. The next call must add a value,
- * open an object or an array.
+ * Sets the name of the member in an object.
+ *
+ * This function must be followed by of these functions:
+ *
+ * - [method@Json.Builder.add_value], to add a scalar value to the member
+ * - [method@Json.Builder.begin_object], to add an object to the member
+ * - [method@Json.Builder.begin_array], to add an array to the member
*
- * Can be called only if the call is associated to an object.
+ * This function can only be called within an open object.
*
- * Return value: (nullable) (transfer none): the #JsonBuilder, or %NULL if the
- * call was inconsistent
+ * Return value: (nullable) (transfer none): the builder instance
*/
JsonBuilder *
json_builder_set_member_name (JsonBuilder *builder,
/**
* json_builder_add_value:
- * @builder: a #JsonBuilder
+ * @builder: a builder
* @node: (transfer full): the value of the member or element
*
- * If called after json_builder_set_member_name(), sets @node as member of the
- * most recent opened object, otherwise @node is added as element of the most
- * recent opened array.
+ * Adds a value to the currently open object member or array.
*
- * The builder will take ownership of the #JsonNode.
+ * If called after [method@Json.Builder.set_member_name], sets the given node
+ * as the value of the current member in the open object; otherwise, the node
+ * is appended to the elements of the open array.
*
- * Return value: (nullable) (transfer none): the #JsonBuilder, or %NULL if the
- * call was inconsistent
+ * The builder will take ownership of the node.
+ *
+ * Return value: (nullable) (transfer none): the builder instance
*/
JsonBuilder *
json_builder_add_value (JsonBuilder *builder,
/**
* json_builder_add_int_value:
- * @builder: a #JsonBuilder
+ * @builder: a builder
* @value: the value of the member or element
*
- * If called after json_builder_set_member_name(), sets @value as member of the
- * most recent opened object, otherwise @value is added as element of the most
- * recent opened array.
+ * Adds an integer value to the currently open object member or array.
+ *
+ * If called after [method@Json.Builder.set_member_name], sets the given value
+ * as the value of the current member in the open object; otherwise, the value
+ * is appended to the elements of the open array.
*
- * See also: json_builder_add_value()
+ * See also: [method@Json.Builder.add_value]
*
- * Return value: (nullable) (transfer none): the #JsonBuilder, or %NULL if the
- * call was inconsistent
+ * Return value: (nullable) (transfer none): the builder instance
*/
JsonBuilder *
json_builder_add_int_value (JsonBuilder *builder,
/**
* json_builder_add_double_value:
- * @builder: a #JsonBuilder
+ * @builder: a builder
* @value: the value of the member or element
*
- * If called after json_builder_set_member_name(), sets @value as member of the
- * most recent opened object, otherwise @value is added as element of the most
- * recent opened array.
+ * Adds a floating point value to the currently open object member or array.
+ *
+ * If called after [method@Json.Builder.set_member_name], sets the given value
+ * as the value of the current member in the open object; otherwise, the value
+ * is appended to the elements of the open array.
*
- * See also: json_builder_add_value()
+ * See also: [method@Json.Builder.add_value]
*
- * Return value: (nullable) (transfer none): the #JsonBuilder, or %NULL if the
- * call was inconsistent
+ * Return value: (nullable) (transfer none): the builder instance
*/
JsonBuilder *
json_builder_add_double_value (JsonBuilder *builder,
/**
* json_builder_add_boolean_value:
- * @builder: a #JsonBuilder
+ * @builder: a builder
* @value: the value of the member or element
*
- * If called after json_builder_set_member_name(), sets @value as member of the
- * most recent opened object, otherwise @value is added as element of the most
- * recent opened array.
+ * Adds a boolean value to the currently open object member or array.
*
- * See also: json_builder_add_value()
+ * If called after [method@Json.Builder.set_member_name], sets the given value
+ * as the value of the current member in the open object; otherwise, the value
+ * is appended to the elements of the open array.
*
- * Return value: (nullable) (transfer none): the #JsonBuilder, or %NULL if the
- * call was inconsistent
+ * See also: [method@Json.Builder.add_value]
+ *
+ * Return value: (nullable) (transfer none): the builder instance
*/
JsonBuilder *
json_builder_add_boolean_value (JsonBuilder *builder,
/**
* json_builder_add_string_value:
- * @builder: a #JsonBuilder
+ * @builder: a builder
* @value: the value of the member or element
*
- * If called after json_builder_set_member_name(), sets @value as member of the
- * most recent opened object, otherwise @value is added as element of the most
- * recent opened array.
+ * Adds a boolean value to the currently open object member or array.
+ *
+ * If called after [method@Json.Builder.set_member_name], sets the given value
+ * as the value of the current member in the open object; otherwise, the value
+ * is appended to the elements of the open array.
*
- * See also: json_builder_add_value()
+ * See also: [method@Json.Builder.add_value]
*
- * Return value: (nullable) (transfer none): the #JsonBuilder, or %NULL if the
- * call was inconsistent
+ * Return value: (nullable) (transfer none): the builder instance
*/
JsonBuilder *
json_builder_add_string_value (JsonBuilder *builder,
/**
* json_builder_add_null_value:
- * @builder: a #JsonBuilder
+ * @builder: a builder
+ *
+ * Adds a null value to the currently open object member or array.
*
- * If called after json_builder_set_member_name(), sets null as member of the
- * most recent opened object, otherwise null is added as element of the most
- * recent opened array.
+ * If called after [method@Json.Builder.set_member_name], sets the given value
+ * as the value of the current member in the open object; otherwise, the value
+ * is appended to the elements of the open array.
*
- * See also: json_builder_add_value()
+ * See also: [method@Json.Builder.add_value]
*
- * Return value: (nullable) (transfer none): the #JsonBuilder, or %NULL if
- * the call was inconsistent
+ * Return value: (nullable) (transfer none): the builder instance
*/
JsonBuilder *
json_builder_add_null_value (JsonBuilder *builder)
typedef struct _JsonBuilderPrivate JsonBuilderPrivate;
typedef struct _JsonBuilderClass JsonBuilderClass;
-/**
- * JsonBuilder:
- *
- * The `JsonBuilder` structure contains only private data and should be
- * accessed using the provided API
- *
- * Since: 0.12
- */
struct _JsonBuilder
{
/*< private >*/
JsonBuilderPrivate *priv;
};
-/**
- * JsonBuilderClass:
- *
- * The `JsonBuilderClass` structure contains only private data
- *
- * Since: 0.12
- */
struct _JsonBuilderClass
{
/*< private >*/
GType
@enum_name@_get_type (void)
{
- static volatile gsize g_enum_type_id__volatile = 0;
+ static gsize g_enum_type_id__volatile = 0;
if (g_once_init_enter (&g_enum_type_id__volatile))
{
* Emmanuele Bassi <ebassi@linux.intel.com>
*/
-/**
- * SECTION:json-gboxed
- * @short_description: Serialize and deserialize GBoxed types
- *
- * GLib's #GBoxed type is a generic wrapper for arbitrary C structures.
- *
- * JSON-GLib allows serialization and deserialization of a #GBoxed type
- * by registering functions mapping a #JsonNodeType to a specific
- * #GType.
- *
- * When registering a #GBoxed type you should also register the
- * corresponding transformation functions, e.g.:
- *
- * |[<!-- language="C" -->
- * GType
- * my_struct_get_type (void)
- * {
- * static GType boxed_type = 0;
- *
- * if (boxed_type == 0)
- * {
- * boxed_type =
- * g_boxed_type_register_static (g_intern_static_string ("MyStruct"),
- * (GBoxedCopyFunc) my_struct_copy,
- * (GBoxedFreeFunc) my_struct_free);
- *
- * json_boxed_register_serialize_func (boxed_type, JSON_NODE_OBJECT,
- * my_struct_serialize);
- * json_boxed_register_deserialize_func (boxed_type, JSON_NODE_OBJECT,
- * my_struct_deserialize);
- * }
- *
- * return boxed_type;
- * }
- * ]|
- *
- * The serialization function will be invoked by json_boxed_serialize():
- * it will be passed a pointer to the C structure and it must return a
- * #JsonNode. The deserialization function will be invoked by
- * json_boxed_deserialize(): it will be passed a #JsonNode for the
- * declared type and it must return a newly allocated C structure.
- *
- * It is possible to check whether a #GBoxed type can be deserialized
- * from a specific #JsonNodeType, and whether a #GBoxed can be serialized
- * and to which specific #JsonNodeType.
- */
-
#include "config.h"
#include <string.h>
* json_boxed_register_serialize_func: (skip)
* @gboxed_type: a boxed type
* @node_type: a node type
- * @serialize_func: serialization function for @boxed_type into
- * a #JsonNode of type @node_type
+ * @serialize_func: serialization function
*
- * Registers a serialization function for a #GBoxed of type @gboxed_type
- * to a #JsonNode of type @node_type
+ * Registers a serialization function for a `GBoxed` of type `gboxed_type`
+ * to a [struct@Json.Node] of type `node_type`.
*
* Since: 0.10
*/
* json_boxed_register_deserialize_func: (skip)
* @gboxed_type: a boxed type
* @node_type: a node type
- * @deserialize_func: deserialization function for @boxed_type from
- * a #JsonNode of type @node_type
+ * @deserialize_func: deserialization function
*
- * Registers a deserialization function for a #GBoxed of type @gboxed_type
- * from a #JsonNode of type @node_type
+ * Registers a deserialization function for a `GBoxed` of type `gboxed_type`
+ * from a [struct@Json.Node] of type `node_type`.
*
* Since: 0.10
*/
/**
* json_boxed_can_serialize:
* @gboxed_type: a boxed type
- * @node_type: (out): the #JsonNode type to which the boxed type can be
- * serialized into
+ * @node_type: (out) (optional): the node type to which the boxed type
+ * can be serialized into
*
- * Checks whether it is possible to serialize a #GBoxed of
- * type @gboxed_type into a #JsonNode. The type of the
- * #JsonNode is placed inside @node_type if the function
- * returns %TRUE and it's undefined otherwise.
+ * Checks whether it is possible to serialize a `GBoxed` of
+ * type `gboxed_type` into a [struct@Json.Node].
*
- * Return value: %TRUE if the type can be serialized,
- * and %FALSE otherwise.
+ * The type of the node is placed inside `node_type` if the function
+ * returns `TRUE`, and it's undefined otherwise.
+ *
+ * Return value: `TRUE` if the type can be serialized, and `FALSE` otherwise
*
* Since: 0.10
*/
/**
* json_boxed_can_deserialize:
* @gboxed_type: a boxed type
- * @node_type: a #JsonNode type
+ * @node_type: a node type
*
- * Checks whether it is possible to deserialize a #GBoxed of
- * type @gboxed_type from a #JsonNode of type @node_type
+ * Checks whether it is possible to deserialize a `GBoxed` of
+ * type `gboxed_type` from a [struct@Json.Node] of type `node_type`.
*
- * Return value: %TRUE if the type can be deserialized, %FALSE otherwise
+ * Return value: `TRUE` if the type can be deserialized, and `FALSE` otherwise
*
* Since: 0.10
*/
/**
* json_boxed_serialize:
* @gboxed_type: a boxed type
- * @boxed: a pointer to a #GBoxed of type @gboxed_type
+ * @boxed: a pointer to a boxed of type `gboxed_type`
+ *
+ * Serializes a pointer to a `GBoxed` of the given type into a [struct@Json.Node].
*
- * Serializes @boxed, a pointer to a #GBoxed of type @gboxed_type,
- * into a #JsonNode
+ * If the serialization is not possible, this function will return `NULL`.
*
- * Return value: (nullable) (transfer full): a #JsonNode with the serialization of
- * the boxed type, or %NULL if serialization either failed or was not possible
+ * Return value: (nullable) (transfer full): a node with the serialized boxed type
*
* Since: 0.10
*/
/**
* json_boxed_deserialize:
* @gboxed_type: a boxed type
- * @node: a #JsonNode
+ * @node: a node
*
- * Deserializes @node into a #GBoxed of @gboxed_type
+ * Deserializes the given [struct@Json.Node] into a `GBoxed` of the given type.
*
- * Return value: (transfer full): the newly allocated #GBoxed. Use
- * g_boxed_free() to release the resources allocated by this
- * function
+ * Return value: (transfer full): the newly allocated boxed data
*
* Since: 0.10
*/
*/
/**
- * SECTION:json-generator
- * @short_description: Generates JSON data streams
+ * JsonGenerator:
*
- * #JsonGenerator provides an object for generating a JSON data stream and
- * put it into a buffer or a file.
+ * `JsonGenerator` provides an object for generating a JSON data stream
+ * from a tree of [struct@Json.Node] instances, and put it into a buffer
+ * or a file.
*/
#include "config.h"
GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
/**
- * JsonGenerator:pretty:
+ * JsonGenerator:pretty: (attributes org.gtk.Property.get=json_generator_get_pretty org.gtk.Property.set=json_generator_set_pretty)
*
* Whether the output should be "pretty-printed", with indentation and
- * newlines. The indentation level can be controlled by using the
- * JsonGenerator:indent property
+ * newlines.
+ *
+ * The indentation level can be controlled by using the
+ * [property@Json.Generator:indent] property.
*/
generator_props[PROP_PRETTY] =
g_param_spec_boolean ("pretty",
G_PARAM_READWRITE);
/**
- * JsonGenerator:indent:
+ * JsonGenerator:indent: (attributes org.gtk.Property.get=json_generator_get_indent org.gtk.Property.set=json_generator_set_indent)
*
* Number of spaces to be used to indent when pretty printing.
*/
G_PARAM_READWRITE);
/**
- * JsonGenerator:root:
+ * JsonGenerator:root: (attributes org.gtk.Property.get=json_generator_get_root org.gtk.Property.set=json_generator_set_root)
*
- * The root #JsonNode to be used when constructing a JSON data
+ * The root node to be used when constructing a JSON data
* stream.
*
* Since: 0.4
G_PARAM_READWRITE);
/**
- * JsonGenerator:indent-char:
+ * JsonGenerator:indent-char: (attributes org.gtk.Property.get=json_generator_get_indent_char org.gtk.Property.set=json_generator_set_indent_char)
*
* The character that should be used when indenting in pretty print.
*
/**
* json_generator_new:
*
- * Creates a new #JsonGenerator. You can use this object to generate a
- * JSON data stream starting from a data object model composed by
- * #JsonNodes.
+ * Creates a new `JsonGenerator`.
+ *
+ * You can use this object to generate a JSON data stream starting from a
+ * data object model composed by [struct@Json.Node]s.
*
- * Return value: the newly created #JsonGenerator instance
+ * Return value: the newly created generator instance
*/
JsonGenerator *
json_generator_new (void)
/**
* json_generator_to_gstring:
- * @generator: a #JsonGenerator
- * @string: a #GString
+ * @generator: a generator
+ * @string: a string buffer
*
- * Generates a JSON data stream from @generator
- * and appends it to @string.
+ * Generates a JSON data stream and appends it to the string buffer.
*
- * Return value: (transfer none): a #GString holding a JSON data stream.
- * Use g_string_free() to free the allocated resources.
+ * Return value: (transfer none): the passed string, updated with
+ * the generated JSON data
*
* Since: 1.4
*/
/**
* json_generator_to_data:
- * @generator: a #JsonGenerator
- * @length: (out): return location for the length of the returned
- * buffer, or %NULL
+ * @generator: a generator
+ * @length: (out) (optional): return location for the length of the returned
+ * buffer
*
* Generates a JSON data stream from @generator and returns it as a
* buffer.
*
- * Return value: a newly allocated buffer holding a JSON data stream.
- * Use g_free() to free the allocated resources.
+ * Return value: (transfer full): a newly allocated string holding a JSON data stream
*/
gchar *
json_generator_to_data (JsonGenerator *generator,
/**
* json_generator_to_file:
- * @generator: a #JsonGenerator
- * @filename: path to the target file
+ * @generator: a generator
+ * @filename: (type filename): the path to the target file
* @error: return location for a #GError, or %NULL
*
- * Creates a JSON data stream and puts it inside @filename, overwriting the
- * current file contents. This operation is atomic.
+ * Creates a JSON data stream and puts it inside `filename`, overwriting
+ * the file's current contents.
+ *
+ * This operation is atomic, in the sense that the data is written to a
+ * temporary file which is then renamed to the given `filename`.
*
* Return value: %TRUE if saving was successful.
*/
/**
* json_generator_to_stream:
- * @generator: a #JsonGenerator
- * @stream: a #GOutputStream
- * @cancellable: (allow-none): a #GCancellable, or %NULL
+ * @generator: a generator
+ * @stream: the output stream used to write the JSON data
+ * @cancellable: (nullable): a `GCancellable`
* @error: return location for a #GError, or %NULL
*
- * Outputs JSON data and streams it (synchronously) to @stream.
+ * Outputs JSON data and writes it (synchronously) to the given stream.
*
- * Return value: %TRUE if the write operation was successful, and %FALSE
- * on failure. In case of error, the #GError will be filled accordingly
+ * Return value: whether the write operation was successful
*
* Since: 0.12
*/
}
/**
- * json_generator_set_root:
- * @generator: a #JsonGenerator
- * @node: a #JsonNode
+ * json_generator_set_root: (attributes org.gtk.Method.set_property=root)
+ * @generator: a generator
+ * @node: the root node
*
- * Sets @node as the root of the JSON data stream to be serialized by
- * the #JsonGenerator.
+ * Sets the root of the JSON data stream to be serialized by
+ * the given generator.
*
- * The passed @node is copied by the generator object, so it can be
+ * The passed `node` is copied by the generator object, so it can be
* safely freed after calling this function.
*/
void
}
/**
- * json_generator_get_root:
- * @generator: a #JsonGenerator
+ * json_generator_get_root: (attributes org.gtk.Method.get_property=root)
+ * @generator: a generator
*
- * Retrieves a pointer to the root #JsonNode set using
- * json_generator_set_root().
+ * Retrieves a pointer to the root node set using
+ * [method@Json.Generator.set_root].
*
- * Return value: (nullable) (transfer none): a #JsonNode, or %NULL. The returned
- * node is owned by the #JsonGenerator and it should not be freed
+ * Return value: (nullable) (transfer none): the root node
*
* Since: 0.14
*/
}
/**
- * json_generator_set_pretty:
- * @generator: a #JsonGenerator
+ * json_generator_set_pretty: (attributes org.gtk.Method.set_property=pretty)
+ * @generator: a generator
* @is_pretty: whether the generated string should be pretty printed
*
- * Sets whether the generated JSON should be pretty printed, using the
- * indentation character specified in the #JsonGenerator:indent-char
- * property and the spacing specified in #JsonGenerator:indent property.
+ * Sets whether the generated JSON should be pretty printed.
+ *
+ * Pretty printing will use indentation character specified in the
+ * [property@Json.Generator:indent-char] property and the spacing
+ * specified in the [property@Json.Generator:indent] property.
*
* Since: 0.14
*/
}
/**
- * json_generator_get_pretty:
- * @generator: a #JsonGenerator
+ * json_generator_get_pretty: (attributes org.gtk.Method.get_property=pretty)
+ * @generator: a generator
*
- * Retrieves the value set using json_generator_set_pretty().
+ * Retrieves the value set using [method@Json.Generator.set_pretty].
*
- * Return value: %TRUE if the generated JSON should be pretty-printed, and
- * %FALSE otherwise
+ * Return value: `TRUE` if the generated JSON should be pretty-printed, and
+ * `FALSE` otherwise
*
* Since: 0.14
*/
}
/**
- * json_generator_set_indent:
- * @generator: a #JsonGenerator
+ * json_generator_set_indent: (attributes org.gtk.Method.set_property=indent)
+ * @generator: a generator
* @indent_level: the number of repetitions of the indentation character
* that should be applied when pretty printing
*
}
/**
- * json_generator_get_indent:
- * @generator: a #JsonGenerator
+ * json_generator_get_indent: (attributes org.gtk.Method.get_property=indent)
+ * @generator: a generator
*
- * Retrieves the value set using json_generator_set_indent().
+ * Retrieves the value set using [method@Json.Generator.set_indent].
*
* Return value: the number of repetitions per indentation level
*
guint
json_generator_get_indent (JsonGenerator *generator)
{
- g_return_val_if_fail (JSON_IS_GENERATOR (generator), FALSE);
+ g_return_val_if_fail (JSON_IS_GENERATOR (generator), 0);
return generator->priv->indent;
}
/**
- * json_generator_set_indent_char:
- * @generator: a #JsonGenerator
+ * json_generator_set_indent_char: (attributes org.gtk.Method.set_property=indent-char)
+ * @generator: a generator
* @indent_char: a Unicode character to be used when indenting
*
- * Sets the character to be used when indenting
+ * Sets the character to be used when indenting.
*
* Since: 0.14
*/
}
/**
- * json_generator_get_indent_char:
- * @generator: a #JsonGenerator
+ * json_generator_get_indent_char: (attributes org.gtk.Method.get_property=indent-char)
+ * @generator: a generator
*
- * Retrieves the value set using json_generator_set_indent_char().
+ * Retrieves the value set using [method@Json.Generator.set_indent_char].
*
* Return value: the character to be used when indenting
*
typedef struct _JsonGeneratorPrivate JsonGeneratorPrivate;
typedef struct _JsonGeneratorClass JsonGeneratorClass;
-/**
- * JsonGenerator:
- *
- * JSON data streams generator. The contents of the #JsonGenerator structure
- * are private and should only be accessed via the provided API.
- */
struct _JsonGenerator
{
/*< private >*/
JsonGeneratorPrivate *priv;
};
-/**
- * JsonGeneratorClass:
- *
- * #JsonGenerator class
- */
struct _JsonGeneratorClass
{
/*< private >*/
* Emmanuele Bassi <ebassi@openedhand.com>
*/
-/**
- * SECTION:json-gobject
- * @short_description: Serialize and deserialize GObjects
- *
- * JSON-GLib provides API for serializing and deserializing #GObject
- * instances to and from JSON data streams.
- *
- * Simple #GObject classes can be (de)serialized into JSON objects, if the
- * properties have compatible types with the native JSON types (integers,
- * booleans, strings, string vectors). If the class to be (de)serialized has
- * complex data types for properties (like boxed types or other objects)
- * then the class should implement the provided #JsonSerializable interface
- * and its virtual functions.
- */
-
#include "config.h"
#include <string.h>
gint value;
gboolean retval = TRUE;
- g_return_val_if_fail (G_TYPE_IS_ENUM (type), 0);
- g_return_val_if_fail (string != NULL, 0);
+ g_return_val_if_fail (G_TYPE_IS_ENUM (type), FALSE);
+ g_return_val_if_fail (string != NULL, FALSE);
value = strtoul (string, &endptr, 0);
if (endptr != string) /* parsed a number */
gunichar ch;
gboolean eos;
- g_return_val_if_fail (G_TYPE_IS_FLAGS (type), 0);
- g_return_val_if_fail (string != 0, 0);
+ g_return_val_if_fail (G_TYPE_IS_FLAGS (type), FALSE);
+ g_return_val_if_fail (string != 0, FALSE);
ret = TRUE;
/**
* json_gobject_deserialize:
- * @gtype: the type of the #GObject to create
- * @node: a #JsonNode of type %JSON_NODE_OBJECT describing the
- * instance of type @gtype
+ * @gtype: the type of the object to create
+ * @node: a node of type `JSON_NODE_OBJECT` describing the
+ * object instance for the given type
*
- * Creates a new #GObject of type @gtype, and constructs it
- * using the members of the passed #JsonObject
+ * Creates a new `GObject` instance of the given type, and constructs it
+ * using the members of the object in the given node.
*
- * Return value: (transfer full): The newly created #GObject
- * instance. Use g_object_unref() to free the resources
- * allocated by this function
+ * Return value: (transfer full): The newly created instance
*
* Since: 0.10
*/
/**
* json_gobject_serialize:
- * @gobject: a #GObject
+ * @gobject: the object to serialize
*
- * Creates a #JsonNode representing the passed #GObject
- * instance. Each member of the returned JSON object will
- * map to a property of the #GObject
+ * Creates a JSON tree representing the passed object instance.
*
- * Return value: (transfer full): the newly created #JsonNode
- * of type %JSON_NODE_OBJECT. Use json_node_unref() to free
- * the resources allocated by this function
+ * Each member of the returned JSON object will map to a property of
+ * the object type.
+ *
+ * The returned JSON tree will be returned as a `JsonNode` with a type
+ * of `JSON_NODE_OBJECT`.
+ *
+ * Return value: (transfer full): the newly created JSON tree
*
* Since: 0.10
*/
/**
* json_construct_gobject:
- * @gtype: the #GType of object to construct
+ * @gtype: the type of the object to construct
* @data: a JSON data stream
* @length: length of the data stream
* @error: return location for a #GError, or %NULL
*
- * Deserializes a JSON data stream and creates the corresponding
- * #GObject class. If @gtype implements the #JsonSerializableIface
- * interface, it will be asked to deserialize all the JSON members
- * into the respective properties; otherwise, the default implementation
- * will be used to translate the compatible JSON native types.
+ * Deserializes a JSON data stream and creates an instance of the given
+ * type
+ *
+ * If the given type implements the [iface@Json.Serializable] interface, it
+ * will be asked to deserialize all the JSON members into their respective
+ * properties; otherwise, the default implementation will be used to translate
+ * the compatible JSON native types.
*
- * Note: the JSON data stream must be an object declaration.
+ * **Note**: the JSON data stream must be an object.
*
- * Return value: (transfer full): a #GObject or %NULL
+ * Return value: (transfer full) (nullable): a new object instance of the given type
*
* Since: 0.4
*
- * Deprecated: 0.10: Use json_gobject_from_data() instead
+ * Deprecated: 0.10: Use [func@Json.gobject_from_data] instead
*/
GObject *
json_construct_gobject (GType gtype,
/**
* json_gobject_from_data:
- * @gtype: the #GType of object to construct
+ * @gtype: the type of the object to construct
* @data: a JSON data stream
- * @length: length of the data stream, or -1 if it is NUL-terminated
+ * @length: length of the data stream, or -1 if it is `NUL`-terminated
* @error: return location for a #GError, or %NULL
*
- * Deserializes a JSON data stream and creates the corresponding
- * #GObject class. If @gtype implements the #JsonSerializableIface
- * interface, it will be asked to deserialize all the JSON members
- * into the respective properties; otherwise, the default implementation
- * will be used to translate the compatible JSON native types.
+ * Deserializes a JSON data stream and creates an instance of the
+ * given type.
*
- * Note: the JSON data stream must be an object declaration.
+ * If the type implements the [iface@Json.Serializable] interface, it will
+ * be asked to deserialize all the JSON members into their respective properties;
+ * otherwise, the default implementation will be used to translate the
+ * compatible JSON native types.
*
- * Return value: (transfer full): a #GObject or %NULL
+ * **Note**: the JSON data stream must be an object
+ *
+ * Return value: (transfer full) (nullable): a new object instance of the given type
*
* Since: 0.10
*/
/**
* json_serialize_gobject:
- * @gobject: a #GObject
- * @length: (out): return value for the length of the buffer, or %NULL
+ * @gobject: the object to serialize
+ * @length: (out) (optional): return value for the length of the buffer
+ *
+ * Serializes a `GObject` instance into a JSON data stream.
*
- * Serializes a #GObject into a JSON data stream. If @gobject implements
- * the #JsonSerializableIface interface, it will be asked to serizalize all
- * its properties; otherwise, the default implementation will be use to
- * translate the compatible types into JSON native types.
+ * If the object implements the [iface@Json.Serializable] interface, it will be
+ * asked to serizalize all its properties; otherwise, the default
+ * implementation will be use to translate the compatible types into JSON
+ * native types.
*
- * Return value: a JSON data stream representing the passed #GObject
+ * Return value: (transfer full): a JSON data stream representing the given object
*
- * Deprecated: 0.10: Use json_gobject_to_data() instead
+ * Deprecated: 0.10: Use [func@Json.gobject_to_data] instead
*/
gchar *
json_serialize_gobject (GObject *gobject,
/**
* json_gobject_to_data:
- * @gobject: a #GObject
- * @length: (out): return value for the length of the buffer, or %NULL
+ * @gobject: the object to serialize
+ * @length: (out) (optional): return value for the length of the buffer
*
- * Serializes a #GObject into a JSON data stream, iterating recursively
- * over each property.
+ * Serializes a `GObject` instance into a JSON data stream, iterating
+ * recursively over each property.
*
- * If @gobject implements the #JsonSerializableIface interface, it will
- * be asked to serialize all its properties; otherwise, the default
+ * If the given object implements the [iface@Json.Serializable] interface,
+ * it will be asked to serialize all its properties; otherwise, the default
* implementation will be use to translate the compatible types into
* JSON native types.
*
- * Return value: a JSON data stream representing the passed #GObject
+ * Return value: a JSON data stream representing the given object
*
* Since: 0.10
*/
/**
* JsonSerializableIface:
- * @serialize_property: virtual function for serializing a #GObject property
- * into a #JsonNode
- * @deserialize_property: virtual function for deserializing a #JsonNode
- * into a #GObject property
+ * @serialize_property: virtual function for serializing an object property
+ * into JSON
+ * @deserialize_property: virtual function for deserializing JSON
+ * into an object property
* @find_property: virtual function for finding a property definition using
* its name
* @list_properties: virtual function for listing the installed property
* @set_property: virtual function for setting a property
* @get_property: virtual function for getting a property
*
- * Interface that allows serializing and deserializing #GObject instances
- * with properties storing complex data types. The json_serialize_gobject()
- * function will check if the passed #GObject implements this interface,
+ * Interface that allows serializing and deserializing object instances
+ * with properties storing complex data types.
+ *
+ * The [func@Json.gobject_from_data] and [func@Json.gobject_to_data]
+ * functions will check if the passed object type implements this interface,
* so it can also be used to override the default property serialization
* sequence.
*/
/**
* JsonBoxedSerializeFunc:
- * @boxed: a #GBoxed
+ * @boxed: a boxed data structure
+ *
+ * Serializes the passed `GBoxed` and stores it inside a `JsonNode`, for instance:
+ *
+ * ```c
+ * static JsonNode *
+ * my_point_serialize (gconstpointer boxed)
+ * {
+ * const MyPoint *point = boxed;
+ *
+ * g_autoptr(JsonBuilder) builder = json_builder_new ();
+ *
+ * json_builder_begin_object (builder);
+ * json_builder_set_member_name (builder, "x");
+ * json_builder_add_double_value (builder, point->x);
+ * json_builder_set_member_name (builder, "y");
+ * json_builder_add_double_value (builder, point->y);
+ * json_builder_end_object (builder);
*
- * Serializes the passed #GBoxed and stores it inside a #JsonNode
+ * return json_builder_get_root (builder);
+ * }
+ * ```
*
- * Return value: the newly created #JsonNode
+ * Return value: the newly created JSON node tree representing the boxed data
*
* Since: 0.10
*/
/**
* JsonBoxedDeserializeFunc:
- * @node: a #JsonNode
+ * @node: a node tree representing a boxed data
+ *
+ * Deserializes the contents of the passed `JsonNode` into a `GBoxed`, for instance:
+ *
+ * ```c
+ * static gpointer
+ * my_point_deserialize (JsonNode *node)
+ * {
+ * double x = 0.0, y = 0.0;
+ *
+ * if (JSON_NODE_HOLDS_ARRAY (node))
+ * {
+ * JsonArray *array = json_node_get_array (node);
+ *
+ * if (json_array_get_length (array) == 2)
+ * {
+ * x = json_array_get_double_element (array, 0);
+ * y = json_array_get_double_element (array, 1);
+ * }
+ * }
+ * else if (JSON_NODE_HOLDS_OBJECT (node))
+ * {
+ * JsonObject *obj = json_node_get_object (node);
+ *
+ * x = json_object_get_double_member_with_default (obj, "x", 0.0);
+ * y = json_object_get_double_member_with_default (obj, "y", 0.0);
+ * }
*
- * Deserializes the contents of the passed #JsonNode into a #GBoxed
+ * // my_point_new() is defined elsewhere
+ * return my_point_new (x, y);
+ * }
+ * ```
*
- * Return value: the newly created boxed type
+ * Return value: the newly created boxed structure
*
* Since: 0.10
*/
#include "json-parser.h"
#include "json-types-private.h"
-/**
- * SECTION:json-gvariant
- * @short_description: Serialize and deserialize GVariant types
- * @Title: JSON GVariant Integration
- *
- * Use json_gvariant_serialize() and json_gvariant_serialize_data() to
- * convert from any #GVariant value to a #JsonNode tree or its string
- * representation.
- *
- * Use json_gvariant_deserialize() and json_gvariant_deserialize_data() to
- * obtain the #GVariant value from a #JsonNode tree or directly from a JSON
- * string.
- *
- * Since many #GVariant data types cannot be directly represented as
- * JSON, a #GVariant type string (signature) should be provided to these
- * methods in order to obtain a correct, type-contrained result.
- * If no signature is provided, conversion can still be done, but the
- * resulting #GVariant value will be "guessed" from the JSON data types
- * using the following rules:
- *
- * ## Strings
- * JSON strings map to GVariant `(s)`.
- *
- * ## Integers
- * JSON integers map to GVariant int64 `(x)`.
- *
- * ## Booleans
- * JSON booleans map to GVariant boolean `(b)`.
- *
- * ## Numbers
- * JSON numbers map to GVariant double `(d)`.
- *
- * ## Arrays
- * JSON arrays map to GVariant arrays of variants `(av)`.
- *
- * ## Objects
- * JSON objects map to GVariant dictionaries of string to variants `(a{sv})`.
- *
- * ## Null values
- * JSON null values map to GVariant maybe variants `(mv)`.
- */
-
/* custom extension to the GVariantClass enumeration to differentiate
* a single dictionary entry from an array of dictionary entries
*/
/**
* json_gvariant_serialize:
- * @variant: A #GVariant to convert
+ * @variant: A `GVariant` to convert
*
- * Converts @variant to a JSON tree.
+ * Converts `variant` to a JSON tree.
*
- * Return value: (transfer full): A #JsonNode representing the root of the
- * JSON data structure obtained from @variant
+ * Return value: (transfer full): the root of the JSON data structure
+ * obtained from `variant`
*
* Since: 0.14
*/
/**
* json_gvariant_serialize_data:
* @variant: A #GVariant to convert
- * @length: (out) (allow-none): Return location for the length of the returned
- * string, or %NULL
+ * @length: (out) (optional): the length of the returned string
*
- * Converts @variant to its JSON encoded string representation. This method
- * is actually a helper function. It uses json_gvariant_serialize() to obtain the
- * JSON tree, and then #JsonGenerator to stringify it.
+ * Converts @variant to its JSON encoded string representation.
+ *
+ * This is a convenience function around [func@Json.gvariant_serialize], to
+ * obtain the JSON tree, and then [class@Json.Generator] to stringify it.
*
* Return value: (transfer full): The JSON encoded string corresponding to
- * @variant
+ * the given variant
*
* Since: 0.14
*/
/**
* json_gvariant_deserialize:
- * @json_node: A #JsonNode to convert
- * @signature: (allow-none): A valid #GVariant type string, or %NULL
- * @error: A pointer to a #GError
+ * @json_node: the node to convert
+ * @signature: (nullable): a valid `GVariant` type string
+ * @error: (nullable): return location for a #GError, or `NULL`
+ *
+ * Converts a JSON data structure to a `GVariant`.
*
- * Converts a JSON data structure to a GVariant value using @signature to
- * resolve ambiguous data types. If no error occurs, the resulting #GVariant
- * is guaranteed to conform to @signature.
+ * If `signature` is not `NULL`, it will be used to resolve ambiguous
+ * data types.
*
- * If @signature is not %NULL but does not represent a valid GVariant type
- * string, %NULL is returned and error is set to %G_IO_ERROR_INVALID_ARGUMENT.
- * If a @signature is provided but the JSON structure cannot be mapped to it,
- * %NULL is returned and error is set to %G_IO_ERROR_INVALID_DATA.
- * If @signature is %NULL, the conversion is done based strictly on the types
+ * If no error occurs, the resulting `GVariant` is guaranteed to conform
+ * to `signature`.
+ *
+ * If `signature` is not `NULL` but does not represent a valid `GVariant` type
+ * string, `NULL` is returned and the `error` is set to
+ * `G_IO_ERROR_INVALID_ARGUMENT`.
+ *
+ * If a `signature` is provided but the JSON structure cannot be mapped to it,
+ * `NULL` is returned and the `error` is set to `G_IO_ERROR_INVALID_DATA`.
+ *
+ * If `signature` is `NULL`, the conversion is done based strictly on the types
* in the JSON nodes.
*
* The returned variant has a floating reference that will need to be sunk
* by the caller code.
*
- * Return value: (transfer none): A newly created, floating #GVariant
- * compliant with @signature, or %NULL on error
+ * Return value: (transfer floating) (nullable): A newly created `GVariant`
*
* Since: 0.14
*/
/**
* json_gvariant_deserialize_data:
* @json: A JSON data string
- * @length: The length of @json, or -1 if %NULL-terminated
- * @signature: (allow-none): A valid #GVariant type string, or %NULL
+ * @length: The length of @json, or -1 if `NUL`-terminated
+ * @signature: (nullable): A valid `GVariant` type string
* @error: A pointer to a #GError
*
- * Converts a JSON string to a #GVariant value. This method works exactly
- * like json_gvariant_deserialize(), but takes a JSON encoded string instead.
- * The string is first converted to a #JsonNode using #JsonParser, and then
- * json_gvariant_deserialize() is called.
+ * Converts a JSON string to a `GVariant` value.
+ *
+ * This function works exactly like [func@Json.gvariant_deserialize], but
+ * takes a JSON encoded string instead.
+ *
+ * The string is first converted to a [struct@Json.Node] using
+ * [class@Json.Parser], and then `json_gvariant_deserialize` is called on
+ * the node.
*
* The returned variant has a floating reference that will need to be sunk
* by the caller code.
*
- * Returns: (transfer none): A newly created, floating #GVariant compliant
- * with @signature, or %NULL on error
+ * Returns: (transfer floating) (nullable): A newly created `GVariant`D compliant
*
* Since: 0.14
*/
#include "json-debug.h"
/**
- * SECTION:json-node
- * @short_description: Node in a JSON object model
+ * JsonNode:
*
- * A #JsonNode is a generic container of elements inside a JSON stream.
- * It can contain fundamental types (integers, booleans, floating point
+ * A generic container of JSON data types.
+ *
+ * `JsonNode` can contain fundamental types (integers, booleans, floating point
* numbers, strings) and complex types (arrays and objects).
*
* When parsing a JSON data stream you extract the root node and walk
* the node tree by retrieving the type of data contained inside the
- * node with the %JSON_NODE_TYPE macro. If the node contains a fundamental
- * type you can retrieve a copy of the #GValue holding it with the
- * json_node_get_value() function, and then use the #GValue API to extract
+ * node with the `JSON_NODE_TYPE` macro. If the node contains a fundamental
+ * type you can retrieve a copy of the `GValue` holding it with the
+ * [method@Json.Node.get_value] function, and then use the `GValue` API to extract
* the data; if the node contains a complex type you can retrieve the
- * #JsonObject or the #JsonArray using json_node_get_object() or
- * json_node_get_array() respectively, and then retrieve the nodes
+ * [struct@Json.Object] or the [struct@Json.Array] using [method@Json.Node.get_object]
+ * or [method@Json.Node.get_array] respectively, and then retrieve the nodes
* they contain.
*
- * A #JsonNode may be marked as immutable using json_node_seal(). This marks the
- * node and all its descendents as read-only, and means that subsequent calls to
- * setter functions (such as json_node_set_array()) on them will abort as a
- * programmer error. By marking a node tree as immutable, it may be referenced
- * in multiple places and its hash value cached for fast lookups, without the
- * possibility of a value deep within the tree changing and affecting hash
- * values. Immutable #JsonNodes may be passed to functions which retain a
- * reference to them without needing to take a copy.
- *
- * #JsonNode supports two types of memory management: alloc/free semantics, and
- * ref/unref semantics. The two may be mixed to a limited extent: nodes may be
- * allocated (which gives them a reference count of 1), referenced zero or more
- * times, unreferenced exactly that number of times (using json_node_unref()),
- * then either unreferenced exactly once more or freed (using json_node_free())
- * to destroy them. json_node_free() must not be used when a node might have a
- * reference count not equal to 1. To this end, json-glib uses json_node_copy()
- * and json_node_unref() internally.
+ * A `JsonNode` may be marked as immutable using [method@Json.Node.seal]. This
+ * marks the node and all its descendents as read-only, and means that
+ * subsequent calls to setter functions (such as [method@Json.Node.set_array])
+ * on them will abort as a programmer error. By marking a node tree as
+ * immutable, it may be referenced in multiple places and its hash value cached
+ * for fast lookups, without the possibility of a value deep within the tree
+ * changing and affecting hash values. Immutable nodes may be passed to
+ * functions which retain a reference to them without needing to take a copy.
+ *
+ * A `JsonNode` supports two types of memory management: `malloc`/`free`
+ * semantics, and reference counting semantics. The two may be mixed to a
+ * limited extent: nodes may be allocated (which gives them a reference count
+ * of 1), referenced one or more times, unreferenced exactly that number of
+ * times (using [method@Json.Node.unref]), then either unreferenced exactly
+ * once more or freed (using [method@Json.Node.free]) to destroy them.
+ * The [method@Json.Node.free] function must not be used when a node might
+ * have a reference count not equal to 1. To this end, JSON-GLib uses
+ * [method@Json.Node.copy] and [method@Json.Node.unref] internally.
*/
-G_DEFINE_BOXED_TYPE (JsonNode, json_node, json_node_copy, json_node_unref);
+G_DEFINE_BOXED_TYPE (JsonNode, json_node, json_node_copy, json_node_unref)
/**
* json_node_get_value_type:
- * @node: a #JsonNode
+ * @node: the node to check
+ *
+ * Returns the `GType` of the payload of the node.
*
- * Returns the #GType of the payload of the node.
+ * For `JSON_NODE_NULL` nodes, the returned type is `G_TYPE_INVALID`.
*
- * Return value: a #GType for the payload.
+ * Return value: the type for the payload
*
* Since: 0.4
*/
/**
* json_node_alloc: (constructor)
*
- * Allocates a new #JsonNode. Use json_node_init() and its variants
- * to initialize the returned value.
+ * Allocates a new, uninitialized node.
+ *
+ * Use [method@Json.Node.init] and its variants to initialize the returned value.
*
- * Return value: (transfer full): the newly allocated #JsonNode. Use
- * json_node_free() to free the resources allocated by this function
+ * Return value: (transfer full): the newly allocated node
*
* Since: 0.16
*/
/**
* json_node_init:
- * @node: the #JsonNode to initialize
+ * @node: the node to initialize
* @type: the type of JSON node to initialize @node to
*
* Initializes a @node to a specific @type.
* If the node has already been initialized once, it will be reset to
* the given type, and any data contained will be cleared.
*
- * Return value: (transfer none): the initialized #JsonNode
+ * Return value: (transfer none): the initialized node
*
* Since: 0.16
*/
/**
* json_node_init_object:
- * @node: the #JsonNode to initialize
- * @object: (allow-none): the #JsonObject to initialize @node with, or %NULL
+ * @node: the node to initialize
+ * @object: (nullable): the JSON object to initialize @node with, or `NULL`
*
- * Initializes @node to %JSON_NODE_OBJECT and sets @object into it.
+ * Initializes @node to `JSON_NODE_OBJECT` and sets @object into it.
*
* This function will take a reference on @object.
*
* If the node has already been initialized once, it will be reset to
* the given type, and any data contained will be cleared.
*
- * Return value: (transfer none): the initialized #JsonNode
+ * Return value: (transfer none): the initialized node
*
* Since: 0.16
*/
/**
* json_node_init_array:
- * @node: the #JsonNode to initialize
- * @array: (allow-none): the #JsonArray to initialize @node with, or %NULL
+ * @node: the node to initialize
+ * @array: (nullable): the JSON array to initialize @node with, or `NULL`
*
- * Initializes @node to %JSON_NODE_ARRAY and sets @array into it.
+ * Initializes @node to `JSON_NODE_ARRAY` and sets @array into it.
*
* This function will take a reference on @array.
*
* If the node has already been initialized once, it will be reset to
* the given type, and any data contained will be cleared.
*
- * Return value: (transfer none): the initialized #JsonNode
+ * Return value: (transfer none): the initialized node
*
* Since: 0.16
*/
/**
* json_node_init_int:
- * @node: the #JsonNode to initialize
+ * @node: the node to initialize
* @value: an integer
*
- * Initializes @node to %JSON_NODE_VALUE and sets @value into it.
+ * Initializes @node to `JSON_NODE_VALUE` and sets @value into it.
*
* If the node has already been initialized once, it will be reset to
* the given type, and any data contained will be cleared.
*
- * Return value: (transfer none): the initialized #JsonNode
+ * Return value: (transfer none): the initialized node
*
* Since: 0.16
*/
/**
* json_node_init_double:
- * @node: the #JsonNode to initialize
+ * @node: the node to initialize
* @value: a floating point value
*
- * Initializes @node to %JSON_NODE_VALUE and sets @value into it.
+ * Initializes @node to `JSON_NODE_VALUE` and sets @value into it.
*
* If the node has already been initialized once, it will be reset to
* the given type, and any data contained will be cleared.
*
- * Return value: (transfer none): the initialized #JsonNode
+ * Return value: (transfer none): the initialized node
*
* Since: 0.16
*/
/**
* json_node_init_boolean:
- * @node: the #JsonNode to initialize
+ * @node: the node to initialize
* @value: a boolean value
*
- * Initializes @node to %JSON_NODE_VALUE and sets @value into it.
+ * Initializes @node to `JSON_NODE_VALUE` and sets @value into it.
*
* If the node has already been initialized once, it will be reset to
* the given type, and any data contained will be cleared.
*
- * Return value: (transfer none): the initialized #JsonNode
+ * Return value: (transfer none): the initialized node
*
* Since: 0.16
*/
/**
* json_node_init_string:
- * @node: the #JsonNode to initialize
- * @value: (allow-none): a string value
+ * @node: the node to initialize
+ * @value: (nullable): a string value
*
- * Initializes @node to %JSON_NODE_VALUE and sets @value into it.
+ * Initializes @node to `JSON_NODE_VALUE` and sets @value into it.
*
* If the node has already been initialized once, it will be reset to
* the given type, and any data contained will be cleared.
*
- * Return value: (transfer none): the initialized #JsonNode
+ * Return value: (transfer none): the initialized node
*
* Since: 0.16
*/
/**
* json_node_init_null:
- * @node: the #JsonNode to initialize
+ * @node: the node to initialize
*
- * Initializes @node to %JSON_NODE_NULL.
+ * Initializes @node to `JSON_NODE_NULL`.
*
* If the node has already been initialized once, it will be reset to
* the given type, and any data contained will be cleared.
*
- * Return value: (transfer none): the initialized #JsonNode
+ * Return value: (transfer none): the initialized node
*
* Since: 0.16
*/
/**
* json_node_new: (constructor)
- * @type: a #JsonNodeType
+ * @type: the type of the node to create
*
- * Creates a new #JsonNode of @type.
+ * Creates a new node holding the given @type.
*
- * This is a convenience function for json_node_alloc() and json_node_init(),
- * and it's the equivalent of:
+ * This is a convenience function for [ctor@Json.Node.alloc] and
+ * [method@Json.Node.init], and it's the equivalent of:
*
- * |[<!-- language="C" -->
- json_node_init (json_node_alloc (), type);
- * ]|
+ * ```c
+ json_node_init (json_node_alloc (), type);
+ * ```
*
- * Return value: (transfer full): the newly created #JsonNode
+ * Return value: (transfer full): the newly created node
*/
JsonNode *
json_node_new (JsonNodeType type)
/**
* json_node_copy:
- * @node: a #JsonNode
+ * @node: the node to copy
*
- * Copies @node. If the node contains complex data types, their reference
+ * Copies @node.
+ *
+ * If the node contains complex data types, their reference
* counts are increased, regardless of whether the node is mutable or
* immutable.
*
* The copy will be immutable if, and only if, @node is immutable. However,
* there should be no need to copy an immutable node.
*
- * Return value: (transfer full): the copied #JsonNode
+ * Return value: (transfer full): the copied of the given node
*/
JsonNode *
json_node_copy (JsonNode *node)
/**
* json_node_ref:
- * @node: a #JsonNode
+ * @node: the node to reference
*
- * Increment the reference count of @node.
+ * Increments the reference count of @node.
*
* Since: 1.2
* Returns: (transfer full): a pointer to @node
/**
* json_node_unref:
- * @node: (transfer full): a #JsonNode
+ * @node: (transfer full): the node to unreference
+ *
+ * Decrements the reference count of @node.
*
- * Decrement the reference count of @node. If it reaches zero, the node is
- * freed.
+ * If the reference count reaches zero, the node is freed.
*
* Since: 1.2
*/
/**
* json_node_set_object:
- * @node: a #JsonNode initialized to %JSON_NODE_OBJECT
- * @object: (nullable): a #JsonObject
+ * @node: a node initialized to `JSON_NODE_OBJECT`
+ * @object: (nullable): a JSON object
+ *
+ * Sets @objects inside @node.
*
- * Sets @objects inside @node. The reference count of @object is increased.
+ * The reference count of @object is increased.
*
- * If @object is %NULL, the node’s existing object is cleared.
+ * If @object is `NULL`, the node’s existing object is cleared.
*
* It is an error to call this on an immutable node, or on a node which is not
* an object node.
/**
* json_node_take_object:
- * @node: a #JsonNode initialized to %JSON_NODE_OBJECT
- * @object: (transfer full): a #JsonObject
+ * @node: a node initialized to `JSON_NODE_OBJECT`
+ * @object: (transfer full): a JSON object
*
- * Sets @object inside @node. The reference count of @object is not increased.
+ * Sets @object inside @node.
+ *
+ * The reference count of @object is not increased.
*
* It is an error to call this on an immutable node, or on a node which is not
* an object node.
/**
* json_node_get_object:
- * @node: a #JsonNode
+ * @node: a node holding a JSON object
+ *
+ * Retrieves the object stored inside a node.
*
- * Retrieves the #JsonObject stored inside a #JsonNode. It is a programmer error
- * to call this on a node which doesn’t hold an object value. Use
- * %JSON_NODE_HOLDS_OBJECT first.
+ * It is a programmer error to call this on a node which doesn’t hold an
+ * object value. Use `JSON_NODE_HOLDS_OBJECT` first.
*
- * Return value: (transfer none) (nullable): the #JsonObject
+ * Return value: (transfer none) (nullable): the JSON object
*/
JsonObject *
json_node_get_object (JsonNode *node)
/**
* json_node_dup_object:
- * @node: a #JsonNode
+ * @node: a node holding a JSON object
+ *
+ * Retrieves the object inside @node.
*
- * Retrieves the #JsonObject inside @node. The reference count of
- * the returned object is increased. It is a programmer error
- * to call this on a node which doesn’t hold an object value. Use
- * %JSON_NODE_HOLDS_OBJECT first.
+ * The reference count of the returned object is increased.
*
- * Return value: (transfer full) (nullable): the #JsonObject
+ * It is a programmer error to call this on a node which doesn’t hold an
+ * object value. Use `JSON_NODE_HOLDS_OBJECT` first.
+ *
+ * Return value: (transfer full) (nullable): the JSON object
*/
JsonObject *
json_node_dup_object (JsonNode *node)
/**
* json_node_set_array:
- * @node: a #JsonNode initialized to %JSON_NODE_ARRAY
- * @array: a #JsonArray
+ * @node: a node initialized to `JSON_NODE_ARRAY`
+ * @array: a JSON array
*
- * Sets @array inside @node and increases the #JsonArray reference count.
+ * Sets @array inside @node.
*
- * It is an error to call this on an immutable node, or on a node which is not
- * an array node.
+ * The reference count of @array is increased.
+ *
+ * It is a programmer error to call this on a node which doesn’t hold an
+ * array value. Use `JSON_NODE_HOLDS_ARRAY` first.
*/
void
json_node_set_array (JsonNode *node,
/**
* json_node_take_array:
- * @node: a #JsonNode initialized to %JSON_NODE_ARRAY
- * @array: (transfer full): a #JsonArray
+ * @node: a node initialized to `JSON_NODE_ARRAY`
+ * @array: (transfer full): a JSON array
+ *
+ * Sets @array inside @node.
*
- * Sets @array into @node without increasing the #JsonArray reference count.
+ * The reference count of @array is not increased.
*
- * It is an error to call this on an immutable node, or a node which is not
- * an array node.
+ * It is a programmer error to call this on a node which doesn’t hold an
+ * array value. Use `JSON_NODE_HOLDS_ARRAY` first.
*/
void
json_node_take_array (JsonNode *node,
/**
* json_node_get_array:
- * @node: a #JsonNode
+ * @node: a node holding an array
+ *
+ * Retrieves the JSON array stored inside a node.
*
- * Retrieves the #JsonArray stored inside a #JsonNode. It is a programmer error
- * to call this on a node which doesn’t hold an array value. Use
- * %JSON_NODE_HOLDS_ARRAY first.
+ * It is a programmer error to call this on a node which doesn’t hold an
+ * array value. Use `JSON_NODE_HOLDS_ARRAY` first.
*
- * Return value: (transfer none) (nullable): the #JsonArray
+ * Return value: (transfer none) (nullable): the JSON array
*/
JsonArray *
json_node_get_array (JsonNode *node)
/**
* json_node_dup_array:
- * @node: a #JsonNode
+ * @node: a node holding an array
+ *
+ * Retrieves the JSON array inside @node.
+ *
+ * The reference count of the returned array is increased.
*
- * Retrieves the #JsonArray stored inside a #JsonNode and returns it
- * with its reference count increased by one. It is a programmer error
- * to call this on a node which doesn’t hold an array value. Use
- * %JSON_NODE_HOLDS_ARRAY first.
+ * It is a programmer error to call this on a node which doesn’t hold an
+ * array value. Use `JSON_NODE_HOLDS_ARRAY` first.
*
- * Return value: (transfer full) (nullable): the #JsonArray with its reference
+ * Return value: (transfer full) (nullable): the JSON array with its reference
* count increased.
*/
JsonArray *
/**
* json_node_get_value:
- * @node: a #JsonNode
+ * @node: a node
* @value: (out caller-allocates): return location for an uninitialized value
*
- * Retrieves a value from a #JsonNode and copies into @value. When done
- * using it, call g_value_unset() on the #GValue. It is a programmer error
- * to call this on a node which doesn’t hold a scalar value. Use
- * %JSON_NODE_HOLDS_VALUE first.
+ * Retrieves a value from a node and copies into @value.
+ *
+ * When done using it, call `g_value_unset()` on the `GValue` to free the
+ * associated resources.
+ *
+ * It is a programmer error to call this on a node which doesn’t hold a scalar
+ * value. Use `JSON_NODE_HOLDS_VALUE` first.
*/
void
json_node_get_value (JsonNode *node,
/**
* json_node_set_value:
- * @node: a #JsonNode initialized to %JSON_NODE_VALUE
- * @value: the #GValue to set
+ * @node: a node initialized to `JSON_NODE_VALUE`
+ * @value: the value to set
+ *
+ * Sets a scalar value inside the given node.
+ *
+ * The contents of the given `GValue` are copied into the `JsonNode`.
+ *
+ * The following `GValue` types have a direct mapping to JSON types:
*
- * Sets @value inside @node. The passed #GValue is copied into the #JsonNode.
+ * - `G_TYPE_INT64`
+ * - `G_TYPE_DOUBLE`
+ * - `G_TYPE_BOOLEAN`
+ * - `G_TYPE_STRING`
+ *
+ * JSON-GLib will also automatically promote the following `GValue` types:
+ *
+ * - `G_TYPE_INT` to `G_TYPE_INT64`
+ * - `G_TYPE_FLOAT` to `G_TYPE_DOUBLE`
*
* It is an error to call this on an immutable node, or on a node which is not
* a value node.
/**
* json_node_free:
- * @node: a #JsonNode
+ * @node: the node to free
*
- * Frees the resources allocated by @node.
+ * Frees the resources allocated by the node.
*/
void
json_node_free (JsonNode *node)
/**
* json_node_seal:
- * @node: a #JsonNode
+ * @node: the node to seal
+ *
+ * Seals the given node, making it immutable to further changes.
*
- * Seals the #JsonNode, making it immutable to further changes. In order to be
- * sealed, the @node must have a type and value set. The value will be
- * recursively sealed — if the node holds an object, that #JsonObject will be
- * sealed, etc.
+ * In order to be sealed, the @node must have a type and value set. The value
+ * will be recursively sealed — if the node holds an object, that JSON object
+ * will be sealed, etc.
*
- * If the @node is already immutable, this is a no-op.
+ * If the `node` is already immutable, this is a no-op.
*
* Since: 1.2
*/
/**
* json_node_is_immutable:
- * @node: a #JsonNode
+ * @node: the node to check
*
* Check whether the given @node has been marked as immutable by calling
- * json_node_seal() on it.
+ * [method@Json.Node.seal] on it.
*
* Since: 1.2
- * Returns: %TRUE if the @node is immutable
+ * Returns: `TRUE` if the @node is immutable
*/
gboolean
json_node_is_immutable (JsonNode *node)
/**
* json_node_type_name:
- * @node: a #JsonNode
+ * @node: a node
*
* Retrieves the user readable name of the data type contained by @node.
*
- * Return value: a string containing the name of the type. The returned string
- * is owned by the node and should never be modified or freed
+ * **Note**: The name is only meant for debugging purposes, and there is no
+ * guarantee the name will stay the same across different versions.
+ *
+ * Return value: (transfer none): a string containing the name of the type
*/
const gchar *
json_node_type_name (JsonNode *node)
/**
* json_node_set_parent:
- * @node: a #JsonNode
- * @parent: (transfer none): the parent #JsonNode of @node
+ * @node: the node to change
+ * @parent: (transfer none) (nullable): the parent node
*
- * Sets the parent #JsonNode of @node.
+ * Sets the parent node for the given `node`.
*
- * It is an error to call this with an immutable @parent. @node may be
- * immutable.
+ * It is an error to call this with an immutable @parent.
+ *
+ * The @node may be immutable.
*
* Since: 0.8
*/
/**
* json_node_get_parent:
- * @node: a #JsonNode
+ * @node: the node to query
*
- * Retrieves the parent #JsonNode of @node.
+ * Retrieves the parent node of the given @node.
*
- * Return value: (transfer none) (nullable): the parent node, or %NULL if @node
+ * Return value: (transfer none) (nullable): the parent node, or `NULL` if @node
* is the root node
*/
JsonNode *
/**
* json_node_set_string:
- * @node: a #JsonNode initialized to %JSON_NODE_VALUE
+ * @node: a node initialized to `JSON_NODE_VALUE`
* @value: a string value
*
* Sets @value as the string content of the @node, replacing any existing
/**
* json_node_get_string:
- * @node: a #JsonNode of type %JSON_NODE_VALUE
+ * @node: a node holding a string
+ *
+ * Gets the string value stored inside a node.
*
- * Gets the string value stored inside a #JsonNode. If the node does not hold a
- * string value, %NULL is returned.
+ * If the node does not hold a string value, `NULL` is returned.
*
* Return value: (nullable): a string value.
*/
/**
* json_node_dup_string:
- * @node: a #JsonNode of type %JSON_NODE_VALUE
+ * @node: a node holding a string
+ *
+ * Gets a copy of the string value stored inside a node.
*
- * Gets a copy of the string value stored inside a #JsonNode. If the node does
- * not hold a string value, %NULL is returned.
+ * If the node does not hold a string value, `NULL` is returned.
*
- * Return value: (transfer full) (nullable): a newly allocated string
- * containing a copy of the #JsonNode contents. Use g_free() to free the
- * allocated resources
+ * Return value: (transfer full) (nullable): a copy of the string
+ * inside the node
*/
gchar *
json_node_dup_string (JsonNode *node)
/**
* json_node_set_int:
- * @node: a #JsonNode of type %JSON_NODE_VALUE
+ * @node: a node initialized to `JSON_NODE_VALUE`
* @value: an integer value
*
* Sets @value as the integer content of the @node, replacing any existing
/**
* json_node_get_int:
- * @node: a #JsonNode of type %JSON_NODE_VALUE
+ * @node: a node holding an integer
+ *
+ * Gets the integer value stored inside a node.
+ *
+ * If the node holds a double value, its integer component is returned.
*
- * Gets the integer value stored inside a #JsonNode. If the node holds a double
- * value, its integer component is returned. If the node holds a %FALSE boolean
- * value, `0` is returned; otherwise a non-zero integer is returned. If the
- * node holds a %JSON_NODE_NULL value or a value of another non-integer type,
- * `0` is returned.
+ * If the node holds a `FALSE` boolean value, `0` is returned; otherwise,
+ * a non-zero integer is returned.
+ *
+ * If the node holds a `JSON_NODE_NULL` value or a value of another
+ * non-integer type, `0` is returned.
*
* Return value: an integer value.
*/
/**
* json_node_set_double:
- * @node: a #JsonNode of type %JSON_NODE_VALUE
+ * @node: a node initialized to `JSON_NODE_VALUE`
* @value: a double value
*
* Sets @value as the double content of the @node, replacing any existing
/**
* json_node_get_double:
- * @node: a #JsonNode of type %JSON_NODE_VALUE
+ * @node: a node holding a floating point value
+ *
+ * Gets the double value stored inside a node.
+ *
+ * If the node holds an integer value, it is returned as a double.
*
- * Gets the double value stored inside a #JsonNode. If the node holds an integer
- * value, it is returned as a double. If the node holds a %FALSE boolean value,
- * `0.0` is returned; otherwise a non-zero double is returned. If the node holds
- * a %JSON_NODE_NULL value or a value of another non-double type, `0.0` is
- * returned.
+ * If the node holds a `FALSE` boolean value, `0.0` is returned; otherwise
+ * a non-zero double is returned.
+ *
+ * If the node holds a `JSON_NODE_NULL` value or a value of another
+ * non-double type, `0.0` is returned.
*
* Return value: a double value.
*/
/**
* json_node_set_boolean:
- * @node: a #JsonNode of type %JSON_NODE_VALUE
+ * @node: a node initialized to `JSON_NODE_VALUE`
* @value: a boolean value
*
* Sets @value as the boolean content of the @node, replacing any existing
/**
* json_node_get_boolean:
- * @node: a #JsonNode of type %JSON_NODE_VALUE
+ * @node: a node holding a boolean value
+ *
+ * Gets the boolean value stored inside a node.
*
- * Gets the boolean value stored inside a #JsonNode. If the node holds an
- * integer or double value which is zero, %FALSE is returned; otherwise %TRUE
- * is returned. If the node holds a %JSON_NODE_NULL value or a value of another
- * non-boolean type, %FALSE is returned.
+ * If the node holds an integer or double value which is zero, `FALSE` is
+ * returned; otherwise `TRUE` is returned.
+ *
+ * If the node holds a `JSON_NODE_NULL` value or a value of another
+ * non-boolean type, `FALSE` is returned.
*
* Return value: a boolean value.
*/
/**
* json_node_get_node_type:
- * @node: a #JsonNode
+ * @node: the node to check
*
- * Retrieves the #JsonNodeType of @node
+ * Retrieves the type of a @node.
*
* Return value: the type of the node
*
/**
* json_node_is_null:
- * @node: a #JsonNode
+ * @node: the node to check
*
- * Checks whether @node is a %JSON_NODE_NULL.
+ * Checks whether @node is a `JSON_NODE_NULL`.
*
- * A %JSON_NODE_NULL node is not the same as a %NULL #JsonNode; a
- * %JSON_NODE_NULL represents a 'null' value in the JSON tree.
+ * A `JSON_NODE_NULL` node is not the same as a `NULL` node; a `JSON_NODE_NULL`
+ * represents a literal `null` value in the JSON tree.
*
- * Return value: %TRUE if the node is null
+ * Return value: `TRUE` if the node is null
*
* Since: 0.8
*/
return node->type == JSON_NODE_NULL;
}
-/**
+/*< private >
* json_type_is_a:
* @sub: sub-type
* @super: super-type
*
- * Check whether @sub is a sub-type of, or equal to, @super. The only sub-type
- * relationship in the JSON Schema type system is that
- * %WBL_PRIMITIVE_TYPE_INTEGER is a sub-type of %WBL_PRIMITIVE_TYPE_NUMBER.
+ * Check whether @sub is a sub-type of, or equal to, @super.
+ *
+ * The only sub-type relationship in the JSON Schema type system is that
+ * an integer type is a sub-type of a number type.
*
* Formally, this function calculates: `@sub <: @super`.
*
* Reference: http://json-schema.org/latest/json-schema-core.html#rfc.section.3.5
*
- * Returns: %TRUE if @sub is a sub-type of, or equal to, @super; %FALSE
- * otherwise
+ * Returns: `TRUE` if @sub is a sub-type of, or equal to, @super; `FALSE` otherwise
* Since: 1.2
*/
static gboolean
-json_type_is_a (JsonNode *sub,
- JsonNode *super)
+json_type_is_a (JsonNode *sub,
+ JsonNode *super)
{
if (super->type == JSON_NODE_VALUE && sub->type == JSON_NODE_VALUE)
{
*
* Check whether @a and @b are equal UTF-8 JSON strings.
*
- * Returns: %TRUE if @a and @b are equal; %FALSE otherwise
+ * Returns: `TRUE` if @a and @b are equal; `FALSE` otherwise
* Since: 1.2
*/
gboolean
* @b: (type utf8): another JSON string
*
* Check whether @a and @b are equal UTF-8 JSON strings and return an ordering
- * over them in strcmp() style.
+ * over them in `strcmp()` style.
+ *
+ * Returns: an integer less than zero if `a < b`, equal to zero if `a == b`, and
+ * greater than zero if `a > b`
*
- * Returns: an integer less than zero if @a < @b, equal to zero if @a == @b, and
- * greater than zero if @a > @b
* Since: 1.2
*/
gint
* json_node_hash:
* @key: (type JsonNode): a JSON node to hash
*
- * Calculate a hash value for the given @key (a #JsonNode).
+ * Calculate a hash value for the given @key.
*
* The hash is calculated over the node and its value, recursively. If the node
* is immutable, this is a fast operation; otherwise, it scales proportionally
* with the size of the node’s value (for example, with the number of members
- * in the #JsonObject if this node contains an object).
+ * in the JSON object if this node contains an object).
*
* Returns: hash value for @key
* Since: 1.2
* @a: (type JsonNode): a JSON node
* @b: (type JsonNode): another JSON node
*
- * Check whether @a and @b are equal #JsonNodes, meaning they have the same
- * type and same values (checked recursively). Note that integer values are
- * compared numerically, ignoring type, so a double value 4.0 is equal to the
- * integer value 4.
+ * Check whether @a and @b are equal node, meaning they have the same
+ * type and same values (checked recursively).
+ *
+ * Note that integer values are compared numerically, ignoring type, so a
+ * double value 4.0 is equal to the integer value 4.
*
- * Returns: %TRUE if @a and @b are equal; %FALSE otherwise
+ * Returns: `TRUE` if @a and @b are equal; `FALSE` otherwise
* Since: 1.2
*/
gboolean
#include "json-types-private.h"
/**
- * SECTION:json-object
- * @short_description: a JSON object representation
+ * JsonObject:
*
- * #JsonObject is the representation of the object type inside JSON. It
- * contains #JsonNodes, which may contain fundamental types, arrays or other
- * objects; each node inside an object, or "member", is accessed using a
- * unique string, or "name".
+ * `JsonObject` is the representation of the object type inside JSON.
*
- * Since objects can be expensive, they are reference counted. You can control
- * the lifetime of a #JsonObject using json_object_ref() and json_object_unref().
+ * A `JsonObject` contains [struct@Json.Node] "members", which may contain
+ * fundamental types, arrays or other objects; each member of an object is
+ * accessed using a unique string, or "name".
+ *
+ * Since objects can be arbitrarily big, copying them can be expensive; for
+ * this reason they are reference counted. You can control the lifetime of
+ * a `JsonObject` using [method@Json.Object.ref] and [method@Json.Object.unref].
+ *
+ * To add or overwrite a member with a given name, use [method@Json.Object.set_member].
+ *
+ * To extract a member with a given name, use [method@Json.Object.get_member].
+ *
+ * To retrieve the list of members, use [method@Json.Object.get_members].
*
- * To add or overwrite a member with a given name, use json_object_set_member().
- * To extract a member with a given name, use json_object_get_member().
- * To retrieve the list of members, use json_object_get_members().
* To retrieve the size of the object (that is, the number of members it has),
- * use json_object_get_size().
+ * use [method@Json.Object.get_size].
*/
G_DEFINE_BOXED_TYPE (JsonObject, json_object, json_object_ref, json_object_unref);
/**
* json_object_new: (constructor)
*
- * Creates a new #JsonObject, an JSON object type representation.
+ * Creates a new object.
*
- * Return value: (transfer full): the newly created #JsonObject
+ * Returns: (transfer full): the newly created object
*/
JsonObject *
json_object_new (void)
/**
* json_object_ref:
- * @object: a #JsonObject
+ * @object: a JSON object
*
- * Increase by one the reference count of a #JsonObject.
+ * Acquires a reference on the given object.
*
- * Return value: (transfer none): the passed #JsonObject, with the reference count
+ * Returns: (transfer none): the given object, with the reference count
* increased by one.
*/
JsonObject *
/**
* json_object_unref:
- * @object: a #JsonObject
+ * @object: a JSON object
+ *
+ * Releases a reference on the given object.
*
- * Decreases by one the reference count of a #JsonObject. If the
- * reference count reaches zero, the object is destroyed and all
- * its allocated resources are freed.
+ * If the reference count reaches zero, the object is destroyed and
+ * all its resources are freed.
*/
void
json_object_unref (JsonObject *object)
/**
* json_object_seal:
- * @object: a #JsonObject
+ * @object: a JSON object
*
- * Seals the #JsonObject, making it immutable to further changes. This will
- * recursively seal all members of the object too.
+ * Seals the object, making it immutable to further changes.
*
- * If the @object is already immutable, this is a no-op.
+ * This function will recursively seal all members of the object too.
+ *
+ * If the object is already immutable, this is a no-op.
*
* Since: 1.2
*/
/**
* json_object_is_immutable:
- * @object: a #JsonObject
+ * @object: a JSON object
*
- * Check whether the given @object has been marked as immutable by calling
- * json_object_seal() on it.
+ * Checks whether the given object has been marked as immutable by calling
+ * [method@Json.Object.seal] on it.
*
* Since: 1.2
- * Returns: %TRUE if the @object is immutable
+ * Returns: `TRUE` if the object is immutable
*/
gboolean
json_object_is_immutable (JsonObject *object)
/**
* json_object_add_member:
- * @object: a #JsonObject
+ * @object: a JSON object
* @member_name: the name of the member
* @node: (transfer full): the value of the member
*
- * Adds a member named @member_name and containing @node into a #JsonObject.
- * The object will take ownership of the #JsonNode.
+ * Adds a new member for the given name and value into an object.
*
- * This function will return if the @object already contains a member
- * @member_name.
+ * This function will return if the object already contains a member
+ * with the same name.
*
- * Deprecated: 0.8: Use json_object_set_member() instead
+ * Deprecated: 0.8: Use [method@Json.Object.set_member] instead
*/
void
json_object_add_member (JsonObject *object,
/**
* json_object_set_member:
- * @object: a #JsonObject
+ * @object: a JSON object
* @member_name: the name of the member
* @node: (transfer full): the value of the member
*
- * Sets @node as the value of @member_name inside @object.
+ * Sets the value of a member inside an object.
+ *
+ * If the object does not have a member with the given name, a new member
+ * is created.
*
- * If @object already contains a member called @member_name then
- * the member's current value is overwritten. Otherwise, a new
- * member is added to @object.
+ * If the object already has a member with the given name, the current
+ * value is overwritten with the new.
*
* Since: 0.8
*/
/**
* json_object_set_int_member:
- * @object: a #JsonObject
+ * @object: a JSON object
* @member_name: the name of the member
* @value: the value of the member
*
- * Convenience function for setting an integer @value of
- * @member_name inside @object.
+ * Convenience function for setting an object member with an integer value.
*
- * See also: json_object_set_member()
+ * See also: [method@Json.Object.set_member], [method@Json.Node.init_int]
*
* Since: 0.8
*/
/**
* json_object_set_double_member:
- * @object: a #JsonObject
+ * @object: a JSON object
* @member_name: the name of the member
* @value: the value of the member
*
- * Convenience function for setting a floating point @value
- * of @member_name inside @object.
+ * Convenience function for setting an object member with a floating point value.
*
- * See also: json_object_set_member()
+ * See also: [method@Json.Object.set_member], [method@Json.Node.init_double]
*
* Since: 0.8
*/
/**
* json_object_set_boolean_member:
- * @object: a #JsonObject
+ * @object: a JSON object
* @member_name: the name of the member
* @value: the value of the member
*
- * Convenience function for setting a boolean @value of
- * @member_name inside @object.
+ * Convenience function for setting an object member with a boolean value.
*
- * See also: json_object_set_member()
+ * See also: [method@Json.Object.set_member], [method@Json.Node.init_boolean]
*
* Since: 0.8
*/
/**
* json_object_set_string_member:
- * @object: a #JsonObject
+ * @object: a JSON object
* @member_name: the name of the member
* @value: the value of the member
*
- * Convenience function for setting a string @value of
- * @member_name inside @object.
+ * Convenience function for setting an object member with a string value.
*
- * See also: json_object_set_member()
+ * See also: [method@Json.Object.set_member], [method@Json.Node.init_string]
*
* Since: 0.8
*/
/**
* json_object_set_null_member:
- * @object: a #JsonObject
+ * @object: a JSON object
* @member_name: the name of the member
*
- * Convenience function for setting a null @value of
- * @member_name inside @object.
+ * Convenience function for setting an object member with a `null` value.
*
- * See also: json_object_set_member()
+ * See also: [method@Json.Object.set_member], [method@Json.Node.init_null]
*
* Since: 0.8
*/
/**
* json_object_set_array_member:
- * @object: a #JsonObject
+ * @object: a JSON object
* @member_name: the name of the member
* @value: (transfer full): the value of the member
*
- * Convenience function for setting an array @value of
- * @member_name inside @object.
- *
- * The @object will take ownership of the passed #JsonArray
+ * Convenience function for setting an object member with an array value.
*
- * See also: json_object_set_member()
+ * See also: [method@Json.Object.set_member], [method@Json.Node.take_array]
*
* Since: 0.8
*/
/**
* json_object_set_object_member:
- * @object: a #JsonObject
+ * @object: a JSON object
* @member_name: the name of the member
* @value: (transfer full): the value of the member
*
- * Convenience function for setting an object @value of
- * @member_name inside @object.
+ * Convenience function for setting an object member with an object value.
*
- * The @object will take ownership of the passed #JsonObject
- *
- * See also: json_object_set_member()
+ * See also: [method@Json.Object.set_member], [method@Json.Node.take_object]
*
* Since: 0.8
*/
/**
* json_object_get_members:
- * @object: a #JsonObject
+ * @object: a JSON object
+ *
+ * Retrieves all the names of the members of an object.
*
- * Retrieves all the names of the members of a #JsonObject. You can
- * obtain the value for each member using json_object_get_member().
+ * You can obtain the value for each member by iterating the returned list
+ * and calling [method@Json.Object.get_member].
*
- * Return value: (element-type utf8) (transfer container) (nullable): a
- * #GList of member names, or %NULL. The content of the list is owned
- * by the #JsonObject and should never be modified or freed. When you
- * have finished using the returned list, use g_list_free() to free
- * the resources it has allocated.
+ * Returns: (element-type utf8) (transfer container) (nullable): the
+ * member names of the object
*/
GList *
json_object_get_members (JsonObject *object)
/**
* json_object_get_values:
- * @object: a #JsonObject
+ * @object: a JSON object
*
- * Retrieves all the values of the members of a #JsonObject.
+ * Retrieves all the values of the members of an object.
*
- * Return value: (element-type JsonNode) (transfer container) (nullable): a
- * #GList of #JsonNodes, or %NULL. The content of the list is owned by the
- * #JsonObject and should never be modified or freed. When you have finished
- * using the returned list, use g_list_free() to free the resources it has
- * allocated.
+ * Returns: (element-type JsonNode) (transfer container) (nullable): the
+ * member values of the object
*/
GList *
json_object_get_values (JsonObject *object)
/**
* json_object_dup_member:
- * @object: a #JsonObject
+ * @object: a JSON object
* @member_name: the name of the JSON object member to access
*
- * Retrieves a copy of the #JsonNode containing the value of @member_name
- * inside a #JsonObject
+ * Retrieves a copy of the value of the given member inside an object.
*
- * Return value: (transfer full) (nullable): a copy of the node for the
- * requested object member or %NULL. Use json_node_unref() when done.
+ * Returns: (transfer full) (nullable): a copy of the value for the
+ * requested object member
*
* Since: 0.6
*/
/**
* json_object_get_member:
- * @object: a #JsonObject
+ * @object: a JSON object
* @member_name: the name of the JSON object member to access
*
- * Retrieves the #JsonNode containing the value of @member_name inside
- * a #JsonObject.
+ * Retrieves the value of the given member inside an object.
*
- * Return value: (transfer none) (nullable): a pointer to the node for the
- * requested object member, or %NULL if it does not exist.
+ * Returns: (transfer none) (nullable): the value for the
+ * requested object member
*/
JsonNode *
json_object_get_member (JsonObject *object,
/**
* json_object_get_int_member:
- * @object: a #JsonObject
- * @member_name: the name of the @object member
+ * @object: a JSON object
+ * @member_name: the name of the object member
*
* Convenience function that retrieves the integer value
* stored in @member_name of @object. It is an error to specify a
* @member_name which does not exist.
*
- * See also: json_object_get_int_member_with_default(),
- * json_object_get_member() and json_object_has_member()
+ * See also: [method@Json.Object.get_int_member_with_default],
+ * [method@Json.Object.get_member], [method@Json.Object.has_member]
*
- * Return value: the integer value of the object's member
+ * Returns: the integer value of the object's member
*
* Since: 0.8
*/
/**
* json_object_get_int_member_with_default:
- * @object: a #JsonObject
- * @member_name: the name of the @object member
+ * @object: a JSON object
+ * @member_name: the name of the object member
* @default_value: the value to return if @member_name is not valid
*
* Convenience function that retrieves the integer value
/**
* json_object_get_double_member:
- * @object: a #JsonObject
+ * @object: a JSON object
* @member_name: the name of the member
*
* Convenience function that retrieves the floating point value
* stored in @member_name of @object. It is an error to specify a
* @member_name which does not exist.
*
- * See also: json_object_get_double_member_with_default(),
- * json_object_get_member() and json_object_has_member()
+ * See also: [method@Json.Object.get_double_member_with_default],
+ * [method@Json.Object.get_member], [method@Json.Object.has_member]
*
- * Return value: the floating point value of the object's member
+ * Returns: the floating point value of the object's member
*
* Since: 0.8
*/
/**
* json_object_get_double_member_with_default:
- * @object: a #JsonObject
+ * @object: a JSON object
* @member_name: the name of the @object member
* @default_value: the value to return if @member_name is not valid
*
/**
* json_object_get_boolean_member:
- * @object: a #JsonObject
+ * @object: a JSON object
* @member_name: the name of the member
*
* Convenience function that retrieves the boolean value
* stored in @member_name of @object. It is an error to specify a
* @member_name which does not exist.
*
- * See also: json_object_get_boolean_member_with_default(),
- * json_object_get_member() and json_object_has_member()
+ * See also: [method@Json.Object.get_boolean_member_with_default],
+ * [method@Json.Object.get_member], [method@Json.Object.has_member]
*
- * Return value: the boolean value of the object's member
+ * Returns: the boolean value of the object's member
*
* Since: 0.8
*/
/**
* json_object_get_boolean_member_with_default:
- * @object: a #JsonObject
+ * @object: a JSON object
* @member_name: the name of the @object member
* @default_value: the value to return if @member_name is not valid
*
/**
* json_object_get_string_member:
- * @object: a #JsonObject
+ * @object: a JSON object
* @member_name: the name of the member
*
* Convenience function that retrieves the string value
* stored in @member_name of @object. It is an error to specify a
* @member_name that does not exist.
*
- * See also: json_object_get_string_member_with_default(),
- * json_object_get_member() and json_object_has_member()
+ * See also: [method@Json.Object.get_string_member_with_default],
+ * [method@Json.Object.get_member], [method@Json.Object.has_member]
*
- * Return value: the string value of the object's member
+ * Returns: the string value of the object's member
*
* Since: 0.8
*/
/**
* json_object_get_string_member_with_default:
- * @object: a #JsonObject
+ * @object: a JSON object
* @member_name: the name of the @object member
* @default_value: the value to return if @member_name is not valid
*
/**
* json_object_get_null_member:
- * @object: a #JsonObject
+ * @object: a JSON object
* @member_name: the name of the member
*
* Convenience function that checks whether the value
* stored in @member_name of @object is null. It is an error to
* specify a @member_name which does not exist.
*
- * See also: json_object_get_member() and json_object_has_member()
+ * See also: [method@Json.Object.get_member], [method@Json.Object.has_member]
*
- * Return value: %TRUE if the value is null
+ * Returns: `TRUE` if the value is `null`
*
* Since: 0.8
*/
/**
* json_object_get_array_member:
- * @object: a #JsonObject
+ * @object: a JSON object
* @member_name: the name of the member
*
* Convenience function that retrieves the array
* stored in @member_name of @object. It is an error to specify a
* @member_name which does not exist.
*
- * See also: json_object_get_member() and json_object_has_member()
+ * If @member_name contains `null`, then this function will return `NULL`.
+ *
+ * See also: [method@Json.Object.get_member], [method@Json.Object.has_member]
*
- * Return value: (transfer none): the array inside the object's member
+ * Returns: (transfer none) (nullable): the array inside the object's member
*
* Since: 0.8
*/
/**
* json_object_get_object_member:
- * @object: a #JsonObject
+ * @object: a JSON object
* @member_name: the name of the member
*
* Convenience function that retrieves the object
* stored in @member_name of @object. It is an error to specify a @member_name
* which does not exist.
*
- * See also: json_object_get_member() and json_object_has_member()
+ * If @member_name contains `null`, then this function will return `NULL`.
*
- * Return value: (transfer none) (nullable): the object inside the object’s
- * member, or %NULL if the value for the member is `null`
+ * See also: [method@Json.Object.get_member], [method@Json.Object.has_member]
+ *
+ * Returns: (transfer none) (nullable): the object inside the object's member
*
* Since: 0.8
*/
/**
* json_object_has_member:
- * @object: a #JsonObject
+ * @object: a JSON object
* @member_name: the name of a JSON object member
*
* Checks whether @object has a member named @member_name.
*
- * Return value: %TRUE if the JSON object has the requested member
+ * Returns: `TRUE` if the JSON object has the requested member
*/
gboolean
json_object_has_member (JsonObject *object,
/**
* json_object_get_size:
- * @object: a #JsonObject
+ * @object: a JSON object
*
- * Retrieves the number of members of a #JsonObject.
+ * Retrieves the number of members of a JSON object.
*
- * Return value: the number of members
+ * Returns: the number of members
*/
guint
json_object_get_size (JsonObject *object)
/**
* json_object_remove_member:
- * @object: a #JsonObject
+ * @object: a JSON object
* @member_name: the name of the member to remove
*
* Removes @member_name from @object, freeing its allocated resources.
/**
* json_object_foreach_member:
- * @object: a #JsonObject
+ * @object: a JSON object
* @func: (scope call): the function to be called on each member
* @data: (closure): data to be passed to the function
*
* Iterates over all members of @object and calls @func on
* each one of them.
*
- * It is safe to change the value of a #JsonNode of the @object
- * from within the iterator @func, but it is not safe to add or
- * remove members from the @object.
+ * It is safe to change the value of a member of the oobject
+ * from within the iterator function, but it is not safe to add or
+ * remove members from the object.
*
- * The order in which the @object members are iterated is the
+ * The order in which the object members are iterated is the
* insertion order.
*
* Since: 0.8
* json_object_hash:
* @key: (type JsonObject): a JSON object to hash
*
- * Calculate a hash value for the given @key (a #JsonObject).
+ * Calculate a hash value for the given @key (a JSON object).
*
* The hash is calculated over the object and all its members, recursively. If
* the object is immutable, this is a fast operation; otherwise, it scales
* @a: (type JsonObject): a JSON object
* @b: (type JsonObject): another JSON object
*
- * Check whether @a and @b are equal #JsonObjects, meaning they have the same
+ * Check whether @a and @b are equal objects, meaning they have the same
* set of members, and the values of corresponding members are equal.
*
- * Returns: %TRUE if @a and @b are equal; %FALSE otherwise
+ * Returns: `TRUE` if @a and @b are equal, and `FALSE` otherwise
* Since: 1.2
*/
gboolean
/**
* json_object_iter_init:
- * @iter: an uninitialised #JsonObjectIter
- * @object: the #JsonObject to iterate over
+ * @iter: an uninitialised JSON object iterator
+ * @object: the JSON object to iterate over
*
- * Initialise the @iter and associate it with @object.
+ * Initialises the @iter and associate it with @object.
*
- * |[<!-- language="C" -->
+ * ```c
* JsonObjectIter iter;
* const gchar *member_name;
* JsonNode *member_node;
* {
* // Do something with @member_name and @member_node.
* }
- * ]|
+ * ```
+ *
+ * The iterator initialized with this function will iterate the
+ * members of the object in an undefined order.
+ *
+ * See also: [method@Json.ObjectIter.init_ordered]
*
* Since: 1.2
*/
/**
* json_object_iter_next:
- * @iter: a #JsonObjectIter
+ * @iter: a JSON object iterator
* @member_name: (out callee-allocates) (transfer none) (optional): return
* location for the member name, or %NULL to ignore
* @member_node: (out callee-allocates) (transfer none) (optional): return
* location for the member value, or %NULL to ignore
*
- * Advance @iter and retrieve the next member in the object. If the end of the
- * object is reached, %FALSE is returned and @member_name and @member_node are
- * set to invalid values. After that point, the @iter is invalid.
+ * Advances the iterator and retrieves the next member in the object.
+ *
+ * If the end of the object is reached, `FALSE` is returned and @member_name
+ * and @member_node are set to invalid values. After that point, the @iter
+ * is invalid.
*
* The order in which members are returned by the iterator is undefined. The
- * iterator is invalidated if its #JsonObject is modified during iteration.
+ * iterator is invalidated if the object is modified during iteration.
*
- * You must use this function with a #JsonObjectIter initialized with
- * json_object_iter_init(); using this function with an iterator initialized
- * with json_object_iter_init_ordered() yields undefined behavior.
+ * You must use this function with an iterator initialized with
+ * [method@Json.ObjectIter.init]; using this function with an iterator
+ * initialized with [method@Json.ObjectIter.init_ordered] yields undefined
+ * behavior.
*
- * See also: json_object_iter_next_ordered()
+ * See also: [method@Json.ObjectIter.next_ordered]
*
- * Returns: %TRUE if @member_name and @member_node are valid; %FALSE if the end
- * of the object has been reached
+ * Returns: `TRUE` if @member_name and @member_node are valid; `FALSE` if
+ * there are no more members
*
* Since: 1.2
*/
/**
* json_object_iter_init_ordered:
- * @iter: an uninitialised #JsonObjectIter
- * @object: the #JsonObject to iterate over
+ * @iter: an uninitialised iterator
+ * @object: the JSON object to iterate over
*
- * Initialise the @iter and associate it with @object.
+ * Initialises the @iter and associate it with @object.
*
- * |[<!-- language="C" -->
+ * ```c
* JsonObjectIter iter;
* const gchar *member_name;
* JsonNode *member_node;
* {
* // Do something with @member_name and @member_node.
* }
- * ]|
+ * ```
*
- * See also: json_object_iter_init()
+ * See also: [method@Json.ObjectIter.init]
*
* Since: 1.6
*/
/**
* json_object_iter_next_ordered:
- * @iter: a #JsonObjectIter
+ * @iter: an ordered JSON object iterator
* @member_name: (out callee-allocates) (transfer none) (optional): return
* location for the member name, or %NULL to ignore
* @member_node: (out callee-allocates) (transfer none) (optional): return
* location for the member value, or %NULL to ignore
*
- * Advance @iter and retrieve the next member in the object. If the end of the
- * object is reached, %FALSE is returned and @member_name and @member_node are
- * set to invalid values. After that point, the @iter is invalid.
+ * Advances the iterator and retrieves the next member in the object.
+ *
+ * If the end of the object is reached, `FALSE` is returned and @member_name and
+ * @member_node are set to invalid values. After that point, the @iter is invalid.
*
* The order in which members are returned by the iterator is the same order in
- * which the members were added to the #JsonObject. The iterator is invalidated
- * if its #JsonObject is modified during iteration.
+ * which the members were added to the `JsonObject`. The iterator is invalidated
+ * if its `JsonObject` is modified during iteration.
*
- * You must use this function with a #JsonObjectIter initialized with
- * json_object_iter_init_ordered(); using this function with an iterator initialized
- * with json_object_iter_init() yields undefined behavior.
+ * You must use this function with an iterator initialized with
+ * [method@Json.ObjectIter.init_ordered]; using this function with an iterator
+ * initialized with [method@Json.ObjectIter.init] yields undefined behavior.
*
- * See also: json_object_iter_next()
+ * See also: [method@Json.ObjectIter.next]
*
- * Returns: %TRUE if @member_name and @member_node are valid; %FALSE if the end
+ * Returns: `TRUE `if @member_name and @member_node are valid; `FALSE` if the end
* of the object has been reached
*
* Since: 1.6
*/
/**
- * SECTION:json-parser
- * @short_description: Parse JSON data streams
+ * JsonParser:
*
- * #JsonParser provides an object for parsing a JSON data stream, either
+ * `JsonParser` provides an object for parsing a JSON data stream, either
* inside a file or inside a static buffer.
+ *
+ * ## Using `JsonParser`
+ *
+ * The `JsonParser` API is fairly simple:
+ *
+ * ```c
+ * gboolean
+ * parse_json (const char *filename)
+ * {
+ * g_autoptr(JsonParser) parser = json_parser_new ();
+ * g_autoptr(GError) error = NULL
+ *
+ * json_parser_load_from_file (parser, filename, &error);
+ * if (error != NULL)
+ * {
+ * g_critical ("Unable to parse '%s': %s", filename, error->message);
+ * return FALSE;
+ * }
+ *
+ * g_autoptr(JsonNode) root = json_parser_get_root (parser);
+ *
+ * // manipulate the object tree from the root node
+ *
+ * return TRUE
+ * }
+ * ```
+ *
+ * By default, the entire process of loading the data and parsing it is
+ * synchronous; the [method@Json.Parser.load_from_stream_async()] API will
+ * load the data asynchronously, but parse it in the main context as the
+ * signals of the parser must be emitted in the same thread. If you do
+ * not use signals, and you wish to also parse the JSON data without blocking,
+ * you should use a `GTask` and the synchronous `JsonParser` API inside the
+ * task itself.
*/
#include "config.h"
/**
* JsonParser:immutable:
*
- * Whether the #JsonNode tree built by the #JsonParser should be immutable
- * when created. Making the output immutable on creation avoids the expense
+ * Whether the tree built by the parser should be immutable
+ * when created.
+ *
+ * Making the output immutable on creation avoids the expense
* of traversing it to make it immutable later.
*
* Since: 1.2
/**
* JsonParser::parse-start:
- * @parser: the #JsonParser that received the signal
+ * @parser: the parser that emitted the signal
*
- * The ::parse-start signal is emitted when the parser began parsing
- * a JSON data stream.
+ * This signal is emitted when a parser starts parsing a JSON data stream.
*/
parser_signals[PARSE_START] =
g_signal_new ("parse-start",
G_TYPE_NONE, 0);
/**
* JsonParser::parse-end:
- * @parser: the #JsonParser that received the signal
+ * @parser: the parser that emitted the signal
*
- * The ::parse-end signal is emitted when the parser successfully
- * finished parsing a JSON data stream
+ * This signal is emitted when a parser successfully finished parsing a
+ * JSON data stream
*/
parser_signals[PARSE_END] =
g_signal_new ("parse-end",
G_TYPE_NONE, 0);
/**
* JsonParser::object-start:
- * @parser: the #JsonParser that received the signal
+ * @parser: the parser that emitted the signal
*
- * The ::object-start signal is emitted each time the #JsonParser
- * starts parsing a #JsonObject.
+ * This signal is emitted each time a parser starts parsing a JSON object.
*/
parser_signals[OBJECT_START] =
g_signal_new ("object-start",
G_TYPE_NONE, 0);
/**
* JsonParser::object-member:
- * @parser: the #JsonParser that received the signal
- * @object: a #JsonObject
+ * @parser: the parser that emitted the signal
+ * @object: the JSON object being parsed
* @member_name: the name of the newly parsed member
*
- * The ::object-member signal is emitted each time the #JsonParser
- * has successfully parsed a single member of a #JsonObject. The
- * object and member are passed to the signal handlers.
+ * The `::object-member` signal is emitted each time a parser
+ * has successfully parsed a single member of a JSON object
*/
parser_signals[OBJECT_MEMBER] =
g_signal_new ("object-member",
G_TYPE_STRING);
/**
* JsonParser::object-end:
- * @parser: the #JsonParser that received the signal
- * @object: the parsed #JsonObject
+ * @parser: the parser that emitted the signal
+ * @object: the parsed JSON object
*
- * The ::object-end signal is emitted each time the #JsonParser
- * has successfully parsed an entire #JsonObject.
+ * The `::object-end` signal is emitted each time a parser
+ * has successfully parsed an entire JSON object.
*/
parser_signals[OBJECT_END] =
g_signal_new ("object-end",
JSON_TYPE_OBJECT);
/**
* JsonParser::array-start:
- * @parser: the #JsonParser that received the signal
+ * @parser: the parser that emitted the signal
*
- * The ::array-start signal is emitted each time the #JsonParser
- * starts parsing a #JsonArray
+ * The `::array-start` signal is emitted each time a parser
+ * starts parsing a JSON array.
*/
parser_signals[ARRAY_START] =
g_signal_new ("array-start",
G_TYPE_NONE, 0);
/**
* JsonParser::array-element:
- * @parser: the #JsonParser that received the signal
- * @array: a #JsonArray
- * @index_: the index of the newly parsed element
+ * @parser: the parser that emitted the signal
+ * @array: a JSON array
+ * @index_: the index of the newly parsed array element
*
- * The ::array-element signal is emitted each time the #JsonParser
- * has successfully parsed a single element of a #JsonArray. The
- * array and element index are passed to the signal handlers.
+ * The `::array-element` signal is emitted each time a parser
+ * has successfully parsed a single element of a JSON array.
*/
parser_signals[ARRAY_ELEMENT] =
g_signal_new ("array-element",
G_TYPE_INT);
/**
* JsonParser::array-end:
- * @parser: the #JsonParser that received the signal
- * @array: the parsed #JsonArray
+ * @parser: the parser that emitted the signal
+ * @array: the parsed JSON array
*
- * The ::array-end signal is emitted each time the #JsonParser
- * has successfully parsed an entire #JsonArray
+ * The `::array-end` signal is emitted each time a parser
+ * has successfully parsed an entire JSON array.
*/
parser_signals[ARRAY_END] =
g_signal_new ("array-end",
JSON_TYPE_ARRAY);
/**
* JsonParser::error:
- * @parser: the parser instance that received the signal
- * @error: a pointer to the #GError
+ * @parser: the parser that emitted the signal
+ * @error: the error
*
- * The ::error signal is emitted each time a #JsonParser encounters
+ * The `::error` signal is emitted each time a parser encounters
* an error in a JSON stream.
*/
parser_signals[ERROR] =
return '=';
}
+ if (priv->has_assignment)
+ g_free (priv->variable_name);
priv->has_assignment = TRUE;
priv->variable_name = name;
/**
* json_parser_new:
*
- * Creates a new #JsonParser instance. You can use the #JsonParser to
- * load a JSON stream from either a file or a buffer and then walk the
- * hierarchy using the data types API.
+ * Creates a new JSON parser.
+ *
+ * You can use the `JsonParser` to load a JSON stream from either a file or a
+ * buffer and then walk the hierarchy using the data types API.
*
- * Return value: the newly created #JsonParser. Use g_object_unref()
- * to release all the memory it allocates.
+ * Returns: (transfer full): the newly created parser
*/
JsonParser *
json_parser_new (void)
/**
* json_parser_new_immutable:
*
- * Creates a new #JsonParser instance with its #JsonParser:immutable property
- * set to %TRUE to create immutable output trees.
+ * Creates a new parser instance with its [property@Json.Parser:immutable]
+ * property set to `TRUE` to create immutable output trees.
*
* Since: 1.2
- * Returns: (transfer full): a new #JsonParser
+ * Returns: (transfer full): the newly created parser
*/
JsonParser *
json_parser_new_immutable (void)
/**
* json_parser_load_from_file:
- * @parser: a #JsonParser
- * @filename: the path for the file to parse
- * @error: return location for a #GError, or %NULL
+ * @parser: a parser
+ * @filename: (type filename): the path for the file to parse
+ * @error: return location for a #GError
*
- * Loads a JSON stream from the content of @filename and parses it. See
- * json_parser_load_from_data().
+ * Loads a JSON stream from the content of `filename` and parses it.
*
* If the file is large or shared between processes,
- * json_parser_load_from_mapped_file() may be a more efficient way to load it.
+ * [method@Json.Parser.load_from_mapped_file] may be a more efficient
+ * way to load it.
*
- * Return value: %TRUE if the file was successfully loaded and parsed.
- * In case of error, @error is set accordingly and %FALSE is returned
+ * See also: [method@Json.Parser.load_from_data]
+ *
+ * Returns: `TRUE` if the file was successfully loaded and parsed.
*/
gboolean
json_parser_load_from_file (JsonParser *parser,
/**
* json_parser_load_from_mapped_file:
- * @parser: a #JsonParser
- * @filename: the path for the file to parse
- * @error: return location for a #GError, or %NULL
+ * @parser: a parser
+ * @filename: (type filename): the path for the file to parse
+ * @error: return location for a #GError
+ *
+ * Loads a JSON stream from the content of `filename` and parses it.
*
- * Loads a JSON stream from the content of @filename and parses it. Unlike
- * json_parser_load_from_file(), @filename will be memory mapped as read-only
- * and parsed. @filename will be unmapped before this function returns.
+ * Unlike [method@Json.Parser.load_from_file], `filename` will be memory
+ * mapped as read-only and parsed. `filename` will be unmapped before this
+ * function returns.
*
- * If mapping or reading the file fails, a %G_FILE_ERROR will be returned.
+ * If mapping or reading the file fails, a `G_FILE_ERROR` will be returned.
*
- * Return value: %TRUE if the file was successfully loaded and parsed.
- * In case of error, @error is set accordingly and %FALSE is returned
+ * Returns: `TRUE` if the file was successfully loaded and parsed.
* Since: 1.6
*/
gboolean
/**
* json_parser_load_from_data:
- * @parser: a #JsonParser
+ * @parser: a parser
* @data: the buffer to parse
- * @length: the length of the buffer, or -1
- * @error: return location for a #GError, or %NULL
+ * @length: the length of the buffer, or -1 if it is `NUL` terminated
+ * @error: return location for a #GError
*
- * Loads a JSON stream from a buffer and parses it. You can call this function
- * multiple times with the same #JsonParser object, but the contents of the
- * parser will be destroyed each time.
+ * Loads a JSON stream from a buffer and parses it.
*
- * Return value: %TRUE if the buffer was succesfully parsed. In case
- * of error, @error is set accordingly and %FALSE is returned
+ * You can call this function multiple times with the same parser, but the
+ * contents of the parser will be destroyed each time.
+ *
+ * Returns: `TRUE` if the buffer was succesfully parsed
*/
gboolean
json_parser_load_from_data (JsonParser *parser,
/**
* json_parser_get_root:
- * @parser: a #JsonParser
+ * @parser: a parser
+ *
+ * Retrieves the top level node from the parsed JSON stream.
*
- * Retrieves the top level node from the parsed JSON stream. If the parser input
- * was an empty string, or if parsing failed, this will be %NULL. It will also
- * be %NULL if it has been stolen using json_parser_steal_root().
+ * If the parser input was an empty string, or if parsing failed, the root
+ * will be `NULL`. It will also be `NULL` if it has been stolen using
+ * [method@Json.Parser.steal_root].
*
- * Return value: (transfer none) (nullable): the root #JsonNode . The returned
- * node is owned by the #JsonParser and should never be modified
- * or freed.
+ * Returns: (transfer none) (nullable): the root node.
*/
JsonNode *
json_parser_get_root (JsonParser *parser)
/**
* json_parser_steal_root:
- * @parser: a #JsonParser
+ * @parser: a parser
+ *
+ * Steals the top level node from the parsed JSON stream.
*
- * Steals the top level node from the parsed JSON stream. This will be %NULL
- * in the same situations as json_parser_get_root() returns %NULL.
+ * This will be `NULL` in the same situations as [method@Json.Parser.get_root]
+ * return `NULL`.
*
- * Returns: (transfer full) (nullable): the top level #JsonNode
+ * Returns: (transfer full) (nullable): the root node
*
* Since: 1.4
*/
/**
* json_parser_get_current_line:
- * @parser: a #JsonParser
+ * @parser: a parser
*
* Retrieves the line currently parsed, starting from 1.
*
* This function has defined behaviour only while parsing; calling this
- * function from outside the signal handlers emitted by #JsonParser will
+ * function from outside the signal handlers emitted by the parser will
* yield 0.
*
- * Return value: the currently parsed line, or 0.
+ * Returns: the currently parsed line, or 0.
*/
guint
json_parser_get_current_line (JsonParser *parser)
/**
* json_parser_get_current_pos:
- * @parser: a #JsonParser
+ * @parser: a parser
*
* Retrieves the current position inside the current line, starting
* from 0.
*
* This function has defined behaviour only while parsing; calling this
- * function from outside the signal handlers emitted by #JsonParser will
+ * function from outside the signal handlers emitted by the parser will
* yield 0.
*
- * Return value: the position in the current line, or 0.
+ * Returns: the position in the current line, or 0.
*/
guint
json_parser_get_current_pos (JsonParser *parser)
/**
* json_parser_has_assignment:
- * @parser: a #JsonParser
- * @variable_name: (out) (allow-none) (transfer none): Return location for the variable
- * name, or %NULL
+ * @parser: a parser
+ * @variable_name: (out) (optional) (transfer none): the variable name
*
* A JSON data stream might sometimes contain an assignment, like:
*
- * |[
- * var _json_data = { "member_name" : [ ...
- * ]|
+ * ```
+ * var _json_data = { "member_name" : [ ...
+ * ```
*
* even though it would technically constitute a violation of the RFC.
*
- * #JsonParser will ignore the left hand identifier and parse the right
- * hand value of the assignment. #JsonParser will record, though, the
+ * `JsonParser` will ignore the left hand identifier and parse the right
+ * hand value of the assignment. `JsonParser` will record, though, the
* existence of the assignment in the data stream and the variable name
* used.
*
- * Return value: %TRUE if there was an assignment, %FALSE otherwise. If
- * @variable_name is not %NULL it will be set to the name of the variable
- * used in the assignment. The string is owned by #JsonParser and should
- * never be modified or freed.
+ * Returns: `TRUE` if there was an assignment, and `FALSE` otherwise
*
* Since: 0.4
*/
/**
* json_parser_load_from_stream:
- * @parser: a #JsonParser
- * @stream: an open #GInputStream
- * @cancellable: (allow-none): a #GCancellable, or %NULL
- * @error: the return location for a #GError, or %NULL
+ * @parser: a parser
+ * @stream: the input stream with the JSON data
+ * @cancellable: (nullable): a #GCancellable
+ * @error: the return location for a #GError
*
* Loads the contents of an input stream and parses them.
*
- * If @cancellable is not %NULL, then the operation can be cancelled by
- * triggering the @cancellable object from another thread. If the
- * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be set
- * on the passed @error.
+ * If `cancellable` is not `NULL`, then the operation can be cancelled by
+ * triggering the cancellable object from another thread. If the
+ * operation was cancelled, `G_IO_ERROR_CANCELLED` will be set
+ * on the given `error`.
*
- * Return value: %TRUE if the data stream was successfully read and
- * parsed, and %FALSE otherwise
+ * Returns: `TRUE` if the data stream was successfully read and
+ * parsed, and `FALSE` otherwise
*
* Since: 0.12
*/
/**
* json_parser_load_from_stream_finish:
- * @parser: a #JsonParser
- * @result: a #GAsyncResult
- * @error: the return location for a #GError or %NULL
+ * @parser: a parser
+ * @result: the result of the asynchronous operation
+ * @error: the return location for a #GError
*
* Finishes an asynchronous stream loading started with
- * json_parser_load_from_stream_async().
+ * [method@Json.Parser.load_from_stream_async].
*
- * Return value: %TRUE if the content of the stream was successfully retrieves
- * and parsed, and %FALSE otherwise. In case of error, the #GError will be
- * filled accordingly.
+ * Returns: `TRUE` if the content of the stream was successfully retrieved
+ * and parsed, and `FALSE` otherwise
*
* Since: 0.12
*/
LoadData *data = g_task_get_task_data (G_TASK (result));
GError *internal_error = NULL;
- /* We need to do this inside the finis() function because JsonParser will emit
+ /* We need to do this inside the finish() function because JsonParser will emit
* signals, and we need to ensure that the signals are emitted in the right
* context; it's easier to do that if we just rely on the async callback being
* called in the right context, even if it means making the finish() function
/**
* json_parser_load_from_stream_async:
- * @parser: a #JsonParser
- * @stream: a #GInputStream
- * @cancellable: (allow-none): a #GCancellable, or %NULL
- * @callback: a #GAsyncReadyCallback to call when the request is satisfied
+ * @parser: a parser
+ * @stream: the input stream with the JSON data
+ * @cancellable: (nullable): a #GCancellable
+ * @callback: (scope async): the function to call when the request is satisfied
* @user_data: the data to pass to @callback
*
- * Asynchronously reads the contents of @stream.
+ * Asynchronously reads the contents of a stream.
*
- * For more details, see json_parser_load_from_stream() which is the
+ * For more details, see [method@Json.Parser.load_from_stream], which is the
* synchronous version of this call.
*
* When the operation is finished, @callback will be called. You should
- * then call json_parser_load_from_stream_finish() to get the result
+ * then call [method@Json.Parser.load_from_stream_finish] to get the result
* of the operation.
*
* Since: 0.12
#define JSON_IS_PARSER_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), JSON_TYPE_PARSER))
#define JSON_PARSER_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), JSON_TYPE_PARSER, JsonParserClass))
+/**
+ * JSON_PARSER_ERROR:
+ *
+ * Error domain for `JsonParser`.
+ */
#define JSON_PARSER_ERROR (json_parser_error_quark ())
typedef struct _JsonParser JsonParser;
* @JSON_PARSER_ERROR_INVALID_DATA: invalid data (Since: 0.18)
* @JSON_PARSER_ERROR_UNKNOWN: unknown error
*
- * Error enumeration for #JsonParser
+ * Error codes for `JSON_PARSER_ERROR`.
*
* This enumeration can be extended at later date
*/
JSON_PARSER_ERROR_UNKNOWN
} JsonParserError;
-/**
- * JsonParser:
- *
- * JSON data streams parser. The contents of the #JsonParser structure are
- * private and should only be accessed via the provided API.
- */
struct _JsonParser
{
/*< private >*/
* @parse_end: class handler for the JsonParser::parse-end signal
* @error: class handler for the JsonParser::error signal
*
- * #JsonParser class.
+ * The class structure for the JsonParser type.
*/
struct _JsonParserClass
{
*/
/**
- * SECTION:json-path
- * @Title: JsonPath
- * @short_description: JSONPath implementation
- *
- * #JsonPath is a simple class implementing the JSONPath syntax for extracting
- * data out of a JSON tree. While the semantics of the JSONPath expressions are
- * heavily borrowed by the XPath specification for XML, the syntax follows the
- * ECMAScript origins of JSON.
- *
- * Once a #JsonPath instance has been created, it has to compile a JSONPath
- * expression using json_path_compile() before being able to match it to a
- * JSON tree; the same #JsonPath instance can be used to match multiple JSON
+ * JsonPath:
+ *
+ * `JsonPath` is a simple class implementing the JSONPath syntax for extracting
+ * data out of a JSON tree.
+ *
+ * While the semantics of the JSONPath expressions are heavily borrowed by the
+ * XPath specification for XML, the syntax follows the ECMAScript origins of
+ * JSON.
+ *
+ * Once a `JsonPath` instance has been created, it has to compile a JSONPath
+ * expression using [method@Json.Path.compile] before being able to match it to
+ * a JSON tree; the same `JsonPath` instance can be used to match multiple JSON
* trees. It it also possible to compile a new JSONPath expression using the
- * same #JsonPath instance; the previous expression will be discarded only if
+ * same `JsonPath` instance; the previous expression will be discarded only if
* the compilation of the new expression is successful.
*
- * The simple convenience function json_path_query() can be used for one-off
- * matching.
+ * The simple convenience function [func@Json.Path.query] can be used for
+ * one-off matching.
*
- * ## Syntax of the JSONPath expressions ##
+ * ## Syntax of the JSONPath expressions
*
* A JSONPath expression is composed by path indices and operators.
* Each path index can either be a member name or an element index inside
- * a JSON tree. A JSONPath expression must start with the '$' operator; each
+ * a JSON tree. A JSONPath expression must start with the `$` operator; each
* path index is separated using either the dot notation or the bracket
* notation, e.g.:
*
- * |[<!-- language="plain" -->
- * // dot notation
- * $.store.book[0].title
+ * ```
+ * // dot notation
+ * $.store.book[0].title
*
- * // bracket notation
- * $['store']['book'][0]['title']
- * ]|
+ * // bracket notation
+ * $['store']['book'][0]['title']
+ * ```
*
* The available operators are:
*
- * * Root node
- * The `$` character represents the root node of the JSON tree, and
+ * * The `$` character represents the root node of the JSON tree, and
* matches the entire document.
*
* * Child nodes can either be matched using `.` or `[]`. For instance,
* [JSONPath website](http://goessner.net/articles/JsonPath/).
*
* ## Example of JSONPath matches
- * The following example shows some of the results of using #JsonPath
+ *
+ * The following example shows some of the results of using `JsonPath`
* on a JSON tree. We use the following JSON description of a bookstore:
*
- * |[<!-- language="plain" -->
- * { "store": {
- * "book": [
- * { "category": "reference", "author": "Nigel Rees",
- * "title": "Sayings of the Century", "price": "8.95" },
- * { "category": "fiction", "author": "Evelyn Waugh",
- * "title": "Sword of Honour", "price": "12.99" },
- * { "category": "fiction", "author": "Herman Melville",
- * "title": "Moby Dick", "isbn": "0-553-21311-3",
- * "price": "8.99" },
- * { "category": "fiction", "author": "J. R. R. Tolkien",
- * "title": "The Lord of the Rings", "isbn": "0-395-19395-8",
- * "price": "22.99" }
- * ],
- * "bicycle": { "color": "red", "price": "19.95" }
- * }
+ * ```json
+ * { "store": {
+ * "book": [
+ * { "category": "reference", "author": "Nigel Rees",
+ * "title": "Sayings of the Century", "price": "8.95" },
+ * { "category": "fiction", "author": "Evelyn Waugh",
+ * "title": "Sword of Honour", "price": "12.99" },
+ * { "category": "fiction", "author": "Herman Melville",
+ * "title": "Moby Dick", "isbn": "0-553-21311-3",
+ * "price": "8.99" },
+ * { "category": "fiction", "author": "J. R. R. Tolkien",
+ * "title": "The Lord of the Rings", "isbn": "0-395-19395-8",
+ * "price": "22.99" }
+ * ],
+ * "bicycle": { "color": "red", "price": "19.95" }
* }
- * ]|
+ * }
+ * ```
*
- * We can parse the JSON using #JsonParser:
+ * We can parse the JSON using [class@Json.Parser]:
*
- * |[<!-- language="C" -->
- * JsonParser *parser = json_parser_new ();
- * json_parser_load_from_data (parser, json_data, -1, NULL);
- * ]|
+ * ```c
+ * JsonParser *parser = json_parser_new ();
+ * json_parser_load_from_data (parser, json_data, -1, NULL);
+ * ```
*
* If we run the following code:
*
- * |[<!-- language="C" -->
- * JsonNode *result;
- * JsonPath *path = json_path_new ();
- * json_path_compile (path, "$.store..author", NULL);
- * result = json_path_match (path, json_parser_get_root (parser));
- * ]|
+ * ```c
+ * JsonNode *result;
+ * JsonPath *path = json_path_new ();
+ * json_path_compile (path, "$.store..author", NULL);
+ * result = json_path_match (path, json_parser_get_root (parser));
+ * ```
*
- * The result #JsonNode will contain an array with all values of the
+ * The `result` node will contain an array with all values of the
* author member of the objects in the JSON tree. If we use a
- * #JsonGenerator to convert the #JsonNode to a string and print it:
+ * [class@Json.Generator] to convert the `result` node to a string
+ * and print it:
*
- * |[<!-- language="C" -->
- * JsonGenerator *generator = json_generator_new ();
- * json_generator_set_root (generator, result);
- * char *str = json_generator_to_data (generator, NULL);
- * g_print ("Results: %s\n", str);
- * ]|
+ * ```c
+ * JsonGenerator *generator = json_generator_new ();
+ * json_generator_set_root (generator, result);
+ * char *str = json_generator_to_data (generator, NULL);
+ * g_print ("Results: %s\n", str);
+ * ```
*
* The output will be:
*
- * |[<!-- language="plain" -->
- * ["Nigel Rees","Evelyn Waugh","Herman Melville","J. R. R. Tolkien"]
- * ]|
+ * ```json
+ * ["Nigel Rees","Evelyn Waugh","Herman Melville","J. R. R. Tolkien"]
+ * ```
*
- * #JsonPath is available since JSON-GLib 0.14
+ * Since: 0.14
*/
#include "config.h"
/**
* json_path_new:
*
- * Creates a new #JsonPath instance.
+ * Creates a new `JsonPath` instance.
*
- * Once created, the #JsonPath object should be used with json_path_compile()
- * and json_path_match().
+ * Once created, the `JsonPath` object should be used with
+ * [method@Json.Path.compile] and [method@Json.Path.match].
*
- * Return value: (transfer full): the newly created #JsonPath instance. Use
- * g_object_unref() to free the allocated resources when done
+ * Return value: (transfer full): the newly created path
*
* Since: 0.14
*/
/**
* json_path_compile:
- * @path: a #JsonPath
+ * @path: a path
* @expression: a JSONPath expression
* @error: return location for a #GError, or %NULL
*
- * Validates and decomposes @expression.
+ * Validates and decomposes the given expression.
*
- * A JSONPath expression must be compiled before calling json_path_match().
+ * A JSONPath expression must be compiled before calling
+ * [method@Json.Path.match].
*
- * Return value: %TRUE on success; on error, @error will be set with
- * the %JSON_PATH_ERROR domain and a code from the #JsonPathError
- * enumeration, and %FALSE will be returned
+ * Return value: `TRUE` if the compilation was successful, and `FALSE`
+ * otherwise
*
* Since: 0.14
*/
/**
* json_path_match:
- * @path: a compiled #JsonPath
- * @root: a #JsonNode
+ * @path: a compiled path
+ * @root: the root node of the JSON data to match
*
- * Matches the JSON tree pointed by @root using the expression compiled
- * into the #JsonPath.
+ * Matches the JSON tree pointed by `root` using the expression compiled
+ * into the `JsonPath`.
*
- * The matching #JsonNodes will be copied into a #JsonArray and
- * returned wrapped in a #JsonNode.
+ * The nodes matching the expression will be copied into an array.
*
- * Return value: (transfer full): a newly-created #JsonNode of type
- * %JSON_NODE_ARRAY containing an array of matching #JsonNodes.
- * Use json_node_unref() when done
+ * Return value: (transfer full): a newly-created node of type
+ * `JSON_NODE_ARRAY` containing the array of matching nodes
*
* Since: 0.14
*/
*
* Queries a JSON tree using a JSONPath expression.
*
- * This function is a simple wrapper around json_path_new(),
- * json_path_compile() and json_path_match(). It implicitly
- * creates a #JsonPath instance, compiles @expression and
- * matches it against the JSON tree pointed by @root.
+ * This function is a simple wrapper around [ctor@Json.Path.new],
+ * [method@Json.Path.compile], and [method@Json.Path.match]. It implicitly
+ * creates a `JsonPath` instance, compiles the given expression and matches
+ * it against the JSON tree pointed by `root`.
*
- * Return value: (transfer full): a newly-created #JsonNode of type
- * %JSON_NODE_ARRAY containing an array of matching #JsonNodes.
- * Use json_node_unref() when done
+ * Return value: (transfer full): a newly-created node of type
+ * `JSON_NODE_ARRAY` containing the array of matching nodes
*
* Since: 0.14
*/
/**
* JSON_PATH_ERROR:
*
- * Error domain for #JsonPath errors
+ * Error domain for `JsonPath`.
*
* Since: 0.14
*/
* JsonPathError:
* @JSON_PATH_ERROR_INVALID_QUERY: Invalid query
*
- * Error code enumeration for the %JSON_PATH_ERROR domain.
+ * Error codes for `JSON_PATH_ERROR`.
+ *
+ * This enumeration can be extended at later date
*
* Since: 0.14
*/
JSON_PATH_ERROR_INVALID_QUERY
} JsonPathError;
-/**
- * JsonPath:
- *
- * The `JsonPath` structure is an opaque object whose members cannot be
- * directly accessed except through the provided API.
- *
- * Since: 0.14
- */
typedef struct _JsonPath JsonPath;
-
-/**
- * JsonPathClass:
- *
- * The `JsonPathClass` structure is an opaque object class whose members
- * cannot be directly accessed.
- *
- * Since: 0.14
- */
typedef struct _JsonPathClass JsonPathClass;
JSON_AVAILABLE_IN_1_0
*/
/**
- * SECTION:json-reader
- * @Title: JsonReader
- * @short_description: A cursor-based parser
+ * JsonReader:
*
- * #JsonReader provides a simple, cursor-based API for parsing a JSON DOM. It
- * is similar, in spirit, to the XML Reader API.
+ * `JsonReader` provides a simple, cursor-based API for parsing a JSON DOM.
*
- * In case of error, #JsonReader will be set in an error state; all subsequent
+ * It is similar, in spirit, to the XML Reader API.
+ *
+ * ## Using `JsonReader`
+ *
+ * ```c
+ * g_autoptr(JsonParser) parser = json_parser_new ();
+ *
+ * // str is defined elsewhere
+ * json_parser_load_from_data (parser, str, -1, NULL);
+ *
+ * g_autoptr(JsonReader) reader = json_reader_new (json_parser_get_root (parser));
+ *
+ * json_reader_read_member (reader, "url");
+ * const char *url = json_reader_get_string_value (reader);
+ * json_reader_end_member (reader);
+ *
+ * json_reader_read_member (reader, "size");
+ * json_reader_read_element (reader, 0);
+ * int width = json_reader_get_int_value (reader);
+ * json_reader_end_element (reader);
+ * json_reader_read_element (reader, 1);
+ * int height = json_reader_get_int_value (reader);
+ * json_reader_end_element (reader);
+ * json_reader_end_member (reader);
+ * ```
+ *
+ * ## Error handling
+ *
+ * In case of error, `JsonReader` will be set in an error state; all subsequent
* calls will simply be ignored until a function that resets the error state is
* called, e.g.:
*
- * |[
+ * ```c
* // ask for the 7th element; if the element does not exist, the
* // reader will be put in an error state
* json_reader_read_element (reader, 6);
*
* // this function resets the error state if any was set
* json_reader_end_element (reader);
- * ]|
+ * ```
*
* If you want to detect the error state as soon as possible, you can use
- * json_reader_get_error():
+ * [method@Json.Reader.get_error]:
*
- * |[<!-- language="C" -->
+ * ```c
* // like the example above, but in this case we print out the
* // error immediately
* if (!json_reader_read_element (reader, 6))
* const GError *error = json_reader_get_error (reader);
* g_print ("Unable to read the element: %s", error->message);
* }
- * ]|
+ * ```
*
- * #JsonReader is available since JSON-GLib 0.12.
+ * Since: 0.12
*/
#include "config.h"
GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
/**
- * JsonReader:root:
+ * JsonReader:root: (attributes org.gtk.Property.set=json_reader_set_root)
*
- * The root of the JSON tree that the #JsonReader should read.
+ * The root of the JSON tree that the reader should read.
*
* Since: 0.12
*/
/**
* json_reader_new:
- * @node: (allow-none): a #JsonNode, or %NULL
+ * @node: (nullable): the root node
+ *
+ * Creates a new reader.
*
- * Creates a new #JsonReader. You can use this object to read the contents of
- * the JSON tree starting from @node
+ * You can use this object to read the contents of the JSON tree starting
+ * from the given node.
*
- * Return value: the newly created #JsonReader. Use g_object_unref() to
- * release the allocated resources when done
+ * Return value: the newly created reader
*
* Since: 0.12
*/
/*
* json_reader_unset_error:
- * @reader: a #JsonReader
+ * @reader: a reader
*
* Unsets the error state of @reader, if set
*
}
/**
- * json_reader_set_root:
- * @reader: a #JsonReader
- * @root: (allow-none): a #JsonNode
+ * json_reader_set_root: (attributes org.gtk.Method.set_property=root)
+ * @reader: a reader
+ * @root: (nullable): the root node
*
- * Sets the root #JsonNode to be read by @reader. The @reader will take
- * a copy of @root
+ * Sets the root node of the JSON tree to be read by @reader.
*
- * If another #JsonNode is currently set as root, it will be replaced.
+ * The reader will take a copy of the node.
*
* Since: 0.12
*/
}
/*
- * json_reader_ser_error:
- * @reader: a #JsonReader
- * @error_code: the #JsonReaderError code for the error
+ * json_reader_set_error:
+ * @reader: a reader
+ * @error_code: the [error@Json.ReaderError] code for the error
* @error_fmt: format string
- * @Varargs: list of arguments for the @error_fmt string
+ * @Varargs: list of arguments for the `error_fmt` string
*
- * Sets the error state of @reader using the given error code
- * and string
+ * Sets the error state of the reader using the given error code
+ * and string.
*
- * Return value: %FALSE, to be used to return immediately from
+ * Return value: `FALSE`, to be used to return immediately from
* the caller function
*/
G_GNUC_PRINTF (3, 4)
/**
* json_reader_get_error:
- * @reader: a #JsonReader
+ * @reader: a reader
*
- * Retrieves the #GError currently set on @reader, if the #JsonReader
- * is in error state
+ * Retrieves the error currently set on the reader.
*
- * Return value: (nullable) (transfer none): the pointer to the error, or %NULL
+ * Return value: (nullable) (transfer none): the current error
*
* Since: 0.12
*/
/**
* json_reader_is_array:
- * @reader: a #JsonReader
+ * @reader: a reader
*
- * Checks whether the @reader is currently on an array
+ * Checks whether the reader is currently on an array.
*
- * Return value: %TRUE if the #JsonReader is on an array, and %FALSE
- * otherwise
+ * Return value: `TRUE` if the reader is on an array
*
* Since: 0.12
*/
/**
* json_reader_is_object:
- * @reader: a #JsonReader
+ * @reader: a reader
*
- * Checks whether the @reader is currently on an object
+ * Checks whether the reader is currently on an object.
*
- * Return value: %TRUE if the #JsonReader is on an object, and %FALSE
- * otherwise
+ * Return value: `TRUE` if the reader is on an object
*
* Since: 0.12
*/
/**
* json_reader_is_value:
- * @reader: a #JsonReader
+ * @reader: a reader
*
- * Checks whether the @reader is currently on a value
+ * Checks whether the reader is currently on a value.
*
- * Return value: %TRUE if the #JsonReader is on a value, and %FALSE
- * otherwise
+ * Return value: `TRUE` if the reader is on a value
*
* Since: 0.12
*/
/**
* json_reader_read_element:
- * @reader: a #JsonReader
+ * @reader: a reader
* @index_: the index of the element
*
- * Advances the cursor of @reader to the element @index_ of the array
- * or the object at the current position.
+ * Advances the cursor of the reader to the element of the array or
+ * the member of the object at the given position.
*
- * You can use the json_reader_get_value* family of functions to retrieve
- * the value of the element; for instance:
+ * You can use [method@Json.Reader.get_value] and its wrapper functions to
+ * retrieve the value of the element; for instance, the following code will
+ * read the first element of the array at the current cursor position:
*
- * |[
+ * ```c
* json_reader_read_element (reader, 0);
* int_value = json_reader_get_int_value (reader);
- * ]|
+ * ```
*
- * After reading the value, json_reader_end_element() should be called to
- * reposition the cursor inside the #JsonReader, e.g.:
+ * After reading the value, you should call [method@Json.Reader.end_element]
+ * to reposition the cursor inside the reader, e.g.:
+ *
+ * ```c
+ * const char *str_value = NULL;
*
- * |[
* json_reader_read_element (reader, 1);
* str_value = json_reader_get_string_value (reader);
* json_reader_end_element (reader);
* json_reader_read_element (reader, 2);
* str_value = json_reader_get_string_value (reader);
* json_reader_end_element (reader);
- * ]|
+ * ```
*
- * If @reader is not currently on an array or an object, or if the @index_ is
- * bigger than the size of the array or the object, the #JsonReader will be
- * put in an error state until json_reader_end_element() is called. This means
- * that if used conditionally, json_reader_end_element() must be called on both
- * code paths:
+ * If the reader is not currently on an array or an object, or if the index is
+ * bigger than the size of the array or the object, the reader will be
+ * put in an error state until [method@Json.Reader.end_element] is called. This
+ * means that, if used conditionally, [method@Json.Reader.end_element] must be
+ * called on all branches:
*
- * |[
+ * ```c
* if (!json_reader_read_element (reader, 1))
* {
+ * g_propagate_error (error, json_reader_get_error (reader));
* json_reader_end_element (reader);
- * g_set_error (error, …);
* return FALSE;
* }
+ * else
+ * {
+ * const char *str_value = json_reader_get_string_value (reader);
+ * json_reader_end_element (reader);
*
- * str_value = json_reader_get_string_value (reader);
- * json_reader_end_element (reader);
- * ]|
+ * // use str_value
*
- * Return value: %TRUE on success, and %FALSE otherwise
+ * return TRUE;
+ * }
+ * ```c
+ *
+ * Return value: `TRUE` on success, and `FALSE` otherwise
*
* Since: 0.12
*/
/**
* json_reader_end_element:
- * @reader: a #JsonReader
+ * @reader: a reader
*
* Moves the cursor back to the previous node after being positioned
- * inside an array
+ * inside an array.
*
- * This function resets the error state of @reader, if any was set
+ * This function resets the error state of the reader, if any was set.
*
* Since: 0.12
*/
/**
* json_reader_count_elements:
- * @reader: a #JsonReader
+ * @reader: a reader
+ *
+ * Counts the elements of the current position, if the reader is
+ * positioned on an array.
*
- * Counts the elements of the current position, if @reader is
- * positioned on an array
+ * In case of failure, the reader is set to an error state.
*
- * Return value: the number of elements, or -1. In case of failure
- * the #JsonReader is set in an error state
+ * Return value: the number of elements, or -1.
*
* Since: 0.12
*/
/**
* json_reader_read_member:
- * @reader: a #JsonReader
+ * @reader: a reader
* @member_name: the name of the member to read
*
- * Advances the cursor of @reader to the @member_name of the object at the
- * current position.
+ * Advances the cursor of the reader to the `member_name` of the object at
+ * the current position.
*
- * You can use the json_reader_get_value* family of functions to retrieve
- * the value of the member; for instance:
+ * You can use [method@Json.Reader.get_value] and its wrapper functions to
+ * retrieve the value of the member; for instance:
*
- * |[
+ * ```c
* json_reader_read_member (reader, "width");
* width = json_reader_get_int_value (reader);
- * ]|
+ * ```
*
- * After reading the value, json_reader_end_member() should be called to
- * reposition the cursor inside the #JsonReader, e.g.:
+ * After reading the value, `json_reader_end_member()` should be called to
+ * reposition the cursor inside the reader, e.g.:
*
- * |[
+ * ```c
* json_reader_read_member (reader, "author");
* author = json_reader_get_string_value (reader);
* json_reader_end_member (reader);
* json_reader_read_member (reader, "title");
* title = json_reader_get_string_value (reader);
* json_reader_end_member (reader);
- * ]|
+ * ```
*
- * If @reader is not currently on an object, or if the @member_name is not
- * defined in the object, the #JsonReader will be put in an error state until
- * json_reader_end_member() is called. This means that if used conditionally,
- * json_reader_end_member() must be called on both code paths:
+ * If the reader is not currently on an object, or if the `member_name` is not
+ * defined in the object, the reader will be put in an error state until
+ * [method@Json.Reader.end_member] is called. This means that if used
+ * conditionally, [method@Json.Reader.end_member] must be called on all branches:
*
- * |[
+ * ```c
* if (!json_reader_read_member (reader, "title"))
* {
+ * g_propagate_error (error, json_reader_get_error (reader));
* json_reader_end_member (reader);
- * g_set_error (error, …);
* return FALSE;
* }
+ * else
+ * {
+ * const char *str_value = json_reader_get_string_value (reader);
+ * json_reader_end_member (reader);
*
- * str_value = json_reader_get_string_value (reader);
- * json_reader_end_member (reader);
- * ]|
+ * // use str_value
+ *
+ * return TRUE;
+ * }
+ * ```
*
- * Return value: %TRUE on success, and %FALSE otherwise
+ * Return value: `TRUE` on success, and `FALSE` otherwise
*
* Since: 0.12
*/
/**
* json_reader_end_member:
- * @reader: a #JsonReader
+ * @reader: a reader
*
* Moves the cursor back to the previous node after being positioned
- * inside an object
+ * inside an object.
*
- * This function resets the error state of @reader, if any was set
+ * This function resets the error state of the reader, if any was set.
*
* Since: 0.12
*/
/**
* json_reader_list_members:
- * @reader: a #JsonReader
+ * @reader: a reader
*
- * Retrieves a list of member names from the current position, if @reader
+ * Retrieves a list of member names from the current position, if the reader
* is positioned on an object.
*
- * Return value: (transfer full): a newly allocated, %NULL-terminated
- * array of strings holding the members name. Use g_strfreev() when
- * done.
+ * In case of failure, the reader is set to an error state.
+ *
+ * Return value: (transfer full) (array zero-terminated=1): the members of
+ * the object
*
* Since: 0.14
*/
/**
* json_reader_count_members:
- * @reader: a #JsonReader
+ * @reader: a reader
*
- * Counts the members of the current position, if @reader is
- * positioned on an object
+ * Counts the members of the current position, if the reader is
+ * positioned on an object.
*
- * Return value: the number of members, or -1. In case of failure
- * the #JsonReader is set in an error state
+ * In case of failure, the reader is set to an error state.
+ *
+ * Return value: the number of members, or -1
*
* Since: 0.12
*/
/**
* json_reader_get_value:
- * @reader: a #JsonReader
+ * @reader: a reader
+ *
+ * Retrieves the value node at the current position of the reader.
*
- * Retrieves the #JsonNode of the current position of @reader
+ * If the current position does not contain a scalar value, the reader
+ * is set to an error state.
*
- * Return value: (nullable) (transfer none): a #JsonNode, or %NULL. The
- * returned node is owned by the #JsonReader and it should not be
- * modified or freed directly
+ * Return value: (nullable) (transfer none): the current value node
*
* Since: 0.12
*/
/**
* json_reader_get_int_value:
- * @reader: a #JsonReader
+ * @reader: a reader
*
- * Retrieves the integer value of the current position of @reader
+ * Retrieves the integer value of the current position of the reader.
+ *
+ * See also: [method@Json.Reader.get_value]
*
* Return value: the integer value
*
/**
* json_reader_get_double_value:
- * @reader: a #JsonReader
+ * @reader: a reader
+ *
+ * Retrieves the floating point value of the current position of the reader.
*
- * Retrieves the floating point value of the current position of @reader
+ * See also: [method@Json.Reader.get_value]
*
* Return value: the floating point value
*
/**
* json_reader_get_string_value:
- * @reader: a #JsonReader
+ * @reader: a reader
*
- * Retrieves the string value of the current position of @reader
+ * Retrieves the string value of the current position of the reader.
+ *
+ * See also: [method@Json.Reader.get_value]
*
* Return value: the string value
*
/**
* json_reader_get_boolean_value:
- * @reader: a #JsonReader
+ * @reader: a reader
+ *
+ * Retrieves the boolean value of the current position of the reader.
*
- * Retrieves the boolean value of the current position of @reader
+ * See also: [method@Json.Reader.get_value]
*
* Return value: the boolean value
*
/**
* json_reader_get_null_value:
- * @reader: a #JsonReader
+ * @reader: a reader
*
- * Checks whether the value of the current position of @reader is 'null'
+ * Checks whether the value of the current position of the reader is `null`.
*
- * Return value: %TRUE if 'null' is set, and %FALSE otherwise
+ * See also: [method@Json.Reader.get_value]
+ *
+ * Return value: `TRUE` if `null` is set, and `FALSE` otherwise
*
* Since: 0.12
*/
/**
* json_reader_get_member_name:
- * @reader: a #JsonReader
+ * @reader: a reader
*
* Retrieves the name of the current member.
*
- * Return value: (nullable) (transfer none): the name of the member, or %NULL
+ * In case of failure, the reader is set to an error state.
+ *
+ * Return value: (nullable) (transfer none): the name of the member
*
* Since: 0.14
*/
/**
* JSON_READER_ERROR:
*
- * Error domain for #JsonReader errors
+ * Error domain for `JsonReader`.
*
* Since: 0.12
*/
* @JSON_READER_ERROR_INVALID_TYPE: The node at the current position does not
* hold a value of the desired type
*
- * Error codes enumeration for #JsonReader errors
+ * Error codes for `JSON_READER_ERROR`.
+ *
+ * This enumeration can be extended at later date
*
* Since: 0.12
*/
JSON_READER_ERROR_INVALID_TYPE
} JsonReaderError;
-/**
- * JsonReader:
- *
- * The `JsonReader` structure contains only private data and should
- * be accessed using the provided API
- *
- * Since: 0.12
- */
struct _JsonReader
{
/*< private >*/
JsonReaderPrivate *priv;
};
-/**
- * JsonReaderClass:
- *
- * The `JsonReaderClass` structure contains only private data
- *
- * Since: 0.12
- */
struct _JsonReaderClass
{
/*< private >*/
*/
/**
- * SECTION:json-serializable
- * @short_description: Interface for serialize and deserialize special GObjects
+ * JsonSerializable:
*
- * #JsonSerializable is an interface for #GObject classes that
- * allows controlling how the class is going to be serialized
- * or deserialized by json_construct_gobject() and
- * json_serialize_gobject() respectively.
+ * `JsonSerializable` is an interface for controlling the serialization
+ * and deserialization of `GObject` classes.
+ *
+ * Implementing this interface allows controlling how the class is going
+ * to be serialized or deserialized by [func@Json.construct_gobject] and
+ * [func@Json.serialize_gobject], respectively.
*/
#include "config.h"
/**
* json_serializable_serialize_property:
- * @serializable: a #JsonSerializable object
- * @property_name: the name of the property
- * @value: the value of the property
- * @pspec: a #GParamSpec
+ * @serializable: a serializable object
+ * @property_name: the name of the property to serialize
+ * @value: the value of the property to serialize
+ * @pspec: a property description
*
- * Asks a #JsonSerializable implementation to serialize a #GObject
- * property into a #JsonNode object.
+ * Asks a `JsonSerializable` implementation to serialize an object
+ * property into a JSON node.
*
- * Return value: a #JsonNode containing the serialized property
+ * Return value: (transfer full): a node containing the serialized property
*/
JsonNode *
json_serializable_serialize_property (JsonSerializable *serializable,
/**
* json_serializable_deserialize_property:
- * @serializable: a #JsonSerializable
- * @property_name: the name of the property
- * @value: (out): a pointer to an uninitialized #GValue
- * @pspec: a #GParamSpec
- * @property_node: a #JsonNode containing the serialized property
+ * @serializable: a serializable object
+ * @property_name: the name of the property to serialize
+ * @value: (out): a pointer to an uninitialized value
+ * @pspec: a property description
+ * @property_node: the JSON node containing the serialized property
+ *
+ * Asks a `JsonSerializable` implementation to deserialize the
+ * property contained inside `property_node` and place its value
+ * into `value`.
*
- * Asks a #JsonSerializable implementation to deserialize the
- * property contained inside @property_node into @value.
+ * The `value` can be:
*
- * The @value can be:
- * - an empty #GValue initialized by %G_VALUE_INIT, which will be automatically
- * initialized with the expected type of the property (since JSON-GLib 1.6)
- * - a #GValue initialized with the expected type of the property
+ * - an empty `GValue` initialized by `G_VALUE_INIT`, which will be automatically
+ * initialized with the expected type of the property by using the given
+ * property description (since JSON-GLib 1.6)
+ * - a `GValue` initialized with the expected type of the property
*
- * Return value: %TRUE if the property was successfully deserialized.
+ * Returns: `TRUE` if the property was successfully deserialized
*/
gboolean
json_serializable_deserialize_property (JsonSerializable *serializable,
iface->get_property = json_serializable_real_get_property;
}
-G_DEFINE_INTERFACE (JsonSerializable, json_serializable, G_TYPE_OBJECT);
+G_DEFINE_INTERFACE (JsonSerializable, json_serializable, G_TYPE_OBJECT)
/**
* json_serializable_default_serialize_property:
- * @serializable: a #JsonSerializable object
- * @property_name: the name of the property
- * @value: the value of the property
- * @pspec: a #GParamSpec
+ * @serializable: a serializable object
+ * @property_name: the name of the property to serialize
+ * @value: the value of the property to serialize
+ * @pspec: a property description
+ *
+ * Calls the default implementation of the [vfunc@Json.Serializable.serialize_property]
+ * virtual function.
*
- * Calls the default implementation of the #JsonSerializable
- * #JsonSerializableIface.serialize_property() virtual function.
+ * This function can be used inside a custom implementation of the
+ * `serialize_property()` virtual function in lieu of calling the
+ * default implementation through `g_type_default_interface_peek()`:
*
- * This function can be used inside a custom implementation
- * of the #JsonSerializableIface.serialize_property() virtual
- * function in lieu of calling the default implementation
- * through g_type_default_interface_peek():
+ * ```c
+ * JsonSerializable *iface;
+ * JsonNode *node;
*
- * |[<!-- language="C" -->
- * JsonSerializable *iface;
- * JsonNode *node;
+ * iface = g_type_default_interface_peek (JSON_TYPE_SERIALIZABLE);
+ * node = iface->serialize_property (serializable, property_name,
+ * value,
+ * pspec);
+ * ```
*
- * iface = g_type_default_interface_peek (JSON_TYPE_SERIALIZABLE);
- * node = iface->serialize_property (serializable, property_name,
- * value,
- * pspec);
- * ]|
+ * This function will return `NULL` if the property could not be
+ * serialized.
*
- * Return value: (transfer full) (nullable): a #JsonNode containing the
- * serialized property, or %NULL if it should be omitted.
+ * Returns: (transfer full) (nullable): a node containing the
+ * serialized property
*
* Since: 0.10
*/
/**
* json_serializable_default_deserialize_property:
- * @serializable: a #JsonSerializable
- * @property_name: the name of the property
- * @value: a pointer to an uninitialized #GValue
- * @pspec: a #GParamSpec
- * @property_node: a #JsonNode containing the serialized property
+ * @serializable: a serializable object
+ * @property_name: the name of the property to deserialize
+ * @value: a pointer to an uninitialized value
+ * @pspec: a property description
+ * @property_node: the JSON node containing the serialized property
*
- * Calls the default implementation of the #JsonSerializable
- * deserialize_property() virtual function
+ * Calls the default implementation of the [vfunc@Json.Serializable.deserialize_property]
+ * virtual function.
*
- * This function can be used inside a custom implementation
- * of the deserialize_property() virtual function in lieu of:
+ * This function can be used inside a custom implementation of the
+ * `deserialize_property()` virtual function in lieu of calling the
+ * default implementation through `g_type_default_interface_peek()`:
*
- * |[<!-- language="C" -->
- * JsonSerializable *iface;
- * gboolean res;
+ * ```c
+ * JsonSerializable *iface;
+ * gboolean res;
*
- * iface = g_type_default_interface_peek (JSON_TYPE_SERIALIZABLE);
- * res = iface->deserialize_property (serializable, property_name,
- * value,
- * pspec,
- * property_node);
- * ]|
+ * iface = g_type_default_interface_peek (JSON_TYPE_SERIALIZABLE);
+ * res = iface->deserialize_property (serializable, property_name,
+ * value,
+ * pspec,
+ * property_node);
+ * ```
*
- * Return value: %TRUE if the property was successfully deserialized.
+ * Return value: `TRUE` if the property was successfully deserialized
*
* Since: 0.10
*/
/**
* json_serializable_find_property:
- * @serializable: a #JsonSerializable
+ * @serializable: a serializable object
* @name: the name of the property
*
- * Calls the #JsonSerializableIface.find_property() implementation on
- * the @serializable instance. *
+ * Calls the [vfunc@Json.Serializable.find_property] implementation on
+ * the `JsonSerializable` instance, which will return the property
+ * description for the given name.
*
- * Return value: (nullable) (transfer none): the #GParamSpec for the property
- * or %NULL if no property was found
+ * Return value: (nullable) (transfer none): the property description
*
* Since: 0.14
*/
/**
* json_serializable_list_properties:
- * @serializable: a #JsonSerializable
- * @n_pspecs: (out): return location for the length of the array
- * of #GParamSpec returned by the function
+ * @serializable: a serializable object
+ * @n_pspecs: (out): return location for the length of the returned array
*
- * Calls the #JsonSerializableIface.list_properties() implementation on
- * the @serializable instance.
+ * Calls the [vfunc@Json.Serializable.list_properties] implementation on
+ * the `JsonSerializable` instance, which will return the list of serializable
+ * properties.
*
- * Return value: (array length=n_pspecs) (transfer container): an array
- * of #GParamSpec. Use g_free() to free the array when done.
+ * Return value: (array length=n_pspecs) (transfer container): the serializable
+ * properties of the object
*
* Since: 0.14
*/
/**
* json_serializable_set_property:
- * @serializable: a #JsonSerializable
- * @pspec: a #GParamSpec
+ * @serializable: a serializable object
+ * @pspec: a property description
* @value: the property value to set
*
- * Calls the #JsonSerializableIface.set_property() implementation
- * on the @serializable instance.
+ * Calls the [vfunc@Json.Serializable.set_property] implementation
+ * on the `JsonSerializable` instance, which will set the property
+ * with the given value.
*
* Since: 0.14
*/
/**
* json_serializable_get_property:
- * @serializable: a #JsonSerializable
- * @pspec: a #GParamSpec
+ * @serializable: a serializable object
+ * @pspec: a property description
* @value: (out): return location for the property value
*
- * Calls the #JsonSerializableIface.get_property() implementation
- * on the @serializable instance.
+ * Calls the [vfunc@Json.Serializable.get_property] implementation
+ * on the `JsonSerializable` instance, which will get the value of
+ * the given property.
*
* Since: 0.14
*/
/**
* JSON_NODE_TYPE:
- * @node: a #JsonNode
+ * @node: (type Json.Node): the [struct@Json.Node] to check
*
- * Evaluates to the #JsonNodeType contained by @node
+ * Evaluates to the [enum@Json.NodeType] value contained by the node.
*/
#define JSON_NODE_TYPE(node) (json_node_get_node_type ((node)))
/**
* JSON_NODE_HOLDS:
- * @node: a #JsonNode
- * @t: a #JsonNodeType
+ * @node: (type Json.Node): the [struct@Json.Node] to check
+ * @t: (type Json.NodeType): the desired [enum@Json.NodeType]
*
- * Evaluates to %TRUE if the @node holds type @t
+ * Evaluates to `TRUE` if the node holds the given type.
*
* Since: 0.10
*/
/**
* JSON_NODE_HOLDS_VALUE:
- * @node: a #JsonNode
+ * @node: (type Json.Node): the [struct@Json.Node] to check
*
- * Evaluates to %TRUE if @node holds a %JSON_NODE_VALUE
+ * Evaluates to `TRUE` if the node holds a scalar value.
*
* Since: 0.10
*/
/**
* JSON_NODE_HOLDS_OBJECT:
- * @node: a #JsonNode
+ * @node: (type Json.Node): the [struct@Json.Node] to check
*
- * Evaluates to %TRUE if @node holds a %JSON_NODE_OBJECT
+ * Evaluates to `TRUE` if the node holds a JSON object.
*
* Since: 0.10
*/
/**
* JSON_NODE_HOLDS_ARRAY:
- * @node: a #JsonNode
+ * @node: (type Json.Node): the [struct@Json.Node] to check
*
- * Evaluates to %TRUE if @node holds a %JSON_NODE_ARRAY
+ * Evaluates to `TRUE` if the node holds a JSON array.
*
* Since: 0.10
*/
/**
* JSON_NODE_HOLDS_NULL:
- * @node: a #JsonNode
+ * @node: (type Json.Node): the [struct@Json.Node] to check
*
- * Evaluates to %TRUE if @node holds a %JSON_NODE_NULL
+ * Evaluates to `TRUE` if the node holds `null`.
*
* Since: 0.10
*/
#define JSON_TYPE_OBJECT (json_object_get_type ())
#define JSON_TYPE_ARRAY (json_array_get_type ())
-/**
- * JsonNode:
- *
- * A generic container of JSON data types. The contents of the #JsonNode
- * structure are private and should only be accessed via the provided
- * functions and never directly.
- */
typedef struct _JsonNode JsonNode;
-
-/**
- * JsonObject:
- *
- * A JSON object type. The contents of the #JsonObject structure are private
- * and should only be accessed by the provided API
- */
typedef struct _JsonObject JsonObject;
-
-/**
- * JsonArray:
- *
- * A JSON array type. The contents of the #JsonArray structure are private
- * and should only be accessed by the provided API
- */
typedef struct _JsonArray JsonArray;
/**
* JsonNodeType:
- * @JSON_NODE_OBJECT: The node contains a #JsonObject
- * @JSON_NODE_ARRAY: The node contains a #JsonArray
+ * @JSON_NODE_OBJECT: The node contains a JSON object
+ * @JSON_NODE_ARRAY: The node contains a JSON array
* @JSON_NODE_VALUE: The node contains a fundamental type
* @JSON_NODE_NULL: Special type, for nodes containing null
*
- * Indicates the content of a #JsonNode.
+ * Indicates the content of a node.
*/
typedef enum {
JSON_NODE_OBJECT,
/**
* JsonObjectForeach:
- * @object: the iterated #JsonObject
+ * @object: the iterated JSON object
* @member_name: the name of the member
- * @member_node: a #JsonNode containing the @member_name value
+ * @member_node: the value of the member
* @user_data: data passed to the function
*
- * The function to be passed to json_object_foreach_member(). You
- * should not add or remove members to and from @object within
- * this function. It is safe to change the value of @member_node.
+ * The function to be passed to [method@Json.Object.foreach_member].
+ *
+ * You should not add or remove members to and from @object within
+ * this function.
+ *
+ * It is safe to change the value of @member_node.
*
* Since: 0.8
*/
/**
* JsonArrayForeach:
- * @array: the iterated #JsonArray
+ * @array: the iterated JSON array
* @index_: the index of the element
- * @element_node: a #JsonNode containing the value at @index_
+ * @element_node: the value of the element at the given @index_
* @user_data: data passed to the function
*
- * The function to be passed to json_array_foreach_element(). You
- * should not add or remove elements to and from @array within
- * this function. It is safe to change the value of @element_node.
+ * The function to be passed to [method@Json.Array.foreach_element].
+ *
+ * You should not add or remove elements to and from @array within
+ * this function.
+ *
+ * It is safe to change the value of @element_node.
*
* Since: 0.8
*/
/**
* JsonObjectIter:
*
- * An iterator used to iterate over the members of a #JsonObject. This must
- * be allocated on the stack and initialised using json_object_iter_init().
- * The order in which members are returned by the iterator is undefined. The
- * iterator is invalidated if its #JsonObject is modified during iteration.
+ * An iterator object used to iterate over the members of a JSON object.
+ *
+ * `JsonObjectIter` must be allocated on the stack and initialised using
+ * [method@Json.ObjectIter.init] or [method@Json.ObjectIter.init_ordered].
+ *
+ * The iterator is invalidated if the object is modified during
+ * iteration.
*
- * All the fields in the #JsonObjectIter structure are private and should
+ * All the fields in the `JsonObjectIter` structure are private and should
* never be accessed directly.
*
* Since: 1.2
* License along with this library. If not, see <http://www.gnu.org/licenses/>.
*/
-/**
- * SECTION:json-utils
- * @Title: Utility API
- * @Short_description: Various utility functions
- *
- * Various utility functions.
- */
-
#include "config.h"
#include "json-utils.h"
* @str: a valid UTF-8 string containing JSON data
* @error: return location for a #GError
*
- * Parses the string in @str and returns a #JsonNode representing
- * the JSON tree. If @str is empty, this function will return %NULL.
+ * Parses the given string and returns the corresponding JSON tree.
+ *
+ * If the string is empty, this function will return `NULL`.
*
- * In case of parsing error, this function returns %NULL and sets
- * @error appropriately.
+ * In case of parsing error, this function returns `NULL` and sets
+ * the error appropriately.
*
- * Returns: (transfer full) (nullable): a #JsonNode, or %NULL
+ * Returns: (transfer full) (nullable): the root node of the JSON tree
*
* Since: 1.2
*/
/**
* json_to_string:
- * @node: a #JsonNode
+ * @node: a JSON tree
* @pretty: whether the output should be prettyfied for printing
*
* Generates a stringified JSON representation of the contents of
- * the passed @node.
+ * the given `node`.
*
- * Returns: (transfer full): the string representation of the #JsonNode
+ * Returns: (transfer full): the string representation of the node
*
* Since: 1.2
*/
}
}
-/**
+/*< private >
* json_value_seal:
- * @value: a #JsonValue
+ * @value: a JSON scalar value
*
- * Seals the #JsonValue, making it immutable to further changes.
+ * Seals the value, making it immutable to further changes.
*
- * If the @value is already immutable, this is a no-op.
- *
- * Since: 1.2
+ * If the value is already immutable, this is a no-op.
*/
void
json_value_seal (JsonValue *value)
#endif
/* XXX: Each new cycle should add a new version symbol here */
+/**
+ * JSON_VERSION_1_0:
+ *
+ * The encoded representation of JSON-GLib version "1.0".
+ */
#define JSON_VERSION_1_0 (G_ENCODE_VERSION (1, 0))
+/**
+ * JSON_VERSION_1_2:
+ *
+ * The encoded representation of JSON-GLib version "1.2".
+ */
#define JSON_VERSION_1_2 (G_ENCODE_VERSION (1, 2))
+/**
+ * JSON_VERSION_1_4:
+ *
+ * The encoded representation of JSON-GLib version "1.4".
+ */
#define JSON_VERSION_1_4 (G_ENCODE_VERSION (1, 4))
+/**
+ * JSON_VERSION_1_6:
+ *
+ * The encoded representation of JSON-GLib version "1.6".
+ */
#define JSON_VERSION_1_6 (G_ENCODE_VERSION (1, 6))
/* evaluates to the current stable version; for development cycles,
* JSON_VERSION_MIN_REQUIRED:
*
* A macro that should be defined by the user prior to including
- * the gdk.h header.
- * The definition should be one of the predefined JSON version
- * macros: %JSON_VERSION_1_0, %JSON_VERSION_1_2,...
+ * the `json-glib/json-glib.h` header.
+ *
+ * The definition should be one of the predefined JSON-GLib version
+ * macros: `JSON_VERSION_1_0`, `JSON_VERSION_1_2`, ...
*
* This macro defines the lower bound for the JSON-GLib API to use.
*
* JSON_VERSION_MAX_ALLOWED:
*
* A macro that should be defined by the user prior to including
- * the json-glib.h header.
+ * the `json-glib/json-glib.h` header.
* The definition should be one of the predefined JSON-GLib version
- * macros: %JSON_VERSION_1_0, %JSON_VERSION_1_2,...
+ * macros: `JSON_VERSION_1_0`, `JSON_VERSION_1_2`, ...
*
* This macro defines the upper bound for the JSON API-GLib to use.
*
#endif
/**
- * SECTION:json-version
- * @short_description: JSON-GLib version checking
- *
- * JSON-GLib provides macros to check the version of the library
- * at compile-time
- */
-
-/**
* JSON_MAJOR_VERSION:
*
- * Json major version component (e.g. 1 if %JSON_VERSION is 1.2.3)
+ * Json major version component (e.g. 1 if `JSON_VERSION` is "1.2.3")
*/
#define JSON_MAJOR_VERSION (@JSON_MAJOR_VERSION@)
/**
* JSON_MINOR_VERSION:
*
- * Json minor version component (e.g. 2 if %JSON_VERSION is 1.2.3)
+ * Json minor version component (e.g. 2 if `JSON_VERSION` is "1.2.3")
*/
#define JSON_MINOR_VERSION (@JSON_MINOR_VERSION@)
/**
* JSON_MICRO_VERSION:
*
- * Json micro version component (e.g. 3 if %JSON_VERSION is 1.2.3)
+ * Json micro version component (e.g. 3 if `JSON_VERSION` is "1.2.3")
*/
#define JSON_MICRO_VERSION (@JSON_MICRO_VERSION@)
/**
* JSON_VERSION
*
- * Json version.
+ * The version of JSON-GLib.
*/
#define JSON_VERSION (@JSON_VERSION@)
/**
* JSON_VERSION_S:
*
- * JSON-GLib version, encoded as a string, useful for printing and
+ * The version of JSON-GLib, encoded as a string, useful for printing and
* concatenation.
*/
#define JSON_VERSION_S "@JSON_VERSION@"
+/**
+ * JSON_ENCODE_VERSION:
+ * @major: (type int): the major version to encode
+ * @minor: (type int): the minor version to encode
+ * @micro: (type int): the micro version to encode
+ *
+ * Encodes a JSON-GLib version in an hexadecimal number, useful for
+ * integer comparisons.
+ */
#define JSON_ENCODE_VERSION(major,minor,micro) \
((major) << 24 | (minor) << 16 | (micro) << 8)
/**
* JSON_VERSION_HEX:
*
- * JSON-GLib version, encoded as an hexadecimal number, useful for
+ * The version of JSON-GLib, encoded as an hexadecimal number, useful for
* integer comparisons.
*/
#define JSON_VERSION_HEX \
* @minor: required minor version
* @micro: required micro version
*
- * Compile-time version checking. Evaluates to %TRUE if the version
- * of Json is greater than the required one.
+ * Compile-time version checking. Evaluates to `TRUE` if the version
+ * of JSON-GLib is greater than the required one.
*/
#define JSON_CHECK_VERSION(major,minor,micro) \
(JSON_MAJOR_VERSION > (major) || \
if gir.found()
gir_args = [
'--quiet',
- '--c-include=json-glib/json-glib.h',
+ '--warn-all',
'-DJSON_COMPILATION',
]
header: 'json-glib/json-glib.h',
install: true,
extra_args: gir_args,
+ fatal_warnings: true,
)
else
json_glib_gir = []
-project('json-glib', 'c', version: '1.6.2',
+project('json-glib', 'c', version: '1.6.4',
license: 'LGPLv2.1+',
default_options: [
'warning_level=1',
'buildtype=debugoptimized',
'c_std=c99',
],
- meson_version: '>= 0.52.0')
+ meson_version: '>= 0.55.3')
# Versioning
json_version = meson.project_version()
cdata.set('JSON_ENABLE_DEBUG', true)
endif
-common_ldflags = []
-if host_system == 'linux'
- common_ldflags += cc.get_supported_link_arguments([
- '-Wl,-Bsymbolic',
- '-Wl,-z,relro',
- '-Wl,-z,now',
- '-Wl,--default-symver',
- ])
-endif
+common_ldflags = cc.get_supported_link_arguments([
+ '-Wl,-Bsymbolic',
+ '-Wl,-z,relro',
+ '-Wl,-z,now',
+ '-Wl,--default-symver',
+])
root_dir = include_directories('.')
subdir('json-glib')
subdir('po')
subdir('doc')
+
+summary({
+ 'prefix': get_option('prefix'),
+ 'includedir': json_includedir,
+ 'libdir': get_option('prefix') / get_option('libdir'),
+ 'datadir': json_datadir,
+ },
+ section: 'Directories',
+)
+
+summary({
+ 'Introspection': get_option('introspection').enabled() or get_option('introspection').auto(),
+ 'Documentation': get_option('gtk_doc').enabled() or get_option('gtk_doc').auto(),
+ 'Manual pages': get_option('man'),
+ 'Tests': get_option('tests'),
+ },
+ section: 'Build',
+ bool_yn: true,
+)
# Galician translation for json-glib.
# Copyright (C) 2012 json-glib's COPYRIGHT HOLDER
# This file is distributed under the same license as the json-glib package.
-# Fran Dieguez <frandieguez@gnome.org>, 2012, 2013, 2017, 2018.
+# Fran Dieguez <frandieguez@gnome.org>, 2012, 2013, 2017, 2018, 2021.
msgid ""
msgstr ""
"Project-Id-Version: json-glib master\n"
"Report-Msgid-Bugs-To: https://gitlab.gnome.org/GNOME/json-glib/issues\n"
-"POT-Creation-Date: 2018-06-30 18:31+0000\n"
-"PO-Revision-Date: 2018-08-30 00:28+0200\n"
+"POT-Creation-Date: 2020-06-16 13:37+0000\n"
+"PO-Revision-Date: 2021-02-23 20:08+0100\n"
"Last-Translator: Fran Dieguez <frandieguez@gnome.org>\n"
"Language-Team: Proxecto Trasno <proxecto@trasno.gal>\n"
"Language: gl\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Plural-Forms: nplurals=2; plural=(n != 1);\n"
-"X-Generator: Virtaal 0.7.1\n"
+"X-Generator: Gtranslator 3.38.0\n"
"X-Project-Style: gnome\n"
#: json-glib/json-glib-format.c:58
#: json-glib/json-glib-format.c:59
msgid "SPACES"
-msgstr "ESPACIOS"
+msgstr "ESPAZOS"
#: json-glib/json-glib-format.c:60
msgid "Output file"
msgstr "FICHEIRO"
#: json-glib/json-glib-format.c:61
-#| msgid "FILE"
msgid "FILE…"
msgstr "FICHEIRO…"
#. and before the list of options.
#: json-glib/json-glib-format.c:192
msgid "Format JSON files."
-msgstr "Formatea de ficheiros JSON."
+msgstr "Formato de ficheiros JSON."
#: json-glib/json-glib-format.c:193
msgid "json-glib-format formats JSON resources."
msgid "Unexpected extra elements in JSON array"
msgstr "Elementos adicionais non agardados no vector JSON"
-#: json-glib/json-gvariant.c:909
+#: json-glib/json-gvariant.c:931
msgid "Invalid string value converting to GVariant"
msgstr "Valor de cadea non válido ao converter a GVariant"
-#: json-glib/json-gvariant.c:964
+#: json-glib/json-gvariant.c:986
msgid ""
"A GVariant dictionary entry expects a JSON object with exactly one member"
msgstr ""
"Unha entrada do dicionario e GVariant agarda un obxecto JSON con só un membro"
-#: json-glib/json-gvariant.c:1242
+#: json-glib/json-gvariant.c:1264
#, c-format
msgid "GVariant class “%c” not supported"
msgstr "Clase «%c» de GVariant non admitida"
-#: json-glib/json-gvariant.c:1290
+#: json-glib/json-gvariant.c:1312
msgid "Invalid GVariant signature"
msgstr "Firma de GVariant non válida"
-#: json-glib/json-gvariant.c:1338
+#: json-glib/json-gvariant.c:1360
msgid "JSON data is empty"
msgstr "Datos de JSON baleiros"
#: json-glib/json-path.c:438
msgid "Missing member name or wildcard after . character"
-msgstr "Falta o nome do membro ou comodín logo do caracter «.»"
+msgstr "Falta o nome do membro ou comodín logo do carácter «.»"
#: json-glib/json-path.c:512
#, c-format
#: json-glib/json-path.c:656
#, c-format
msgid "Invalid first character “%c”"
-msgstr "Primeiro caracter «%c» non válido"
+msgstr "Primeiro carácter «%c» non válido"
#: json-glib/json-reader.c:474
#, c-format
#: json-glib/json-reader.c:951 json-glib/json-reader.c:996
#: json-glib/json-reader.c:1032 json-glib/json-reader.c:1058
msgid "No node available at the current position"
-msgstr "Non hai ningún nodo dipoñíbel na posición actual"
+msgstr "Non hai ningún nodo dispoñíbel na posición actual"
#: json-glib/json-reader.c:592
#, c-format
msgid ""
msgstr ""
"Project-Id-Version: json-glib master\n"
-"Report-Msgid-Bugs-To: http://bugzilla.gnome.org/enter_bug.cgi?product=json-"
-"glib&keywords=I18N+L10N&component=general\n"
-"POT-Creation-Date: 2014-03-10 22:18+0000\n"
-"PO-Revision-Date: 2014-03-11 12:23+0300\n"
-"Last-Translator: Yuri Myasoedov <omerta13@yandex.ru>\n"
+"Report-Msgid-Bugs-To: https://gitlab.gnome.org/GNOME/json-glib/issues\n"
+"POT-Creation-Date: 2020-06-16 13:37+0000\n"
+"PO-Revision-Date: 2021-06-28 14:25+0300\n"
+"Last-Translator: Alexey Rubtsov <rushills@gmail.com>\n"
"Language-Team: русский <gnome-cyr@gnome.org>\n"
"Language: ru\n"
"MIME-Version: 1.0\n"
"Content-Transfer-Encoding: 8bit\n"
"Plural-Forms: nplurals=3; plural=(n%10==1 && n%100!=11 ? 0 : n%10>=2 && n"
"%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2);\n"
-"X-Generator: Poedit 1.5.4\n"
+"X-Generator: Poedit 3.0\n"
-#: ../json-glib/json-glib-format.c:50
+#: json-glib/json-glib-format.c:58
msgid "Prettify output"
msgstr "Выводить в удобочитаемой форме"
-#: ../json-glib/json-glib-format.c:51
+#: json-glib/json-glib-format.c:59
msgid "Indentation spaces"
msgstr "Отступы"
+#: json-glib/json-glib-format.c:59
+msgid "SPACES"
+msgstr "ОТСТУПЫ"
+
+#: json-glib/json-glib-format.c:60
+msgid "Output file"
+msgstr "Выходной файл"
+
+#: json-glib/json-glib-format.c:60 json-glib/json-glib-validate.c:115
+msgid "FILE"
+msgstr "ФАЙЛ"
+
+#: json-glib/json-glib-format.c:61
+msgid "FILE…"
+msgstr "ФАЙЛ…"
+
#. Translators: the first %s is the program name, the second one
#. * is the URI of the file, the third is the error message.
#.
-#: ../json-glib/json-glib-format.c:77 ../json-glib/json-glib-validate.c:63
+#: json-glib/json-glib-format.c:87 json-glib/json-glib-format.c:120
+#: json-glib/json-glib-validate.c:63
#, c-format
msgid "%s: %s: error opening file: %s\n"
msgstr "%s: %s: не удалось открыть файл: %s\n"
#. Translators: the first %s is the program name, the second one
#. * is the URI of the file, the third is the error message.
#.
-#: ../json-glib/json-glib-format.c:89 ../json-glib/json-glib-validate.c:75
+#: json-glib/json-glib-format.c:99 json-glib/json-glib-validate.c:75
#, c-format
msgid "%s: %s: error parsing file: %s\n"
msgstr "%s: %s: не удалось разобрать файл: %s\n"
#. Translators: the first %s is the program name, the
#. * second one is the URI of the file.
#.
-#: ../json-glib/json-glib-format.c:108
+#: json-glib/json-glib-format.c:138
#, c-format
msgid "%s: %s: error writing to stdout"
msgstr "%s: %s: не удалось записать в стандартный вывод"
#. Translators: the first %s is the program name, the second one
#. * is the URI of the file, the third is the error message.
#.
-#: ../json-glib/json-glib-format.c:128 ../json-glib/json-glib-validate.c:87
+#: json-glib/json-glib-format.c:159 json-glib/json-glib-validate.c:87
#, c-format
msgid "%s: %s: error closing: %s\n"
msgstr "%s: %s: не удалось закрыть: %s\n"
-#: ../json-glib/json-glib-format.c:157 ../json-glib/json-glib-validate.c:115
-msgid "FILE"
-msgstr "ФАЙЛ"
-
#. Translators: this message will appear after the usage string
#. and before the list of options.
-#: ../json-glib/json-glib-format.c:160
+#: json-glib/json-glib-format.c:192
msgid "Format JSON files."
msgstr "Форматирование файлов JSON."
-#: ../json-glib/json-glib-format.c:161
+#: json-glib/json-glib-format.c:193
msgid "json-glib-format formats JSON resources."
msgstr "json-glib-format форматирует ресурсы JSON."
#. * means the user is calling json-glib-validate without any
#. * argument.
#.
-#: ../json-glib/json-glib-format.c:178 ../json-glib/json-glib-validate.c:136
+#: json-glib/json-glib-format.c:208 json-glib/json-glib-validate.c:136
#, c-format
msgid "Error parsing commandline options: %s\n"
msgstr "Не удалось разобрать параметры командной строки: %s\n"
-#: ../json-glib/json-glib-format.c:180 ../json-glib/json-glib-format.c:194
-#: ../json-glib/json-glib-validate.c:138 ../json-glib/json-glib-validate.c:152
+#: json-glib/json-glib-format.c:210 json-glib/json-glib-format.c:224
+#: json-glib/json-glib-validate.c:138 json-glib/json-glib-validate.c:152
#, c-format
-msgid "Try \"%s --help\" for more information."
-msgstr "Используйте «%s --help» для получения подробной информации."
+msgid "Try “%s --help” for more information."
+msgstr ""
+"Для получения дополнительной информации используйте команду «%s --help»."
#. Translators: the %s is the program name. This error message
#. * means the user is calling json-glib-validate without any
#. * argument.
#.
-#: ../json-glib/json-glib-format.c:192 ../json-glib/json-glib-validate.c:150
+#: json-glib/json-glib-format.c:222 json-glib/json-glib-validate.c:150
#, c-format
msgid "%s: missing files"
msgstr "%s: отсутствуют файлы"
#. Translators: this message will appear after the usage string
#. and before the list of options.
-#: ../json-glib/json-glib-validate.c:118
+#: json-glib/json-glib-validate.c:118
msgid "Validate JSON files."
msgstr "Проверка корректности файлов JSON."
-#: ../json-glib/json-glib-validate.c:119
+#: json-glib/json-glib-validate.c:119
msgid "json-glib-validate validates JSON data at the given URI."
msgstr ""
"json-glib-validate проверяет корректность данных JSON по заданному URI."
-#: ../json-glib/json-gobject.c:917
+#. translators: the %s is the name of the data structure
+#: json-glib/json-gobject.c:940
#, c-format
-msgid "Expecting a JSON object, but the root node is of type `%s'"
+msgid "Expecting a JSON object, but the root node is of type “%s”"
msgstr "Ожидается объект JSON, но корневой узел имеет тип «%s»"
-#: ../json-glib/json-gvariant.c:545
+#. translators: the '%s' is the type name
+#: json-glib/json-gvariant.c:524
#, c-format
-msgid "Unexpected type '%s' in JSON node"
+msgid "Unexpected type “%s” in JSON node"
msgstr "Неожиданный тип «%s» в узле JSON"
-#: ../json-glib/json-gvariant.c:615
+#: json-glib/json-gvariant.c:594
msgid "Missing elements in JSON array to conform to a tuple"
msgstr "Отсутствуют элементы в массиве JSON для соответствия кортежу"
-#: ../json-glib/json-gvariant.c:643
-msgid "Missing closing symbol ')' in the GVariant tuple type"
+#: json-glib/json-gvariant.c:622
+msgid "Missing closing symbol “)” in the GVariant tuple type"
msgstr "Отсутствует закрывающий символ «)» в кортеже типа GVariant"
-#: ../json-glib/json-gvariant.c:651
+#: json-glib/json-gvariant.c:630
msgid "Unexpected extra elements in JSON array"
msgstr "Неожиданные дополнительные символы в массиве JSON"
-#: ../json-glib/json-gvariant.c:930
+#: json-glib/json-gvariant.c:931
msgid "Invalid string value converting to GVariant"
msgstr "Некорректное строковое значение для преобразования к GVariant"
-#: ../json-glib/json-gvariant.c:986
+#: json-glib/json-gvariant.c:986
msgid ""
"A GVariant dictionary entry expects a JSON object with exactly one member"
msgstr ""
"Элемент словаря GVariant должен быть объектом JSON с единственным членом"
-#: ../json-glib/json-gvariant.c:1266
+#: json-glib/json-gvariant.c:1264
#, c-format
-msgid "GVariant class '%c' not supported"
+msgid "GVariant class “%c” not supported"
msgstr "Класс GVariant «%c» не поддерживается"
-#: ../json-glib/json-gvariant.c:1314
+#: json-glib/json-gvariant.c:1312
msgid "Invalid GVariant signature"
msgstr "Недопустимая подпись GVariant"
-#: ../json-glib/json-gvariant.c:1362
+#: json-glib/json-gvariant.c:1360
msgid "JSON data is empty"
msgstr "Данные JSON отсутствуют"
-#: ../json-glib/json-parser.c:817
+#. translators: %s: is the file name, the first %d is the line
+#. * number, the second %d is the position on the line, and %s is
+#. * the error message
+#.
+#: json-glib/json-parser.c:909
#, c-format
msgid "%s:%d:%d: Parse error: %s"
msgstr "%s:%d:%d: ошибка разбора: %s"
-#: ../json-glib/json-parser.c:885
+#: json-glib/json-parser.c:992
msgid "JSON data must be UTF-8 encoded"
msgstr "Данные JSON должны быть в кодировке UTF-8"
-#: ../json-glib/json-path.c:438
+#: json-glib/json-path.c:389
msgid "Only one root node is allowed in a JSONPath expression"
msgstr "В выражении JSONPath может быть только один корневой узел"
-#: ../json-glib/json-path.c:447
+#. translators: the %c is the invalid character
+#: json-glib/json-path.c:398
#, c-format
-msgid "Root node followed by invalid character '%c'"
+msgid "Root node followed by invalid character “%c”"
msgstr "Корневой узел заканчивается некорректным символом «%c»"
-#: ../json-glib/json-path.c:487
+#: json-glib/json-path.c:438
msgid "Missing member name or wildcard after . character"
msgstr "Отсутствует имя члена или шаблон после символа «.»"
-#: ../json-glib/json-path.c:561
+#: json-glib/json-path.c:512
#, c-format
-msgid "Malformed slice expression '%*s'"
+msgid "Malformed slice expression “%*s”"
msgstr "Неправильное выражение среза «%*s»"
-#: ../json-glib/json-path.c:605
+#: json-glib/json-path.c:556
#, c-format
-msgid "Invalid set definition '%*s'"
-msgstr "Ð\9dевеÑ\80ное опÑ\80еделение пÑ\80иÑ\81воениÑ\8f «%*s»"
+msgid "Invalid set definition “%*s”"
+msgstr "Ð\9dевеÑ\80ное опÑ\80еделение набоÑ\80а «%*s»"
-#: ../json-glib/json-path.c:658
+#: json-glib/json-path.c:609
#, c-format
-msgid "Invalid slice definition '%*s'"
+msgid "Invalid slice definition “%*s”"
msgstr "Неверное определение среза «%*s»"
-#: ../json-glib/json-path.c:686
+#: json-glib/json-path.c:637
#, c-format
-msgid "Invalid array index definition '%*s'"
+msgid "Invalid array index definition “%*s”"
msgstr "Неверное определение индекса массива «%*s»"
-#: ../json-glib/json-path.c:705
+#: json-glib/json-path.c:656
#, c-format
-msgid "Invalid first character '%c'"
+msgid "Invalid first character “%c”"
msgstr "Неверный первый символ «%c»"
-#: ../json-glib/json-reader.c:463
+#: json-glib/json-reader.c:474
#, c-format
msgid ""
-"The current node is of type '%s', but an array or an object was expected."
+"The current node is of type “%s”, but an array or an object was expected."
msgstr "Текущий узел имеет тип «%s», но ожидается массив или объект."
-#: ../json-glib/json-reader.c:475
+#: json-glib/json-reader.c:486
#, c-format
msgid ""
-"The index '%d' is greater than the size of the array at the current position."
+"The index “%d” is greater than the size of the array at the current position."
msgstr "В текущей позиции индекс «%d» больше размера массива."
-#: ../json-glib/json-reader.c:492
+#: json-glib/json-reader.c:503
#, c-format
msgid ""
-"The index '%d' is greater than the size of the object at the current "
+"The index “%d” is greater than the size of the object at the current "
"position."
-msgstr "Ð\92 Ñ\82екÑ\83Ñ\89ей позиÑ\86ии индекÑ\81 «%d» болÑ\8cÑ\88е Ñ\80азмеÑ\80а обÑ\8aекÑ\82а."
+msgstr "Ð\98ндекÑ\81 «%d» болÑ\8cÑ\88е, Ñ\87ем Ñ\80азмеÑ\80 обÑ\8aекÑ\82а в Ñ\82екÑ\83Ñ\89ей позиÑ\86ии."
-#: ../json-glib/json-reader.c:577 ../json-glib/json-reader.c:731
-#: ../json-glib/json-reader.c:782 ../json-glib/json-reader.c:820
-#: ../json-glib/json-reader.c:858 ../json-glib/json-reader.c:896
-#: ../json-glib/json-reader.c:934 ../json-glib/json-reader.c:979
-#: ../json-glib/json-reader.c:1015 ../json-glib/json-reader.c:1041
+#: json-glib/json-reader.c:585 json-glib/json-reader.c:751
+#: json-glib/json-reader.c:799 json-glib/json-reader.c:837
+#: json-glib/json-reader.c:875 json-glib/json-reader.c:913
+#: json-glib/json-reader.c:951 json-glib/json-reader.c:996
+#: json-glib/json-reader.c:1032 json-glib/json-reader.c:1058
msgid "No node available at the current position"
msgstr "В текущей позиции отсутствует узел"
-#: ../json-glib/json-reader.c:584
+#: json-glib/json-reader.c:592
#, c-format
-msgid "The current position holds a '%s' and not an array"
-msgstr "Ð\92 Ñ\82екÑ\83Ñ\89ей позиÑ\86ии Ñ\81одеÑ\80жиÑ\82Ñ\81Ñ\8f «%s», а не массив"
+msgid "The current position holds a “%s” and not an array"
+msgstr "ТекÑ\83Ñ\89аÑ\8f позиÑ\86иÑ\8f Ñ\81одеÑ\80жиÑ\82 «%s», а не массив"
-#: ../json-glib/json-reader.c:647
+#: json-glib/json-reader.c:668
#, c-format
-msgid "The current node is of type '%s', but an object was expected."
+msgid "The current node is of type “%s”, but an object was expected."
msgstr "Текущий узел имеет тип «%s», но ожидается объект."
-#: ../json-glib/json-reader.c:654
+#: json-glib/json-reader.c:675
#, c-format
-msgid "The member '%s' is not defined in the object at the current position."
+msgid "The member “%s” is not defined in the object at the current position."
msgstr "В текущей позиции член «%s» не определён в объекте."
-#: ../json-glib/json-reader.c:738 ../json-glib/json-reader.c:789
+#: json-glib/json-reader.c:758 json-glib/json-reader.c:806
#, c-format
-msgid "The current position holds a '%s' and not an object"
+msgid "The current position holds a “%s” and not an object"
msgstr "В текущей позиции содержится «%s», а не объект"
-#: ../json-glib/json-reader.c:829 ../json-glib/json-reader.c:867
-#: ../json-glib/json-reader.c:905 ../json-glib/json-reader.c:943
-#: ../json-glib/json-reader.c:988
+#: json-glib/json-reader.c:846 json-glib/json-reader.c:884
+#: json-glib/json-reader.c:922 json-glib/json-reader.c:960
+#: json-glib/json-reader.c:1005
#, c-format
-msgid "The current position holds a '%s' and not a value"
+msgid "The current position holds a “%s” and not a value"
msgstr "В текущей позиции содержится «%s», а не значение"
-#: ../json-glib/json-reader.c:951
+#: json-glib/json-reader.c:968
msgid "The current position does not hold a string type"
msgstr "В текущей позиции не содержится строковое значение"
--- /dev/null
+[wrap-git]
+directory=gi-docgen
+url=https://gitlab.gnome.org/GNOME/gi-docgen.git
+push-url=ssh://git@gitlab.gnome.org:GNOME/gi-docgen.git
+revision=main
+depth=1
directory=glib
url=https://gitlab.gnome.org/GNOME/glib.git
push-url=git@gitlab.gnome.org:GNOME/glib.git
-revision=master
+revision=main
projects / platform / upstream / json-glib.git / commitdiff