ucl 0.1.3.1 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9a2fae349a8cdd822fbe00b6aa665cbdb04116e0c3dd9d6f7e21cd60d9420b07
-  data.tar.gz: b61d92056c4d69c0be28e3a4515fbb187a5e10a522ae181c38a6c00b51f28d21
+  metadata.gz: 03ae85a910a91ff58975400ecfc0fa2d71a73491c448935e083c909e74a888b7
+  data.tar.gz: '07085efe0e973f192f82fbe5bb0afa4afada1ea7d4f8e97e83f550c615f66322'
 SHA512:
-  metadata.gz: b6bbdf996a6be09f56dc12d1709f35b8e0f13a22ff1f0581af11c526b74b82eca11ac352989bd2414691a86ce4025e0caffcd0f196b200a5dcff650c8fc55d61
-  data.tar.gz: ae3d58daa278a8f97f055ec47dbd2f874d3cd953bda701217d5b09999411a2617bcb340f9c826ca2db742bf4ed3999ebee55b0794485f40c452ff6acda2aa2fd
+  metadata.gz: 544b300d55a2599c199464048da8206a206e688f13dc6b6eebcf7954e5adaac886686e0c5be322ee48531b213de8d888514834cfff2d87949e84885f650399ab
+  data.tar.gz: 7deaa1b5f34932b98b7afcbf71904aa08bd9ad3fd3a87b5f7f29ba5e66be7ec651bb7ddd6e6182e84c4d9baa867e4c7f5f490e0db5bc5e6613d295a8fb0dc239

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Stéphane D'Alu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,181 @@
+ruby-ucl
+========
+
+Ruby bindings to the [libucl][1] library for parsing configuration files
+written in the **U**niversal **C**onfiguration **L**anguage (UCL).
+
+UCL is a configuration format inspired by [nginx][2] and JSON. It is a
+superset of JSON, so any valid JSON document is also valid UCL, while
+adding a more relaxed, human-friendly syntax (unquoted keys, comments,
+optional commas, multipliers, macros, …).
+
+Parsed configurations are returned as plain Ruby objects (`Hash`,
+`Array`, `String`, `Integer`, `Float`, `true`/`false`, `nil`), so no
+special object model has to be learned.
+
+
+Installation
+------------
+
+~~~sh
+gem install ucl
+~~~
+
+Or add it to your `Gemfile`:
+
+~~~ruby
+gem 'ucl'
+~~~
+
+The extension binds to the native [libucl][1] library (version 0.8.2 or
+later). At build time it is located as follows:
+
+1. If a system-wide libucl is found (via `pkg-config`, or under `/opt` or
+   `/usr/local`), it is used.
+2. Otherwise libucl is **downloaded and compiled from source** automatically
+   (using [mini_portile2][4] and CMake). This requires `cmake` and a C
+   compiler to be available.
+
+You can force the source build regardless of any system installation:
+
+~~~sh
+gem install ucl -- --enable-vendor-libucl
+# or, with Bundler:
+bundle config set build.ucl --enable-vendor-libucl
+~~~
+
+> **Debian/Ubuntu note:** do **not** `apt install libucl-dev`. That package
+> is an unrelated [UCL *data-compression* library][3] that merely shares the
+> name — it does not provide `ucl_parser_new`. Since the configuration
+> parser is not packaged for Debian, just install `cmake` and a compiler and
+> let the gem build libucl from source. (The parser *is* packaged on Fedora,
+> Homebrew and FreeBSD ports as `libucl`.)
+
+
+Usage
+-----
+
+~~~ruby
+require 'ucl'
+
+# Parse a string of UCL data
+UCL.parse(File.read('foo.conf'))
+
+# Parse a file directly (enables file-relative variables such as $FILENAME)
+UCL.load_file('foo.conf')
+
+# Pass flags explicitly (combine them with a bitwise OR)
+UCL.load_file('foo.conf', UCL::KEY_SYMBOL | UCL::KEY_LOWERCASE)
+
+# Or set the default flags applied to every subsequent call
+UCL.flags = UCL::KEY_SYMBOL
+UCL.parse('name = value')          #=> { :name => "value" }
+~~~
+
+Both `parse` and `load_file` accept an optional `flags` argument. When it
+is omitted, the value of `UCL.flags` (default: no flag) is used.
+
+On a malformed configuration, or if conversion of the parsed tree fails,
+a `UCL::Error` is raised.
+
+Given a configuration like:
+
+~~~nginx
+# a sample configuration
+name = example
+timeout = 30s            # parsed as a number of seconds
+max_size = 10mb          # size multipliers are understood
+
+servers = [
+    { host = a.example, port = 8080 },
+    { host = b.example, port = 8081 },
+]
+
+logging {
+    level = info
+    enabled = yes
+}
+~~~
+
+`UCL.load_file` returns:
+
+~~~ruby
+{
+  "name"     => "example",
+  "timeout"  => 30.0,
+  "max_size" => 10485760,
+  "servers"  => [ { "host" => "a.example", "port" => 8080 },
+                  { "host" => "b.example", "port" => 8081 } ],
+  "logging"  => { "level" => "info", "enabled" => true },
+}
+~~~
+
+
+Flags
+-----
+
+| Flag             | Effect                                                        |
+|------------------|---------------------------------------------------------------|
+| `KEY_SYMBOL`     | Return object keys as `Symbol` instead of `String`.           |
+| `KEY_LOWERCASE`  | Convert all keys to lower case.                               |
+| `NO_TIME`        | Do not parse time values; keep them as strings.              |
+| `DISABLE_MACRO`  | Disable processing of macros (e.g. `.include`).              |
+| `NO_FILEVARS`    | Do not predefine `$FILENAME` / `$CURDIR` (affects `parse`; `load_file` still sets them from the file). |
+
+
+Type mapping
+------------
+
+| UCL type   | Ruby type                |
+|------------|--------------------------|
+| object     | `Hash`                   |
+| array      | `Array`                  |
+| string     | `String`                 |
+| integer    | `Integer`                |
+| float      | `Float`                  |
+| time       | `Float` (seconds)        |
+| boolean    | `true` / `false`         |
+| null       | `nil`                    |
+
+Notes:
+
+* The parser uses explicit (not implicit) arrays, so a key repeated several
+  times is collected into an `Array` of its values:
+
+  ~~~ruby
+  UCL.parse("a = 1\na = 2")   #=> { "a" => [1, 2] }
+  UCL.parse("a = 1")          #=> { "a" => 1 }
+  ~~~
+
+* Integers understand size multipliers (`1k` → 1000, `1kb` → 1024,
+  `1mb` → 1048576), hexadecimal (`0x1f` → 31) and JSON is accepted as-is.
+
+* Returned strings carry their verbatim bytes but are tagged with the
+  `ASCII-8BIT` (binary) encoding; call `String#force_encoding('UTF-8')` if
+  you need them as UTF-8.
+
+
+Development
+-----------
+
+~~~sh
+bundle install          # install development dependencies
+rake compile            # build the C extension into ext/
+rake test               # compile and run the test suite
+rake clobber            # remove all generated files
+~~~
+
+`rake test` works with the development gems installed system-wide too; with
+a `Gemfile.lock` present, prefix commands with `bundle exec`.
+
+
+License
+-------
+
+Released under the MIT License. See [LICENSE](LICENSE).
+
+
+[1]: https://github.com/vstakhov/libucl
+[2]: https://nginx.org/
+[3]: https://www.oberhumer.com/opensource/ucl/
+[4]: https://github.com/flavorjones/mini_portile

