oicana 0.10.0.rc.1

data/lib/oicana/template.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+module Oicana
+  # @api private
+  # Frees a generated object on #close, once no call is using it anymore. Objects that
+  # are never closed are freed by the garbage collector.
+  class NativeHandle
+    def initialize(object, free_function, name)
+      @object = object
+      @free_function = free_function
+      @name = name
+      @lock = Mutex.new
+      @calls = 0
+      @closed = false
+    end
+
+    def use
+      @lock.synchronize do
+        raise ClosedError, "#{@name} is already closed" if @closed
+
+        @calls += 1
+      end
+      begin
+        Oicana.translate_errors { yield @object }
+      ensure
+        @lock.synchronize do
+          @calls -= 1
+          free if @closed && @calls.zero?
+        end
+      end
+    end
+
+    def close
+      @lock.synchronize do
+        next if @closed
+
+        @closed = true
+        free if @calls.zero?
+      end
+    end
+
+    private
+
+    def free
+      ObjectSpace.undefine_finalizer(@object)
+      OicanaUniffi.rust_call(@free_function, @object.instance_variable_get(:@handle))
+      @object = nil
+    end
+  end
+
+  # A packed Oicana template, ready to be compiled repeatedly.
+  #
+  # Create templates at startup, not per request. A template is safe to use from
+  # multiple threads, and native calls release the GVL.
+  #
+  #   Oicana::Template.open(File.binread("invoice-0.1.0.zip")) do |template|
+  #     pdf = template.export_pdf(json_inputs: { "invoice" => { "number" => "2026-001" } })
+  #   end
+  class Template
+    # Warnings of the warm-up compilation, or nil.
+    attr_reader :warnings
+
+    # Load a packed template and compile it once to warm up its caches.
+    #
+    # json_inputs map keys to JSON documents as Strings, or to values that are encoded
+    # with JSON.generate. blob_inputs map keys to BlobInput values or binary Strings.
+    def initialize(template, json_inputs: {}, blob_inputs: {}, mode: :development, limits: nil)
+      object = Oicana.translate_errors do
+        OicanaUniffi::Template.new(template.b, Convert.json_inputs(json_inputs), Convert.blob_inputs(blob_inputs),
+                                   Convert.mode(mode), Convert.limits(limits))
+      end
+      @warnings = object.warnings
+      @handle = NativeHandle.new(object, :uniffi_oicana_uniffi_fn_free_template, "template")
+    end
+
+    # Create a template, yield it, and close it afterwards.
+    def self.open(template, **options)
+      instance = new(template, **options)
+      return instance unless block_given?
+
+      begin
+        yield instance
+      ensure
+        instance.close
+      end
+    end
+
+    # Compile and export a template in a single native call, without caching anything.
+    #
+    # Skips the warm-up compilation, so it is the fastest way to render a template
+    # exactly once. Returns an ExportOnceResult.
+    def self.export_once(template, json_inputs: {}, blob_inputs: {}, format: :pdf, mode: :production,
+                         pixels_per_pt: 1.0, pages: nil, limits: nil)
+      result = Oicana.translate_errors do
+        OicanaUniffi.export_once(template.b, Convert.json_inputs(json_inputs), Convert.blob_inputs(blob_inputs),
+                                 Convert.mode(mode), Convert.format(format, pixels_per_pt), Convert.pages(pages),
+                                 Convert.limits(limits))
+      end
+      ExportOnceResult.new(document: result.bytes, warnings: result.warnings)
+    end
+
+    # Compile the template into a CompiledDocument whose pages can be exported repeatedly.
+    def compile(json_inputs: {}, blob_inputs: {}, mode: :production)
+      json = Convert.json_inputs(json_inputs)
+      blobs = Convert.blob_inputs(blob_inputs)
+      native_mode = Convert.mode(mode)
+      CompiledDocument.new(@handle.use { |template| template.compile(json, blobs, native_mode) })
+    end
+
+    # Compile the template and export it as :pdf, :png or :svg.
+    #
+    # pages is a 0-based page index or Range, for example 0, 1..2 or 3.., and defaults to
+    # the whole document.
+    def export(format: :pdf, json_inputs: {}, blob_inputs: {}, mode: :production, pixels_per_pt: 1.0, pages: nil)
+      document = compile(json_inputs: json_inputs, blob_inputs: blob_inputs, mode: mode)
+      begin
+        document.export(format: format, pixels_per_pt: pixels_per_pt, pages: pages)
+      ensure
+        document.close
+      end
+    end
+
+    # Compile the template and export it to PDF. Tagging is turned off when exporting a
+    # subset of pages.
+    def export_pdf(json_inputs: {}, blob_inputs: {}, mode: :production, pages: nil)
+      export(format: :pdf, json_inputs: json_inputs, blob_inputs: blob_inputs, mode: mode, pages: pages)
+    end
+
+    # Compile the template and export it to PNG. Multiple pages are stacked vertically.
+    def export_png(json_inputs: {}, blob_inputs: {}, mode: :production, pixels_per_pt: 1.0, pages: nil)
+      export(format: :png, json_inputs: json_inputs, blob_inputs: blob_inputs, mode: mode,
+             pixels_per_pt: pixels_per_pt, pages: pages)
+    end
+
+    # Compile the template and export it to SVG.
+    def export_svg(json_inputs: {}, blob_inputs: {}, mode: :production, pages: nil)
+      export(format: :svg, json_inputs: json_inputs, blob_inputs: blob_inputs, mode: mode, pages: pages)
+    end
+
+    # The template's Manifest.
+    def manifest
+      Convert.manifest(@handle.use(&:manifest))
+    end
+
+    # The content of a text file inside the template.
+    def source(path)
+      @handle.use { |template| template.source(path) }
+    end
+
+    # The content of a file inside the template, as a binary String.
+    def file(path)
+      @handle.use { |template| template.file(path) }
+    end
+
+    # Enable or disable the validation of JSON inputs against their schemas. Validation
+    # is enabled by default.
+    def validate_inputs=(validate)
+      @handle.use { |template| template.set_validate_inputs(validate ? true : false) }
+    end
+
+    # Free the template. Documents compiled from it stay usable.
+    def close
+      @handle.close
+    end
+  end
+
+  # A compiled document that can be exported repeatedly without compiling again.
+  class CompiledDocument
+    # PageSize of every page, in document order.
+    attr_reader :pages
+    # Warnings of the compilation, or nil.
+    attr_reader :warnings
+
+    # @api private
+    def initialize(object)
+      @pages = object.pages.map { |page| PageSize.new(width: page.width, height: page.height) }.freeze
+      @warnings = object.warnings
+      @handle = NativeHandle.new(object, :uniffi_oicana_uniffi_fn_free_compileddocument, "document")
+    end
+
+    # The number of pages.
+    def page_count
+      @pages.length
+    end
+
+    # Export the document as :pdf, :png or :svg. See Template#export for pages.
+    def export(format: :pdf, pixels_per_pt: 1.0, pages: nil)
+      native_format = Convert.format(format, pixels_per_pt)
+      native_pages = Convert.pages(pages)
+      @handle.use { |document| document.export(native_format, native_pages) }
+    end
+
+    # Export the document to PDF. Tagging is turned off when exporting a subset of pages.
+    def export_pdf(pages: nil)
+      export(format: :pdf, pages: pages)
+    end
+
+    # Export the document to PNG. Multiple pages are stacked vertically.
+    def export_png(pixels_per_pt: 1.0, pages: nil)
+      export(format: :png, pixels_per_pt: pixels_per_pt, pages: pages)
+    end
+
+    # Export the document to SVG.
+    def export_svg(pages: nil)
+      export(format: :svg, pages: pages)
+    end
+
+    # Free the document.
+    def close
+      @handle.close
+    end
+  end
+end

