etassia-native 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ad82fe8761289ebe9e5a7774a68667f747318cfc6c07eaedaa5a459b15bdcdef
+  data.tar.gz: d09df242a26ebbbe0019de672709091a8af7ef28b6890467bb551654ea3c8d77
+SHA512:
+  metadata.gz: 654196fe987e74cbedd99d6edb3e34113c495aeeb373331bccb0a8bee3f040d46155119f0010ce2867489f3a7ed3cd08bc7e82c35c9d1205e2e3cd22c67c1ddf
+  data.tar.gz: 84080656b0b0eb0c44d8b7c95c788d25d69dbf30f57362eca88b948c3aa98402209b52bdda4731f30044e5b3e159d892c3af687bf403619e5d7b40388e649e73

data/lib/etassia/native/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Native
+    VERSION = "0.1.0"
+  end
+end

data/lib/etassia/native.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require "json"
+require "rbconfig"
+require "ffi"
+
+module Etassia
+  # Renders through the etassia-ffi C ABI (see crates/etassia-ffi/README.md).
+  #
+  # The shared library is looked up in this order:
+  #   1. ENV["ETASSIA_NATIVE_LIB"] — exact file path; when set, nothing else is searched.
+  #   2. lib/etassia/native/ inside an installed platform gem (precompiled, no compile at install).
+  #   3. <repo>/target/release, then <repo>/target/debug.
+  # When no library is found, or the Rust core answers `Unported`, render
+  # falls back to a pure-Ruby callable (default: the `etassia` gem's Etassia.render).
+  module Native
+    LIBRARY_ENV = "ETASSIA_NATIVE_LIB"
+    REPO_ROOT = File.expand_path("../../../..", __dir__)
+    PACKAGED_DIR = File.join(__dir__, "native").freeze
+    SEARCH_DIRS = [PACKAGED_DIR,
+                   File.join(REPO_ROOT, "target", "release"),
+                   File.join(REPO_ROOT, "target", "debug")].freeze
+
+    # The Rust core declined this diagram type; the caller should fall back.
+    class Unported < StandardError; end
+
+    # Any other error the native library reports (parse, encoding, ...). Never falls back.
+    class RenderError < StandardError
+      attr_reader :error_class, :line, :col
+
+      def initialize(error_class, message, line, col)
+        @error_class = error_class
+        @line = line
+        @col = col
+        super("#{error_class} at #{line}:#{col}: #{message}")
+      end
+    end
+
+    # Neither the native library nor the pure-Ruby fallback can render.
+    class Unavailable < StandardError; end
+
+    # Loads one cdylib and calls its three entry points.
+    class Library
+      # Matches `struct EtassiaBuf` in crates/etassia-ffi/src/lib.rs (24 bytes on 64-bit).
+      class Buf < FFI::Struct
+        layout :ptr, :pointer,
+               :len, :size_t,
+               :status, :int
+      end
+
+      attr_reader :path
+
+      def initialize(path)
+        @path = path
+        buf = Buf
+        @lib = Module.new do
+          extend FFI::Library
+
+          ffi_lib path
+          attach_function :etassia_render, %i[pointer size_t pointer], buf.by_value
+          attach_function :etassia_detect, %i[pointer size_t], buf.by_value
+          attach_function :etassia_free, [buf.by_value], :void
+        end
+      end
+
+      def render(source)
+        ptr, len = input(source)
+        take(@lib.etassia_render(ptr, len, nil))
+      end
+
+      def detect(source)
+        ptr, len = input(source)
+        take(@lib.etassia_detect(ptr, len))
+      end
+
+      private
+
+      def input(source)
+        bytes = source.to_s.encode(Encoding::UTF_8).b
+        ptr = FFI::MemoryPointer.new(:uint8, [bytes.bytesize, 1].max)
+        ptr.put_bytes(0, bytes)
+        [ptr, bytes.bytesize]
+      end
+
+      # Copies the buffer out, always frees it, then maps status to result or error.
+      def take(buf)
+        body = buf[:ptr].read_bytes(buf[:len]).force_encoding(Encoding::UTF_8)
+        status = buf[:status]
+        @lib.etassia_free(buf)
+        return body if status.zero?
+
+        raise_error(body)
+      end
+
+      def raise_error(json)
+        info = JSON.parse(json)
+        raise Unported, info["message"] if info["class"] == "Unported"
+
+        raise RenderError.new(info["class"], info["message"], info["line"], info["col"])
+      end
+    end
+
+    class << self
+      # Pure-Ruby renderer used when the native path cannot answer. Injectable.
+      attr_writer :fallback
+
+      def fallback
+        @fallback ||= method(:pure_ruby_render)
+      end
+
+      # Path of the library that would be loaded, or nil.
+      def library_path
+        override = ENV.fetch(LIBRARY_ENV, nil)
+        return (File.file?(override) ? override : nil) if override && !override.empty?
+
+        SEARCH_DIRS.map { |dir| File.join(dir, library_filename) }.find { |path| File.file?(path) }
+      end
+
+      def available?
+        !library_path.nil?
+      end
+
+      # SVG for `source`. Uses the native library, or the fallback when it is
+      # missing or reports Unported. Other native errors raise RenderError.
+      def render(source, fallback: self.fallback)
+        lib = library
+        return fallback.call(source) if lib.nil?
+
+        lib.render(source)
+      rescue Unported
+        fallback.call(source)
+      end
+
+      # Diagram type name for `source`. Native only; raises Unavailable without a library.
+      def detect(source)
+        lib = library or raise Unavailable,
+                               "#{LIBRARY_ENV} not set and no #{library_filename} in the gem or under target/"
+
+        lib.detect(source)
+      end
+
+      def library
+        path = library_path
+        return nil if path.nil?
+
+        @libraries ||= {}
+        @libraries[path] ||= Library.new(path)
+      end
+
+      private
+
+      def library_filename
+        case RbConfig::CONFIG["host_os"]
+        when /darwin/ then "libetassia_ffi.dylib"
+        when /mswin|mingw/ then "etassia_ffi.dll"
+        else "libetassia_ffi.so"
+        end
+      end
+
+      def pure_ruby_render(source)
+        begin
+          require "etassia"
+        rescue LoadError
+          raise Unavailable, "native library not found and the pure-Ruby 'etassia' gem is not installed"
+        end
+        raise Unavailable, "the 'etassia' gem does not define Etassia.render" unless Etassia.respond_to?(:render)
+
+        Etassia.render(source)
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,53 @@
+--- !ruby/object:Gem::Specification
+name: etassia-native
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Etassia contributors
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ffi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/etassia/native.rb
+- lib/etassia/native/version.rb
+licenses:
+- BSD-2-Clause
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.23
+specification_version: 4
+summary: Ruby binding to the etassia-ffi C ABI, with a pure-Ruby fallback
+test_files: []