paru 1.5.0 → 1.5.1

data/lib/paru/filter_error.rb

@@ -1,5 +1,7 @@
+# frozen_string_literal: true
+
 #--
-# Copyright 2015, 2016, 2017 Huub de Beer <Huub@heerdebeer.org>
+# Copyright 2015--2025 Huub de Beer <Huub@heerdebeer.org>
 #
 # This file is part of Paru
 #
@@ -16,10 +18,10 @@
 # You should have received a copy of the GNU General Public License
 # along with Paru.  If not, see <http://www.gnu.org/licenses/>.
 #++
-require_relative "./error.rb"
+require_relative 'error'
 
 module Paru
-    # A FilterError raised when there is an error while running a filter.
-    class FilterError < Error
-    end
+  # A FilterError raised when there is an error while running a filter.
+  class FilterError < Error
+  end
 end

data/lib/paru/info.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright 2022 Huub de Beer <Huub@heerdebeer.org>
+# Copyright 2022-2025 Huub de Beer <Huub@heerdebeer.org>
 #
 # This file is part of Paru
 #
@@ -18,7 +18,8 @@
 #++
 
 # frozen_string_literal: false
-require_relative "error.rb"
+
+require_relative 'error'
 
 module Paru
   # Information about pandoc
@@ -38,51 +39,49 @@ module Paru
     #
     # @param path [String] the path to pandoc. Defaults to 'pandoc', i.e.,
     # assumes it's on the environment's path.
-    def initialize(path = "pandoc")
-      begin
-        # Get pandoc's version information
-        version_string = ''
-        IO.popen("#{path} --version", 'r+') do |p|
-          p.close_write
-          version_string << p.read
-        end
+    def initialize(path = 'pandoc')
+      # Get pandoc's version information
+      version_string = ''
+      IO.popen("#{path} --version", 'r+') do |p|
+        p.close_write
+        version_string << p.read
+      end
 
-        # Extract the version as an array of integers, like SemVer.
-        @version = version_string
-          .match(/pandoc.* (\d+\.\d+.*)$/)[1]
-          .split(".")
-          .map {|s| s.to_i}
+      # Extract the version as an array of integers, like SemVer.
+      @version = version_string
+                 .match(/pandoc.* (\d+\.\d+.*)$/)[1]
+                 .split('.')
+                 .map(&:to_i)
 
-        # Extract the data directory
-        @data_dir = version_string.match(/User data directory: (.+)$/)[1]
+      # Extract the data directory
+      @data_dir = version_string.match(/User data directory: (.+)$/)[1]
 
-        # Extract scripting engine
-        @scripting_engine = version_string.match(/Scripting engine: (.+)$/)[1]
-      rescue StandardError => err
-        warn "Error extracting pandoc's information: #{err.message}"
-        warn "Using made up values instead."
+      # Extract scripting engine
+      @scripting_engine = version_string.match(/Scripting engine: (.+)$/)[1]
+    rescue StandardError => e
+      warn "Error extracting pandoc's information: #{e.message}"
+      warn 'Using made up values instead.'
 
-        @version = @version || [2, 18]
-        @data_dir = @data_dir || "."
-        @scripting_engine = @scripting_engine || "Lua 5.4"
-      end
+      @version ||= [2, 18]
+      @data_dir ||= '.'
+      @scripting_engine ||= 'Lua 5.4'
     end
 
     # Get pandoc's info by key like a Hash for backwards compatability.
     #
     # @deprecated Use Info's getters instead.
-    # 
+    #
     # @param key [String|Symbol] the key for the information to look up.
     # Info only supports keys 'version' and 'data_dir'.
     # @return [Any] Information associated with the key.
     # @raise [Error] for an unknown key.
     def [](key)
       case key
-      when "verion", :version
+      when 'verion', :version
         version
-      when "data_dir", :data_dir
+      when 'data_dir', :data_dir
         data_dir
-      when "scripting_engine", :scripting_engine
+      when 'scripting_engine', :scripting_engine
         scripting_engine
       else
         throw Error.new "Info does not know key '#{key}'"

data/lib/paru/pandoc.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright 2015, 2016, 2017, 2022 Huub de Beer <Huub@heerdebeer.org>
+# Copyright 2015--2025 Huub de Beer <Huub@heerdebeer.org>
 #
 # This file is part of Paru
 #
@@ -18,286 +18,279 @@
 #++
 
 # frozen_string_literal: false
-require "open3"
-require "shellwords"
-require "yaml"
 
-require_relative "error.rb"
-require_relative "info.rb"
+require 'open3'
+require 'shellwords'
+require 'yaml'
+
+require_relative 'error'
+require_relative 'info'
 
 module Paru
