asciidoctor-latexmath 1.0.0.beta.2 → 2.0.0.alpha.1

data/lib/asciidoctor/latexmath/command_runner.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+
+module Asciidoctor
+  module Latexmath
+    class CommandRunner
+      Result = Struct.new(:stdout, :stderr, :exit_status, :duration, keyword_init: true)
+
+      class << self
+        attr_writer :backend
+
+        def backend
+          @backend ||= SystemRunner.new
+        end
+
+        def run(command, timeout:, chdir:, env: {}, stdin: nil)
+          backend.run(command, timeout: timeout, chdir: chdir, env: env, stdin: stdin)
+        end
+
+        def with_backend(temp_backend)
+          previous = backend
+          self.backend = temp_backend
+          yield
+        ensure
+          self.backend = previous
+        end
+      end
+
+      class NullRunner
+        def run(_command, timeout:, **_rest)
+          raise ArgumentError, "timeout must be positive" unless timeout&.positive?
+
+          Result.new(stdout: "", stderr: "", exit_status: 0, duration: 0.0)
+        end
+      end
+
+      class SystemRunner
+        DEFAULT_WAIT_INTERVAL = 0.05
+        KILL_GRACE_SECONDS = 2.0
+
+        def run(command, timeout:, chdir:, env: {}, stdin: nil)
+          raise ArgumentError, "timeout must be positive" unless timeout&.positive?
+
+          start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          stdout_read, stdout_write = IO.pipe
+          stderr_read, stderr_write = IO.pipe
+
+          spawn_options = {
+            chdir: chdir,
+            out: stdout_write,
+            err: stderr_write,
+            pgroup: true
+          }
+
+          pid = Process.spawn(env, *command, spawn_options)
+          stdout_write.close
+          stderr_write.close
+
+          stdout_thread = Thread.new { stdout_read.read }
+          stderr_thread = Thread.new { stderr_read.read }
+
+          wait_with_timeout(pid, timeout)
+
+          exit_status = $?.exitstatus
+          stdout_output = stdout_thread.value
+          stderr_output = stderr_thread.value
+          duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+
+          Result.new(stdout: stdout_output, stderr: stderr_output, exit_status: exit_status, duration: duration)
+        rescue Errno::ENOENT => error
+          raise StageFailureError, "Executable not found: #{error.message.split.last}"
+        ensure
+          stdout_read&.close unless stdout_read&.closed?
+          stderr_read&.close unless stderr_read&.closed?
+        end
+
+        private
+
+        def wait_with_timeout(pid, timeout)
+          deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+
+          loop do
+            result = Process.wait(pid, Process::WNOHANG)
+            return result if result
+
+            if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+              terminate_process_group(pid)
+              raise RenderTimeoutError, "command timed out after #{timeout}s"
+            end
+
+            sleep(DEFAULT_WAIT_INTERVAL)
+          end
+        end
+
+        def terminate_process_group(pid)
+          Process.kill("TERM", -pid)
+          grace_deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + KILL_GRACE_SECONDS
+
+          loop do
+            result = Process.wait(pid, Process::WNOHANG)
+            return result if result
+
+            break if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= grace_deadline
+
+            sleep(DEFAULT_WAIT_INTERVAL)
+          end
+
+          Process.kill("KILL", -pid)
+          Process.wait(pid)
+        rescue Errno::ESRCH, Errno::ECHILD
+        end
+      end
+    end
+  end
+end

data/lib/asciidoctor/latexmath/converters/html5.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "asciidoctor/converter/html5"
+
+require_relative "../html_builder"
+require_relative "../renderer_service"
+
+module Asciidoctor
+  module Latexmath
+    module Converters
+      module Html5
+        def convert_stem(node)
+          if latexmath_block?(node)
+            convert_latexmath_block(node)
+          else
+            super
+          end
+        end
+
+        def convert_inline_quoted(node)
+          if latexmath_inline?(node)
+            convert_latexmath_inline(node)
+          else
+            super
+          end
+        end
+
+        private
+
+        def latexmath_block?(node)
+          node.style == "latexmath"
+        end
+
+        def latexmath_inline?(node)
+          node.type == :latexmath
+        end
+
+        def convert_latexmath_block(node)
+          result = latexmath_renderer_service(node.document)
+            .render_block_content(node.parent || node.document, node.source, safe_attributes(node.attributes))
+
+          return result.placeholder_html if result.type == :placeholder
+
+          HtmlBuilder.block_html(node, result)
+        end
+
+        def convert_latexmath_inline(node)
+          result = latexmath_renderer_service(node.document)
+            .render_inline_content(node.parent || node.document, node.text, safe_attributes(node.attributes))
+
+          return result.placeholder_html if result.type == :placeholder
+
+          HtmlBuilder.inline_html(node, result)
+        end
+
+        def latexmath_renderer_service(document)
+          document.instance_variable_get(:@latexmath_renderer_service) || begin
+            service = RendererService.new(document)
+            document.instance_variable_set(:@latexmath_renderer_service, service)
+            service
+          end
+        end
+
+        def safe_attributes(attrs)
+          attrs ? attrs.dup : {}
+        end
+      end
+    end
+  end
+end
+
+Asciidoctor::Converter::Html5Converter.prepend(Asciidoctor::Latexmath::Converters::Html5)

