fulgur_chart 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1feeff546e3edbf804f27aaf4e51fb50d1da3297286064a58e1775e36110bcfb
+  data.tar.gz: 89ee391afe75cd21d7f60ed05b533e00b280a3eea21e66f99369dc8f9f4a1d69
+SHA512:
+  metadata.gz: bfe60580a7c4781031e81a20a74128b1d0d19fc421899703e61f0f44db9f76a448e9aa64440e4d9b69470d89b6ed599295b432928f1258748e28e1986a5913fa
+  data.tar.gz: 2e2d40dbeaefe0460c6c6703922c4f480b9a0903a395468d05d7c9c71ce41e0884947e1897e86cf40fbde8025b4ecd653d616f87d61ce20cff64e739922901f8

data/README.md

@@ -0,0 +1,112 @@
+# fulgur_chart (Ruby)
+
+Ruby binding for [fulgur-chart](https://github.com/fulgur-rs/fulgur-chart) — render
+chart.js v4 / Vega-Lite JSON specs to deterministic SVG/PNG via a Rust native extension
+([magnus](https://github.com/matsadler/magnus) / [rb-sys](https://github.com/oxidize-rb/rb-sys)).
+
+## Requirements
+
+- Ruby >= 3.0
+- A Rust toolchain (`cargo`) — the gem builds a native extension at install time.
+
+## Build / test from source
+
+```sh
+cd crates/bindings/ruby
+bundle install
+bundle exec rake          # compile the native extension + run the test suite
+```
+
+`bundle exec rake` runs the `compile` task (which builds the Rust extension) followed by
+the minitest suite.
+
+## Usage
+
+The API is a fluent **builder**: `FulgurChart.build(spec)` returns a builder you configure with
+chainable setters and finish with `render(:svg)` / `render(:png)`.
+
+```ruby
+require "fulgur_chart"
+
+spec = <<~JSON
+  {
+    "type": "bar",
+    "data": {
+      "labels": ["a", "b", "c"],
+      "datasets": [{ "data": [1, 3, 2] }]
+    }
+  }
+JSON
+
+# SVG (UTF-8 String)
+svg = FulgurChart.build(spec).render(:svg)
+File.write("chart.svg", svg)
+
+# PNG (binary / ASCII-8BIT String) — write with binwrite to avoid encoding mangling
+png = FulgurChart.build(spec).width(800).height(600).scale(2.0).render(:png)
+File.binwrite("chart.png", png)
+
+# Set a default format with .format, then call render with no argument
+png2 = FulgurChart.build(spec).format(:png).render
+
+# The builder is reusable and reconfigurable between renders
+chart = FulgurChart.build(spec).dsl(:chartjs)
+a = chart.width(400).render(:svg)
+b = chart.width(1234).render(:svg)
+
+# JSON Schema for a DSL (compact JSON String)
+chartjs_schema  = FulgurChart.schema(:chartjs)
+vegalite_schema = FulgurChart.schema("vegalite")
+
+# Library version (String, e.g. "0.1.0")
+FulgurChart.version
+```
+
+The DSL is auto-detected from the spec: a top-level `mark` key selects Vega-Lite, a
+top-level `type` key selects chart.js. Use `.dsl(:chartjs)` / `.dsl(:vegalite)` to override.
+Options accept either a Symbol or a String (`.dsl(:chartjs)` == `.dsl("chartjs")`).
+
+### API
+
+| Method | Returns |
+| --- | --- |
+| `FulgurChart.build(spec_json)` | a `FulgurChart::Builder` |
+| `builder.render(format = nil)` | `String` — `:svg` → UTF-8, `:png` → binary (ASCII-8BIT). Format precedence: argument > `.format()` > default `:svg` |
+| `FulgurChart.render(spec_json, format, **opts)` | low-level primitive the builder calls; same return contract |
+| `FulgurChart.schema(dsl)` | JSON Schema `String` for `:chartjs` or `:vegalite` |
+| `FulgurChart.version` | version `String` |
+
+### Builder setters
+
+Each setter returns the builder for chaining; all are optional.
+
+| Setter | Type | Notes |
+| --- | --- | --- |
+| `.width(w)` / `.height(h)` | Float | Canvas size override (applied before input-limit validation). |
+| `.scale(s)` | Float | Raster scale factor; raster output only (ignored when rendering `:svg`). Default `1.0`. |
+| `.strict` / `.strict(bool)` | Bool | Reject unknown keys (raises `StrictError`). `.strict` ⇒ `true`. Default `false`. |
+| `.dsl(d)` | `:chartjs` \| `:vegalite` (Symbol/String) | Override DSL auto-detection. |
+| `.font(bytes)` | binary `String` | A TTF/OTF font to use instead of the bundled default (Noto Sans JP). |
+| `.format(f)` | `:svg` \| `:png` (Symbol/String) | Default format for a terminal `render` with no argument. |
+
+### Errors
+
+The error hierarchy lives in the native extension under the `FulgurChart` module
+(the module is `FulgurChart`, not `Fulgur`, to avoid a top-level collision with the
+Fulgur PDF library when both gems are loaded in the same process):
+
+- `FulgurChart::ParseError < StandardError` — invalid JSON, undetectable DSL, unknown format,
+  input-limit violations.
+- `FulgurChart::StrictError < FulgurChart::ParseError` — unknown key encountered under `.strict`.
+- `FulgurChart::RenderError < StandardError` — raster rendering failure.
+
+Note the font-error asymmetry: an invalid font raises `FulgurChart::ParseError` when rendering
+`:svg` but `FulgurChart::RenderError` when rendering `:png`, because the two outputs go through
+different render pipelines.
+
+## Note: packaging
+
+The published-gem story — source-installing the path-dependent Rust core and shipping
+cross-platform prebuilt gems — is tracked as a follow-up. Today the gem builds against the
+in-repo core via a Cargo path dependency, so it is intended for use from within this
+repository (build from source as shown above).

data/ext/fulgur_chart/Cargo.toml

@@ -0,0 +1,15 @@
+[package]
+name = "fulgur_chart"
+version = "0.3.0"
+edition = "2021"
+publish = false
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+magnus = "0.7"
+fulgur-chart = "0.3.0"
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+schemars = { version = "1.2", features = ["preserve_order"] }

data/ext/fulgur_chart/extconf.rb

@@ -0,0 +1,4 @@
+require "mkmf"
+require "rb_sys/mkmf"
+
+create_rust_makefile("fulgur_chart/fulgur_chart")

data/ext/fulgur_chart/src/lib.rs

@@ -0,0 +1,255 @@
+use fulgur_chart::guard::{validate_spec, InputLimits};
+use magnus::{
+    function,
+    prelude::*,
+    scan_args::{get_kwargs, scan_args},
+    Error, ExceptionClass, RHash, RString, Ruby, Value,
+};
+
+// --- error helpers (classification is by CALL SITE, never by parsing the message) ---
+
+fn exc_class(ruby: &Ruby, name: &str) -> ExceptionClass {
+    let module = ruby
+        .define_module("FulgurChart")
+        .expect("FulgurChart module defined in init");
+    module
+        .const_get::<_, ExceptionClass>(name)
+        .expect("error class defined in init")
+}
+
+fn parse_err(ruby: &Ruby, msg: impl Into<String>) -> Error {
+    Error::new(exc_class(ruby, "ParseError"), msg.into())
+}
+
+fn strict_err(ruby: &Ruby, msg: impl Into<String>) -> Error {
+    Error::new(exc_class(ruby, "StrictError"), msg.into())
+}
+
+// The image path classifies raster errors as RenderError (asymmetry vs the SVG path,
+// which maps font/render failures to ParseError).
+fn render_err(ruby: &Ruby, msg: impl Into<String>) -> Error {
+    Error::new(exc_class(ruby, "RenderError"), msg.into())
+}
+
+/// Coerce a Ruby argument to a String, accepting both String and Symbol (idiomatic Ruby lets
+/// callers pass `dsl: :chartjs` / `format: :png`). magnus's String conversion rejects Symbols,
+/// so without this `to_s` coercion a symbol would raise TypeError instead of being accepted.
+fn coerce_string(v: Value) -> Result<String, Error> {
+    v.funcall("to_s", ())
+}
+
+// --- DSL detection + parse (mirrors fulgur-chart-cli `detect_dsl` / `parse_spec`) ---
+
+/// Lightweight serde helper that only deserialises the top-level keys used for DSL detection.
+#[derive(serde::Deserialize)]
+struct DslDetector {
+    mark: Option<serde::de::IgnoredAny>,
+    #[serde(rename = "type")]
+    r#type: Option<serde::de::IgnoredAny>,
+}
+
+/// Infer DSL from spec JSON: `mark` key → vegalite, `type` key → chartjs, neither → Err.
+fn detect_dsl(json: &str) -> Result<&'static str, String> {
+    let d: DslDetector = serde_json::from_str(json).map_err(|e| format!("invalid JSON: {e}"))?;
+    if d.mark.is_some() {
+        return Ok("vegalite");
+    }
+    if d.r#type.is_some() {
+        return Ok("chartjs");
+    }
+    Err("cannot auto-detect DSL: specify dsl: 'chartjs' or 'vegalite'".to_string())
+}
+
+/// Parse a spec JSON string to IR using the specified DSL (chartjs or vegalite).
+fn parse_spec(json: &str, dsl: &str, strict: bool) -> Result<fulgur_chart::ir::ChartSpec, String> {
+    match dsl {
+        "vegalite" => fulgur_chart::frontend::vegalite::parse(json, strict),
+        _ => fulgur_chart::frontend::chartjs::parse(json, strict), // "chartjs"
+    }
+}
+
+// --- RenderOptions ---
+
+#[derive(Default)]
+struct Opts {
+    width: Option<f64>,
+    height: Option<f64>,
+    // Consumed by the image path (render_chart_to_png); the SVG path ignores scale.
+    scale: f32,
+    strict: bool,
+    dsl: Option<String>,
+    font: Option<Vec<u8>>,
+}
+
+/// Parse optional RenderOptions from the kwargs hash. Tolerates extra keys (e.g. `format:`
+/// passed by render_image in Task 3) via the trailing `RHash` splat, so unknown keys do not
+/// raise here.
+fn parse_opts(ruby: &Ruby, kw: RHash) -> Result<Opts, Error> {
+    let args = get_kwargs::<
+        _,
+        (),
+        (
+            Option<f64>,
+            Option<f64>,
+            Option<f64>,
+            Option<bool>,
+            Option<Value>,
+            Option<RString>,
+        ),
+        RHash, // splat: collect + ignore unknown keys
+    >(
+        kw,
+        &[],
+        &["width", "height", "scale", "strict", "dsl", "font"],
+    )?;
+    let (width, height, scale, strict, dsl_val, font) = args.optional;
+
+    // Accept String or Symbol for `dsl`; an explicit nil arrives as None (→ auto-detect).
+    let dsl = match dsl_val {
+        Some(v) => {
+            let d = coerce_string(v)?;
+            if d != "chartjs" && d != "vegalite" {
+                return Err(parse_err(ruby, format!("unsupported DSL '{d}'")));
+            }
+            Some(d)
+        }
+        None => None,
+    };
+
+    // Copy the font bytes out of the Ruby string immediately; the borrow is unsafe and must
+    // not outlive any subsequent VM allocation.
+    let font = font.map(|s| unsafe { s.as_slice().to_vec() });
+
+    Ok(Opts {
+        width,
+        height,
+        scale: scale.map(|s| s as f32).unwrap_or(1.0),
+        strict: strict.unwrap_or(false),
+        dsl,
+        font,
+    })
+}
+
+/// Build and validate the IR, mirroring the processing order of `render_one`.
+/// Reusable by render_svg / render_image (Task 3) / schema-less paths.
+fn build_ir(
+    ruby: &Ruby,
+    spec_json: &str,
+    opts: &Opts,
+) -> Result<fulgur_chart::ir::ChartSpec, Error> {
+    // 1. Resolve DSL: explicit opts.dsl OR auto-detect.
+    let dsl: &str = match &opts.dsl {
+        Some(d) => d.as_str(),
+        None => detect_dsl(spec_json).map_err(|e| parse_err(ruby, e))?,
+    };
+
+    // 2. Parse NON-strict → IR (render from this).
+    // Contract §3: propagate the core's error String verbatim. The exception class — not a
+    // message prefix — conveys parse/strict/render, so no CLI-style "error: ..." decoration.
+    let mut ir = parse_spec(spec_json, dsl, false).map_err(|e| parse_err(ruby, e))?;
+
+    // 3. If strict, re-parse with strict=true (discard IR; unknown key → StrictError).
+    if opts.strict {
+        parse_spec(spec_json, dsl, true).map_err(|e| strict_err(ruby, e))?;
+    }
+
+    // 4. Apply width/height overrides BEFORE guard.
+    if let Some(w) = opts.width {
+        ir.width = w;
+    }
+    if let Some(h) = opts.height {
+        ir.height = h;
+    }
+
+    // 5. Guard (failure → ParseError).
+    validate_spec(&ir, &InputLimits::default()).map_err(|e| parse_err(ruby, e))?;
+
+    Ok(ir)
+}
+
+// --- public API: render (low-level primitive; the FulgurChart::Builder is the intended API) ---
+
+/// `FulgurChart.render(spec_json, format, **opts)` → String.
+///
+/// `format` is "svg" (→ UTF-8 String) or "png" (→ binary/ASCII-8BIT String), as a String or
+/// Symbol. Unknown format → ParseError. `opts` are the RenderOptions kwargs
+/// (width/height/scale/strict/dsl/font). Driven by `FulgurChart::Builder#render`, but also
+/// callable directly: `FulgurChart.render(spec, :png, width: 800)`.
+fn render(ruby: &Ruby, args: &[Value]) -> Result<RString, Error> {
+    let scanned = scan_args::<(String, Value), (), (), (), RHash, ()>(args)?;
+    let (spec_json, format_val) = scanned.required;
+    let format = coerce_string(format_val)?; // accept String or Symbol
+    let opts = parse_opts(ruby, scanned.keywords)?;
+    let ir = build_ir(ruby, &spec_json, &opts)?;
+
+    match format.as_str() {
+        "svg" => {
+            // Font present → render_chart_with_font (Err → ParseError on the SVG path);
+            // else the bundled-font render.
+            let svg = match &opts.font {
+                Some(bytes) => fulgur_chart::render::render_chart_with_font(&ir, bytes)
+                    .map_err(|e| parse_err(ruby, e))?,
+                None => fulgur_chart::render::render_chart(&ir),
+            };
+            Ok(ruby.str_new(&svg)) // UTF-8 String
+        }
+        "png" => {
+            let fb: &[u8] = opts
+                .font
+                .as_deref()
+                .unwrap_or(fulgur_chart::font::DEFAULT_FONT);
+            // Invalid font on the image path → RenderError (the SVG path maps this to ParseError).
+            let png = fulgur_chart::raster_direct::render_chart_to_png(&ir, opts.scale, fb)
+                .map_err(|e| render_err(ruby, e))?;
+            Ok(ruby.str_from_slice(&png)) // ASCII-8BIT (BINARY) String
+        }
+        other => Err(parse_err(
+            ruby,
+            format!("unsupported format '{other}' (supported: svg, png)"),
+        )),
+    }
+}
+
+// --- public API: schema ---
+
+/// Return the JSON Schema (compact JSON String) for the given DSL (String or Symbol).
+/// Mirrors the CLI's `run_schema`; unknown DSL → ParseError (consistent with `parse_opts`).
+fn schema(ruby: &Ruby, dsl: Value) -> Result<String, Error> {
+    let dsl = coerce_string(dsl)?;
+    let s = match dsl.as_str() {
+        "chartjs" => schemars::schema_for!(fulgur_chart::schema::ChartJsSpec),
+        "vegalite" => schemars::schema_for!(fulgur_chart::schema::VegaLiteSpec),
+        other => {
+            return Err(parse_err(
+                ruby,
+                format!("unsupported DSL '{other}' (supported: chartjs, vegalite)"),
+            ))
+        }
+    };
+    serde_json::to_string(&s).map_err(|e| render_err(ruby, format!("schema serialization: {e}")))
+}
+
+fn version() -> String {
+    fulgur_chart::version().to_string()
+}
+
+#[magnus::init]
+fn init(ruby: &Ruby) -> Result<(), Error> {
+    // Module name is `FulgurChart` (NOT `Fulgur`): a top-level `Fulgur` would collide with the
+    // Fulgur PDF library if both gems are loaded in the same process.
+    let module = ruby.define_module("FulgurChart")?;
+
+    // Canonical error hierarchy (single source of truth). lib/fulgur_chart.rb does not redefine
+    // these or alias anything.
+    let std_err = ruby.exception_standard_error();
+    let parse = module.define_error("ParseError", std_err)?;
+    module.define_error("StrictError", parse)?;
+    module.define_error("RenderError", std_err)?;
+
+    module.define_module_function("version", function!(version, 0))?;
+    module.define_module_function("schema", function!(schema, 1))?;
+    // Low-level render primitive; the FulgurChart::Builder (FulgurChart.build(...)) is the
+    // intended API and calls this under the hood.
+    module.define_module_function("render", function!(render, -1))?;
+    Ok(())
+}

data/lib/fulgur_chart.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+# Native extension. Defines the FulgurChart module with:
+#   - FulgurChart.schema(dsl), FulgurChart.version
+#   - FulgurChart.render(spec_json, format, **opts)  (low-level render primitive; the builder
+#     below is the intended API, but render is also callable directly)
+#   - errors:  FulgurChart::ParseError / StrictError / RenderError
+# Module name is `FulgurChart` (NOT `Fulgur`) to avoid a top-level collision with the
+# Fulgur (PDF) library when both gems are loaded in the same process.
+require_relative "fulgur_chart/fulgur_chart"
+
+module FulgurChart
+  # Entry point for the builder API:
+  #
+  #   FulgurChart.build(spec_json).width(800).dsl(:chartjs).render(:svg)  # => String
+  #   FulgurChart.build(spec_json).format(:png).render                    # => binary String
+  #
+  # `spec_json` is a chart.js v4 / Vega-Lite DSL JSON string. The behavior (DSL auto-detect,
+  # options, error classes, determinism) follows docs/binding-api-contract.md.
+  def self.build(spec_json)
+    Builder.new(spec_json)
+  end
+
+  # Fluent, reusable builder. Setters mutate and return self; `render` may be called multiple
+  # times and the builder may be reconfigured between calls.
+  class Builder
+    def initialize(spec_json)
+      @spec = spec_json
+      @opts = {}
+    end
+
+    # Override the chart width / height (px). Applied before input-limit validation.
+    def width(value)
+      set(:width, value)
+    end
+
+    def height(value)
+      set(:height, value)
+    end
+
+    # Raster scale factor (ignored when rendering SVG).
+    def scale(value)
+      set(:scale, value)
+    end
+
+    # Force the input DSL ("chartjs"/"vegalite" or the matching Symbol). Omit to auto-detect.
+    def dsl(value)
+      set(:dsl, value)
+    end
+
+    # TrueType/OpenType font bytes (binary String). Omit to use the bundled Noto Sans JP.
+    def font(bytes)
+      set(:font, bytes)
+    end
+
+    # Reject unknown keys. `strict` => true; `strict(false)` => false.
+    def strict(value = true)
+      set(:strict, value)
+    end
+
+    # Default output format for a terminal `render` with no argument (Symbol/String).
+    def format(value)
+      set(:format, value)
+    end
+
+    # Render to the given format ("svg"/"png" or the matching Symbol). Format precedence:
+    # explicit argument > `.format()` setter > default :svg. Returns a UTF-8 String for svg
+    # and a binary (ASCII-8BIT) String for png.
+    def render(fmt = nil)
+      # Distinguish "no explicit format" (nil) from a falsy-but-explicit one (e.g. false).
+      # An explicit argument always wins per the documented precedence; an invalid value is
+      # forwarded to the native layer to raise ParseError rather than silently falling back.
+      resolved =
+        if fmt.nil?
+          @opts.key?(:format) ? @opts[:format] : :svg
+        else
+          fmt
+        end
+      FulgurChart.render(@spec, resolved, **@opts.reject { |key, _| key == :format })
+    end
+
+    private
+
+    def set(key, value)
+      @opts[key] = value
+      self
+    end
+  end
+end

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification
+name: fulgur_chart
+version: !ruby/object:Gem::Version
+  version: 0.3.0
+platform: ruby
+authors:
+- Fulgur
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-06-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rb_sys
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: Render chart.js / Vega-Lite specs to deterministic SVG/PNG (Rust core)
+email:
+executables: []
+extensions:
+- ext/fulgur_chart/extconf.rb
+extra_rdoc_files: []
+files:
+- README.md
+- ext/fulgur_chart/Cargo.toml
+- ext/fulgur_chart/extconf.rb
+- ext/fulgur_chart/src/lib.rs
+- lib/fulgur_chart.rb
+homepage: https://github.com/fulgur-rs/fulgur-chart
+licenses:
+- MIT OR Apache-2.0
+metadata:
+  homepage_uri: https://github.com/fulgur-rs/fulgur-chart
+  source_code_uri: https://github.com/fulgur-rs/fulgur-chart
+  changelog_uri: https://github.com/fulgur-rs/fulgur-chart/blob/main/crates/fulgur-chart/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Render chart.js / Vega-Lite specs to deterministic SVG/PNG (Rust core)
+test_files: []