data/lib/oicana/types.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Oicana
+  # The value of a blob input. Metadata is passed to the template along with the data
+  # and must be a Hash, or nil for none.
+  BlobInput = Data.define(:data, :metadata) do
+    def initialize(data:, metadata: nil)
+      super
+    end
+  end
+
+  # Limits for reading a packed template. nil uses the default of Oicana.
+  ZipLimits = Data.define(:max_entries, :max_total_decompressed_bytes) do
+    def initialize(max_entries: nil, max_total_decompressed_bytes: nil)
+      super
+    end
+  end
+
+  # The size of a page in points.
+  PageSize = Data.define(:width, :height)
+
+  # A font face registered by the host. path is nil for fonts registered from memory.
+  RegisteredFont = Data.define(:family, :path)
+
+  # The result of Template.export_once. warnings is nil when there are none.
+  ExportOnceResult = Data.define(:document, :warnings)
+
+  # A template's manifest.
+  Manifest = Data.define(:package, :oicana)
+
+  # The Typst package a template is.
+  PackageInfo = Data.define(:name, :version, :entrypoint, :authors, :license, :description, :homepage,
+                            :repository)
+
+  # The Oicana configuration of a template. inputs holds JsonInputDefinition and
+  # BlobInputDefinition values in manifest order.
+  OicanaConfig = Data.define(:manifest_version, :inputs, :validate_json_inputs_by_default, :export, :fonts)
+
+  # An input taking a JSON value. default, development and schema name files in the template.
+  JsonInputDefinition = Data.define(:key, :required, :default, :development, :schema, :validate)
+
+  # An input taking arbitrary bytes. default and development are BlobFallback values or nil.
+  BlobInputDefinition = Data.define(:key, :required, :default, :development)
+
+  # A blob from the template, used when no value is supplied.
+  BlobFallback = Data.define(:file, :meta)
+
+  # How compiled documents are exported.
+  ExportConfig = Data.define(:pdf)
+
+  # How documents are exported to PDF.
+  PdfExportConfig = Data.define(:standards, :tagged)
+
+  # Fonts a template expects from its host.
+  FontConfig = Data.define(:require)
+
+  # @api private
+  # Conversions between the public types and the generated bindings.
+  module Convert
+    MODES = {
+      development: OicanaUniffi::CompilationMode::DEVELOPMENT,
+      production: OicanaUniffi::CompilationMode::PRODUCTION
+    }.freeze
+
+    module_function
+
+    def mode(mode)
+      MODES.fetch(mode) { raise ArgumentError, "unknown compilation mode #{mode.inspect}, use :development or :production" }
+    end
+
+    def format(format, pixels_per_pt)
+      case format
+      when :pdf then OicanaUniffi::ExportFormat::PDF.new
+      when :svg then OicanaUniffi::ExportFormat::SVG.new
+      when :png then OicanaUniffi::ExportFormat::PNG.new(Float(pixels_per_pt))
+      else raise ArgumentError, "unknown export format #{format.inspect}, use :pdf, :png or :svg"
+      end
+    end
+
+    def json_inputs(inputs)
+      inputs.to_h do |key, value|
+        [key.to_s, value.is_a?(String) ? utf8(value, key) : JSON.generate(value)]
+      end
+    end
+
+    # Binary strings, as read by File.binread or from HTTP bodies, are taken to be UTF-8.
+    def utf8(json, key)
+      json = json.encoding == Encoding::BINARY ? json.dup.force_encoding(Encoding::UTF_8) : json.encode(Encoding::UTF_8)
+      raise InvalidInputError, "the JSON input #{key.to_s.inspect} is not valid UTF-8" unless json.valid_encoding?
+
+      json
+    rescue EncodingError => e
+      raise InvalidInputError, "the JSON input #{key.to_s.inspect} cannot be converted to UTF-8: #{e.message}"
+    end
+
+    def blob_inputs(inputs)
+      inputs.to_h do |key, value|
+        blob = value.is_a?(BlobInput) ? value : BlobInput.new(data: value)
+        metadata = blob.metadata.nil? ? "{}" : JSON.generate(blob.metadata)
+        [key.to_s, OicanaUniffi::BlobInput.new(data: blob.data.b, metadata: metadata)]
+      end
+    end
+
+    def pages(pages)
+      return nil if pages.nil?
+
+      range = pages.is_a?(Integer) ? (pages..pages) : pages
+      raise ArgumentError, "pages must be an Integer or a Range, got #{pages.inspect}" unless range.is_a?(Range)
+
+      first = range.begin
+      last = range.end
+      last -= 1 if last && range.exclude_end?
+      [first, last].compact.each do |index|
+        raise InvalidInputError, "page indices must not be negative, got #{pages.inspect}" if index.negative?
+      end
+      OicanaUniffi::PageRange.new(start: first, _end: last)
+    end
+
+    def limits(limits)
+      return nil if limits.nil?
+
+      OicanaUniffi::ZipLimits.new(max_entries: limits.max_entries,
+                                  max_total_decompressed_bytes: limits.max_total_decompressed_bytes)
+    end
+
+    def manifest(json)
+      data = JSON.parse(json)
+      package = data.fetch("package")
+      oicana = data.fetch("oicana")
+      Manifest.new(
+        package: PackageInfo.new(**package.slice(*PackageInfo.members.map(&:to_s)).transform_keys(&:to_sym)),
+        oicana: OicanaConfig.new(
+          manifest_version: oicana.fetch("manifestVersion"),
+          inputs: oicana.fetch("inputs").map { |input| input_definition(input) },
+          validate_json_inputs_by_default: oicana.fetch("validateJsonInputsByDefault"),
+          export: ExportConfig.new(pdf: PdfExportConfig.new(standards: oicana.dig("export", "pdf", "standards"),
+                                                            tagged: oicana.dig("export", "pdf", "tagged"))),
+          fonts: FontConfig.new(require: oicana.dig("fonts", "require"))
+        )
+      )
+    end
+
+    def input_definition(input)
+      if input.fetch("type") == "json"
+        JsonInputDefinition.new(**input.slice(*JsonInputDefinition.members.map(&:to_s)).transform_keys(&:to_sym))
+      else
+        BlobInputDefinition.new(key: input.fetch("key"), required: input.fetch("required"),
+                                default: blob_fallback(input["default"]),
+                                development: blob_fallback(input["development"]))
+      end
+    end
+
+    def blob_fallback(fallback)
+      fallback && BlobFallback.new(file: fallback.fetch("file"), meta: fallback["meta"])
+    end
+  end
+end

