From 4c32c3998476e12c34984d52253eaa4ae3bf6769 Mon Sep 17 00:00:00 2001 From: Matthias Andreas Benkard Date: Sun, 12 Dec 2021 21:23:53 +0100 Subject: Javadocs and README. Change-Id: I10d7cb87ca22475f3f73fb25acd813aa1f8d2bb8 --- README.md | 43 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) create mode 100644 README.md (limited to 'README.md') diff --git a/README.md b/README.md new file mode 100644 index 0000000..e482857 --- /dev/null +++ b/README.md @@ -0,0 +1,43 @@ +# GVariant for Java + +This library provides a [GVariant][] parser in pure Java. + + +## Overview + +The two foundational classes are `Value` and `Decoder`. + +`Value` is a sum type (sealed interface) that represents a +[GVariant][] value. Its subtypes represent the different types of +values that [GVariant][] supports. + +Instances of `Decoder` read a given concrete subtype of `Value` from a +[ByteBuffer][]. The class also contains factory methods to create +those instances. + +The various subclasses of `Decoder` together implement the [GVariant +serialization][] specification. + + +## Example + +To parse a [GVariant][] value of type `"a(si)"`, which is an array of +pairs of [String][] and `int`, you can use the following code: + + record ExampleRecord(Value.Str s, Value.Int32 i) {} + + var decoder = + Decoder.ofArray( + Decoder.ofStructure( + ExampleRecord.class, + Decoder.ofStr(StandardCharsets.UTF_8), + Decoder.ofInt32().withByteOrder(ByteOrder.LITTLE_ENDIAN))); + + byte[] bytes = ...; + Value.Array> example = decoder.decode(bytes); + + +[ByteBuffer]: https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/nio/ByteBuffer.html +[GVariant]: https://docs.gtk.org/glib/struct.Variant.html +[GVariant serialization]: https://people.gnome.org/~desrt/gvariant-serialisation.pdf +[String]: https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/lang/String.html -- cgit v1.2.3