fulgur_chart 0.3.0-aarch64-linux

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 239e98d6a8a35abc6ee3c1de4ffc33f2f93787c5a69c8cd3cdb7672ebc4a0f2c
+  data.tar.gz: fd107d207f45fa6e25c040ed31cdc5a230c7c7fdcb1262a6b0774aa1802b05e6
+SHA512:
+  metadata.gz: 3f5c233d9a5d99d30c16bba26dceb65403538eee37c1decf945344e59e9fc5d11d31e8ca688b8b2dc52b2c23f288550b22154bfc97a3d75f3c6ce07437eb0dd7
+  data.tar.gz: 13d0c4ebf2802c391f370218083244f955c0fc8eb1d637de352514f07a5a0cf6e7f7732bb0d60c693681b3f54acdef4af154bc4c030aaefd367fe5d6b6d47133

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/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,54 @@
+--- !ruby/object:Gem::Specification
+name: fulgur_chart
+version: !ruby/object:Gem::Version
+  version: 0.3.0
+platform: aarch64-linux
+authors:
+- Fulgur
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-06-21 00:00:00.000000000 Z
+dependencies: []
+description: Render chart.js / Vega-Lite specs to deterministic SVG/PNG (Rust core)
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/fulgur_chart.rb
+- lib/fulgur_chart/3.1/fulgur_chart.so
+- lib/fulgur_chart/3.2/fulgur_chart.so
+- lib/fulgur_chart/3.3/fulgur_chart.so
+- lib/fulgur_chart/3.4/fulgur_chart.so
+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.1'
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: 3.5.dev
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.23
+signing_key: 
+specification_version: 4
+summary: Render chart.js / Vega-Lite specs to deterministic SVG/PNG (Rust core)
+test_files: []