add config library

Makefile.am

@@ -4,11 +4,13 @@ SUBDIRS = \
 	vendored/libveb \
 	vendored/libglibc \
 	vendored/libczmq \
+	vendored/libtomlc99 \
 	src/libmissing \
 	src/libutil \
 	src/libhostlist \
 	src/libidset \
 	src/liboptparse \
+	src/libconf \
 	doc
 
 EXTRA_DIST = \

configure.ac

@@ -99,6 +99,7 @@ AC_CONFIG_FILES( \
   vendored/libveb/Makefile \
   vendored/libglibc/Makefile \
   vendored/libczmq/Makefile \
+  vendored/libtomlc99/Makefile \
   src/libmissing/Makefile \
   src/libutil/Makefile \
   src/libhostlist/Makefile \
@@ -107,6 +108,8 @@ AC_CONFIG_FILES( \
   src/libidset/flux-idset.pc \
   src/liboptparse/Makefile \
   src/liboptparse/flux-optparse.pc \
+  src/libconf/Makefile \
+  src/libconf/flux-conf.pc \
   doc/Makefile \
   doc/test/Makefile \
 )

doc/Makefile.am

@@ -12,7 +12,8 @@ MAN3_FILES_PRIMARY = \
 	man3/idset_encode.3 \
 	man3/idset_decode.3 \
 	man3/idset_add.3 \
-	man3/idset_alloc.3
+	man3/idset_alloc.3 \
+	man3/flux_conf_create.3
 
 MAN3_FILES_SECONDARY = \
 	man3/hostlist_destroy.3 \
@@ -59,7 +60,13 @@ MAN3_FILES_SECONDARY = \
 	man3/idset_has_intersection.3 \
 	man3/idset_clear_all.3 \
 	man3/idset_free.3 \
-	man3/idset_free_check.3
+	man3/idset_free_check.3 \
+	man3/flux_conf_incref.3 \
+	man3/flux_conf_decref.3 \
+	man3/flux_conf_copy.3 \
+	man3/flux_conf_unpack.3 \
+	man3/flux_conf_pack.3 \
+	man3/flux_conf_parse.3
 
 RST_FILES  = \
 	$(MAN3_FILES_PRIMARY:.3=.rst)

doc/man3/common/json_pack.rst

@@ -0,0 +1,77 @@
+Flux API functions that are based on Jansson's :func:`json_pack`
+accept the following tokens in their format string.
+The type in parenthesis denotes the resulting JSON type, and
+the type in brackets (if any) denotes the C type that is expected as
+the corresponding argument or arguments.
+
+**s** (string)['const char \*']
+   Convert a null terminated UTF-8 string to a JSON string.
+
+**s?** (string)['const char \*']
+   Like **s**, but if the argument is NULL, outputs a JSON null value.
+
+**s#** (string)['const char \*', 'int']
+   Convert a UTF-8 buffer of a given length to a JSON string.
+
+**s%** (string)['const char \*', 'size_t']
+   Like **s#** but the length argument is of type size_t.
+
+**+** ['const char \*']
+   Like **s**, but concatenate to the previous string.
+   Only valid after a string.
+
+**+#** ['const char \*', 'int']
+   Like **s#**, but concatenate to the previous string.
+   Only valid after a string.
+
+**+%** ['const char \*', 'size_t']
+   Like **+#**, but the length argument is of type size_t.
+
+**n** (null)
+   Output a JSON null value. No argument is consumed.
+
+**b** (boolean)['int']
+   Convert a C int to JSON boolean value. Zero is converted to
+   *false* and non-zero to *true*.
+
+**i** (integer)['int']
+   Convert a C int to JSON integer.
+
+**I** (integer)['int64_t']
+   Convert a C int64_t to JSON integer.
+   Note: Jansson expects a json_int_t here without committing to a size,
+   but Flux guarantees that this is a 64-bit integer.
+
+**f** (real)['double']
+   Convert a C double to JSON real.
+
+**o** (any value)['json_t \*']
+   Output any given JSON value as-is. If the value is added to an array
+   or object, the reference to the value passed to **o** is stolen by the
+   container.
+
+**O** (any value)['json_t \*']
+   Like **o**, but the argument's reference count is incremented. This
+   is useful if you pack into an array or object and want to keep the reference
+   for the JSON value consumed by **O** to yourself.
+
+**o?**, **O?** (any value)['json_t \*']
+   Like **o** and **O**, respectively, but if the argument is NULL,
+   output a JSON null value.
+
+**[fmt]** (array)
+   Build an array with contents from the inner format string. **fmt** may
+   contain objects and arrays, i.e. recursive value building is supported.
+
+**{fmt}** (object)
+   Build an object with contents from the inner format string **fmt**.
+   The first, third, etc. format specifier represent a key, and must be a
+   string as object keys are always strings. The second, fourth, etc.
+   format specifier represent a value. Any value may be an object or array,
+   i.e. recursive value building is supported.
+
+Whitespace, **:** (colon) and **,** (comma) are ignored.
+
+These descriptions came from the Jansson 2.9 manual.
+
+See also: Jansson API: Building Values: http://jansson.readthedocs.io/en/2.9/apiref.html#building-values

doc/man3/common/json_unpack.rst

@@ -0,0 +1,71 @@
+Flux API functions that are based on Jansson's :func:`json_unpack`
+accept the following tokens in their format string.
+The type in parenthesis denotes the resulting JSON type, and
+the type in brackets (if any) denotes the C type that is expected as
+the corresponding argument or arguments.
+
+**s** (string)['const char \*']
+   Convert a JSON string to a pointer to a null terminated UTF-8 string.
+   The resulting string is extracted by using 'json_string_value()'
+   internally, so it exists as long as there are still references to the
+   corresponding JSON string.
+
+**s%** (string)['const char \*', 'size_t']
+   Convert a JSON string to a pointer to a null terminated UTF-8
+   string and its length.
+
+**n** (null)
+   Expect a JSON null value. Nothing is extracted.
+
+**b** (boolean)['int']
+   Convert a JSON boolean value to a C int, so that *true* is converted to 1
+   and *false* to 0.
+
+**i** (integer)['int']
+   Convert a JSON integer to a C int.
+
+**I** (integer)['int64_t']
+   Convert a JSON integer to a C int64_t.
+   Note: Jansson expects a json_int_t here without committing to a size,
+   but Flux guarantees that this is a 64-bit integer.
+
+**f** (real)['double']
+   Convert JSON real to a C double.
+
+**F** (real)['double']
+   Convert JSON number (integer or real) to a C double.
+
+**o** (any value)['json_t \*']
+   Store a JSON value, with no conversion, to a json_t pointer.
+
+**O** (any value)['json_t \*']
+   Like **o**, but the JSON value's reference count is incremented.
+
+**[fmt]** (array)
+   Convert each item in the JSON array according to the inner format
+   string. **fmt** may contain objects and arrays, i.e. recursive value
+   extraction is supported.
+
+**{fmt}** (object)
+   Convert each item in the JSON object according to the inner format
+   string **fmt**. The first, third, etc. format specifier represent a
+   key, and must by **s**. The corresponding argument to unpack functions
+   is read as the object key. The second, fourth, etc. format specifier
+   represent a value and is written to the address given as the corresponding
+   argument. Note that every other argument is read from and every other
+   is written to. **fmt** may contain objects and arrays as values, i.e.
+   recursive value extraction is supported. Any **s** representing a key
+   may be suffixed with **?** to make the key optional. If the key is not
+   found, nothing is extracted.
+
+**!**
+   This special format specifier is used to enable the check that all
+   object and array items are accessed, on a per-value basis. It must
+   appear inside an array or object as the last format specifier before
+   the closing bracket or brace.
+
+Whitespace, **:** (colon) and **,** (comma) are ignored.
+
+These descriptions came from the Jansson 2.9 manual.
+
+See also: Jansson API: Parsing and Validating Values: http://jansson.readthedocs.io/en/2.9/apiref.html#parsing-and-validating-values

doc/man3/flux_conf_create.rst

@@ -0,0 +1,94 @@
+===================
+flux_conf_create(3)
+===================
+
+.. default-domain:: c
+
+SYNOPSIS
+========
+
+.. code-block:: c
+
+  #include <flux/conf.h>
+
+  flux_conf_t *flux_conf_create (void);
+
+  const flux_conf_t *flux_conf_incref (const flux_conf_t *conf);
+
+  void flux_conf_decref (const flux_conf_t *conf);
+
+  flux_conf_t *flux_conf_copy (const flux_conf_t *conf);
+
+  int flux_conf_unpack (const flux_conf_t *conf,
+                        flux_error_t *error,
+                        const char *fmt,
+                        ...);
+
+  flux_conf_t *flux_conf_pack (const char *fmt, ...);
+
+  flux_conf_t *flux_conf_parse (const char *path, flux_error_t *error);
+
+Link with :command:`-lflux-conf`.
+
+DESCRIPTION
+===========
+
+Flux configuration is represented by a :type:`flux_conf_t` object.
+
+:func:`flux_conf_create` creates an empty object with a reference
+count of one.
+
+:func:`flux_conf_incref` increments the object reference count.
+:func:`flux_conf_decref` decrements the object reference count
+and destroys it when the count reaches zero.
+
+:func:`flux_conf_copy` duplicates an object.
+
+:func:`flux_conf_unpack` unpacks an object using Jansson
+:func:`json_unpack` style arguments.
+
+:func:`flux_conf_pack` creates an object using Jansson
+:func:`json_pack` style arguments.
+
+:func:`flux_conf_parse` parse a TOML configuration file at :var:`path`
+and creates a config object that contains the result.
+
+ENCODING JSON PAYLOADS
+======================
+
+.. include:: common/json_pack.rst
+
+DECODING JSON PAYLOADS
+======================
+
+.. include:: common/json_unpack.rst
+
+RETURN VALUE
+============
+
+:func:`flux_conf_create`, :func:`flux_conf_copy`, :func:`flux_conf_pack`,
+and :func:`flux_conf_incref` return a :type:`flux_conf_t` object on success.
+On error, NULL is returned, and :var:`errno` is set.
+
+:func:`flux_conf_unpack` returns 0 on success, or -1 on failure with
+:var:`errno` set.
+
+:func:`flux_conf_parse` returns 0 on success.  On error, it returns -1,
+:var:`errno` set, and if :var:`error` is non-NULL, it is filled with
+a human readable error message.
+
+ERRORS
+======
+
+EINVAL
+   Invalid argument.
+
+ENOMEM
+   Out of memory.
+
+RESOURCES
+=========
+
+.. include:: common/resources.rst
+
+TOML: Tom's Oblivious, Minimal Language https://github.com/toml-lang/toml

doc/manpages.py

@@ -69,4 +69,11 @@
     ('man3/idset_alloc','idset_alloc', 'Allocate an id from an idset', [author], 3),
     ('man3/idset_alloc','idset_free', 'Allocate an id from an idset', [author], 3),
     ('man3/idset_alloc','idset_free_check', 'Allocate an id from an idset', [author], 3),
+    ('man3/flux_conf_create','flux_conf_create', 'create a config object', [author], 3),
+    ('man3/flux_conf_create','flux_conf_incref', 'take reference on config object', [author], 3),
+    ('man3/flux_conf_create','flux_conf_decref', 'drop reference on config object', [author], 3),
+    ('man3/flux_conf_create','flux_conf_copy', 'copy config object', [author], 3),
+    ('man3/flux_conf_create','flux_conf_unpack', 'parse config object', [author], 3),
+    ('man3/flux_conf_create','flux_conf_pack', 'build config object', [author], 3),
+    ('man3/flux_conf_create','flux_conf_parse', 'parse TOML config', [author], 3),
 ]