data/lib/asciidoctor/latexmath/errors.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Shuai Zhang
+#
+# SPDX-License-Identifier: LGPL-3.0-or-later WITH LGPL-3.0-linking-exception
+
+module Asciidoctor
+  module Latexmath
+    class LatexmathError < StandardError; end
+
+    class UnsupportedFormatError < LatexmathError; end
+
+    class MissingToolError < LatexmathError
+      attr_reader :tool
+
+      def initialize(tool, message = nil)
+        @tool = tool
+        super(message || "Missing required tool: #{tool}")
+      end
+    end
+
+    class InvalidAttributeError < LatexmathError; end
+
+    class UnsupportedValueError < InvalidAttributeError
+      attr_reader :category, :subject, :value, :supported, :hints
+
+      def initialize(category:, subject:, value:, supported:, hint: nil)
+        @category = category
+        @subject = subject
+        @value = value
+        @supported = supported
+        @hints = Array(hint).compact
+        super(build_message)
+      end
+
+      private
+
+      def build_message
+        descriptor = subject ? "#{subject}=#{present_value}" : present_value
+        base = "unsupported #{category}: '#{descriptor}' (supported: #{formatted_supported})"
+        hints.empty? ? base : "#{base}\nhint: #{formatted_hints}"
+      end
+
+      def present_value
+        (value.nil? || value.to_s.empty?) ? "<empty>" : value.to_s
+      end
+
+      def formatted_supported
+        case supported
+        when Array
+          values = supported.map { |entry| entry.to_s.strip }.reject(&:empty?)
+          values.sort_by { |entry| entry.downcase }.join(", ")
+        else
+          supported.to_s
+        end
+      end
+
+      def formatted_hints
+        hints.map(&:to_s).reject(&:empty?).join("; ")
+      end
+    end
+
+    class TargetConflictError < LatexmathError; end
+
+    class RenderTimeoutError < LatexmathError; end
+
+    class StageFailureError < LatexmathError; end
+
+    module ErrorHandling
+      class Policy
+        attr_reader :mode
+
+        def initialize(mode)
+          @mode = mode
+        end
+
+        def abort?
+          mode == :abort
+        end
+
+        def log?
+          mode == :log
+        end
+
+        alias_method :abort, :abort?
+        alias_method :log, :log?
+      end
+
+      SUPPORTED_POLICIES = {
+        abort: Policy.new(:abort),
+        log: Policy.new(:log)
+      }.freeze
+
+      def self.policy(name)
+        SUPPORTED_POLICIES.fetch(name.to_sym) do
+          raise ArgumentError, "Unknown on-error policy: #{name}"
+        end
+      end
+
+      module Placeholder
+        HTML_HEADER = %(<pre class="highlight latexmath-error" role="note" data-latex-error="1">)
+        HTML_FOOTER = "</pre>"
+
+        def self.render(message:, command:, stdout:, stderr:, source:, latex_source:)
+          body = [
+            "Error: #{message}",
+            "Command: #{command}",
+            "Stdout: #{present_or_placeholder(stdout)}",
+            "Stderr: #{present_or_placeholder(stderr)}",
+            "Source (AsciiDoc): #{source}",
+            "Source (LaTeX): #{latex_source}"
+          ].join("\n")
+
+          <<~HTML.rstrip
+            #{HTML_HEADER}
+            #{escape_html(body)}
+            #{HTML_FOOTER}
+          HTML
+        end
+
+        def self.present_or_placeholder(value)
+          return "<empty>" if value.nil? || value.to_s.empty?
+
+          value
+        end
+
+        def self.escape_html(text)
+          text.to_s.gsub("&", "&amp;").gsub("<", "&lt;").gsub(">", "&gt;")
+        end
+        private_class_method :escape_html, :present_or_placeholder
+      end
+    end
+  end
+end