-    # Pandoc is a wrapper around the pandoc document converter. See
-    # <http://pandoc.org/README.html> for details about pandoc.  The Pandoc
-    # class is basically a straightforward translation from the pandoc command
-    # line program to Ruby. It is a Rubyesque API to work with pandoc.
+  # Pandoc is a wrapper around the pandoc document converter. See
+  # <http://pandoc.org/README.html> for details about pandoc.  The Pandoc
+  # class is basically a straightforward translation from the pandoc command
+  # line program to Ruby. It is a Rubyesque API to work with pandoc.
+  #
+  # For information about writing pandoc filters in Ruby see {Filter}.
+  #
+  # Creating a Paru pandoc converter in Ruby is quite straightforward: you
+  # create a new Paru::Pandoc object with a block that configures that
+  # Pandoc object with pandoc options. Each command-line option to pandoc is
+  # a method on the Pandoc object. Command-line options with dashes in them,
+  # such as "--reference-docx", can be called by replacing the dash with an
+  # underscore. So, "--reference-docx" becomes the method +reference_docx+.
+  #
+  # Pandoc command-line flags, such as "--parse-raw", "--chapters", or
+  # "--toc", have been translated to Paru::Pandoc methods that take an
+  # optional Boolean parameter; +true+ is the default value. Therefore, if
+  # you want to enable a flag, no parameter is needed.
+  #
+  # All other pandoc command-line options are translated to Paru::Pandoc
+  # methods that take either one String or Number argument, or a list of
+  # String arguments if that command-line option can occur more than once
+  # (such as "--include-before-header" or "--filter").
+  #
+  # Once you have configured a Paru::Pandoc converter, you can call
+  # +convert+ or +<<+ (which is an alias for +convert+) with a string to
+  # convert. You can call +convert+ as often as you like and, if you like,
+  # reconfigure the converter in between!
+  #
+  #
+  # @example Convert the markdown string 'hello *world*' to HTML
+  #     Paru::Pandoc.new do
+  #         from 'markdown
+  #         to 'html'
+  #     end << 'hello *world*'
+  #
+  # @example Convert a HTML file to DOCX with a reference file
+  #     Paru::Pandoc.new do
+  #         from "html"
+  #         to "docx"
+  #         reference_docx "styled_output.docx"
+  #         output "output.docx"
+  #     end.convert File.read("input.html")
+  #
+  # @example Convert a markdown file to html but add in references in APA style
+  #     Paru::Pandoc.new do
+  #         from "markdown"
+  #         toc
+  #         bibliography "literature.bib"
+  #         to "html"
+  #         csl "apa.csl"
+  #         output "report_with_references.md"
+  #     end << File.read("report.md")
+  #
+  #
+  class Pandoc
+    # Use a readable option separator on Unix-like systems, but fall back
+    # to a space on Windows.
+    DEFAULT_OPTION_SEP = Gem.win_platform? ? ' ' : " \\\n\t"
+
+    # Path to the pandoc executatble to use by paru.
+    PARU_PANDOC_PATH = 'PARU_PANDOC_PATH'.freeze
+
+    # Gather information about the pandoc installation. It runs +pandoc
+    # --version+ and extracts pandoc's version number and default data
+    # directory. This method is typically used in scripts that use Paru to
+    # automate the use of pandoc.
     #
-    # For information about writing pandoc filters in Ruby see {Filter}.
+    # @return [Info] Pandoc's version, such as "[2.10.1]" and the data directory, such as "/home/huub/.pandoc".
+    def self.info
+      @@info
+    end
+
+    # Create a new Pandoc converter, optionally configured by a block with
+    # pandoc options. See {#configure} on how to configure a converter.
     #
-    # Creating a Paru pandoc converter in Ruby is quite straightforward: you
-    # create a new Paru::Pandoc object with a block that configures that
-    # Pandoc object with pandoc options. Each command-line option to pandoc is
-    # a method on the Pandoc object. Command-line options with dashes in them,
-    # such as "--reference-docx", can be called by replacing the dash with an
-    # underscore. So, "--reference-docx" becomes the method +reference_docx+.
+    # @param block [Proc] an optional configuration block.
+    def initialize(&block)
+      @options = {}
+      configure(&block) if block_given?
+    end
+
+    # Configure this Pandoc converter with block. In the block you can
+    # call all pandoc options as methods on this converter. In multi-word
+    # options the dash (-) is replaced by an underscore (_)
     #
