hx_ruby 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ed966ca9ef6f53c6fc8eb54f403e685ccce968c18857095d48bc46c0fb8eda14
+  data.tar.gz: f7cc0f292ffba4285a9612fd2d8e14d7dd78290ce18998475306b20874a5af57
+SHA512:
+  metadata.gz: 4418e948a6106c092c8d40ac27bac2b427e4835f677ac4593825f2ef8aa091cef139a71d325c977617540553b984adff1f98c67ffecc7d6672569dab1b7bd2f5
+  data.tar.gz: fae787afd40a83fd3f7e35342148d84ca3426807767f2059e7b2495fe913ec24b48021893f2a4bf55949e3eb9750c86e2c125773bcac6adecf307b1cf1fe39f4

data/ext/hx_ruby/Cargo.toml

@@ -0,0 +1,41 @@
+# Every value is written out, and nothing here is inherited from the workspace.
+#
+# This is the one manifest in the repository that leaves it: `gem build` copies
+# it verbatim into the gem, and it is compiled on a machine where there is no
+# workspace to inherit from. `edition.workspace = true` there is not a fallback,
+# it is an error - "failed to find a workspace root" - and the gem will not
+# install. CI checks that nothing in this file says `workspace`.
+#
+# The cost is that the version is written in two places. `.github/workflows/ci.yml`
+# fails if it stops matching the workspace's.
+[package]
+name = "hx-ruby"
+description = "Ruby bindings over hx-catalog's preset inspector, so the tone browser reads .hlx files with the same code the desktop uses"
+version = "0.3.0"
+edition = "2021"
+license = "MIT"
+repository = "https://github.com/crmne/tonepush"
+rust-version = "1.87"
+
+[lib]
+# The name Ruby dlopen's and the `Init_hx_ruby` entry it calls; keep it in step
+# with the gem's `require "hx_ruby/hx_ruby"`.
+name = "hx_ruby"
+crate-type = ["cdylib"]
+
+[dependencies]
+# The whole point: parse presets with hx-catalog's inspector, never a Ruby
+# reimplementation. hx-proto is the preset model those facts ultimately describe
+# and is kept as a direct dependency so this binding can surface its types
+# without a manifest change.
+#
+# Named by version and not by path, unlike every other crate here, because this
+# manifest is the one that leaves the repository: `gem build` copies it verbatim
+# into the gem, and it is then compiled on a machine that has no workspace and
+# no sibling crates. A path would point at nothing there. The workspace root
+# patches both back to the local sources, so building here still compiles what
+# is checked out rather than what was last published.
+hx-catalog = "0.3.0"
+hx-proto = "0.3.0"
+magnus = "0.8"
+serde_json = "1"

data/ext/hx_ruby/extconf.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "mkmf"
+require "rb_sys/mkmf"
+
+# Builds the Rust cdylib beside this file and installs it as
+# lib/hx_ruby/hx_ruby.so, which lib/hx_ruby.rb then requires.
+create_rust_makefile("hx_ruby/hx_ruby")

data/ext/hx_ruby/src/lib.rs

