Add an experimental opt-in libfyaml backend

.github/workflows/libfyaml.yml

@@ -0,0 +1,60 @@
+name: libfyaml
+
+on:
+  push:
+  pull_request:
+  schedule:
+    - cron: '33 11 * * 0'
+  workflow_dispatch:
+
+# Exercises the experimental, opt-in libfyaml backend (--enable-libfyaml).
+# libfyaml is not supported on Windows, so this workflow runs on Linux and
+# macOS only. The default libyaml backend is covered by test.yml/libyaml.yml.
+jobs:
+  ruby-versions:
+    uses: ruby/actions/.github/workflows/ruby_versions.yml@master
+    with:
+      engine: cruby
+      min_version: 3.0
+
+  build:
+    needs: ruby-versions
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: ${{ fromJson(needs.ruby-versions.outputs.versions) }}
+        os: [ ubuntu-latest, macos-latest ]
+
+    env:
+      LIBFYAML_VERSION: "0.9.6"
+
+    steps:
+      - uses: actions/checkout@v7.0.0
+      - name: Set up Ruby and libfyaml
+        uses: ruby/setup-ruby-pkgs@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          apt-get: "pkg-config"
+          brew: "libfyaml pkg-config"
+      - name: Build libfyaml from source
+        # The libfyaml-dev package on Ubuntu is 0.8, which crashes the emitter,
+        # so build a known-good release. macOS uses the Homebrew build above.
+        if: runner.os == 'Linux'
+        run: |
+          curl -fsSL "https://github.com/pantoniou/libfyaml/releases/download/v${LIBFYAML_VERSION}/libfyaml-${LIBFYAML_VERSION}.tar.gz" | tar xz
+          cd "libfyaml-${LIBFYAML_VERSION}"
+          ./configure --prefix=/usr/local
+          make -j"$(nproc)"
+          sudo make install
+          sudo ldconfig
+      - name: Install dependencies
+        run: bundle install --jobs 3
+      - name: Compile with the libfyaml backend
+        run: rake compile -- --enable-libfyaml
+      - name: Verify the libfyaml backend is active
+        run: |
+          ruby -Ilib -rpsych -e 'abort "expected the libfyaml backend, got #{Psych::BACKEND}" unless Psych::BACKEND == "libfyaml"'
+          ruby -Ilib -rpsych -e 'puts "libfyaml #{Psych.libfyaml_version}"'
+      - name: Run test
+        run: rake test

README.md

@@ -23,6 +23,7 @@ Psych.dump("foo")     # => "--- foo\n...\n"
 ## Dependencies
 
 * libyaml
+* libfyaml (optional, only for the experimental `--enable-libfyaml` backend)
 
 ## Installation
 
@@ -57,6 +58,58 @@ gem 'psych'
 
 JRuby ships with a pure Java implementation of Psych.
 