-    # Pandoc command-line flags, such as "--parse-raw", "--chapters", or
-    # "--toc", have been translated to Paru::Pandoc methods that take an
-    # optional Boolean parameter; +true+ is the default value. Therefore, if
-    # you want to enable a flag, no parameter is needed.
+    # Pandoc has a number of command line options. Most are simple options,
+    # like flags, that can be set only once. Other options can occur more than
+    # once, such as the css option: to add more than one css file to a
+    # generated standalone html file, use the css options once for each
+    # stylesheet to include. Other options do have the pattern key[:value],
+    # which can also occur multiple times, such as metadata.
     #
-    # All other pandoc command-line options are translated to Paru::Pandoc
-    # methods that take either one String or Number argument, or a list of
-    # String arguments if that command-line option can occur more than once
-    # (such as "--include-before-header" or "--filter").
+    # All options are specified in a pandoc_options.yaml. If it is an option
+    # that can occur only once, the value of the option in that yaml file is
+    # its default value. If the option can occur multiple times, its value is
+    # an array with one value, the default value.
     #
-    # Once you have configured a Paru::Pandoc converter, you can call
-    # +convert+ or +<<+ (which is an alias for +convert+) with a string to
-    # convert. You can call +convert+ as often as you like and, if you like,
-    # reconfigure the converter in between!
+    # @param block [Proc] the options to pandoc
+    # @return [Pandoc] this Pandoc converter
     #
+    # @example Configure converting HTML to LaTeX with a LaTeX engine
+    #   converter.configure do
+    #       from 'html'
+    #       to 'latex'
+    #       latex_engine 'lualatex'
+    #   end
     #
-    # @example Convert the markdown string 'hello *world*' to HTML
-    #     Paru::Pandoc.new do
-    #         from 'markdown
-    #         to 'html'
-    #     end << 'hello *world*'
+    def configure(&block)
+      instance_eval(&block)
+      self
+    end
+
+    # Converts input string to output string using the pandoc invocation
+    # configured in this Pandoc instance.
     #
-    # @example Convert a HTML file to DOCX with a reference file
-    #     Paru::Pandoc.new do
-    #         from "html"
-    #         to "docx"
-    #         reference_docx "styled_output.docx"
-    #         output "output.docx"
-    #     end.convert File.read("input.html")
+    # @param input [String] the input string to convert
+    # @return [String] the converted output as a string. Note. For some
+    # formats, output to STDOUT is not supported (see pandoc's manual) and
+    # the result string will be empty.
     #
-    # @example Convert a markdown file to html but add in references in APA style
-    #     Paru::Pandoc.new do
-    #         from "markdown"
-    #         toc
-    #         bibliography "literature.bib"
-    #         to "html"
-    #         csl "apa.csl"
-    #         output "report_with_references.md"
-    #     end << File.read("report.md")
+    # The following two examples are the same:
     #
+    # @example Using convert
+    #   output = converter.convert 'this is a *strong* word'
     #
-    class Pandoc
-
-        # Use a readable option separator on Unix-like systems, but fall back
-        # to a space on Windows.
-        DEFAULT_OPTION_SEP = if Gem.win_platform? then " " else " \\\n\t" end
-        
-        # Path to the pandoc executatble to use by paru.
-        PARU_PANDOC_PATH = "PARU_PANDOC_PATH"
-
-        # Gather information about the pandoc installation. It runs +pandoc
-        # --version+ and extracts pandoc's version number and default data
-        # directory. This method is typically used in scripts that use Paru to
-        # automate the use of pandoc.
-        #
-        # @return [Info] Pandoc's version, such as "[2.10.1]" and the data directory, such as "/home/huub/.pandoc".
-        def self.info()
-            @@info
-        end
-
-        # Create a new Pandoc converter, optionally configured by a block with
-        # pandoc options. See {#configure} on how to configure a converter.
-        #
-        # @param block [Proc] an optional configuration block.
-        def initialize(&block)
-            @options = {}
-            configure(&block) if block_given?
-        end
-
-        # Configure this Pandoc converter with block. In the block you can
-        # call all pandoc options as methods on this converter. In multi-word
-        # options the dash (-) is replaced by an underscore (_)
-        #
-        # Pandoc has a number of command line options. Most are simple options,
-        # like flags, that can be set only once. Other options can occur more than
-        # once, such as the css option: to add more than one css file to a
-        # generated standalone html file, use the css options once for each
-        # stylesheet to include. Other options do have the pattern key[:value],
-        # which can also occur multiple times, such as metadata. 
-        #
-        # All options are specified in a pandoc_options.yaml. If it is an option
-        # that can occur only once, the value of the option in that yaml file is
-        # its default value. If the option can occur multiple times, its value is
-        # an array with one value, the default value.
-        #
-        # @param block [Proc] the options to pandoc
-        # @return [Pandoc] this Pandoc converter
-        #
-        # @example Configure converting HTML to LaTeX with a LaTeX engine
-        #   converter.configure do
-        #       from 'html'
-        #       to 'latex'
-        #       latex_engine 'lualatex'
-        #   end
-        #
-        def configure(&block)
-            instance_eval(&block)
-            self
-        end
+    # @example Using <<
+    #   output = converter << 'this is a *strong* word'
+    def convert(input)
+      run_converter to_command, input
+    end
+    alias << convert
 