data/ext/extconf.rb

@@ -1,6 +1,69 @@
 require 'mkmf'
 
+# Pinned libucl (vstakhov's Universal Configuration Language parser) used
+# when the library has to be built from source. NOTE: this is *not* the
+# Debian `libucl-dev` package, which is an unrelated compression library.
+LIBUCL_VERSION = '0.9.4'
+LIBUCL_SHA256  = '319d8ff13441f55d91cd7f3708a54bd03779733e26958c2346c5109014520aaf'
 
-have_library('ucl')
+# Force building libucl from source, ignoring any system installation:
+#   gem install ucl -- --enable-vendor-libucl
+#   bundle config set build.ucl --enable-vendor-libucl
+#   UCL_VENDOR_LIBUCL=1 rake compile
+force_vendor = enable_config('vendor-libucl', false) ||
+               ENV.key?('UCL_VENDOR_LIBUCL')
 
-create_makefile("ucl")
+# Locate a system-wide libucl: pkg-config first, then the usual prefixes.
+def system_libucl
+  return true if pkg_config('libucl')
+
+  find_header( 'ucl.h',                 '/opt/include', '/usr/local/include') &&
+    find_library('ucl', 'ucl_parser_new', '/opt/lib',     '/usr/local/lib')
+end
+
+if !force_vendor && system_libucl
+  message "Using system libucl.\n"
+else
+  message "Building libucl #{LIBUCL_VERSION} from source.\n"
+
+  # Building from source needs cmake and a working C compiler.
+  missing = []
+  missing << 'cmake'          unless find_executable('cmake')
+  missing << 'a C compiler'   unless try_compile('int main(void) { return 0; }')
+  unless missing.empty?
+    abort "\nBuilding libucl from source requires #{missing.join(' and ')}, " \
+          "which #{missing.length > 1 ? 'are' : 'is'} not available.\n"      \
+          "Install the missing tool(s), or provide a system-wide libucl.\n"
+  end
+
+  require 'mini_portile2'
+
+  recipe = MiniPortileCMake.new('libucl', LIBUCL_VERSION)
+  recipe.files = [{
+    url:    "https://github.com/vstakhov/libucl/archive/refs/tags/#{LIBUCL_VERSION}.tar.gz",
+    sha256: LIBUCL_SHA256,
+  }]
+  # Static, position-independent build with every optional feature disabled.
+  recipe.configure_options += %w[
+    -DCMAKE_BUILD_TYPE=Release
+    -DBUILD_SHARED_LIBS=OFF
+    -DCMAKE_POSITION_INDEPENDENT_CODE=ON
+    -DENABLE_URL_INCLUDE=OFF
+    -DENABLE_LUA=OFF
+    -DENABLE_UTILS=OFF
+  ]
+  recipe.cook     # download, verify checksum, cmake build + install into recipe.path
+  recipe.activate
+
+  $INCFLAGS << " -I#{recipe.path}/include"
+  $LIBPATH.unshift "#{recipe.path}/lib"
+  have_library('m') # libucl relies on the math library
+
+  unless find_header( 'ucl.h',                 "#{recipe.path}/include") &&
+         find_library('ucl', 'ucl_parser_new', "#{recipe.path}/lib")
+    abort "\nlibucl was built but could not be linked " \
+          "(check the static archive name/dir under #{recipe.path}/lib).\n"
+  end
+end
+
+create_makefile('ucl')