data/lib/oicana/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Oicana
+  VERSION = "0.10.0.rc.1"
+end

data/lib/oicana.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative "oicana/version"
+require_relative "oicana/native"
+require_relative "oicana/oicana_uniffi"
+require_relative "oicana/errors"
+require_relative "oicana/types"
+require_relative "oicana/template"
+
+Oicana::Native.patch_bindings
+
+# Generate documents from Typst templates packed with the Oicana CLI.
+module Oicana
+  # Make fonts available to every template created afterwards. Takes the content of font
+  # files; data that holds no font is ignored. Returns the number of font faces added.
+  def self.register_fonts(*fonts)
+    OicanaUniffi.register_fonts(fonts.flatten.map(&:b))
+  end
+
+  # Make font files, or every font file in the given directories, available to every
+  # template created afterwards. Returns the number of font faces added.
+  def self.register_font_paths(*paths)
+    OicanaUniffi.register_font_paths(paths.flatten.map(&:to_s))
+  end
+
+  # The RegisteredFont faces registered with register_fonts or register_font_paths.
+  def self.registered_fonts
+    OicanaUniffi.registered_fonts.map { |font| RegisteredFont.new(family: font.family, path: font.path) }
+  end
+
+  # Drop all registered fonts. Existing templates keep the fonts they were created with.
+  def self.clear_fonts
+    OicanaUniffi.clear_fonts
+  end
+
+  # Set the coloring of compilation diagnostics for all templates: :none or :ansi.
+  def self.configure_diagnostic_color(color)
+    native = { none: OicanaUniffi::DiagnosticColor::NONE, ansi: OicanaUniffi::DiagnosticColor::ANSI }.fetch(color) do
+      raise ArgumentError, "unknown diagnostic color #{color.inspect}, use :none or :ansi"
+    end
+    OicanaUniffi.configure_diagnostic_color(native)
+  end
+
+  # Evict cache entries after each compilation that were not used within the last
+  # max_age evictions. nil disables the eviction, 0 clears the whole cache every time.
+  # The default is 10.
+  def self.configure_automatic_cache_eviction(max_age)
+    OicanaUniffi.configure_automatic_cache_eviction(max_age)
+  end
+
+  # Evict cache entries that were not used within the last max_age evictions.
+  def self.evict_cache(max_age)
+    OicanaUniffi.evict_cache(max_age)
+  end
+
+  # The version of the loaded native library.
+  def self.native_version
+    OicanaUniffi.version
+  end
+end

metadata

@@ -0,0 +1,66 @@
+--- !ruby/object:Gem::Specification
+name: oicana
+version: !ruby/object:Gem::Version
+  version: 0.10.0.rc.1
+platform: ruby
+authors:
+- Oicana
+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'
+email:
+- hello@oicana.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.md
+- README.md
+- lib/oicana.rb
+- lib/oicana/errors.rb
+- lib/oicana/native.rb
+- lib/oicana/oicana_uniffi.rb
+- lib/oicana/template.rb
+- lib/oicana/types.rb
+- lib/oicana/version.rb
+homepage: https://oicana.com
+licenses:
+- PolyForm-Noncommercial-1.0.0
+metadata:
+  source_code_uri: https://github.com/oicana/oicana/tree/main/integrations/ruby
+  documentation_uri: https://oicana.com/docs
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Generate typeset PDFs in Ruby from Typst templates, in process. No headless
+  browser, no per-document fees.
+test_files: []