-        # Converts input string to output string using the pandoc invocation
-        # configured in this Pandoc instance.
-        #
-        # @param input [String] the input string to convert
-        # @return [String] the converted output as a string. Note. For some
-        # formats, output to STDOUT is not supported (see pandoc's manual) and
-        # the result string will be empty.
-        #
-        # The following two examples are the same:
-        #
-        # @example Using convert
-        #   output = converter.convert 'this is a *strong* word'
-        #
-        # @example Using <<
-        #   output = converter << 'this is a *strong* word'
-        def convert(input)
-            run_converter to_command, input
-        end
-        alias << convert
-
-        # Converts an input file to output string using the pandoc invocation
-        # configured in this Pandoc instance. The path to the input file is
-        # appended to that invocation.
-        #
-        # @param input_file [String] the path to the input file to convert
-        # @return [String] the converted output as a string. Note. For some
-        # formats, output to STDOUT is not supported (see pandoc's manual) and
-        # the result string will be empty.
-        #
-        # @example Using convert_file
-        #   output = converter.convert_file 'files/document.md'
-        def convert_file(input_file)
-            run_converter "#{to_command} #{input_file}"
-        end
+    # Converts an input file to output string using the pandoc invocation
+    # configured in this Pandoc instance. The path to the input file is
+    # appended to that invocation.
+    #
+    # @param input_file [String] the path to the input file to convert
+    # @return [String] the converted output as a string. Note. For some
+    # formats, output to STDOUT is not supported (see pandoc's manual) and
+    # the result string will be empty.
+    #
+    # @example Using convert_file
+    #   output = converter.convert_file 'files/document.md'
+    def convert_file(input_file)
+      run_converter "#{to_command} #{input_file}"
+    end
 
-        # Create a string representation of this converter's pandoc command
-        # line invocation. This is useful for debugging purposes.
-        #
-        # @param option_sep [String] the string to separate options with
-        # @return [String] This converter's command line invocation string.
-        def to_command(option_sep = DEFAULT_OPTION_SEP)
-            "#{escape(@@pandoc_exec)}\t#{to_option_string option_sep}"
-        end
+    # Create a string representation of this converter's pandoc command
+    # line invocation. This is useful for debugging purposes.
+    #
+    # @param option_sep [String] the string to separate options with
+    # @return [String] This converter's command line invocation string.
+    def to_command(option_sep = DEFAULT_OPTION_SEP)
+      "#{escape(@@pandoc_exec)}\t#{to_option_string option_sep}"
+    end
 
-        private
-        
-        def to_option_string(option_sep)
-            options_arr = []
-            @options.each do |option, value|
-                option_string = "--#{option.to_s.gsub '_', '-'}"
-
-                case value
-                when TrueClass then
-                    # Flags don't have a value, only its name
-                    # For example: --standalone
-                    options_arr.push "#{option_string}"
-                when FalseClass then
-                    # Skip this option; consider a flag with value false as unset
-                when Array then
-                    # This option can occur multiple times: list each with its value.
-                    # For example: --css=main.css --css=print.css
-                    options_arr.push value.map {|val| "#{option_string}=#{escape(val.to_s)}"}.join(option_sep)
-                else
-                    # All options that aren't flags and can occur only once have the
-                    # same pattern: --option=value
-                    options_arr.push "#{option_string}=#{escape(value.to_s)}"
-                end
-            end
-            options_arr.join(option_sep)
+    private
+
+    def to_option_string(option_sep)
+      options_arr = []
+      @options.each do |option, value|
+        option_string = "--#{option.to_s.gsub '_', '-'}"
+
+        case value
+        when TrueClass
+          # Flags don't have a value, only its name
+          # For example: --standalone
+          options_arr.push option_string.to_s
+        when FalseClass
+        # Skip this option; consider a flag with value false as unset
+        when Array
+          # This option can occur multiple times: list each with its value.
+          # For example: --css=main.css --css=print.css
+          options_arr.push value.map { |val| "#{option_string}=#{escape(val.to_s)}" }.join(option_sep)
+        else
+          # All options that aren't flags and can occur only once have the
+          # same pattern: --option=value
+          options_arr.push "#{option_string}=#{escape(value.to_s)}"
         end