+## Experimental libfyaml backend
+
+Psych ships an experimental, opt-in backend built on
+[libfyaml](https://github.com/pantoniou/libfyaml), a fully YAML 1.2 compliant
+parser and emitter. It is compiled only when you explicitly pass
+`--enable-libfyaml` at build time. Without the flag the default libyaml
+backend is used and nothing changes.
+
+```bash
+# libfyaml and pkg-config must be installed first, for example:
+#   apt-get install libfyaml-dev   # Debian/Ubuntu
+#   brew install libfyaml          # macOS
+gem install psych -- --enable-libfyaml
+```
+
+This backend is not supported on Windows.
+
+Because libfyaml follows YAML 1.2, the YAML 1.1 booleans `yes`, `no`, `on`, and
+`off` load as plain strings instead of `true`/`false` (only `true`/`false` are
+booleans). This resolves the so-called "Norway problem", where the country
+code `no` was parsed as `false`:
+
+```ruby
+Psych.load("country: no") # => {"country" => "no"}
+```
+
+You can check which backend is active:
+
+```ruby
+Psych::BACKEND         # => "libfyaml" (or "libyaml")
+Psych.libfyaml_version # => "0.9.6"
+```
+
+The backend is experimental. Its output is valid YAML but is formatted
+differently from libyaml in places, and a few emitter edge cases are not yet
+matched. The default libyaml backend remains the supported choice.
+
+Two more differences are worth knowing. Scalars emitted with the default
+(`ANY`) style may be quoted or laid out differently from libyaml, so
+byte-for-byte output is not guaranteed to match. On a parse error,
+`Psych::SyntaxError#problem` carries libfyaml's full diagnostic message and
+`Psych::SyntaxError#context` is always `nil`, whereas libyaml splits the
+description across `#problem` and `#context`.
+
+This backend targets YAML 1.2 compliance, not speed. In a rough
+single-machine benchmark that loads and dumps in-memory documents, parsing
+was roughly on par with libyaml (sometimes faster on string-heavy input),
+while emitting was about 1.7x to 1.9x slower. Your numbers will vary, but the
+shape holds: libfyaml is competitive at parsing and slower at emitting. Use
+this backend when you need YAML 1.2 semantics. If throughput is your priority,
+keep using the default libyaml backend.
+
 ## Release
 
 We used the trusted publisher and [rubygems/release-gem](https://github.com/rubygems/release-gem) workflow.

ext/psych/extconf.rb

@@ -2,6 +2,28 @@
 # frozen_string_literal: true
 require 'mkmf'
 
+# Experimental, opt-in libfyaml backend.  Only used when psych is built with
+# --enable-libfyaml.  Without the flag nothing below changes and the default
+# libyaml backend is built exactly as before.
+if enable_config("libfyaml", false)
+  if $mswin or $mingw or $cygwin
+    abort "The libfyaml backend (--enable-libfyaml) is not supported on Windows"
+  end
+  unless pkg_config('libfyaml')
+    abort "libfyaml was requested with --enable-libfyaml but was not found via pkg-config"
+  end
+  # libfyaml 0.8 and earlier crash psych's emitter, so require a known-good
+  # version rather than building something that segfaults at runtime.
+  pkgconfig = ENV["PKG_CONFIG"] || "pkg-config"
+  unless system(pkgconfig, "--atleast-version=0.9", "libfyaml")
+    abort "The libfyaml backend requires libfyaml 0.9 or newer"
+  end
+  $defs << "-DPSYCH_USE_LIBFYAML"
+
+  create_makefile 'psych'
+  return
+end
+
 if $mswin or $mingw or $cygwin
   $CPPFLAGS << " -DYAML_DECLARE_STATIC"
 end

ext/psych/psych.c

@@ -2,14 +2,25 @@
 
 /* call-seq: Psych.libyaml_version
  *
- * Returns the version of libyaml being used
+ * Returns the version of the underlying YAML library as a three-element
+ * array. This is libyaml by default. On the experimental libfyaml backend,
+ * where libyaml is not linked, it reports the libfyaml version instead.
  */
 static VALUE libyaml_version(VALUE module)
 {
     int major, minor, patch;
     VALUE list[3];
 
+#ifdef PSYCH_USE_LIBFYAML
+    /* Experimental libfyaml backend: there is no libyaml linked in.  Report
+     * the libfyaml version so callers still receive a 3-element version. */
+    const struct fy_version *v = fy_version_default();
+    major = v ? v->major : 0;
+    minor = v ? v->minor : 0;
+    patch = 0;
+#else
     yaml_get_version(&major, &minor, &patch);
+#endif
 
     list[0] = INT2NUM(major);
     list[1] = INT2NUM(minor);
@@ -18,6 +29,20 @@ static VALUE libyaml_version(VALUE module)
     return rb_ary_new4((long)3, list);
 }
 
+#ifdef PSYCH_USE_LIBFYAML
+/* call-seq: Psych.libfyaml_version
+ *
+ * Returns the libfyaml version string. This method is only defined when
+ * psych was built with the experimental libfyaml backend
+ * (+--enable-libfyaml+).
+ */
+static VALUE libfyaml_version(VALUE module)
+{
+    const char *v = fy_library_version();
+    return v ? rb_usascii_str_new2(v) : Qnil;
+}
+#endif
+
 VALUE mPsych;
 
 void Init_psych(void)
@@ -29,6 +54,13 @@ void Init_psych(void)
 
     rb_define_singleton_method(mPsych, "libyaml_version", libyaml_version, 0);
 
+#ifdef PSYCH_USE_LIBFYAML
+    rb_define_singleton_method(mPsych, "libfyaml_version", libfyaml_version, 0);
+    rb_define_const(mPsych, "BACKEND", rb_usascii_str_new2("libfyaml"));
+#else
+    rb_define_const(mPsych, "BACKEND", rb_usascii_str_new2("libyaml"));
+#endif
+
     Init_psych_parser();
     Init_psych_emitter();
     Init_psych_to_ruby();

ext/psych/psych.h

@@ -4,7 +4,11 @@
 #include <ruby.h>
 #include <ruby/encoding.h>
 
+#ifdef PSYCH_USE_LIBFYAML
+#include <libfyaml.h>
+#else
 #include <yaml.h>
+#endif
 
 #include <psych_parser.h>
 #include <psych_emitter.h>

ext/psych/psych_emitter.c

@@ -1,5 +1,7 @@
 #include <psych.h>
 
+#ifndef PSYCH_USE_LIBFYAML
+
 #if !defined(RARRAY_CONST_PTR)
 #define RARRAY_CONST_PTR(s) (const VALUE *)RARRAY_PTR(s)
 #endif
@@ -587,3 +589,5 @@ void Init_psych_emitter(void)
     id_indentation = rb_intern("indentation");
     id_canonical   = rb_intern("canonical");
 }
+
+#endif /* PSYCH_USE_LIBFYAML */