Skip to content
Commits on Source (56)
Hide whitespace changes
Inline Side-by-side
CONTRIBUTING.md 0 → 100644
View file @ 4e26666a
# 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.
NEWS
View file @ 4e26666a
......@@ -26,6 +26,10 @@ Overview of changes for 1.6
• 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
==============================
......
README.md
View file @ 4e26666a
......@@ -17,7 +17,7 @@ GLib is a C library providing common and efficient data types for the C
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:
......@@ -34,9 +34,8 @@ In order to build JSON-GLib you will need:
* [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
--------------------------------------------------------------------------------
......@@ -44,50 +43,13 @@ To build JSON-GLib just run:
```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
......@@ -111,9 +73,9 @@ Copyright 2007, 2008 OpenedHand Ltd
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
build-aux/dist-docs.py 0 → 100644
View file @ 4e26666a
#!/usr/bin/env python3
import os
import shutil
import subprocess
from pathlib import PurePath
references = [
'docs/json-glib/json-glib-1.0',
]
sourceroot = os.environ.get('MESON_SOURCE_ROOT')
buildroot = os.environ.get('MESON_BUILD_ROOT')
distroot = os.environ.get('MESON_DIST_ROOT')
for reference in references:
src_path = os.path.join(buildroot, reference)
if os.path.isdir(src_path):
dst_path = os.path.join(distroot, reference)
shutil.copytree(src_path, dst_path)
doc/json-gboxed.md 0 → 100644
View file @ 4e26666a
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`.
doc/json-glib-docs.xml deleted 100644 → 0
View file @ 47651cf3
<?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>
doc/json-glib-overrides.txt deleted 100644 → 0
View file @ 47651cf3
<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>
doc/json-glib-sections.txt deleted 100644 → 0
View file @ 47651cf3
<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>
doc/json-glib.toml.in 0 → 100644
View file @ 4e26666a
[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
doc/json-gobject.md 0 → 100644
View file @ 4e26666a
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.
doc/json-gvariant.md 0 → 100644
View file @ 4e26666a
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)`.
doc/meson.build
View file @ 4e26666a
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)
......
doc/xml/gtkdocentities.ent.in deleted 100644 → 0
View file @ 47651cf3
<!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@">
doc/xml/meson.build deleted 100644 → 0
View file @ 47651cf3
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)
json-glib/json-array.c
View file @ 4e26666a
......@@ -26,20 +26,24 @@
#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);
......@@ -47,9 +51,9 @@ 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)
......@@ -68,9 +72,9 @@ 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)
......@@ -87,12 +91,12 @@ 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)
......@@ -107,10 +111,11 @@ 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
......@@ -135,12 +140,13 @@ json_array_unref (JsonArray *array)
/**
* 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
*/
......@@ -165,13 +171,13 @@ json_array_seal (JsonArray *array)
/**
* 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)
......@@ -184,14 +190,12 @@ 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)
......@@ -211,14 +215,12 @@ 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
*/
......@@ -240,13 +242,12 @@ json_array_dup_element (JsonArray *array,
/**
* 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,
......@@ -260,13 +261,13 @@ 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
*
......@@ -290,13 +291,13 @@ json_array_get_int_element (JsonArray *array,
/**
* 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
*
......@@ -320,15 +321,15 @@ json_array_get_double_element (JsonArray *array,
/**
* 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
*/
......@@ -350,16 +351,15 @@ json_array_get_boolean_element (JsonArray *array,
/**
* 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
*/
......@@ -384,14 +384,15 @@ json_array_get_string_element (JsonArray *array,
/**
* 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
*/
......@@ -421,13 +422,12 @@ json_array_get_null_element (JsonArray *array,
/**
* 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
*
......@@ -454,13 +454,12 @@ json_array_get_array_element (JsonArray *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
*
......@@ -487,9 +486,9 @@ json_array_get_object_element (JsonArray *array,
/**
* 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
*/
......@@ -503,11 +502,10 @@ json_array_get_length (JsonArray *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,
......@@ -521,12 +519,12 @@ 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
*/
......@@ -541,12 +539,12 @@ json_array_add_int_element (JsonArray *array,
/**
* 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
*/
......@@ -561,12 +559,12 @@ json_array_add_double_element (JsonArray *array,
/**
* 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
*/
......@@ -581,12 +579,12 @@ json_array_add_boolean_element (JsonArray *array,
/**
* 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
*/
......@@ -610,11 +608,11 @@ json_array_add_string_element (JsonArray *array,
/**
* 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
*/
......@@ -628,13 +626,14 @@ json_array_add_null_element (JsonArray *array)
/**
* 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
*/
......@@ -661,13 +660,14 @@ json_array_add_array_element (JsonArray *array,
/**
* 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
*/
......@@ -694,11 +694,12 @@ json_array_add_object_element (JsonArray *array,
/**
* 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,
......@@ -712,16 +713,16 @@ 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
*/
......@@ -747,15 +748,16 @@ json_array_foreach_element (JsonArray *array,
/**
* 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
......@@ -785,14 +787,17 @@ json_array_hash (gconstpointer key)
/**
* 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
......
json-glib/json-builder.c
View file @ 4e26666a
......@@ -23,20 +23,44 @@
*/
/**
* 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"
......@@ -190,8 +214,9 @@ json_builder_class_init (JsonBuilderClass *klass)
/**
* 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
......@@ -238,10 +263,11 @@ json_builder_is_valid_add_mode (JsonBuilder *builder)
/**
* 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)
......@@ -252,11 +278,13 @@ 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)
......@@ -266,13 +294,15 @@ 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)
......@@ -294,9 +324,9 @@ 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)
......@@ -308,16 +338,19 @@ 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)
......@@ -363,15 +396,14 @@ 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)
......@@ -403,16 +435,16 @@ 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)
......@@ -457,15 +489,14 @@ 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)
......@@ -497,16 +528,20 @@ 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,
......@@ -528,17 +563,18 @@ 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,
......@@ -578,17 +614,18 @@ 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,
......@@ -623,17 +660,18 @@ 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,
......@@ -669,17 +707,18 @@ 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,
......@@ -715,17 +754,18 @@ 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,
......@@ -761,16 +801,17 @@ 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)
......
json-glib/json-builder.h
View file @ 4e26666a
......@@ -42,14 +42,6 @@ typedef struct _JsonBuilder JsonBuilder;
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 >*/
......@@ -58,13 +50,6 @@ struct _JsonBuilder
JsonBuilderPrivate *priv;
};
/**
* JsonBuilderClass:
*
* The `JsonBuilderClass` structure contains only private data
*
* Since: 0.12
*/
struct _JsonBuilderClass
{
/*< private >*/
......
json-glib/json-enum-types.c.in
View file @ 4e26666a
......@@ -18,7 +18,7 @@
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))
{
......
json-glib/json-gboxed.c
View file @ 4e26666a
......@@ -19,53 +19,6 @@
* 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>
......@@ -137,11 +90,10 @@ lookup_boxed_transform (GSList *transforms,
* 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
*/
......@@ -182,11 +134,10 @@ json_boxed_register_serialize_func (GType gboxed_type,
* 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
*/
......@@ -226,16 +177,16 @@ json_boxed_register_deserialize_func (GType gboxed_type,
/**
* 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
*/
......@@ -263,12 +214,12 @@ json_boxed_can_serialize (GType gboxed_type,
/**
* 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
*/
......@@ -291,13 +242,13 @@ json_boxed_can_deserialize (GType gboxed_type,
/**
* 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
*/
......@@ -321,13 +272,11 @@ json_boxed_serialize (GType gboxed_type,
/**
* 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
*/
......
json-glib/json-generator.c
View file @ 4e26666a
......@@ -22,11 +22,11 @@
*/
/**
* 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"
......@@ -203,11 +203,13 @@ json_generator_class_init (JsonGeneratorClass *klass)
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",
......@@ -217,7 +219,7 @@ json_generator_class_init (JsonGeneratorClass *klass)
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.
*/
......@@ -230,9 +232,9 @@ json_generator_class_init (JsonGeneratorClass *klass)
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
......@@ -245,7 +247,7 @@ json_generator_class_init (JsonGeneratorClass *klass)
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.
*
......@@ -469,11 +471,12 @@ dump_object (JsonGenerator *generator,
/**
* 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)
......@@ -483,14 +486,13 @@ 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
*/
......@@ -512,15 +514,14 @@ json_generator_to_gstring (JsonGenerator *generator,
/**
* 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,
......@@ -541,12 +542,15 @@ 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.
*/
......@@ -571,15 +575,14 @@ json_generator_to_file (JsonGenerator *generator,
/**
* 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
*/
......@@ -607,14 +610,14 @@ json_generator_to_stream (JsonGenerator *generator,
}
/**
* 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
......@@ -639,14 +642,13 @@ json_generator_set_root (JsonGenerator *generator,
}
/**
* 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
*/
......@@ -659,13 +661,15 @@ json_generator_get_root (JsonGenerator *generator)
}
/**
* 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
*/
......@@ -690,13 +694,13 @@ json_generator_set_pretty (JsonGenerator *generator,
}
/**
* 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
*/
......@@ -709,8 +713,8 @@ json_generator_get_pretty (JsonGenerator *generator)
}
/**
* 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
*
......@@ -737,10 +741,10 @@ json_generator_set_indent (JsonGenerator *generator,
}
/**
* 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
*
......@@ -749,17 +753,17 @@ json_generator_set_indent (JsonGenerator *generator,
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
*/
......@@ -782,10 +786,10 @@ json_generator_set_indent_char (JsonGenerator *generator,
}
/**
* 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
*
......