+      end
+      options_arr.join(option_sep)
+    end
 
-        # determine pandoc_executable to use in paru
-        @@pandoc_exec = if ENV.has_key? PARU_PANDOC_PATH
-                            ENV[PARU_PANDOC_PATH]
-                        else
-                            "pandoc"
-                        end
+    # determine pandoc_executable to use in paru
+    @@pandoc_exec = if ENV.key? PARU_PANDOC_PATH
+                      ENV[PARU_PANDOC_PATH]
+                    else
+                      'pandoc'
+                    end
 
-        @@info = Info.new(@@pandoc_exec)
+    @@info = Info.new(@@pandoc_exec)
 
-        # For each pandoc command line option a method is defined as follows:
-        OPTIONS = YAML.load_file File.join(__dir__, "pandoc_options.yaml")
+    # For each pandoc command line option a method is defined as follows:
+    OPTIONS = YAML.load_file File.join(__dir__, 'pandoc_options.yaml')
 
-        OPTIONS.each_pair do |option, default|
-            if OPTIONS[option].is_a? Array then
+    OPTIONS.each_pair do |option, default|
+      if OPTIONS[option].is_a? Array
 
-                # option can be set multiple times, for example adding multiple css
-                # files
+        # option can be set multiple times, for example adding multiple css
+        # files
 
-                define_method(option) do |value = default|
-                    value = [] if value.nil?
+        define_method(option) do |value = default|
+          value = [] if value.nil?
 
-                    if @options[option].nil? then
-                        @options[option] = []
-                    end
+          @options[option] = [] if @options[option].nil?
 
-                    if value.is_a? Array then
-                        @options[option] += value
-                    else
-                        @options[option].push value
-                    end
-
-                    self
-                end
+          if value.is_a? Array
+            @options[option] += value
+          else
+            @options[option].push value
+          end
 
-            else
-                # option can be set only once, for example a flag or a template
+          self
+        end
 
-                default = OPTIONS[option]
-                define_method(option) do |value = default|
-                    value = default if value.nil?
+      else
+        # option can be set only once, for example a flag or a template
 
-                    @options[option] = value
-                    self
-                end
+        default = OPTIONS[option]
+        define_method(option) do |value = default|
+          value = default if value.nil?
 
-            end
+          @options[option] = value
+          self
         end
 
-        private 
-
-        def escape(str)
-            if Gem.win_platform?
-                escaped = str.gsub("\\", "\\\\")
-                "\"#{escaped}\""
-            else
-                str.shellescape
-            end
-        end
+      end
+    end
 
-        def run_converter(command, input = nil)
-            begin
-                output = ''
-                error = ''
-                status = 0
-
-                Open3.popen3(command) do |stdin, stdout, stderr, thread|
-                    stdin << input unless input.nil?
-                    stdin.close
-                    output << stdout.read
-                    error << stderr.read
-                    status = thread.value.exitstatus
-                end
-
-                warn error unless error.empty?
-
-                if 0 < status
-                    # pandoc exited with an error
-                    raise Paru::Error.new "error while running:\n\n#{command}\n\nPandoc responded with:\n\n#{error}\n"
-                end
-
-                output
-            rescue Paru::Error => err
-                raise err
-            rescue StandardError => err
-                throw Error.new "Unable to run pandoc via command '#{command}': #{err.message}"
-            end
-        end
+    def escape(str)
+      if Gem.win_platform?
+        escaped = str.gsub('\\', '\\\\')
+        "\"#{escaped}\""
+      else
+        str.shellescape
+      end
     end
 
+    def run_converter(command, input = nil)
+      output = ''
+      error = ''
+      status = 0
+
+      Open3.popen3(command) do |stdin, stdout, stderr, thread|
+        stdin << input unless input.nil?
+        stdin.close
+        output << stdout.read
+        error << stderr.read
+        status = thread.value.exitstatus
+      end
+
+      warn error unless error.empty?
+
+      if status.positive?
+        # pandoc exited with an error
+        raise Paru::Error, "error while running:\n\n#{command}\n\nPandoc responded with:\n\n#{error}\n"
+      end
+
+      output
+    rescue Paru::Error => e
+      raise e
+    rescue StandardError => e
+      throw Error.new "Unable to run pandoc via command '#{command}': #{e.message}"
+    end
+  end
 end