doc/test/spell.en.pws

@@ -40,3 +40,15 @@ maxid
 NUL
 ssize
 typedef
+conf
+config
+decref
+fmt
+incref
+jansson
+jansson's
+json
+TOML
+github
+UTF
+whitespace

src/libconf/Makefile.am

@@ -0,0 +1,69 @@
+AM_CFLAGS = \
+	$(WARNING_CFLAGS) \
+	$(CODE_COVERAGE_CFLAGS)
+
+AM_LDFLAGS = \
+	$(CODE_COVERAGE_LIBS)
+
+AM_CPPFLAGS = \
+	-I$(top_srcdir) \
+	-I$(top_srcdir)/vendored/libccan \
+	-I$(top_srcdir)/src/include \
+	$(JANSSON_CFLAGS) \
+	$(CODE_COVERAGE_CPPFLAGS)
+
+pkgconfig_DATA = flux-conf.pc
+
+noinst_LTLIBRARIES = \
+	libconf.la
+
+fluxinclude_HEADERS = \
+	conf.h
+
+lib_LTLIBRARIES = \
+	libflux-conf.la
+
+libflux_conf_la_SOURCES =
+libflux_conf_la_LIBADD = \
+	$(builddir)/libconf.la \
+	$(top_builddir)/src/libutil/libutil.la \
+	$(top_builddir)/vendored/libtomlc99/libtomlc99.la \
+	$(JANSSON_LIBS)
+libflux_conf_la_LDFLAGS = \
+	-export-symbols-regex "^(flux_conf_|__asan)" \
+	-version-info 1:0:0 \
+	-shared -export-dynamic --disable-static \
+	$(ld_gc_sections) \
+	$(san_ld_zdef_flag)
+
+libconf_la_SOURCES = \
+	conf.c \
+	conf_private.h \
+	tomltk.h \
+	tomltk.c
+
+TESTS = \
+	test_tomltk.t \
+	test_conf.t
+
+check_PROGRAMS = \
+	$(TESTS)
+
+test_ldadd = \
+	$(top_builddir)/vendored/libtap/libtap.la \
+	$(builddir)/libconf.la \
+	$(top_builddir)/src/libutil/libutil.la \
+	$(top_builddir)/vendored/libtomlc99/libtomlc99.la \
+	$(JANSSON_LIBS)
+
+TEST_EXTENSIONS = .t
+T_LOG_DRIVER = env AM_TAP_AWK='$(AWK)' $(SHELL) \
+       $(top_srcdir)/config/tap-driver.sh
+
+test_tomltk_t_SOURCES = test/tomltk.c
+test_tomltk_t_CPPFLAGS = $(AM_CPPFLAGS)
+test_tomltk_t_LDADD = $(test_ldadd)
+
+test_conf_t_SOURCES = test/conf.c
+test_conf_t_CPPFLAGS = $(AM_CPPFLAGS)
+test_conf_t_LDADD = $(test_ldadd)