carve-lang 0.1.0

data/ext/carve/src/lib.rs

@@ -0,0 +1,288 @@
+//! Native Ruby binding for the Carve markup language.
+//!
+//! Wraps the `carve` crate (carve-rs) with magnus, exposing a `Carve` Ruby
+//! module:
+//!
+//! * `Carve.to_html(source)` -> HTML String
+//! * `Carve.to_html_with_extensions(source, extensions)` -> HTML String,
+//!   where `extensions` is an Array of extension name Strings/Symbols.
+//! * `Carve.to_html_full(source, extensions, mode, renderers)` -> HTML String,
+//!   the static-render-mode primitive: `mode` is `"interactive"` (default) or
+//!   `"static"`; `renderers` is a Hash of build-time renderer callables.
+//!
+//! The pure-Ruby wrapper in `lib/carve.rb` adds the keyword-argument form
+//! `Carve.to_html(source, extensions: [...], mode: ..., renderers: {...})` on
+//! top of these primitives.
+
+mod ast_json;
+
+use ast_json::document_to_json;
+use carve_rs::{
+    Autolink, CarveExtension, Citations, CodeCallouts, Details, ExternalLinks, FencedRender,
+    HeadingPermalinks, ListTable, MathBlock, Mode, Options, Spoiler, StaticRenderers, TabNormalize,
+    TableOfContents,
+    Wikilinks,
+};
+use magnus::value::{InnerValue, Opaque};
+use magnus::{function, prelude::*, Error, RArray, RHash, Ruby, Value};
+
+/// HTML-escape a string for the renderer-failure fallback path.
+///
+/// carve-rs emits a *present* static renderer's return value verbatim (it is
+/// the renderer's job to produce safe HTML). So when our Ruby wrapper has to
+/// fall back to the construct source - because the callable raised or returned
+/// a non-string - that source MUST be escaped here, or a source containing HTML
+/// (e.g. `<img onerror=...>`) would be emitted raw. The no-renderer path inside
+/// carve-rs already escapes its `<pre><code>` source block; this keeps the
+/// failing-renderer floor equally safe rather than a raw-passthrough hole.
+fn escape_html(s: &str) -> String {
+    let mut out = String::with_capacity(s.len());
+    for ch in s.chars() {
+        match ch {
+            '&' => out.push_str("&amp;"),
+            '<' => out.push_str("&lt;"),
+            '>' => out.push_str("&gt;"),
+            '"' => out.push_str("&quot;"),
+            '\'' => out.push_str("&#39;"),
+            _ => out.push(ch),
+        }
+    }
+    out
+}
+
+/// Build an owned, boxed extension instance from a Ruby-facing name.
+///
+/// Accepts both snake_case (`math_block`) and hyphenated (`math-block`) forms
+/// so symbols and strings map cleanly. Returns `None` for an unknown name; the
+/// caller turns that into a Ruby `ArgumentError`.
+fn extension_for(name: &str) -> Option<Box<dyn CarveExtension>> {
+    // Normalize: lowercase, hyphens -> underscores, strip surrounding space.
+    let key = name.trim().to_ascii_lowercase().replace('-', "_");
+    let ext: Box<dyn CarveExtension> = match key.as_str() {
+        "autolink" => Box::new(Autolink::new()),
+        "details" => Box::new(Details::new()),
+        "list_table" | "listtable" => Box::new(ListTable::new()),
+        "math_block" | "mathblock" | "math" => Box::new(MathBlock::new()),
+        "heading_permalinks" | "permalinks" => Box::new(HeadingPermalinks::new()),
+        "citations" => Box::new(Citations::new()),
+        "code_callouts" | "codecallouts" => Box::new(CodeCallouts::new()),
+        "tab_normalize" | "tabnormalize" => Box::new(TabNormalize::new()),
+        "wikilinks" => Box::new(Wikilinks::new()),
+        "external_links" | "externallinks" => Box::new(ExternalLinks::new()),
+        // The mermaid preset carries the static-renderer key, so a static
+        // render can consult `renderers: {'mermaid' => ...}`. (Plain
+        // `FencedRender::new("text")`/`new("mermaid")` would degrade to source
+        // even with a renderer supplied, since it has no static-renderer key.)
+        // `fenced_render` now maps to the mermaid preset (was the no-key
+        // `text` claim before static mode) to match the carve-py sibling and
+        // expose a renderer-capable default; `mermaid` is an explicit alias.
+        "fenced_render" | "fencedrender" | "mermaid" => Box::new(FencedRender::mermaid()),
+        // Graphviz/DOT preset; its static path consults
+        // `renderers: {'graphviz' => ...}`, else degrades to the DOT source.
+        "fenced_render_graphviz" | "graphviz" | "dot" => Box::new(FencedRender::graphviz()),
+        // Chart.js preset (JSON mode); its static path consults
+        // `renderers: {'chart' => ...}`, else degrades to the JSON source.
+        "fenced_render_chart" | "chart" => Box::new(FencedRender::chart()),
+        "spoiler" => Box::new(Spoiler::new()),
+        "table_of_contents" | "tableofcontents" | "toc" => Box::new(TableOfContents::new()),
+        _ => return None,
+    };
+    Some(ext)
+}
+
+/// Map a Ruby-facing mode string to a carve-rs [`Mode`].
+///
+/// Rejects any unknown string with `ArgumentError`, mirroring the spec's
+/// "MUST reject an unknown mode value" (no guessing) and the unknown-extension
+/// error style. Omitting the mode in Ruby defaults to `"interactive"`, so
+/// existing callers are unaffected.
+fn parse_mode(ruby: &Ruby, mode: &str) -> Result<Mode, Error> {
+    match mode {
+        "interactive" => Ok(Mode::Interactive),
+        "static" => Ok(Mode::Static),
+        other => Err(Error::new(
+            ruby.exception_arg_error(),
+            format!(
+                "Unknown Carve render mode: {other:?} (supported: \"interactive\", \"static\")"
+            ),
+        )),
+    }
+}
+
+/// Invoke a stored Ruby callable's `call` method with `args`, returning its
+/// String result or the HTML-escaped `fallback` on any failure.
+///
+/// "Any failure" = the callable raised, OR returned a value that is not a
+/// String. Both degrade to the escaped fallback so a bad renderer never
+/// produces blank output and can never inject raw HTML. The render runs
+/// synchronously on the Ruby thread, so `Ruby::get()` succeeds here.
+fn call_renderer<A>(callable: &Opaque<Value>, args: A, fallback: &str) -> String
+where
+    A: magnus::ArgList,
+{
+    let Ok(ruby) = Ruby::get() else {
+        // Not on a Ruby thread - cannot call back; degrade safely.
+        return escape_html(fallback);
+    };
+    let value: Value = callable.get_inner_with(&ruby);
+    match value.funcall::<_, _, String>("call", args) {
+        Ok(s) => s,
+        // Callable raised, or returned a non-String: escaped-source fallback.
+        Err(_) => escape_html(fallback),
+    }
+}
+
+/// Wrap a Ruby diagram callable `(String) -> String` into a carve-rs closure.
+///
+/// On a raising / non-string-returning callable it degrades to the
+/// HTML-escaped source (see [`call_renderer`]).
+fn wrap_diagram(callable: Opaque<Value>) -> Box<dyn Fn(&str) -> String + 'static> {
+    Box::new(move |src: &str| call_renderer(&callable, (src,), src))
+}
+
+/// Wrap a Ruby math callable `(String, bool) -> String` into a carve-rs
+/// closure.
+///
+/// Same contract as [`wrap_diagram`] (including the HTML-escaped fallback), but
+/// the callable receives the TeX source and a `display` flag (`true` for block
+/// / display math, `false` for inline).
+fn wrap_math(callable: Opaque<Value>) -> Box<dyn Fn(&str, bool) -> String + 'static> {
+    Box::new(move |tex: &str, display: bool| call_renderer(&callable, (tex, display), tex))
+}
+
+/// Build a [`StaticRenderers`] from a Ruby Hash of callables.
+///
+/// Recognized keys (String or Symbol): `"mermaid"` / `"chart"` / `"graphviz"`
+/// (callables `(String) -> String`) and `"math"` (callable
+/// `(String, bool) -> String`). Unknown keys raise `ArgumentError`. A missing
+/// key leaves that renderer absent, so the matching static path degrades to
+/// source.
+fn build_renderers(ruby: &Ruby, hash: RHash) -> Result<StaticRenderers, Error> {
+    let mut out = StaticRenderers::default();
+    // Collect (key, value) pairs; RHash::each is not exposed, so use foreach.
+    let mut pairs: Vec<(String, Value)> = Vec::new();
+    hash.foreach(|key: Value, value: Value| {
+        // Accept both String and Symbol keys via to_string-style coercion.
+        let name: String = key.to_r_string()?.to_string()?;
+        pairs.push((name, value));
+        Ok(magnus::r_hash::ForEach::Continue)
+    })?;
+
+    for (name, value) in pairs {
+        let callable: Opaque<Value> = Opaque::from(value);
+        match name.trim().to_ascii_lowercase().as_str() {
+            "mermaid" => out.mermaid = Some(wrap_diagram(callable)),
+            "chart" => out.chart = Some(wrap_diagram(callable)),
+            "graphviz" => out.graphviz = Some(wrap_diagram(callable)),
+            "math" => out.math = Some(wrap_math(callable)),
+            other => {
+                return Err(Error::new(
+                    ruby.exception_arg_error(),
+                    format!(
+                        "Unknown Carve renderer key: {other:?} (supported: \"mermaid\", \"chart\", \"graphviz\", \"math\")"
+                    ),
+                ));
+            }
+        }
+    }
+    Ok(out)
+}
+
+/// Render Carve source to HTML with no extensions enabled.
+fn to_html(source: String) -> String {
+    carve_rs::to_html(&source)
+}
+
+/// Parse Carve source and return its AST as a JSON string.
+///
+/// The pure-Ruby wrapper (`Carve.parse`) turns this into a tree of Ruby
+/// Hashes/Arrays. Parsing uses the default profile (no extensions); the AST is
+/// the raw parse tree, so render-stage extension rewrites are not applied.
+fn to_ast_json(source: String) -> String {
+    document_to_json(&carve_rs::parse(&source))
+}
+
+/// Render Carve source to HTML with the named extensions enabled.
+///
+/// `names` is a Ruby Array of Strings/Symbols. An unrecognized name raises a
+/// Ruby `ArgumentError`. Always interactive mode, no renderers.
+fn to_html_with_extensions(ruby: &Ruby, source: String, names: RArray) -> Result<String, Error> {
+    let boxed = boxed_extensions(ruby, names)?;
+    let mut options = Options::new();
+    for ext in &boxed {
+        options = options.with_extension(ext.as_ref());
+    }
+    Ok(carve_rs::to_html_with_options(&source, &options))
+}
+
+/// Collect owned, boxed extension instances from a Ruby Array of names.
+///
+/// carve_rs::Options holds `&dyn CarveExtension` with a lifetime tied to the
+/// caller's scope, so the boxes must outlive the Options + render call; the
+/// caller keeps the returned Vec alive across both.
+fn boxed_extensions(ruby: &Ruby, names: RArray) -> Result<Vec<Box<dyn CarveExtension>>, Error> {
+    let mut boxed: Vec<Box<dyn CarveExtension>> = Vec::with_capacity(names.len());
+    for item in names.into_iter() {
+        let name: String = item.to_r_string()?.to_string()?;
+        match extension_for(&name) {
+            Some(ext) => boxed.push(ext),
+            None => {
+                return Err(Error::new(
+                    ruby.exception_arg_error(),
+                    format!("Unknown Carve extension: {name:?}"),
+                ));
+            }
+        }
+    }
+    Ok(boxed)
+}
+
+/// Full static-render-mode primitive: extensions + mode + renderers.
+///
+/// * `names` - Ruby Array of extension name Strings/Symbols (may be empty).
+/// * `mode` - `"interactive"` (default) or `"static"`; unknown raises
+///   `ArgumentError`.
+/// * `renderers` - Ruby Hash of build-time renderer callables (keys
+///   `mermaid` / `chart` / `graphviz` -> `(String) -> String`, `math` ->
+///   `(String, bool) -> String`), consulted only on the static HTML path.
+fn to_html_full(
+    ruby: &Ruby,
+    source: String,
+    names: RArray,
+    mode: String,
+    renderers: RHash,
+) -> Result<String, Error> {
+    let parsed_mode = parse_mode(ruby, &mode)?;
+    let static_renderers = build_renderers(ruby, renderers)?;
+    let boxed = boxed_extensions(ruby, names)?;
+
+    let mut options = Options::new()
+        .with_mode(parsed_mode)
+        .with_renderers(static_renderers);
+    for ext in &boxed {
+        options = options.with_extension(ext.as_ref());
+    }
+    Ok(carve_rs::to_html_with_options(&source, &options))
+}
+
+/// Entry point invoked by Ruby when the extension is loaded.
+///
+/// `name = "carve"` makes the macro emit the `Init_carve` symbol that matches
+/// the compiled object `carve.so` (the [lib] name), even though the crate
+/// package is named `carve-rb`.
+#[magnus::init(name = "carve")]
+fn init(ruby: &Ruby) -> Result<(), Error> {
+    let module = ruby.define_module("Carve")?;
+    // Native primitives. The pure-Ruby wrapper in lib/carve.rb defines the
+    // public `Carve.to_html(source, extensions:, mode:, renderers:)` on top of
+    // these. `_to_html` is the no-extension fast path; the wrapper owns the
+    // bare `to_html` name.
+    module.define_singleton_method("_to_html", function!(to_html, 1))?;
+    module.define_singleton_method("_to_ast_json", function!(to_ast_json, 1))?;
+    module.define_singleton_method(
+        "to_html_with_extensions",
+        function!(to_html_with_extensions, 2),
+    )?;
+    module.define_singleton_method("to_html_full", function!(to_html_full, 4))?;
+    Ok(())
+}

