kramdown-plantuml 1.0.0 → 1.1.1

data/kramdown-plantuml.gemspec

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative 'lib/which'
+require_relative 'lib/kramdown-plantuml/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'kramdown-plantuml'
+  spec.version       = Kramdown::PlantUml::VERSION
+  spec.authors       = ['Swedbank Pay']
+  spec.email         = ['opensource@swedbankpay.com']
+
+  spec.summary       = <<~SUMMARY
+    kramdown-plantuml allows you to use PlantUML syntax within fenced code
+    blocks with Kramdown (Jekyll's default Markdown parser).
+  SUMMARY
+  spec.homepage      = 'https://github.com/SwedbankPay/kramdown-plantuml'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = Gem::Requirement.new('>= 2.5.0')
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/SwedbankPay/kramdown-plantuml'
+
+  # 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
+    if Which.which('git')
+      files = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+      # Explicitly add plantuml.jar to the list of files as it is not committed to Git.
+      files.append(Dir['bin/**/plantuml*.jar'].first)
+    else
+      puts "Git not found, no files added to #{spec.name}."
+    end
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'kramdown', '~> 2.3'
+  spec.add_dependency 'kramdown-parser-gfm', '~> 1.1'
+  spec.add_dependency 'open3', '~> 0.1'
+
+  spec.add_development_dependency 'rake', '~> 13.0'
+  spec.add_development_dependency 'rspec', '~> 3.2'
+  spec.add_development_dependency 'rspec-its', '~> 1.3'
+  spec.add_development_dependency 'rubocop', '~> 1.12'
+  spec.add_development_dependency 'rubocop-rake', '~> 0.6'
+  spec.add_development_dependency 'rubocop-rspec', '~> 2.4'
+end

data/lib/kramdown-plantuml.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative 'kramdown-plantuml/version'
+require_relative 'kramdown-plantuml/converter'
+require_relative 'kramdown_html'

data/lib/kramdown-plantuml/bool_env.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Kramdown
+  module PlantUml
+    # Converts envrionment variables to boolean values
+    class BoolEnv
+      TRUTHY_VALUES = %w[t true yes y 1].freeze
+      FALSEY_VALUES = %w[f false n no 0].freeze
+
+      def initialize(name)
+        @name = name
+        @value = ENV.key?(name) ? ENV[name] : nil
+        @value = @value.to_s.downcase unless @value.nil?
+      end
+
+      def true?
+        return true if TRUTHY_VALUES.include?(@value)
+        return false if FALSEY_VALUES.include?(@value) || @value.nil? || value.empty?
+
+        raise "The value '#{@value}' of '#{@name}' can't be converted to a boolean"
+      end
+    end
+  end
+end

data/lib/kramdown-plantuml/console_logger.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative 'bool_env'
+
+module Kramdown
+  module PlantUml
+    # Logs to $stdout and $stderr
+    class ConsoleLogger
+      LOG_LEVELS = %i[debug info warn error].freeze
+
+      def initialize(level)
+        @configured_log_level = level
+      end
+
+      def debug(message)
+        write(:debug, message)
+      end
+
+      def info(message)
+        write(:info, message)
+      end
+
+      def warn(message)
+        write(:warn, message)
+      end
+
+      def error(message)
+        write(:error, message)
+      end
+
+      private
+
+      def write(level, message)
+        return false unless write_message?(level)
+
+        pipe = pipe_for(level)
+        pipe.write("\n#{message}")
+      end
+
+      def write_message?(level_of_message)
+        LOG_LEVELS.index(@configured_log_level) <= LOG_LEVELS.index(level_of_message)
+      end
+
+      def pipe_for(level)
+        case level
+        when :debug, :info
+          $stdout
+        when :warn, :error
+          $stderr
+        else
+          raise ArgumentError, "Unknown log level '#{level}'."
+        end
+      end
+    end
+  end
+end

data/lib/kramdown-plantuml/converter.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative 'version'
+require_relative 'themer'
+require_relative 'plantuml_error'
+require_relative 'logger'
+require_relative 'executor'
+
+module Kramdown
+  module PlantUml
+    # Converts PlantUML markup to SVG
+    class Converter
+      def initialize(options = {})
+        @themer = Themer.new(options)
+        @logger = Logger.init
+        @executor = Executor.new
+      end
+
+      def convert_plantuml_to_svg(plantuml)
+        plantuml = @themer.apply_theme(plantuml)
+        plantuml = plantuml.strip
+        @logger.debug "PlantUML converting diagram:\n#{plantuml}"
+        result = @executor.execute(plantuml)
+        result.validate(plantuml)
+        svg = result.without_xml_prologue
+        wrap(svg)
+      end
+
+      private
+
+      def wrap(svg)
+        theme_class = @themer.theme_name ? "theme-#{@themer.theme_name}" : ''
+        class_name = "plantuml #{theme_class}".strip
+
+        wrapper_element_start = "<div class=\"#{class_name}\">"
+        wrapper_element_end = '</div>'
+
+        "#{wrapper_element_start}#{svg}#{wrapper_element_end}"
+      end
+    end
+  end
+end

data/lib/kramdown-plantuml/executor.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: false
+
+require 'open3'
+require_relative '../which'
+require_relative 'logger'
+require_relative 'plantuml_result'
+
+module Kramdown
+  module PlantUml
+    # Executes the PlantUML Java application.
+    class Executor
+      def initialize
+        @logger = Logger.init
+        @plantuml_jar_file = find_plantuml_jar_file
+
+        raise IOError, 'Java can not be found' unless Which.which('java')
+        raise IOError, "No 'plantuml.jar' file could be found" if @plantuml_jar_file.nil?
+        raise IOError, "'#{@plantuml_jar_file}' does not exist" unless File.exist? @plantuml_jar_file
+      end
+
+      def execute(stdin)
+        cmd = "java -Djava.awt.headless=true -jar #{@plantuml_jar_file} -tsvg -failfast -pipe"
+        cmd << if @logger.debug?
+                 ' -verbose'
+               else
+                 ' -nometadata'
+               end
+
+        @logger.debug "PlantUML executing: #{cmd}"
+
+        stdout, stderr, status = Open3.capture3 cmd, stdin_data: stdin
+
+        @logger.debug "PlantUML exit code: #{status.exitstatus}"
+
+        PlantUmlResult.new(stdout, stderr, status)
+      end
+
+      private
+
+      def find_plantuml_jar_file
+        dir = File.dirname __dir__
+        jar_glob = File.join dir, '../bin/**/plantuml*.jar'
+        first_jar = Dir[jar_glob].first
+        File.expand_path first_jar unless first_jar.nil?
+      end
+    end
+  end
+end

data/lib/kramdown-plantuml/hash.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+# Ruby's Hash class.
+class ::Hash
+  # Via https://stackoverflow.com/a/25835016/2257038
+  def symbolize_keys
+    h = map do |k, v|
+      v_sym = v.instance_of?(Hash) ? v.symbolize_keys : v
+      [k.to_sym, v_sym]
+    end
+
+    h.to_h
+  end
+end

data/lib/kramdown-plantuml/logger.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require_relative 'console_logger'
+
+module Kramdown
+  module PlantUml
+    # Provides theming support for PlantUML
+    class Logger
+      def initialize(logger)
+        raise ArgumentError, 'logger cannot be nil' if logger.nil?
+        raise ArgumentError, 'logger must respond to #debug' unless logger.respond_to? :debug
+        raise ArgumentError, 'logger must respond to #info' unless logger.respond_to? :info
+        raise ArgumentError, 'logger must respond to #warn' unless logger.respond_to? :warn
+        raise ArgumentError, 'logger must respond to #error' unless logger.respond_to? :error
+
+        @logger = logger
+      end
+
+      def debug(message)
+        @logger.debug(message)
+      end
+
+      def info(message)
+        @logger.info(message)
+      end
+
+      def warn(message)
+        @logger.warn(message)
+      end
+
+      def error(message)
+        @logger.error(message)
+      end
+
+      def debug?
+        self.class.level == :debug
+      end
+
+      class << self
+        def init
+          inner = nil
+
+          begin
+            require 'jekyll'
+            inner = Jekyll.logger
+          rescue LoadError
+            inner = ConsoleLogger.new(level)
+          end
+
+          Logger.new(inner)
+        end
+
+        def level
+          @level ||= level_from_env
+        end
+
+        private
+
+        def level_from_env
+          return :debug if BoolEnv.new('DEBUG').true?
+          return :debug if BoolEnv.new('VERBOSE').true?
+
+          :warn
+        end
+      end
+    end
+  end
+end

data/lib/kramdown-plantuml/plantuml_error.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Kramdown
+  module PlantUml
+    # PlantUML Error
+    class PlantUmlError < StandardError
+      def initialize(plantuml, stderr, exitcode)
+        message = <<~MESSAGE
+          Conversion of the following PlantUML diagram failed:
+
+          #{plantuml}
+
+          The error received from PlantUML was:
+
+          Exit code: #{exitcode}
+          #{stderr}
+        MESSAGE
+
+        super message
+      end
+
+      def self.should_raise?(exitcode, stderr)
+        return false if exitcode.zero?
+
+        !stderr.nil? && !stderr.empty? && \
+          # If stderr is not empty, but contains the string 'CoreText note:',
+          # the error is caused by a bug in Java, and should be ignored.
+          # Circumvents https://bugs.openjdk.java.net/browse/JDK-8244621
+          !stderr.include?('CoreText note:')
+      end
+    end
+  end
+end

data/lib/kramdown-plantuml/plantuml_result.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative 'logger'
+require_relative 'plantuml_error'
+
+module Kramdown
+  module PlantUml
+    # Executes the PlantUML Java application.
+    class PlantUmlResult
+      attr_reader :stdout, :stderr, :exitcode
+
+      def initialize(stdout, stderr, status)
+        @stdout = stdout
+        @stderr = stderr
+        @exitcode = status.exitstatus
+        @logger = Logger.init
+      end
+
+      def without_xml_prologue
+        return @stdout if @stdout.nil? || @stdout.empty?
+
+        xml_prologue_start = '<?xml'
+        xml_prologue_end = '?>'
+
+        start_index = @stdout.index(xml_prologue_start)
+
+        return @stdout if start_index.nil?
+
+        end_index = @stdout.index(xml_prologue_end, xml_prologue_start.length)
+
+        return @stdout if end_index.nil?
+
+        end_index += xml_prologue_end.length
+
+        @stdout.slice! start_index, end_index
+
+        @stdout
+      end
+
+      def validate(plantuml)
+        raise PlantUmlError.new(plantuml, @stderr, @exitcode) if PlantUmlError.should_raise?(@exitcode, @stderr)
+
+        return if @stderr.nil? || @stderr.empty?
+
+        @logger.debug("PlantUML log:\n#{@stderr}")
+      end
+    end
+  end
+end

data/lib/kramdown-plantuml/themer.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: false
+
+require_relative 'hash'
+require_relative 'logger'
+
+module Kramdown
+  module PlantUml
+    # Provides theming support for PlantUML
+    class Themer
+      attr_reader :theme_name, :theme_directory
+
+      def initialize(options = {})
+        options = options.symbolize_keys
+        @logger = Logger.init
+        @logger.debug(options)
+        @theme_name, @theme_directory = theme_options(options)
+      end
+
+      def apply_theme(plantuml)
+        return plantuml if plantuml.nil? || plantuml.empty? || @theme_name.nil? || @theme_name.empty?
+
+        startuml = '@startuml'
+        startuml_index = plantuml.index(startuml) + startuml.length
+
+        return plantuml if startuml_index.nil?
+
+        /@startuml.*/.match(plantuml) do |match|
+          theme_string = "\n!theme #{@theme_name}"
+          theme_string << " from #{@theme_directory}" unless @theme_directory.nil?
+
+          return plantuml.insert match.end(0), theme_string
+        end
+
+        plantuml
+      end
+
+      private
+
+      def theme_options(options)
+        return nil unless options.key?(:theme)
+
+        theme = options[:theme] || {}
+        theme_name = theme.key?(:name) ? theme[:name] : nil
+        theme_directory = theme.key?(:directory) ? theme[:directory] : nil
+
+        [theme_name, theme_directory]
+      end
+    end
+  end
+end