wcl 0.2.3.alpha1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3e5c8aad8cfd3f0c1dff7cf957a5dd20704f18eaad80e6b37286d2157e08bb6e
+  data.tar.gz: fa13a51a38fdbe98ec55d102eafdfbd33dc4cb8e3ed7823a9f19a1a77ac38ab7
+SHA512:
+  metadata.gz: de89bae27e663707e68fd03d8bbcfda250018c6c047f37d3b4c231b67564805d8a1fa48e86cc2173c6f6a53b025e27ce76a74aa89824cf4533f7430ddaae4396
+  data.tar.gz: b0ba5a0d6944c07e6c6760ba07a8ea78eac4d111d96eb67b585bab064b7f40b8522bae737d5333aea0659f7988c37b9ee32660a9b7c10d5699fc854cd0c04f0c

data/lib/wcl/callback.rb

@@ -0,0 +1,59 @@
+require "json"
+
+module Wcl
+  # Thread-local callback bridge for custom functions invoked from WASM.
+  module Callback
+    module_function
+
+    def set_functions(fn_hash)
+      Thread.current[:wcl_functions] = fn_hash
+    end
+
+    def clear_functions
+      Thread.current[:wcl_functions] = nil
+    end
+
+    def invoke(name, args_json)
+      functions = Thread.current[:wcl_functions]
+      return [false, "callback not found: #{name}"] if functions.nil? || !functions.key?(name)
+
+      begin
+        args = JSON.parse(args_json)
+        ruby_args = args.map { |a| json_to_ruby(a) }
+        result = functions[name].call(ruby_args)
+        result_json = JSON.generate(ruby_to_json(result))
+        [true, result_json]
+      rescue => e
+        [false, e.message]
+      end
+    end
+
+    def json_to_ruby(val)
+      case val
+      when nil, true, false, Integer, Float, String
+        val
+      when Array
+        val.map { |v| json_to_ruby(v) }
+      when Hash
+        val.transform_values { |v| json_to_ruby(v) }
+      else
+        val
+      end
+    end
+
+    def ruby_to_json(val)
+      case val
+      when nil, true, false, Integer, Float, String
+        val
+      when Array
+        val.map { |v| ruby_to_json(v) }
+      when Hash
+        val.transform_values { |v| ruby_to_json(v) }
+      when Set
+        { "__type" => "set", "items" => val.map { |v| ruby_to_json(v) } }
+      else
+        val
+      end
+    end
+  end
+end

data/lib/wcl/convert.rb

@@ -0,0 +1,78 @@
+require "json"
+
+module Wcl
+  # JSON-to-Ruby value conversion for WCL WASM binding.
+  module Convert
+    module_function
+
+    def json_to_ruby(val)
+      case val
+      when nil, true, false, String
+        val
+      when Integer
+        val
+      when Float
+        val == val.to_i && !val.is_a?(Float) ? val.to_i : val
+      when Array
+        val.map { |v| json_to_ruby(v) }
+      when Hash
+        # Check for set encoding
+        if val["__type"] == "set" && val.key?("items")
+          items = val["items"].map { |v| json_to_ruby(v) }
+          begin
+            Set.new(items)
+          rescue
+            items
+          end
+        # Check for block ref encoding
+        elsif val.key?("kind") && (val.key?("attributes") || val.key?("children") || val.key?("decorators"))
+          json_to_block_ref(val)
+        else
+          val.transform_values { |v| json_to_ruby(v) }
+        end
+      else
+        val
+      end
+    end
+
+    def json_to_values(json_str)
+      data = JSON.parse(json_str)
+      data.transform_values { |v| json_to_ruby(v) }
+    end
+
+    def json_to_blocks(json_str)
+      data = JSON.parse(json_str)
+      data.map { |b| json_to_block_ref(b) }
+    end
+
+    def json_to_diagnostics(json_str)
+      data = JSON.parse(json_str)
+      data.map do |d|
+        Diagnostic.new(
+          severity: d["severity"],
+          message: d["message"],
+          code: d["code"]
+        )
+      end
+    end
+
+    def json_to_block_ref(obj)
+      attrs = (obj["attributes"] || {}).transform_values { |v| json_to_ruby(v) }
+      children = (obj["children"] || []).map { |c| json_to_block_ref(c) }
+      decorators = (obj["decorators"] || []).map do |d|
+        Decorator.new(
+          name: d["name"],
+          args: (d["args"] || {}).transform_values { |v| json_to_ruby(v) }
+        )
+      end
+
+      BlockRef.new(
+        kind: obj["kind"],
+        id: obj["id"],
+        attributes: attrs,
+        children: children,
+        decorators: decorators
+      )
+    end
+  end
+end

data/lib/wcl/document.rb