data/lib/carve/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Carve
+  VERSION = "0.1.0"
+end

data/lib/carve.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+# Carve: Ruby bindings for the Carve markup language.
+#
+# This file loads the compiled native extension (built from ext/carve, a Rust
+# crate wrapping the carve-rs engine via magnus) and layers a small,
+# idiomatic Ruby API on top of the raw primitives it exports.
+require "json"
+require_relative "carve/version"
+
+# Load the compiled native extension. Built by `rake compile` to
+# lib/carve/carve.so (or .bundle on macOS).
+require_relative "carve/carve"
+
+module Carve
+  # Extension names the native binding understands (snake_case or hyphenated).
+  EXTENSIONS = %i[
+    autolink
+    details
+    list_table
+    math_block
+    heading_permalinks
+    citations
+    code_callouts
+    tab_normalize
+    wikilinks
+    external_links
+    fenced_render
+    fenced_render_graphviz
+    fenced_render_chart
+    spoiler
+    table_of_contents
+  ].freeze
+
+  # Render modes the native binding understands.
+  #
+  # +:interactive+ (default) emits live HTML with client-script hooks (e.g.
+  # `<pre class="mermaid">`, `<details>`). +:static+ emits self-contained HTML
+  # for print / PDF / archival: it forces disclosure (`<details open>`) and
+  # pre-renders client-script constructs through the +renderers:+ callables,
+  # degrading to (escaped) source when a renderer is absent or fails.
+  MODES = %i[interactive static].freeze
+
+  # Renderer keys accepted by the +renderers:+ Hash (see .to_html). Each maps a
+  # construct's source to a self-contained HTML string emitted on the static
+  # path. +mermaid+ / +chart+ / +graphviz+ are callables `(String) -> String`;
+  # +math+ is `(String, display_bool) -> String`.
+  RENDERER_KEYS = %i[mermaid chart graphviz math].freeze
+
+  class << self
+    # Render Carve +source+ to an HTML string.
+    #
+    # With no extensions:
+    #   Carve.to_html("# Hello")             # => "<section ...>\n  <h1>Hello</h1>..."
+    #
+    # With extensions (Array of names as Symbols or Strings):
+    #   Carve.to_html(src, extensions: [:math_block])
+    #   Carve.to_html(src, extensions: %w[math-block list-table])
+    #
+    # Recognized extension names: see Carve::EXTENSIONS. Names may be given
+    # snake_case (:math_block) or hyphenated ("math-block").
+    #
+    # An unknown extension name raises ArgumentError (from the native layer).
+    #
+    # ==== Static render mode
+    #
+    # Pass +mode: :static+ (or "static") to emit self-contained HTML for print /
+    # PDF / archival. In static mode disclosure is forced (`<details open>`) and
+    # client-script constructs are pre-rendered through the +renderers:+ Hash:
+    #
+    #   Carve.to_html(src, extensions: [:fenced_render], mode: :static,
+    #                 renderers: { mermaid: ->(s) { "<svg>#{s}</svg>" } })
+    #
+    # Renderer callables (Symbol or String keys, see Carve::RENDERER_KEYS):
+    #   * +:mermaid+ / +:chart+ / +:graphviz+ -> callable `(String) -> String`
+    #   * +:math+                             -> callable `(String, display) -> String`
+    #
+    # When a needed renderer is absent, or a renderer raises / returns a
+    # non-String, the construct degrades to its HTML-ESCAPED source (never blank,
+    # never raw HTML). Omitting +mode:+ defaults to interactive (non-breaking).
+    #
+    # An unknown mode or renderer key raises ArgumentError (from the native
+    # layer).
+    def to_html(source, extensions: nil, mode: nil, renderers: nil)
+      list = Array(extensions)
+
+      # Fast path: interactive (default), no extensions, no renderers.
+      if list.empty? && (mode.nil? || mode.to_s == "interactive") && (renderers.nil? || renderers.empty?)
+        return _to_html(source.to_s)
+      end
+
+      to_html_full(
+        source.to_s,
+        list.map(&:to_s),
+        (mode || :interactive).to_s,
+        renderers || {},
+      )
+    end
+
+    # Parse Carve +source+ into an AST: a tree of Ruby Hashes and Arrays.
+    #
+    #   Carve.parse("# Hi")
+    #   # => {type: "document", frontmatter: {}, footnote_defs: {},
+    #   #     children: [{type: "heading", level: 1,
+    #   #                 children: [{type: "text", value: "Hi"}], attrs: nil}],
+    #   #     source_len: 4}
+    #
+    # Every node is a Hash with a +:type+ key plus its fields; child collections
+    # are Arrays; +:attrs+ is +nil+ or a Hash of +{id:, classes:, key_values:}+.
+    # Keys are symbols. This is the raw parse tree (default profile, no
+    # extensions), suitable for a custom renderer (e.g. Carve -> PDF).
+    def parse(source)
+      # max_nesting: false - the engine already bounds nesting (its own
+      # MAX_NESTING_DEPTH cap), and that cap exceeds Ruby JSON's default
+      # max_nesting of 100. Without this, deeply-nested-but-valid documents
+      # that Carve.to_html renders fine would raise JSON::NestingError here.
+      JSON.parse(_to_ast_json(source.to_s), symbolize_names: true, max_nesting: false)
+    end
+  end
+end

metadata

@@ -0,0 +1,112 @@
+--- !ruby/object:Gem::Specification
+name: carve-lang
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- markup-carve
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-07-12 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'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rake-compiler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !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'
+description: |-
+  Parse and render Carve markup to HTML from Ruby. A native extension
+  (magnus + rb-sys) over the carve-rs engine, mirroring how Djot's djotter
+  gem wraps the jotdown crate. No parser is reimplemented in Ruby.
+email:
+executables: []
+extensions:
+- ext/carve/extconf.rb
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- ext/carve/Cargo.lock
+- ext/carve/Cargo.toml
+- ext/carve/extconf.rb
+- ext/carve/src/ast_json.rs
+- ext/carve/src/lib.rs
+- lib/carve.rb
+- lib/carve/version.rb
+homepage: https://github.com/markup-carve/carve-rb
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Native Ruby bindings for the Carve markup language.
+test_files: []