data/ext/ucl.c

@@ -11,13 +11,53 @@
 /**
  * Document-class: UCL
  *
- * UCL configuration file.
+ * Parser for configuration files written in the Universal Configuration
+ * Language (UCL), a JSON-superset format handled by the libucl library.
+ *
+ * Parsed configurations are returned as plain Ruby objects (Hash, Array,
+ * String, Integer, Float, true/false, nil).
+ *
+ * @example Parse a string
+ *   UCL.parse('name = value')        #=> { "name" => "value" }
+ *
+ * @example Load a file with symbol keys
+ *   UCL.load_file('foo.conf', UCL::KEY_SYMBOL)
+ *
+ * @see https://github.com/vstakhov/libucl
  */
 
 /**
  * Document-class: UCL::Error
  *
- * Generic error raised by UCL.
+ * Raised when a configuration cannot be parsed, or when the parsed tree
+ * cannot be converted to Ruby objects.
+ */
+
+/**
+ * Document-const: KEY_LOWERCASE
+ * Flag: convert all object keys to lower case.
+ */
+
+/**
+ * Document-const: NO_TIME
+ * Flag: do not parse time values; keep them as strings.
+ */
+
+/**
+ * Document-const: DISABLE_MACRO
+ * Flag: disable processing of macros (e.g. <code>.include</code>).
+ */
+
+/**
+ * Document-const: NO_FILEVARS
+ * Flag: do not predefine the file variables (<code>$FILENAME</code>,
+ * <code>$CURDIR</code>). This affects {UCL.parse}; {UCL.load_file} still
+ * derives those variables from the file being loaded.
+ */
+
+/**
+ * Document-const: KEY_SYMBOL
+ * Flag: return object keys as Symbol instead of String.
  */
 
 
@@ -32,13 +72,13 @@ static int ucl_allowed_c_flags = UCL_PARSER_KEY_LOWERCASE |
 
 
 