@@ -0,0 +1,129 @@
+//! Ruby bindings over `hx_catalog`'s preset inspector.
+//!
+//! The tone browser is a Rails app, but it must not grow a second, drifting
+//! copy of the `.hlx` reader in Ruby. So parsing stays here: this crate hands a
+//! preset's JSON to [`hx_catalog::inspect`] - the very reader the desktop uses -
+//! and returns the facts as a plain Ruby Hash. The Rails side is then a thin
+//! value object over those facts, never a parser.
+
+use hx_catalog::{Catalog, ChainContent, OutputTarget, Tone};
+use magnus::{function, prelude::*, Error, ExceptionClass, RHash, Ruby};
+
+/// `HxRuby.inspect_hlx(json)` -> a Hash of the tone facts a browser sorts by.
+///
+/// Raises `HxRuby::CatalogNotInstalled` when the HX Edit resources are missing,
+/// `HxRuby::Error` for any other catalog read failure, and `ArgumentError` when
+/// the string is not valid preset JSON. It resolves both DSPs and every block,
+/// and by construction never panics.
+fn inspect_hlx(ruby: &Ruby, json: String) -> Result<RHash, Error> {
+    let value: serde_json::Value = serde_json::from_str(&json).map_err(|e| {
+        Error::new(
+            ruby.exception_arg_error(),
+            format!("not a valid .hlx preset: {e}"),
+        )
+    })?;
+
+    let catalog = Catalog::load().map_err(|e| load_error(ruby, &e))?;
+    let tone = hx_catalog::inspect(&value, &catalog);
+    tone_to_hash(ruby, &tone)
+}
+
+/// Turn a catalog load failure into the right Ruby exception. "Not installed"
+/// is its own class so the Rails app can rescue the one recoverable case - the
+/// resources are absent - apart from a genuine read or parse fault.
+fn load_error(ruby: &Ruby, error: &hx_catalog::Error) -> Error {
+    let class = match error {
+        hx_catalog::Error::NotInstalled(_) => hx_error_class(ruby, "CatalogNotInstalled"),
+        _ => hx_error_class(ruby, "Error"),
+    };
+    Error::new(class, error.to_string())
+}
+
+/// Re-resolve one of the crate's exception classes, defined in [`init`]. Falls
+/// back to `RuntimeError` if the module is somehow gone, so a lookup miss still
+/// raises rather than panics.
+fn hx_error_class(ruby: &Ruby, name: &str) -> ExceptionClass {
+    ruby.define_module("HxRuby")
+        .and_then(|module| module.const_get(name))
+        .unwrap_or_else(|_| ruby.exception_runtime_error())
+}
+
+fn tone_to_hash(ruby: &Ruby, tone: &Tone) -> Result<RHash, Error> {
+    let hash = ruby.hash_new();
+    hash.aset(ruby.to_symbol("name"), tone.name.as_str())?;
+
+    let blocks = ruby.ary_new();
+    for block in &tone.blocks {
+        let entry = ruby.hash_new();
+        entry.aset(ruby.to_symbol("path"), block.path)?;
+        entry.aset(ruby.to_symbol("position"), block.position)?;
+        entry.aset(ruby.to_symbol("model_number"), block.model_number)?;
+        entry.aset(ruby.to_symbol("model_name"), block.model_name.as_str())?;
+        // nil when the model sits in no browse category, which is rare.
+        entry.aset(ruby.to_symbol("category"), block.category)?;
+        entry.aset(ruby.to_symbol("enabled"), block.enabled)?;
+
+        let params = ruby.hash_new();
+        for (name, value) in &block.params {
+            params.aset(name.as_str(), *value)?;
+        }
+        entry.aset(ruby.to_symbol("params"), params)?;
+
+        blocks.push(entry)?;
+    }
+    hash.aset(ruby.to_symbol("blocks"), blocks)?;
+
+    let models_used = ruby.ary_new();
+    for number in &tone.models_used {
+        models_used.push(*number)?;
+    }
+    hash.aset(ruby.to_symbol("models_used"), models_used)?;
+
+    hash.aset(ruby.to_symbol("has_amp"), tone.has_amp)?;
+    hash.aset(ruby.to_symbol("has_cab_or_ir"), tone.has_cab_or_ir)?;
+    hash.aset(
+        ruby.to_symbol("chain_content"),
+        chain_content_name(tone.chain_content),
+    )?;
+    hash.aset(
+        ruby.to_symbol("output_target"),
+        output_target_name(tone.output_target_guess),
+    )?;
+
+    let skipped = ruby.ary_new();
+    for note in &tone.skipped {
+        skipped.push(note.as_str())?;
+    }
+    hash.aset(ruby.to_symbol("skipped"), skipped)?;
+
+    Ok(hash)
+}
+
+/// Snake-case names that line up with the Rails `Tone` enums, so the value
+/// object can hand them straight to Active Record.
+fn chain_content_name(content: ChainContent) -> &'static str {
+    match content {
+        ChainContent::FullRig => "full_rig",
+        ChainContent::AmpAndCab => "amp_and_cab",
+        ChainContent::AmpOnly => "amp_only",
+        ChainContent::EffectsOnly => "effects_only",
+    }
+}
+
+/// The inspector only knows whether the tone carries its own speaker, so it
+/// offers two honest guesses rather than the browser's full output vocabulary.
+fn output_target_name(target: OutputTarget) -> &'static str {
+    match target {
+        OutputTarget::FrfrPa => "frfr_pa",
+        OutputTarget::GuitarCabOrDi => "guitar_cab_or_di",
+    }
+}
+
+#[magnus::init]
+fn init(ruby: &Ruby) -> Result<(), Error> {
+    let module = ruby.define_module("HxRuby")?;
+    let base = module.define_error("Error", ruby.exception_standard_error())?;
+    module.define_error("CatalogNotInstalled", base)?;
+    module.define_singleton_method("inspect_hlx", function!(inspect_hlx, 1))?;
+    Ok(())
+}