@@ -0,0 +1,80 @@
+require "json"
+
+module Wcl
+  # A parsed and evaluated WCL document.
+  class Document
+    def initialize(handle)
+      @handle = handle
+      @closed = false
+      @values = nil
+      @diagnostics = nil
+
+      ObjectSpace.define_finalizer(self, self.class._invoke_release(handle))
+    end
+
+    def self._invoke_release(handle)
+      proc { WasmRuntime.get.document_free(handle) rescue nil }
+    end
+
+    def values
+      raise "Document is closed" if @closed
+
+      @values ||= Convert.json_to_values(WasmRuntime.get.document_values(@handle))
+    end
+
+    def has_errors?
+      raise "Document is closed" if @closed
+
+      WasmRuntime.get.document_has_errors(@handle)
+    end
+
+    def errors
+      diagnostics.select(&:error?)
+    end
+
+    def diagnostics
+      raise "Document is closed" if @closed
+
+      @diagnostics ||= Convert.json_to_diagnostics(WasmRuntime.get.document_diagnostics(@handle))
+    end
+
+    def query(query_str)
+      raise "Document is closed" if @closed
+
+      json_str = WasmRuntime.get.document_query(@handle, query_str)
+      result = JSON.parse(json_str)
+      raise ValueError, result["error"] if result.key?("error")
+
+      Convert.json_to_ruby(result["ok"])
+    end
+
+    def blocks
+      raise "Document is closed" if @closed
+
+      json_str = WasmRuntime.get.document_blocks(@handle)
+      Convert.json_to_blocks(json_str)
+    end
+
+    def blocks_of_type(kind)
+      raise "Document is closed" if @closed
+
+      json_str = WasmRuntime.get.document_blocks_of_type(@handle, kind)
+      Convert.json_to_blocks(json_str)
+    end
+
+    def close
+      return if @closed
+
+      @closed = true
+      WasmRuntime.get.document_free(@handle)
+      ObjectSpace.undefine_finalizer(self)
+    end
+
+    def to_h
+      { values: values, has_errors: has_errors?, diagnostics: diagnostics.map(&:inspect) }
+    end
+  end
+
+  # Error raised for invalid queries.
+  class ValueError < StandardError; end
+end

data/lib/wcl/types.rb

@@ -0,0 +1,92 @@
+module Wcl
+  # A reference to a WCL block with its attributes.
+  class BlockRef
+    attr_reader :kind, :id, :attributes, :children, :decorators
+
+    def initialize(kind:, id: nil, attributes: {}, children: [], decorators: [])
+      @kind = kind
+      @id = id
+      @attributes = attributes
+      @children = children
+      @decorators = decorators
+    end
+
+    def get(key)
+      @attributes[key]
+    end
+
+    def [](key)
+      @attributes[key]
+    end
+
+    def has_decorator?(name)
+      @decorators.any? { |d| d.name == name }
+    end
+
+    def to_h
+      {
+        kind: @kind,
+        id: @id,
+        attributes: @attributes,
+        children: @children.map(&:to_h),
+        decorators: @decorators.map(&:to_h)
+      }
+    end
+
+    def inspect
+      if @id
+        "#<Wcl::BlockRef(#{@kind} #{@id})>"
+      else
+        "#<Wcl::BlockRef(#{@kind})>"
+      end
+    end
+    alias_method :to_s, :inspect
+  end
+
+  # A WCL decorator with name and arguments.
+  class Decorator
+    attr_reader :name, :args
+
+    def initialize(name:, args: {})
+      @name = name
+      @args = args
+    end
+
+    def to_h
+      { name: @name, args: @args }
+    end
+
+    def inspect
+      "#<Wcl::Decorator(@#{@name})>"
+    end
+    alias_method :to_s, :inspect
+  end
+
+  # A WCL diagnostic (error, warning, etc.).
+  class Diagnostic
+    attr_reader :severity, :message, :code
+
+    def initialize(severity:, message:, code: nil)
+      @severity = severity
+      @message = message
+      @code = code
+    end
+
+    def error?
+      @severity == "error"
+    end
+
+    def warning?
+      @severity == "warning"
+    end
+
+    def inspect
+      if @code
+        "#<Wcl::Diagnostic(#{@severity}: [#{@code}] #{@message})>"
+      else
+        "#<Wcl::Diagnostic(#{@severity}: #{@message})>"
+      end
+    end
+    alias_method :to_s, :inspect
+  end
+end

data/lib/wcl/version.rb

@@ -0,0 +1,3 @@
+module Wcl
+  VERSION = "0.2.3.alpha1"
+end

data/lib/wcl/wasm_runtime.rb