-VALUE
+static VALUE
 _iterate_valid_ucl(ucl_object_t const *root, int flags, bool *failed)
 {
-    ucl_object_iter_t   it  = ucl_object_iterate_new(NULL);
+    ucl_object_iter_t   it  = NULL;   /* only allocated for objects/arrays */
     const ucl_object_t *obj = NULL;
 
-    VALUE val;
+    VALUE val = Qnil;
 
     switch (root->type) {
     case UCL_INT:
@@ -64,10 +104,12 @@ _iterate_valid_ucl(ucl_object_t const *root, int flags, bool *failed)
 	val = rb_float_new(ucl_object_todouble(root));
 	break;
 	
-    case UCL_OBJECT:
+    case UCL_OBJECT: {
+	bool iterated = false;
 	val = rb_hash_new();
-	it  = ucl_object_iterate_reset(it, root);
+	it  = ucl_object_iterate_new(root);
 	while ((obj = ucl_object_iterate_safe(it, !true))) {
+	    iterated = true;
 	    size_t keylen;
 	    const char *key = ucl_object_keyl(obj, &keylen);
 	    VALUE v_key = rb_str_new(key, keylen);
@@ -75,17 +117,25 @@ _iterate_valid_ucl(ucl_object_t const *root, int flags, bool *failed)
 		v_key = rb_to_symbol(v_key);
 	    rb_hash_aset(val, v_key, _iterate_valid_ucl(obj, flags, failed));
 	}
-	*failed = ucl_object_iter_chk_excpn(it);
+	/* An empty object has a NULL hash that the safe iterator reports as an
+	 * exception (EINVAL); ignore that and only flag a genuine error that
+	 * occurs while iterating. Accumulate so a nested failure deeper in the
+	 * tree is never cleared by a successful parent iteration. */
+	if (iterated && ucl_object_iter_chk_excpn(it)) *failed = true;
 	break;
-	
-    case UCL_ARRAY:
+    }
+
+    case UCL_ARRAY: {
+	bool iterated = false;
 	val = rb_ary_new();
-	it = ucl_object_iterate_reset(it, root);
+	it = ucl_object_iterate_new(root);
 	while ((obj = ucl_object_iterate_safe(it, !true))) {
+	    iterated = true;
 	    rb_ary_push(val, _iterate_valid_ucl(obj, flags, failed));
 	}
-	*failed = ucl_object_iter_chk_excpn(it);
+	if (iterated && ucl_object_iter_chk_excpn(it)) *failed = true;
 	break;
+    }
 	
     case UCL_USERDATA:
 	val = rb_str_new(root->value.sv, root->len);
@@ -96,14 +146,20 @@ _iterate_valid_ucl(ucl_object_t const *root, int flags, bool *failed)
 	break;
 	
     default:
-	rb_bug("unhandled type (%d)", root->type);
-	
+	rb_raise(eUCLError, "unhandled UCL type (%d)", root->type);
+
     }
 
-    ucl_object_iterate_free(it);
+    if (it != NULL) ucl_object_iterate_free(it);
     return val;
 }
 
+/**
+ * Default flags applied by {UCL.parse} and {UCL.load_file} when none are
+ * given explicitly.
+ *
+ * @return [Integer] the current default flags (0 by default)
+ */
 static VALUE
 ucl_s_get_flags(VALUE klass)
 {
@@ -111,6 +167,17 @@ ucl_s_get_flags(VALUE klass)
 }
 
 