data/lib/hx_ruby/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module HxRuby
+  # Kept in step with the Rust workspace version so the gem and the crate it
+  # wraps move together.
+  VERSION = "0.3.0"
+end

data/lib/hx_ruby.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "hx_ruby/version"
+
+# Load the compiled Rust extension. rake-compiler installs it under a Ruby
+# version directory for gems that ship several; a plain extconf build (what
+# Bundler runs for a path gem) drops it straight in lib/hx_ruby. Try the
+# versioned path first, then fall back.
+begin
+  ruby_version = RUBY_VERSION[/\d+\.\d+/]
+  require_relative "hx_ruby/#{ruby_version}/hx_ruby"
+rescue LoadError
+  begin
+    require_relative "hx_ruby/hx_ruby"
+  rescue LoadError => e
+    # Bundler does not compile a path gem's extension on install, so a fresh
+    # checkout has to build it once.
+    raise LoadError, "#{e.message}\n\nThe hx_ruby native extension is not " \
+      "built yet. From the gem directory run: bundle exec rake compile"
+  end
+end
+
+# Ruby bindings over hx-catalog's `.hlx` inspector.
+#
+# The native `HxRuby.inspect_hlx(json)` is defined in Rust (see ext/hx_ruby).
+# It takes a preset's JSON string and returns a Hash of tone facts, raising
+# {HxRuby::CatalogNotInstalled} when the HX Edit resources are missing and
+# {HxRuby::Error} for any other catalog read failure.
+module HxRuby
+end

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification
+name: hx_ruby
+version: !ruby/object:Gem::Version
+  version: 0.3.0
+platform: ruby
+authors:
+- Carmine Paolino
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-08-10 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: Ruby bindings over hx-catalog's preset inspector, so the tone browser
+  reads .hlx files with the same Rust code the desktop uses instead of reimplementing
+  parsing in Ruby.
+email:
+- carmine@paolino.me
+executables: []
+extensions:
+- ext/hx_ruby/extconf.rb
+extra_rdoc_files: []
+files:
+- ext/hx_ruby/Cargo.toml
+- ext/hx_ruby/extconf.rb
+- ext/hx_ruby/src/lib.rs
+- lib/hx_ruby.rb
+- lib/hx_ruby/version.rb
+homepage: https://docs.tonepush.rocks
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://docs.tonepush.rocks
+  source_code_uri: https://github.com/crmne/tonepush
+  changelog_uri: https://github.com/crmne/tonepush/releases
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.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: Parse Line 6 .hlx presets into tone facts with the TonePush Rust catalog
+test_files: []