data/lib/asciidoctor/latexmath/html_builder.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+module Asciidoctor
+  module Latexmath
+    module HtmlBuilder
+      LINE_FEED = "\n"
+
+      module_function
+
+      def block_html(node, result)
+        attrs = result.attributes.dup
+        target = attrs.delete("target") || result.target
+        alt_text = attrs.delete("alt") || result.alt_text || ""
+        original = attrs.delete("data-latex-original") || result.alt_text || ""
+        role_attr = attrs.delete("role") || "math"
+        width = attrs.delete("width")
+        height = attrs.delete("height")
+
+        residual_attrs = attrs.except("format")
+
+        classes = ["imageblock"]
+        classes.concat(node.roles) if node.respond_to?(:roles)
+        classes << "math" unless classes.include?("math")
+        class_value = classes.reject(&:empty?).uniq.join(" ")
+
+        div_attrs = []
+        div_attrs << %(id="#{escape_html_attribute(node.id)}") if node.id
+        div_attrs << %(class="#{escape_html_attribute(class_value)}") unless class_value.empty?
+        div_attrs << %(role="#{escape_html_attribute(role_attr)}") if role_attr
+        div_attrs << %(data-latex-original="#{escape_html_attribute(original)}") unless original.to_s.empty?
+        if node.respond_to?(:attr) && (align = node.attr("align"))
+          div_attrs << %(style="text-align: #{escape_html_attribute(align)};")
+        end
+
+        img_attrs = []
+        img_attrs << %(src="#{escape_html_attribute(target)}") if target
+        img_attrs << %(alt="#{escape_html_attribute(alt_text)}") unless alt_text.to_s.empty?
+        img_attrs << %(role="#{escape_html_attribute(role_attr)}") if role_attr
+        img_attrs << %(data-latex-original="#{escape_html_attribute(original)}") unless original.to_s.empty?
+        img_attrs << %(width="#{escape_html_attribute(width)}") if width
+        img_attrs << %(height="#{escape_html_attribute(height)}") if height
+        residual_attrs.each do |key, value|
+          next if value.nil?
+
+          img_attrs << %(#{key}="#{escape_html_attribute(value)}")
+        end
+
+        div_attr_string = div_attrs.empty? ? "" : " " + div_attrs.join(" ")
+        lines = []
+        lines << %(<div#{div_attr_string}>)
+        if node.respond_to?(:title?) && node.title?
+          caption = node.respond_to?(:captioned_title) ? node.captioned_title : node.title
+          lines << %(<div class="title">#{caption}</div>)
+        end
+        lines << %(<div class="content">)
+        lines << %(<img #{img_attrs.join(" ")}>)
+        lines << %(</div>)
+        lines << %(</div>)
+        lines.join(LINE_FEED)
+      end
+
+      def inline_html(node, result)
+        attrs = result.attributes.dup
+        target = attrs.delete("target") || result.target
+        alt_text = attrs.delete("alt") || result.alt_text || ""
+        role_attr = attrs.delete("role") || "math"
+        original = attrs.delete("data-latex-original") || result.alt_text || ""
+        width = attrs.delete("width")
+        height = attrs.delete("height")
+
+        classes = ["image"]
+        classes.concat(role_attr.to_s.split) if role_attr
+        if node.respond_to?(:role) && node.role
+          classes.concat(node.role.to_s.split)
+        end
+        classes << "math" unless classes.include?("math")
+        span_class = classes.reject(&:empty?).uniq.join(" ")
+
+        img_attrs = []
+        img_attrs << %(src="#{escape_html_attribute(target)}") if target
+        img_attrs << %(alt="#{escape_html_attribute(alt_text)}") unless alt_text.to_s.empty?
+        img_attrs << %(role="#{escape_html_attribute(role_attr)}") if role_attr
+        img_attrs << %(data-latex-original="#{escape_html_attribute(original)}") unless original.to_s.empty?
+        img_attrs << %(width="#{escape_html_attribute(width)}") if width
+        img_attrs << %(height="#{escape_html_attribute(height)}") if height
+        attrs.each do |key, value|
+          next if key == "format" || value.nil?
+
+          img_attrs << %(#{key}="#{escape_html_attribute(value)}")
+        end
+
+        span_attr = span_class.empty? ? "" : %( class="#{escape_html_attribute(span_class)}")
+        %(<span#{span_attr}><img #{img_attrs.join(" ")}></span>)
+      end
+
+      def escape_html_attribute(value)
+        ::CGI.escapeHTML(value.to_s)
+      end
+    end
+  end
+end

data/lib/asciidoctor/latexmath/math_expression.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Shuai Zhang
+#
+# SPDX-License-Identifier: LGPL-3.0-or-later WITH LGPL-3.0-linking-exception
+
+module Asciidoctor
+  module Latexmath
+    class MathExpression
+      attr_reader :content, :entry_type, :target_basename, :attributes, :options, :location
+
+      def initialize(content:, entry_type:, target_basename: nil, attributes: {}, options: [], location: nil)
+        @content = content
+        @entry_type = entry_type
+        @target_basename = target_basename
+        @attributes = attributes
+        @options = options
+        @location = location
+      end
+    end
+  end
+end

data/lib/asciidoctor/latexmath/path_utils.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module Asciidoctor
+  module Latexmath
+    module PathUtils
+      module_function
+
+      def normalize_separators(path)
+        return path unless path.is_a?(String) || path.is_a?(Symbol)
+
+        path.to_s.tr("\\", "/")
+      end
+
+      def absolute_path?(path)
+        return false if path.nil?
+
+        normalized = normalize_separators(path).to_s
+        return false if normalized.empty?
+
+        normalized.start_with?("/", "~") ||
+          normalized.match?(/\A[A-Za-z]:\//) ||
+          normalized.start_with?("//")
+      end
+
+      def expand_path(path, base_dir)
+        return nil if path.nil?
+
+        normalized_path = normalize_separators(path)
+        normalized_base = normalize_separators(base_dir || Dir.pwd)
+
+        if absolute_path?(normalized_path)
+          File.expand_path(normalized_path)
+        else
+          File.expand_path(normalized_path, normalized_base)
+        end
+      end
+
+      def clean_join(*parts)
+        normalized_parts = parts.compact.map { |part| normalize_separators(part) }
+        File.join(*normalized_parts)
+      end
+    end
+  end
+end

data/lib/asciidoctor/latexmath/processors/block_processor.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Shuai Zhang
+#
+# SPDX-License-Identifier: LGPL-3.0-or-later WITH LGPL-3.0-linking-exception
+
+require "asciidoctor"
+require "asciidoctor/extensions"
+
+require_relative "../renderer_service"
+
+module Asciidoctor
+  module Latexmath
+    module Processors
+      class BlockProcessor < ::Asciidoctor::Extensions::BlockProcessor
+        use_dsl
+
+        named :latexmath
+        on_context :listing, :literal, :open, :pass, :paragraph, :stem
+        parse_content_as :raw
+
+        def process(parent, reader, attrs)
+          result = renderer_service(parent).render_block(parent, reader, attrs)
+          return create_block(parent, :pass, result.placeholder_html, {}) if result.type == :placeholder
+
+          create_image_block(parent, build_block_attributes(result, attrs))
+        end
+
+        private
+
+        def renderer_service(parent)
+          document = parent.document
+          document.instance_variable_get(:@latexmath_renderer_service) || begin
+            service = RendererService.new(document)
+            document.instance_variable_set(:@latexmath_renderer_service, service)
+            service
+          end
+        end
+
+        def build_block_attributes(result, original_attrs)
+          attributes = result.attributes.dup
+          attributes["target"] ||= result.target
+          attributes["alt"] = sanitize_alt(fetch_attr(original_attrs, :alt), result.alt_text)
+          attributes["data-latex-original"] = result.alt_text
+          attributes["role"] = merge_roles(attributes["role"], fetch_attr(original_attrs, :role))
+          if (align = fetch_attr(original_attrs, :align))
+            attributes["align"] = align
+          end
+          attributes
+        end
+
+        def fetch_attr(attrs, name)
+          return nil unless attrs
+
+          attrs[name.to_s] || attrs[name]
+        end
+
+        def sanitize_alt(user_value, fallback)
+          return fallback if user_value.nil?
+
+          value = user_value.to_s
+          value.empty? ? fallback : value
+        end
+
+        def merge_roles(existing_role, additional_role)
+          existing = existing_role.to_s.split
+          additional = additional_role.to_s.split
+          combined = (existing + additional).uniq
+          combined.empty? ? nil : combined.join(" ")
+        end
+      end
+    end
+  end
+end

data/lib/asciidoctor/latexmath/processors/inline_macro_processor.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Shuai Zhang
+#
+# SPDX-License-Identifier: LGPL-3.0-or-later WITH LGPL-3.0-linking-exception
+
+require "asciidoctor"
+require "asciidoctor/extensions"
+
+require_relative "../renderer_service"
+
+module Asciidoctor
+  module Latexmath
+    module Processors
+      class InlineMacroProcessor < ::Asciidoctor::Extensions::InlineMacroProcessor
+        use_dsl
+
+        named :latexmath
+
+        def process(parent, target, attrs)
+          content = attrs["text"] || target
+          result = renderer_service(parent).render_inline_content(parent, content, attrs)
+          return create_inline(parent, :quoted, result.placeholder_html) if result.type == :placeholder
+
+          create_inline(parent, :image, nil, build_inline_attributes(result, attrs))
+        end
+
+        private
+
+        def renderer_service(parent)
+          document = parent.document
+          document.instance_variable_get(:@latexmath_renderer_service) || begin
+            service = RendererService.new(document)
+            document.instance_variable_set(:@latexmath_renderer_service, service)
+            service
+          end
+        end
+
+        def build_inline_attributes(result, original_attrs)
+          attributes = result.attributes.dup
+          attributes["target"] ||= result.target
+          attributes["alt"] = sanitize_alt(fetch_attr(original_attrs, :alt), result.alt_text)
+          attributes["data-latex-original"] = result.alt_text
+          attributes["role"] = merge_roles(attributes["role"], fetch_attr(original_attrs, :role))
+          attributes
+        end
+
+        def fetch_attr(attrs, name)
+          return nil unless attrs
+
+          attrs[name.to_s] || attrs[name]
+        end
+
+        def sanitize_alt(user_value, fallback)
+          return fallback if user_value.nil?
+
+          value = user_value.to_s
+          value.empty? ? fallback : value
+        end
+
+        def merge_roles(existing_role, additional_role)
+          existing = existing_role.to_s.split
+          additional = additional_role.to_s.split
+          combined = (existing + additional).uniq
+          combined.empty? ? nil : combined.join(" ")
+        end
+      end
+    end
+  end
+end

data/lib/asciidoctor/latexmath/processors/statistics_postprocessor.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "asciidoctor"
+require "asciidoctor/extensions"
+
+module Asciidoctor
+  module Latexmath
+    module Processors
+      class StatisticsPostprocessor < ::Asciidoctor::Extensions::Postprocessor
+        def process(document, output)
+          service = document.instance_variable_get(:@latexmath_renderer_service)
+          service&.send(:flush_statistics)
+          output
+        end
+      end
+    end
+  end
+end

data/lib/asciidoctor/latexmath/render_request.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Shuai Zhang
+#
+# SPDX-License-Identifier: LGPL-3.0-or-later WITH LGPL-3.0-linking-exception
+
+module Asciidoctor
+  module Latexmath
+    class RenderRequest
+      attr_reader :expression, :format, :engine, :preamble, :fontsize, :ppi, :timeout, :keep_artifacts,
+        :nocache, :cachedir, :artifacts_dir, :tool_overrides, :content_hash, :preamble_hash, :fontsize_hash
+
+      def initialize(expression:, format:, engine:, preamble:, fontsize:, ppi:, timeout:, keep_artifacts:, nocache:, cachedir:, artifacts_dir:, tool_overrides:, content_hash:, preamble_hash:, fontsize_hash:)
+        @expression = expression
+        @format = format
+        @engine = engine
+        @preamble = preamble
+        @fontsize = fontsize
+        @ppi = ppi
+        @timeout = timeout
+        @keep_artifacts = keep_artifacts
+        @nocache = nocache
+        @cachedir = cachedir
+        @artifacts_dir = artifacts_dir
+        @tool_overrides = tool_overrides
+        @content_hash = content_hash
+        @preamble_hash = preamble_hash
+        @fontsize_hash = fontsize_hash
+      end
+    end
+  end
+end