+/**
+ * Set the default flags applied by {UCL.parse} and {UCL.load_file} when
+ * none are given explicitly.
+ *
+ * @param val [Integer] flags, combined with a bitwise OR
+ *
+ * @example
+ *   UCL.flags = UCL::KEY_SYMBOL | UCL::KEY_LOWERCASE
+ *
+ * @return [Integer] the flags that were set
+ */
 static VALUE
 ucl_s_set_flags(VALUE klass, VALUE val)
 {
@@ -121,12 +188,19 @@ ucl_s_set_flags(VALUE klass, VALUE val)
 
 
 /**
- * Parse a configuration file
+ * Parse a UCL configuration from a string.
+ *
+ * @param data  [String]  the UCL configuration to parse
+ * @param flags [Integer] parsing flags combined with a bitwise OR;
+ *   defaults to {UCL.flags} when omitted
  *
- * @param data [String]
- * @param flags [Integer]
+ * @example
+ *   UCL.parse('name = value')            #=> { "name" => "value" }
+ *   UCL.parse('name = value', UCL::KEY_SYMBOL)  #=> { :name => "value" }
+ *
+ * @raise [UCL::Error] if the configuration is malformed
  *
- * @return configuration file as ruby objects.
+ * @return [Hash, Array, Object] the configuration as Ruby objects
  */
 static VALUE
 ucl_s_parse(int argc, VALUE *argv, VALUE klass)
@@ -142,23 +216,27 @@ ucl_s_parse(int argc, VALUE *argv, VALUE klass)
 
     struct ucl_parser *parser =
 	ucl_parser_new(c_flags | UCL_PARSER_NO_IMPLICIT_ARRAYS);
+    if (parser == NULL)
+	rb_raise(eUCLError, "failed to allocate UCL parser");
 
     ucl_parser_add_chunk(parser,
 			 (unsigned char *)RSTRING_PTR(data),
 			 RSTRING_LEN(data));
-    
+
     if (ucl_parser_get_error(parser)) {
-	const char *errormsg = ucl_parser_get_error(parser);
-	if (parser != NULL) { ucl_parser_free(parser); }
-	rb_raise(eUCLError, "%s", errormsg);
+	/* Copy the message into the exception before freeing the parser:
+	 * ucl_parser_get_error() points into memory owned by the parser. */
+	VALUE err = rb_exc_new2(eUCLError, ucl_parser_get_error(parser));
+	ucl_parser_free(parser);
+	rb_exc_raise(err);
     }
 
     bool          failed = false;
     ucl_object_t *root   = ucl_parser_get_object(parser);
     VALUE         res    = _iterate_valid_ucl(root, FIX2INT(flags), &failed);
 
-    if (parser != NULL) { ucl_parser_free(parser); }
-    if (root   != NULL) { ucl_object_unref(root);  }
+    ucl_parser_free(parser);
+    if (root != NULL) { ucl_object_unref(root); }
 
     if (failed) {
     	rb_raise(eUCLError, "failed to iterate over ucl object");
@@ -169,15 +247,22 @@ ucl_s_parse(int argc, VALUE *argv, VALUE klass)
 
 
 /**
- * Load configuration file
+ * Load and parse a UCL configuration from a file.
  *
- * @param file  [String] 
- * @param flags [Integer]
+ * Unlike {UCL.parse}, this defines the file variables ($FILENAME,
+ * $CURDIR) from the loaded file, so they can be referenced from within
+ * the configuration.
+ *
+ * @param file  [String]  path to the configuration file
+ * @param flags [Integer] parsing flags combined with a bitwise OR;
+ *   defaults to {UCL.flags} when omitted
  *
  * @example
  *   UCL.load_file('foo.conf', UCL::KEY_SYMBOL)
  *
- * @return configuration file as ruby objects.
+ * @raise [UCL::Error] if the file cannot be read or is malformed
+ *
+ * @return [Hash, Array, Object] the configuration as Ruby objects
  */
 static VALUE
 ucl_s_load_file(int argc, VALUE *argv, VALUE klass)
@@ -194,23 +279,27 @@ ucl_s_load_file(int argc, VALUE *argv, VALUE klass)
 
     struct ucl_parser *parser =
 	ucl_parser_new(c_flags | UCL_PARSER_NO_IMPLICIT_ARRAYS);
+    if (parser == NULL)
+	rb_raise(eUCLError, "failed to allocate UCL parser");
 
     ucl_parser_add_file(parser, c_file);
     ucl_parser_set_filevars(parser, c_file, false);
-	
+
     if (ucl_parser_get_error(parser)) {
-	const char *errormsg = ucl_parser_get_error(parser);
-	if (parser != NULL) { ucl_parser_free(parser); }
-	rb_raise(eUCLError, "%s", errormsg);
+	/* Copy the message into the exception before freeing the parser:
+	 * ucl_parser_get_error() points into memory owned by the parser. */
+	VALUE err = rb_exc_new2(eUCLError, ucl_parser_get_error(parser));
+	ucl_parser_free(parser);
+	rb_exc_raise(err);
     }
 
     bool          failed = false;
     ucl_object_t *root   = ucl_parser_get_object(parser);
     VALUE         res    = _iterate_valid_ucl(root, FIX2INT(flags), &failed);
 
-    if (parser != NULL) { ucl_parser_free(parser); }
-    if (root   != NULL) { ucl_object_unref(root);  }
-    
+    ucl_parser_free(parser);
+    if (root != NULL) { ucl_object_unref(root); }
+
     if (failed) {
     	rb_raise(eUCLError, "failed to iterate over ucl object");
     }

data/test/test_ucl.rb

@@ -0,0 +1,323 @@
+require 'minitest/autorun'
+require 'tempfile'
+
+# Load the compiled extension. By default it is looked up in ../ext (where
+# `rake compile` builds it); UCL_EXT_DIR can point elsewhere.
+libdir = ENV['UCL_EXT_DIR'] || File.expand_path('../ext', __dir__)
+$LOAD_PATH.unshift(libdir) unless $LOAD_PATH.include?(libdir)
+require 'ucl'
+
+class TestUCL < Minitest::Test
+  def setup
+    # UCL.flags is global state; keep tests independent.
+    UCL.flags = 0
+  end
+
+  # ---- scalar types -------------------------------------------------------
+
+  def test_integer
+    assert_equal({ 'n' => 42 }, UCL.parse('n = 42'))
+  end
+
+  def test_negative_integer
+    assert_equal({ 'n' => -5 }, UCL.parse('n = -5'))
+  end
+
+  def test_large_integer
+    assert_equal({ 'n' => 9_999_999_999_999 }, UCL.parse('n = 9999999999999'))
+  end
+
+  def test_max_int64
+    assert_equal({ 'n' => 9_223_372_036_854_775_807 },
+                 UCL.parse('n = 9223372036854775807'))
+  end
+
+  def test_hexadecimal_integer
+    assert_equal({ 'h' => 31 }, UCL.parse('h = 0x1f'))
+  end
+
+  def test_float
+    assert_equal({ 'f' => 1.5 }, UCL.parse('f = 1.5'))
+  end
+
+  def test_float_with_exponent
+    assert_equal({ 'f' => 1500.0 }, UCL.parse('f = 1.5e3'))
+  end
+
+  def test_string
+    assert_equal({ 's' => 'hello' }, UCL.parse('s = hello'))
+  end
+
+  def test_quoted_string
+    assert_equal({ 's' => 'hello world' }, UCL.parse('s = "hello world"'))
+  end
+
+  def test_string_keeps_utf8_bytes
+    # Strings are returned with ASCII-8BIT encoding, but the bytes are the
+    # verbatim (UTF-8) content of the configuration.
+    s = UCL.parse('s = "héllo"')['s']
+    assert_equal 'héllo'.b, s.b
+  end
+
+  def test_booleans
+    assert_equal({ 't' => true, 'f' => false }, UCL.parse("t = true\nf = false"))
+  end
+
+  def test_boolean_word_variants
+    assert_equal({ 'a' => true, 'b' => true, 'c' => false, 'd' => false },
+                 UCL.parse("a = yes\nb = on\nc = off\nd = no"))
+  end
+
+  def test_null
+    assert_equal({ 'z' => nil }, UCL.parse('z = null'))
+  end
+
+  # ---- size multipliers ---------------------------------------------------
+
+  def test_si_multiplier
+    assert_equal({ 's' => 1000 }, UCL.parse('s = 1k'))
+  end
+
+  def test_binary_multipliers
+    assert_equal({ 'a' => 1024, 'b' => 1_048_576 },
+                 UCL.parse("a = 1kb\nb = 1mb"))
+  end
+
+  # ---- containers ---------------------------------------------------------
+
+  def test_array
+    assert_equal({ 'a' => [1, 2, 3] }, UCL.parse('a = [1, 2, 3]'))
+  end
+
+  def test_mixed_type_array
+    assert_equal({ 'a' => [1, 'two', true, nil] },
+                 UCL.parse('a = [1, "two", true, null]'))
+  end
+
+  def test_nested_arrays
+    assert_equal({ 'a' => [[1, 2], [3, 4]] }, UCL.parse('a = [[1,2],[3,4]]'))
+  end
+
+  def test_array_of_objects
+    assert_equal({ 'a' => [{ 'x' => 1 }, { 'y' => 2 }] },
+                 UCL.parse('a = [ {x=1}, {y=2} ]'))
+  end
+
+  def test_nested_object
+    assert_equal({ 'o' => { 'x' => 1 } }, UCL.parse('o { x = 1 }'))
+  end
+
+  def test_deeply_nested
+    assert_equal({ 'a' => { 'b' => { 'c' => { 'd' => 1 } } } },
+                 UCL.parse('a { b { c { d = 1 } } }'))
+  end
+
+  def test_dotted_key_is_kept_flat
+    assert_equal({ 'a.b.c' => 1 }, UCL.parse('a.b.c = 1'))
+  end
+
+  # ---- JSON compatibility -------------------------------------------------
+
+  def test_parses_json
+    assert_equal({ 'a' => 1, 'b' => [2, 3] }, UCL.parse('{"a": 1, "b": [2,3]}'))
+  end
+
+  # ---- comments -----------------------------------------------------------
+
+  def test_comments_are_ignored
+    assert_equal({ 'x' => 1, 'y' => 2 },
+                 UCL.parse("# header\nx = 1 # inline\ny = 2"))
+  end
+
+  # ---- duplicate keys become an explicit array ----------------------------
+
+  def test_duplicate_keys_make_array
+    assert_equal({ 'k' => [1, 2, 3] }, UCL.parse("k = 1\nk = 2\nk = 3"))
+  end
+
+  def test_single_key_stays_scalar
+    assert_equal({ 'k' => 1 }, UCL.parse('k = 1'))
+  end
+
+  # ---- empty objects (regression: used to raise) --------------------------
+
+  def test_empty_input_returns_empty_hash
+    assert_equal({}, UCL.parse(''))
+  end
+
+  def test_whitespace_only_returns_empty_hash
+    assert_equal({}, UCL.parse("   \n  "))
+  end
+
+  def test_comment_only_returns_empty_hash
+    assert_equal({}, UCL.parse("# nothing here\n"))
+  end
+
+  def test_empty_object
+    assert_equal({ 'e' => {} }, UCL.parse('e {}'))
+  end
+
+  def test_nested_empty_object
+    assert_equal({ 'a' => { 'b' => {} } }, UCL.parse('a { b {} }'))
+  end
+
+  def test_empty_object_then_more_keys
+    assert_equal({ 'a' => {}, 'b' => 2 }, UCL.parse("a {}\nb = 2"))
+  end
+
+  def test_empty_array
+    assert_equal({ 'a' => [] }, UCL.parse('a = []'))
+  end
+
+  # ---- time ---------------------------------------------------------------
+
+  def test_time_is_parsed_to_float
+    assert_equal({ 't' => 10.0 }, UCL.parse('t = 10s'))
+  end
+
+  def test_no_time_keeps_string
+    assert_equal({ 't' => '10s' }, UCL.parse('t = 10s', UCL::NO_TIME))
+  end
+
+  # ---- key flags ----------------------------------------------------------
+
+  def test_key_symbol
+    assert_equal({ name: 'value' }, UCL.parse('name = value', UCL::KEY_SYMBOL))
+  end
+
+  def test_key_symbol_recurses_into_nested_objects
+    assert_equal({ o: { x: 1 } }, UCL.parse('o { x = 1 }', UCL::KEY_SYMBOL))
+  end
+
+  def test_key_lowercase
+    assert_equal({ 'foo' => 1 }, UCL.parse('FOO = 1', UCL::KEY_LOWERCASE))
+  end
+
+  def test_combined_flags
+    assert_equal({ foo: 1 },
+                 UCL.parse('FOO = 1', UCL::KEY_SYMBOL | UCL::KEY_LOWERCASE))
+  end
+
+  # ---- macros -------------------------------------------------------------
+
+  def test_disable_macro_does_not_process_include
+    # DISABLE_MACRO stops macros from being executed, so the referenced file
+    # is never read. libucl versions differ in how they treat the macro line:
+    # older ones ignore it (parsing only the remaining keys), newer ones reject
+    # it as an invalid key. Both outcomes are acceptable here.
+    config = %(.include "/no/such/file"\nx = 1)
+    begin
+      assert_equal({ 'x' => 1 }, UCL.parse(config, UCL::DISABLE_MACRO))
+    rescue UCL::Error => e
+      refute_empty e.message
+    end
+  end
+
+  def test_include_of_missing_file_raises_without_flag
+    assert_raises(UCL::Error) { UCL.parse(%(.include "/no/such"\nx = 1)) }
+  end
+
+  # ---- file variables -----------------------------------------------------
+
+  def test_no_filevars_leaves_variable_unexpanded
+    assert_equal({ 'd' => '$CURDIR' },
+                 UCL.parse('d = $CURDIR', UCL::NO_FILEVARS))
+  end
+
+  def test_parse_expands_curdir_by_default
+    refute_equal '$CURDIR', UCL.parse('d = $CURDIR')['d']
+  end
+
+  # ---- default flags ------------------------------------------------------
+
+  def test_flags_default_to_zero
+    assert_equal 0, UCL.flags
+  end
+
+  def test_flags_are_used_as_default
+    UCL.flags = UCL::KEY_SYMBOL
+    assert_equal({ name: 'value' }, UCL.parse('name = value'))
+  end
+
+  def test_explicit_flags_override_default
+    UCL.flags = UCL::KEY_SYMBOL
+    assert_equal({ 'name' => 'value' }, UCL.parse('name = value', 0))
+  end
+
+  # ---- result object ------------------------------------------------------
+
+  def test_result_is_mutable
+    result = UCL.parse('a = 1')
+    result['b'] = 2
+    assert_equal({ 'a' => 1, 'b' => 2 }, result)
+  end
+
+  # ---- load_file ----------------------------------------------------------
+
+  def test_load_file
+    with_conf("list = [1, 2, 3]\nname = test\n") do |path|
+      assert_equal({ 'list' => [1, 2, 3], 'name' => 'test' },
+                   UCL.load_file(path))
+    end
+  end
+
+  def test_load_file_sets_filename_variable
+    with_conf('f = "$FILENAME"' + "\n") do |path|
+      assert_equal({ 'f' => File.realpath(path) }, UCL.load_file(path))
+    end
+  end
+
+  def test_load_file_with_flags
+    with_conf("Name = value\n") do |path|
+      assert_equal({ name: 'value' },
+                   UCL.load_file(path, UCL::KEY_SYMBOL | UCL::KEY_LOWERCASE))
+    end
+  end
+
+  def test_load_missing_file_raises
+    assert_raises(UCL::Error) { UCL.load_file('/no/such/file.conf') }
+  end
+
+  # ---- errors -------------------------------------------------------------
+
+  def test_malformed_raises_ucl_error
+    assert_raises(UCL::Error) { UCL.parse('a = [') }
+  end
+
+  def test_error_message_is_present
+    err = assert_raises(UCL::Error) { UCL.parse('a = [') }
+    refute_empty err.message
+  end
+
+  def test_error_is_a_standard_error
+    assert_operator UCL::Error, :<, StandardError
+  end
+
+  def test_repeated_malformed_parses_do_not_crash
+    100.times do
+      assert_raises(UCL::Error) { UCL.parse('} bad {') }
+    end
+  end
+
+  def test_parse_rejects_non_string
+    assert_raises(TypeError) { UCL.parse(42) }
+  end
+
+  # ---- constants ----------------------------------------------------------
+
+  def test_constants_defined
+    %i[KEY_SYMBOL KEY_LOWERCASE NO_TIME DISABLE_MACRO NO_FILEVARS].each do |c|
+      assert UCL.const_defined?(c), "UCL::#{c} should be defined"
+    end
+  end
+
+  private
+
+  def with_conf(content)
+    Tempfile.create(['ucl', '.conf']) do |f|
+      f.write(content)
+      f.flush
+      yield f.path
+    end
+  end
+end

data/ucl.gemspec

@@ -1,12 +1,12 @@
 Gem::Specification.new do |s|
     s.name        = 'ucl'
-    s.version     = '0.1.3.1'
-    s.summary     = " Universal configuration library parser"
+    s.version     = '0.1.4'
+    s.summary     = 'Universal Configuration Language (UCL) parser'
     s.description =  <<~EOF
-      
-      Read configuration file in UCL format (binding to the libucl).
-
-      EOF
+      Parse configuration files written in the Universal Configuration
+      Language (UCL), a human-friendly JSON superset. Native bindings to
+      the libucl library; results are returned as plain Ruby objects.
+    EOF
 
     s.homepage    = 'https://github.com/sdalu/ruby-ucl'
     s.license     = 'MIT'
@@ -15,5 +15,15 @@ Gem::Specification.new do |s|
     s.email       = [ 'sdalu@sdalu.com' ]
 
     s.extensions  = [ 'ext/extconf.rb' ]
-    s.files       = %w[ ucl.gemspec ]  + Dir['ext/**/*.{c,h,rb}']
+    s.files       = %w[ ucl.gemspec README.md LICENSE ] +
+                    Dir['ext/**/*.{c,h,rb}'] +
+                    Dir['test/**/*.rb']
+
+    # Used at build time to download and compile libucl from source when no
+    # system-wide installation is found (requires cmake and a C compiler).
+    s.add_dependency 'mini_portile2', '~> 2.8'
+
+    s.add_development_dependency 'rake'
+    s.add_development_dependency 'minitest', '~> 5.0'
+    s.add_development_dependency 'yard'
 end

metadata

@@ -1,19 +1,74 @@
 --- !ruby/object:Gem::Specification
 name: ucl
 version: !ruby/object:Gem::Version
-  version: 0.1.3.1
+  version: 0.1.4
 platform: ruby
 authors:
 - Stéphane D'Alu
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-02-02 00:00:00.000000000 Z
-dependencies: []
-description: |2+
-
-  Read configuration file in UCL format (binding to the libucl).
-
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: mini_portile2
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: |
+  Parse configuration files written in the Universal Configuration
+  Language (UCL), a human-friendly JSON superset. Native bindings to
+  the libucl library; results are returned as plain Ruby objects.
 email:
 - sdalu@sdalu.com
 executables: []
@@ -21,14 +76,16 @@ extensions:
 - ext/extconf.rb
 extra_rdoc_files: []
 files:
+- LICENSE
+- README.md
 - ext/extconf.rb
 - ext/ucl.c
+- test/test_ucl.rb
 - ucl.gemspec
 homepage: https://github.com/sdalu/ruby-ucl
 licenses:
 - MIT
 metadata: {}
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -43,9 +100,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.26
-signing_key:
+rubygems_version: 4.0.9
 specification_version: 4
-summary: Universal configuration library parser
+summary: Universal Configuration Language (UCL) parser
 test_files: []
-...