@@ -0,0 +1,188 @@
+require "wasmtime"
+
+module Wcl
+  # Singleton WASM runtime that loads and manages the wcl_wasm module.
+  class WasmRuntime
+    @instance = nil
+    @init_mutex = Mutex.new
+
+    def self.get
+      return @instance if @instance
+
+      @init_mutex.synchronize do
+        @instance ||= new
+      end
+      @instance
+    end
+
+    def initialize
+      @mutex = Mutex.new
+      @engine = Wasmtime::Engine.new
+
+      wasm_path = File.join(__dir__, "wcl_wasm.wasm")
+      @module = Wasmtime::Module.from_file(@engine, wasm_path)
+
+      @linker = Wasmtime::Linker.new(@engine)
+      Wasmtime::WASI::P1.add_to_linker_sync(@linker)
+      define_host_functions
+
+      @store = Wasmtime::Store.new(@engine, wasi_p1_config: Wasmtime::WasiConfig.new)
+      @wasm_instance = @linker.instantiate(@store, @module)
+
+      # Cache exported functions
+      @alloc = @wasm_instance.export("wcl_wasm_alloc").to_func
+      @dealloc = @wasm_instance.export("wcl_wasm_dealloc").to_func
+      @string_free = @wasm_instance.export("wcl_wasm_string_free").to_func
+      @parse_fn = @wasm_instance.export("wcl_wasm_parse").to_func
+      @parse_with_functions_fn = @wasm_instance.export("wcl_wasm_parse_with_functions").to_func
+      @doc_free = @wasm_instance.export("wcl_wasm_document_free").to_func
+      @doc_values = @wasm_instance.export("wcl_wasm_document_values").to_func
+      @doc_has_errors = @wasm_instance.export("wcl_wasm_document_has_errors").to_func
+      @doc_diagnostics = @wasm_instance.export("wcl_wasm_document_diagnostics").to_func
+      @doc_query = @wasm_instance.export("wcl_wasm_document_query").to_func
+      @doc_blocks = @wasm_instance.export("wcl_wasm_document_blocks").to_func
+      @doc_blocks_of_type = @wasm_instance.export("wcl_wasm_document_blocks_of_type").to_func
+      @memory = @wasm_instance.export("memory").to_memory
+    end
+
+    # -- Public API (all synchronized) ------------------------------------
+
+    def parse(source, options_json)
+      @mutex.synchronize do
+        src_ptr = write_string(source)
+        opts_ptr = write_string(options_json)
+        begin
+          @parse_fn.call(src_ptr, opts_ptr)
+        ensure
+          dealloc_string(src_ptr, source) if src_ptr != 0
+          dealloc_string(opts_ptr, options_json) if opts_ptr != 0 && options_json
+        end
+      end
+    end
+
+    def parse_with_functions(source, options_json, func_names_json)
+      @mutex.synchronize do
+        src_ptr = write_string(source)
+        opts_ptr = write_string(options_json)
+        names_ptr = write_string(func_names_json)
+        begin
+          @parse_with_functions_fn.call(src_ptr, opts_ptr, names_ptr)
+        ensure
+          dealloc_string(src_ptr, source) if src_ptr != 0
+          dealloc_string(opts_ptr, options_json) if opts_ptr != 0 && options_json
+          dealloc_string(names_ptr, func_names_json) if names_ptr != 0
+        end
+      end
+    end
+
+    def document_free(handle)
+      @mutex.synchronize { @doc_free.call(handle) }
+    end
+
+    def document_values(handle)
+      @mutex.synchronize do
+        ptr = @doc_values.call(handle)
+        consume_string(ptr)
+      end
+    end
+
+    def document_has_errors(handle)
+      @mutex.synchronize { @doc_has_errors.call(handle) != 0 }
+    end
+
+    def document_diagnostics(handle)
+      @mutex.synchronize do
+        ptr = @doc_diagnostics.call(handle)
+        consume_string(ptr)
+      end
+    end
+
+    def document_query(handle, query)
+      @mutex.synchronize do
+        q_ptr = write_string(query)
+        begin
+          ptr = @doc_query.call(handle, q_ptr)
+          consume_string(ptr)
+        ensure
+          dealloc_string(q_ptr, query) if q_ptr != 0
+        end
+      end
+    end
+
+    def document_blocks(handle)
+      @mutex.synchronize do
+        ptr = @doc_blocks.call(handle)
+        consume_string(ptr)
+      end
+    end
+
+    def document_blocks_of_type(handle, kind)
+      @mutex.synchronize do
+        k_ptr = write_string(kind)
+        begin
+          ptr = @doc_blocks_of_type.call(handle, k_ptr)
+          consume_string(ptr)
+        ensure
+          dealloc_string(k_ptr, kind) if k_ptr != 0
+        end
+      end
+    end
+
+    private
+
+    def define_host_functions
+      @linker.func_new(
+        "env", "host_call_function",
+        [:i32, :i32, :i32, :i32, :i32, :i32], [:i32]
+      ) do |caller, name_ptr, name_len, args_ptr, args_len, result_ptr_out, result_len_out|
+        memory = caller.export("memory").to_memory
+
+        name = memory.read(name_ptr, name_len).force_encoding("UTF-8")
+        args_json = memory.read(args_ptr, args_len).force_encoding("UTF-8")
+
+        success, result_json = Callback.invoke(name, args_json)
+
+        if result_json
+          result_bytes = result_json.encode("UTF-8")
+          alloc_fn = caller.export("wcl_wasm_alloc").to_func
+          ptr = alloc_fn.call(result_bytes.bytesize)
+
+          memory.write(ptr, result_bytes)
+          memory.write(result_ptr_out, [ptr].pack("V"))
+          memory.write(result_len_out, [result_bytes.bytesize].pack("V"))
+        end
+
+        success ? 0 : -1
+      end
+    end
+
+    def write_string(str)
+      return 0 if str.nil?
+
+      encoded = str.encode("UTF-8")
+      ptr = @alloc.call(encoded.bytesize + 1)
+      @memory.write(ptr, encoded + "\0")
+      ptr
+    end
+
+    def read_c_string(ptr)
+      return "" if ptr == 0
+
+      data = @memory.read(ptr, @memory.data_size - ptr)
+      null_idx = data.index("\0") || data.size
+      data[0, null_idx].force_encoding("UTF-8")
+    end
+
+    def consume_string(ptr)
+      return "" if ptr == 0
+
+      s = read_c_string(ptr)
+      @string_free.call(ptr)
+      s
+    end
+
+    def dealloc_string(ptr, original)
+      @dealloc.call(ptr, original.encode("UTF-8").bytesize + 1)
+    end
+  end
+end

