metanorma-plugin-plantuml 1.0.0

data/lib/metanorma/plugin/plantuml/backend.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "fileutils"
+require_relative "wrapper"
+require_relative "utils"
+require_relative "errors"
+
+module Metanorma
+  module Plugin
+    module Plantuml
+      # Backend class for PlantUML diagram generation
+      # Adapted from metanorma-standoc's PlantUMLBlockMacroBackend
+      class Backend
+        class << self
+          def plantuml_installed?
+            unless Wrapper.available?
+              raise "PlantUML not installed"
+            end
+          end
+
+          def plantuml_available?
+            Wrapper.available?
+          end
+
+          def generate_file(parent, reader, format_override = nil)
+            ldir, imagesdir, fmt = generate_file_prep(parent)
+            fmt = format_override if format_override
+            plantuml_content = prep_source(reader)
+
+            # Extract filename from PlantUML source if specified
+            extracted_filename = extract_plantuml_filename(plantuml_content)
+
+            absolute_path, relative_path = path_prep(ldir, imagesdir)
+            filename = extracted_filename ? "#{extracted_filename}.#{fmt}" : generate_unique_filename(fmt)
+            output_file = File.join(absolute_path, filename)
+
+            result = Wrapper.generate(
+              plantuml_content,
+              format: fmt,
+              output_file: output_file
+            )
+
+            unless result[:success]
+              raise "No image output from PlantUML: #{result[:error].message}"
+            end
+
+            File.join(relative_path, filename)
+          end
+
+          def generate_multiple_files(parent, reader, formats, attrs)
+            # Generate files for each format
+            filenames = formats.map do |format|
+              generate_file(parent, reader, format)
+            end
+
+            # Return data for BlockProcessor to create image block
+            through_attrs = generate_attrs attrs
+            through_attrs["target"] = filenames.first
+
+            # Store additional formats for potential future use
+            through_attrs["data-formats"] = formats.join(",")
+            through_attrs["data-files"] = filenames.join(",")
+
+            through_attrs
+          end
+
+          def generate_file_prep(parent)
+            ldir = localdir(parent)
+            imagesdir = parent.document.attr("imagesdir")
+            fmt = parent.document.attr("plantuml-image-format")&.strip&.downcase || "png"
+            [ldir, imagesdir, fmt]
+          end
+
+          def localdir(parent)
+            ret = Utils.localdir(parent.document)
+            File.writable?(ret) or
+              raise "Destination directory #{ret} not writable for PlantUML!"
+            ret
+          end
+
+          def path_prep(localdir, imagesdir)
+            path = Pathname.new(File.join(localdir, "_plantuml_images"))
+            sourcepath = imagesdir ? File.join(localdir, imagesdir) : localdir
+            path.mkpath
+            File.writable?(path) or
+              raise "Destination path #{path} not writable for PlantUML!"
+            [path, Pathname.new(path).relative_path_from(Pathname.new(sourcepath)).to_s]
+          end
+
+          def prep_source(reader)
+            src = reader.source
+
+            # Validate that we have matching start/end pairs
+            validate_plantuml_delimiters(src)
+            src
+          end
+
+          def generate_attrs(attrs)
+            %w(id align float title role width height alt)
+              .inject({}) do |memo, key|
+              memo[key] = attrs[key] if attrs.has_key?(key)
+              memo
+            end
+          end
+
+          private
+
+          def validate_plantuml_delimiters(src)
+            # Find @start... pattern (case insensitive, support all PlantUML diagram types)
+            start_match = src.match(/^@start(\w+)/i)
+            unless start_match
+              raise "PlantUML content must start with @start... directive!"
+            end
+
+            diagram_type = start_match[1].downcase
+            end_pattern = "@end#{diagram_type}"
+
+            # Look for matching @end... directive (case insensitive)
+            unless src.match(/#{Regexp.escape(end_pattern)}\s*$/mi)
+              raise "@start#{diagram_type} without matching #{end_pattern} in PlantUML!"
+            end
+          end
+
+          def extract_plantuml_filename(plantuml_content)
+            # Extract filename from any @start... line if specified
+            # Only match when filename is on the same line as @start... (no newlines)
+            lines = plantuml_content.lines
+            first_line = lines.first&.strip
+            return nil unless first_line
+
+            match = first_line.match(/^@start\w+\s+(.+)$/i)
+            return nil unless match
+
+            filename = match[1].strip
+            return nil if filename.nil? || filename.empty?
+
+            # Sanitize filename for filesystem use
+            sanitize_filename(filename)
+          end
+
+          def sanitize_filename(filename)
+            # Remove quotes and sanitize for filesystem
+            filename = filename.gsub(/^["']|["']$/, "")
+            # Replace any non-alphanumeric characters (except dash, underscore, dot) with underscore
+            filename.gsub(/[^\w\-.]/, "_")
+                    .gsub(/\.{2,}/, "_")  # Replace multiple dots with underscore
+                    .gsub(/_{2,}/, "_")   # Replace multiple underscores with single
+                    .gsub(/^[_\-\.]+|[_\-\.]+$/, "")  # Remove leading/trailing special chars
+          end
+
+          def generate_unique_filename(format)
+            timestamp = Time.now.strftime("%Y%m%d_%H%M%S_%L")
+            "plantuml_#{timestamp}.#{format}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/metanorma/plugin/plantuml/block_processor.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "asciidoctor"
+require "asciidoctor/extensions"
+require_relative "backend"
+
+module Metanorma
+  module Plugin
+    module Plantuml
+      # PlantUML block processor for Asciidoctor
+      class BlockProcessor < ::Asciidoctor::Extensions::BlockProcessor
+        use_dsl
+        named :plantuml
+        on_context :literal
+        parse_content_as :raw
+
+        def abort(parent, reader, attrs, msg)
+          warn msg
+          attrs["language"] = "plantuml"
+          create_listing_block(
+            parent,
+            reader.source,
+            (attrs.reject { |k, _v| k.to_s.match?(/^\d+$/) })
+          )
+        end
+
+        def process(parent, reader, attrs)
+          # Check for document-level disable flag
+          if parent.document.attr("plantuml-disabled")
+            return abort(parent, reader, attrs, "PlantUML processing disabled")
+          end
+
+          # Check PlantUML availability explicitly
+          unless Backend.plantuml_available?
+            return abort(parent, reader, attrs, "PlantUML not installed")
+          end
+
+          # Parse format specifications
+          formats = parse_formats(attrs, parent.document)
+
+          if formats.length == 1
+            # Single format - original behavior
+            filename = Backend.generate_file(parent, reader, formats.first)
+            through_attrs = Backend.generate_attrs attrs
+            through_attrs["target"] = filename
+            create_image_block parent, through_attrs
+          else
+            # Multiple formats - generate multiple files
+            through_attrs = Backend.generate_multiple_files(parent, reader, formats, attrs)
+            create_image_block parent, through_attrs
+          end
+        rescue StandardError => e
+          abort(parent, reader, attrs, e.message)
+        end
+
+        private
+
+        def parse_formats(attrs, document)
+          # Check for formats attribute (multiple formats)
+          if attrs["formats"]
+            formats = attrs["formats"].split(",").map(&:strip).map(&:downcase)
+            return formats.select { |f| valid_format?(f) }
+          end
+
+          # Check for format attribute (single format override)
+          if attrs["format"]
+            format = attrs["format"].strip.downcase
+            return [format] if valid_format?(format)
+          end
+
+          # Fall back to document attribute or default
+          default_format = document.attr("plantuml-image-format")&.strip&.downcase || "png"
+          [default_format]
+        end
+
+        def valid_format?(format)
+          %w[png svg pdf txt eps].include?(format)
+        end
+      end
+    end
+  end
+end

data/lib/metanorma/plugin/plantuml/config.rb

@@ -0,0 +1,48 @@
+require "rbconfig"
+
+module Metanorma
+  module Plugin
+    module Plantuml
+      class Config
+        attr_accessor :java_path, :memory_limit, :output_dir, :temp_dir
+
+        def initialize
+          @java_path = "java"
+          @memory_limit = "1024m"
+          @output_dir = nil
+          @temp_dir = nil
+        end
+
+        def jvm_options
+          options = [
+            "-Xss5m",
+            "-Xmx#{memory_limit}",
+            "-Djava.awt.headless=true"
+          ]
+
+          if RbConfig::CONFIG["host_os"].match?(/darwin|mac os/)
+            options << "-Dapple.awt.UIElement=true"
+          end
+
+          options
+        end
+
+        def java_command
+          [java_path, *jvm_options]
+        end
+      end
+
+      class << self
+        attr_writer :configuration
+      end
+
+      def self.configuration
+        @configuration ||= Config.new
+      end
+
+      def self.configure
+        yield(configuration)
+      end
+    end
+  end
+end

data/lib/metanorma/plugin/plantuml/errors.rb

@@ -0,0 +1,42 @@
+module Metanorma
+  module Plugin
+    module Plantuml
+      class PlantumlError < StandardError
+        def initialize(message = nil, original_error = nil)
+          super(message)
+          @original_error = original_error
+        end
+
+        attr_reader :original_error
+      end
+
+      class JarNotFoundError < PlantumlError
+        def initialize(jar_path = nil)
+          message = jar_path ?
+            "PlantUML JAR file not found at: #{jar_path}" :
+            "PlantUML JAR file not found"
+          super(message)
+        end
+      end
+
+      class JavaNotFoundError < PlantumlError
+        def initialize
+          super("Java runtime not found. Please ensure Java is installed and available in PATH")
+        end
+      end
+
+      class GenerationError < PlantumlError
+        def initialize(message, java_error = nil)
+          super("PlantUML generation failed: #{message}")
+          @original_error = java_error
+        end
+      end
+
+      class InvalidFormatError < PlantumlError
+        def initialize(format, available_formats)
+          super("Invalid format '#{format}'. Available formats: #{available_formats.join(', ')}")
+        end
+      end
+    end
+  end
+end

data/lib/metanorma/plugin/plantuml/utils.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "liquid"
+require "pathname"
+
+module Metanorma
+  module Plugin
+    module Plantuml
+      module Utils
+        class << self
+          def localdir(document)
+            document.attributes["localdir"] ||
+              document.attributes["docdir"] ||
+              File.dirname(document.attributes["docfile"] || ".")
+          end
+
+          def relative_file_path(document, file_path)
+            return file_path if Pathname.new(file_path).absolute?
+
+            docdir = document.attributes["docdir"] || Dir.pwd
+            File.expand_path(file_path, docdir)
+          end
+
+        end
+      end
+    end
+  end
+end

data/lib/metanorma/plugin/plantuml/version.rb

@@ -0,0 +1,8 @@
+module Metanorma
+  module Plugin
+    module Plantuml
+      VERSION = "1.0.0"
+      PLANTUML_JAR_VERSION = "1.2025.4"
+    end
+  end
+end

data/lib/metanorma/plugin/plantuml/wrapper.rb

@@ -0,0 +1,256 @@
+require "open3"
+require "base64"
+require "tempfile"
+require "fileutils"
+require "tmpdir"
+require "rbconfig"
+require_relative "version"
+require_relative "errors"
+require_relative "config"
+
+module Metanorma
+  module Plugin
+    module Plantuml
+      class Wrapper
+        PLANTUML_JAR_NAME = "plantuml.jar"
+        PLANTUML_JAR_PATH = File.join(File.dirname(__FILE__), "..", "..", "..", "..", "data", PLANTUML_JAR_NAME)
+
+        SUPPORTED_FORMATS = %w[png svg pdf txt eps].freeze
+        DEFAULT_FORMAT = "png"
+
+        class << self
+          def jvm_options
+            options = ["-Xss5m", "-Xmx1024m"]
+
+            if RbConfig::CONFIG["host_os"].match?(/darwin|mac os/)
+              options << "-Dapple.awt.UIElement=true"
+            end
+
+            options
+          end
+
+          def generate(content, format: DEFAULT_FORMAT, output_file: nil, base64: false, **options)
+            validate_format!(format)
+            ensure_jar_available!
+            ensure_java_available!
+
+            result = if output_file
+                       generate_to_file(content, format, output_file, options)
+                     elsif base64
+                       generate_to_base64(content, format, options)
+                     else
+                       generate_to_temp_file(content, format, options)
+                     end
+
+            { success: true }.merge(result)
+          rescue PlantumlError => e
+            { success: false, error: e }
+          end
+
+          def generate_from_file(input_file, format: DEFAULT_FORMAT, output_file: nil, base64: false, **options)
+            unless File.exist?(input_file)
+              raise GenerationError.new("Input file not found: #{input_file}")
+            end
+
+            content = File.read(input_file)
+            generate(content, format: format, output_file: output_file, base64: base64, **options)
+          end
+
+          def version
+            return nil unless available?
+
+            cmd = [configuration.java_path, *jvm_options, "-jar", PLANTUML_JAR_PATH, "-version"]
+            output, error, status = Open3.capture3(*cmd)
+
+            if status.success?
+              # Extract version from output
+              version_match = output.match(/PlantUML version ([\d.]+)/)
+              version_match ? version_match[1] : PLANTUML_JAR_VERSION
+            else
+              nil
+            end
+          rescue StandardError
+            nil
+          end
+
+          def available?
+            return false if ENV["PLANTUML_DISABLED"] == "true"
+            File.exist?(PLANTUML_JAR_PATH) && java_available?
+          end
+
+          def jar_path
+            PLANTUML_JAR_PATH
+          end
+
+          private
+
+          def configuration
+            Plantuml.configuration
+          end
+
+          def validate_format!(format)
+            format_str = format.to_s.downcase
+            unless SUPPORTED_FORMATS.include?(format_str)
+              raise InvalidFormatError.new(format, SUPPORTED_FORMATS)
+            end
+          end
+
+          def ensure_jar_available!
+            unless File.exist?(PLANTUML_JAR_PATH)
+              raise JarNotFoundError.new(PLANTUML_JAR_PATH)
+            end
+          end
+
+          def ensure_java_available!
+            unless java_available?
+              raise JavaNotFoundError.new
+            end
+          end
+
+          def java_available?
+            cmd = [configuration.java_path, "-version"]
+            _, _, status = Open3.capture3(*cmd)
+            status.success?
+          rescue StandardError
+            false
+          end
+
+          def generate_to_file(content, format, output_file, options)
+            output_dir = File.dirname(output_file)
+            FileUtils.mkdir_p(output_dir) unless Dir.exist?(output_dir)
+
+            execute_plantuml(content, format, output_file, options)
+
+            unless File.exist?(output_file)
+              raise GenerationError.new("Output file was not created: #{output_file}")
+            end
+
+            { output_path: File.expand_path(output_file) }
+          end
+
+          def generate_to_base64(content, format, options)
+            Tempfile.create(['plantuml_output', ".#{format}"]) do |temp_file|
+              temp_file.close
+
+              execute_plantuml(content, format, temp_file.path, options)
+
+              unless File.exist?(temp_file.path)
+                raise GenerationError.new("Temporary output file was not created")
+              end
+
+              encoded_content = Base64.strict_encode64(File.read(temp_file.path))
+              { base64: encoded_content }
+            end
+          end
+
+          def generate_to_temp_file(content, format, options)
+            temp_dir = configuration.temp_dir || Dir.tmpdir
+            timestamp = Time.now.strftime("%Y%m%d_%H%M%S_%L")
+            output_file = File.join(temp_dir, "plantuml_#{timestamp}.#{format}")
+
+            generate_to_file(content, format, output_file, options)
+          end
+
+          def execute_plantuml(content, format, output_file, options)
+            Tempfile.create(['plantuml_input', '.puml']) do |input_file|
+              input_file.write(content)
+              input_file.close
+
+              # PlantUML generates output files based on filename specified in @start... line
+              # We need to use a temp directory and then move the file
+              Dir.mktmpdir do |temp_dir|
+                cmd = build_command(input_file.path, format, temp_dir, options)
+
+                output, error, status = Open3.capture3(*cmd)
+
+                unless status.success?
+                  error_message = error.empty? ? "Unknown PlantUML error" : error.strip
+                  raise GenerationError.new(error_message, error)
+                end
+
+                # Find the generated file and move it to the desired location
+                if output_file
+                  generated_file = find_generated_file(temp_dir, content, format)
+                  if generated_file && File.exist?(generated_file)
+                    FileUtils.mv(generated_file, output_file)
+                  else
+                    # Debug: List what files were actually generated
+                    generated_files = Dir.glob(File.join(temp_dir, "*"))
+                    error_msg = "Generated file not found in temp directory. "
+                    error_msg += "Expected: #{generated_file}. "
+                    error_msg += "Found files: #{generated_files.map { |f| File.basename(f) }.join(', ')}"
+                    raise GenerationError.new(error_msg)
+                  end
+                end
+
+                output
+              end
+            end
+          end
+
+          def find_generated_file(temp_dir, content, format)
+            # PlantUML generates files based on the filename specified in @start... line
+            extension = format.to_s.downcase
+
+            # First, try to extract filename from PlantUML content
+            plantuml_filename = extract_plantuml_filename_from_content(content)
+
+            if plantuml_filename
+              # Look for file with PlantUML-specified name
+              generated_file = File.join(temp_dir, "#{plantuml_filename}.#{extension}")
+              return generated_file if File.exist?(generated_file)
+            end
+
+            # Fallback: scan directory for any generated files with correct extension
+            Dir.glob(File.join(temp_dir, "*.#{extension}")).first
+          end
+
+          def extract_plantuml_filename_from_content(content)
+            # Extract the raw filename from @start... line (don't sanitize)
+            match = content.match(/^@start\w+\s+(.+)$/mi)
+            return nil unless match
+
+            filename = match[1].strip.split("\n").first&.strip
+            return nil if filename.nil? || filename.empty?
+
+            # Remove quotes but keep the original name as PlantUML will use it
+            filename.gsub(/^["']|["']$/, "")
+          end
+
+          def build_command(input_file, format, output_dir, options)
+            cmd = [
+              configuration.java_path,
+              *jvm_options,
+              "-jar", PLANTUML_JAR_PATH
+            ]
+
+            # Add format-specific options
+            case format.to_s.downcase
+            when "png"
+              cmd << "-tpng"
+            when "svg"
+              cmd << "-tsvg"
+            when "pdf"
+              cmd << "-tpdf"
+            when "txt"
+              cmd << "-ttxt"
+            when "eps"
+              cmd << "-teps"
+            end
+
+            # Add output directory option
+            cmd << "-o" << output_dir
+
+            # Add charset option for better compatibility
+            cmd << "-charset" << "UTF-8"
+
+            # Add input file
+            cmd << input_file
+
+            cmd
+          end
+        end
+      end
+    end
+  end
+end

data/lib/metanorma-plugin-plantuml.rb

@@ -0,0 +1,15 @@
+
+module Metanorma
+  module Plugin
+    module Plantuml
+    end
+  end
+end
+
+require "metanorma/plugin/plantuml/version"
+require "metanorma/plugin/plantuml/errors"
+require "metanorma/plugin/plantuml/config"
+require "metanorma/plugin/plantuml/wrapper"
+require "metanorma/plugin/plantuml/utils"
+require "metanorma/plugin/plantuml/backend"
+require "metanorma/plugin/plantuml/block_processor"

data/metanorma-plugin-plantuml.gemspec

@@ -0,0 +1,35 @@
+lib = File.expand_path("lib", __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "metanorma/plugin/plantuml/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "metanorma-plugin-plantuml"
+  spec.version       = Metanorma::Plugin::Plantuml::VERSION
+  spec.authors       = ["Ribose Inc."]
+  spec.email         = ["open.source@ribose.com"]
+
+  spec.summary       = "Metanorma plugin for PlantUML"
+  spec.description   = "Metanorma plugin for PlantUML"
+
+  spec.homepage      = "https://github.com/metanorma/metanorma-plugin-plantuml"
+  spec.license       = "BSD-2-Clause"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been
+  # added into git.
+  spec.files         = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      f.match(%r{^(test|spec|features)/})
+    end
+  end + ["data/plantuml.jar"]
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.required_ruby_version = ">= 2.7.0" # rubocop:disable Gemspec/RequiredRubyVersion
+
+  spec.add_dependency "asciidoctor"
+  spec.add_dependency "isodoc"
+
+  spec.metadata["rubygems_mfa_required"] = "false"
+end