data/lib/wcl.rb

@@ -0,0 +1,53 @@
+require "json"
+require_relative "wcl/version"
+require_relative "wcl/types"
+require_relative "wcl/callback"
+require_relative "wcl/convert"
+require_relative "wcl/wasm_runtime"
+require_relative "wcl/document"
+
+module Wcl
+  module_function
+
+  # Parse a WCL source string and return a Document.
+  def parse(source, root_dir: nil, allow_imports: nil, max_import_depth: nil,
+            max_macro_depth: nil, max_loop_depth: nil, max_iterations: nil,
+            functions: nil, variables: nil)
+    options = {}
+    options["rootDir"] = root_dir.to_s if root_dir
+    options["allowImports"] = allow_imports unless allow_imports.nil?
+    options["maxImportDepth"] = max_import_depth if max_import_depth
+    options["maxMacroDepth"] = max_macro_depth if max_macro_depth
+    options["maxLoopDepth"] = max_loop_depth if max_loop_depth
+    options["maxIterations"] = max_iterations if max_iterations
+    options["variables"] = variables if variables
+
+    options_json = options.empty? ? nil : JSON.generate(options)
+    runtime = WasmRuntime.get
+
+    if functions && !functions.empty?
+      Callback.set_functions(functions)
+      begin
+        func_names_json = JSON.generate(functions.keys)
+        handle = runtime.parse_with_functions(source, options_json, func_names_json)
+      ensure
+        Callback.clear_functions
+      end
+    else
+      handle = runtime.parse(source, options_json)
+    end
+
+    Document.new(handle)
+  end
+
+  # Parse a WCL file and return a Document.
+  def parse_file(path, **kwargs)
+    path = path.to_s
+    source = File.read(path)
+  rescue Errno::ENOENT, Errno::EACCES => e
+    raise IOError, "#{path}: #{e.message}"
+  else
+    kwargs[:root_dir] ||= File.dirname(File.expand_path(path))
+    parse(source, **kwargs)
+  end
+end

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification
+name: wcl
+version: !ruby/object:Gem::Version
+  version: 0.2.3.alpha1
+platform: ruby
+authors:
+- Wil Taylor
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: wasmtime
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '42'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '42'
+description: Ruby bindings for WCL, powered by a WASM module and the wasmtime runtime.
+  Provides the full 11-phase parsing pipeline with native Ruby types.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/wcl.rb
+- lib/wcl/callback.rb
+- lib/wcl/convert.rb
+- lib/wcl/document.rb
+- lib/wcl/types.rb
+- lib/wcl/version.rb
+- lib/wcl/wasm_runtime.rb
+- lib/wcl/wcl_wasm.wasm
+homepage: https://github.com/wiltaylor/wcl
+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.1'
+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: WCL (Wil's Configuration Language) Ruby bindings
+test_files: []