pandocomatic 1.1.3 → 2.0.0

data/lib/pandocomatic/pandoc_metadata.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #--
-# Copyright 2014-2023, Huub de Beer <Huub@heerdebeer.org>
+# Copyright 2014-2024, Huub de Beer <Huub@heerdebeer.org>
 #
 # This file is part of pandocomatic.
 #
@@ -26,6 +26,7 @@ module Pandocomatic
   require_relative 'error/pandoc_metadata_error'
   require_relative 'pandocomatic_yaml'
 
+  # Regular expression to find the start of metadata blocks in a string.
   BLOCK_START = /^---[ \t]*$/
 
   # Regular expression to find metadata blocks in a string. This regular
@@ -45,6 +46,15 @@ module Pandocomatic
       extract_metadata(input).first
     end
 
+    # Create an empty metadata object with only the source format set.
+    #
+    # @param src_format [String] the source format
+    # @return [PandocMetadata[ empty metadata with only pandoc's source format
+    # set.
+    def self.empty(src_format)
+      PandocMetadata.new({ 'pandocomatic_' => { 'pandoc' => { 'from' => src_format } } })
+    end
+
     # Collect the metadata embedded in the src file and create a new
     # PandocMetadata instance
     #
@@ -236,20 +246,19 @@ module Pandocomatic
 
       def extract_blocks(input, path)
         starts = input.scan(BLOCK_START)
+
         if starts.empty?
           # No YAML metadata blocks expected
           return []
         end
 
         # Expect YAML metadata blocks
-        begin
-          input
-            .scan(METADATA_BLOCK)
-            .map { |match| PandocomaticYAML.load "---#{match.join}...", path }
-            .select { |block| !block.nil? and !block.empty? }
-        rescue StandardError => e
-          raise PandocMetadataError.new :expected_to_find_YAML_metadata_blocks, e, path
-        end
+        input
+          .scan(METADATA_BLOCK)
+          .map { |match| PandocomaticYAML.load "---#{match.join}...", path }
+          .select { |block| !block.nil? and !block.empty? }
+      rescue StandardError => e
+        raise PandocMetadataError.new :expected_to_find_YAML_metadata_blocks, e, path
       end
     end
 

data/lib/pandocomatic/pandocomatic.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #--
-# Copyright 2014—2022, Huub de Beer <huub@heerdebeer.org>
+# Copyright 2014—2024, Huub de Beer <huub@heerdebeer.org>
 #
 # This file is part of pandocomatic.
 #
@@ -22,6 +22,7 @@ module Pandocomatic
   Encoding.default_external = Encoding::UTF_8 # ensure unicode encoding
   Encoding.default_internal = Encoding::UTF_8
 
+  require 'logger'
   require 'paru'
   require 'tempfile'
 
@@ -36,6 +37,7 @@ module Pandocomatic
   require_relative 'printer/configuration_errors_printer'
   require_relative 'printer/finish_printer'
   require_relative 'printer/summary_printer'
+  require_relative 'printer/unknown_error_printer'
 
   require_relative 'command/convert_dir_command'
   require_relative 'command/convert_list_command'
@@ -45,7 +47,98 @@ module Pandocomatic
   require_relative 'version'
 
   # The Pandocomatic class controlls the pandocomatic conversion process
-  class Pandocomatic
+  module Pandocomatic
+    # Pandocomatic's log. Depending on given command-line arguments,
+    # pandocomatic will log its actions to file or not log anything at all.
+    class Log
+      # Add pandocomatic's command-line arguments to the log
+      #
+      # @param [String[]] args
+      def pandocomatic_called_with(args)
+        @args = if args.respond_to? :join
+                  args.join(' ')
+                else
+                  args
+                end
+      end
+
+      # Install a logger that writes to a given log file for given log level
+      #
+      # @param log_file [String] name or path to log file
+      # @param log_level [String] log level, one of "fatal", "error",
+      # "warning", or "debug". Defaults to "info"
+      def install_file_logger(log_file, log_level = 'info')
+        unless log_file.nil?
+          begin
+            @logger = Logger.new(log_file, level: log_level)
+            @logger.formatter = proc do |severity, datetime, _progname, msg|
+              date_format = datetime.strftime('%Y-%m-%d %H:%M:%S')
+              "#{date_format} #{severity.ljust(5)}: #{msg}\n"
+            end
+          rescue StandardError => e
+            warn "Unable to create log file '#{log_file}' with log level '#{log_level}' because:\n#{e}."
+            warn 'Continuing with logging disabled.'
+          end
+        end
+
+        info '------------ START ---------------'
+        info "Running #{$PROGRAM_NAME} #{@args}"
+      end
+
+      # Log a debug message
+      #
+      # @param [String] msg
+      def debug(msg)
+        @logger&.debug(msg)
+      end
+
+      # Log an error message
+      #
+      # @param [String] msg
+      def error(msg)
+        @logger&.error(msg)
+      end
+
+      # Log a fatal message
+      #
+      # @param [String] msg
+      def fatal(msg)
+        @logger&.fatal(msg)
+      end
+
+      # Log an informational message
+      #
+      # @param [String] msg
+      def info(msg)
+        @logger&.info(msg)
+      end
+
+      # Log a warning message
+      #
+      # @param [String] msg
+      def warn(msg)
+        @logger&.warn(msg)
+      end
+
+      # Indent given string with given number of spaces. Intended for logging
+      # purposes.
+      #
+      # @param str [String] string to indent
+      # @param number_of_spaces [Number] number of spaces to indent string
+      # @return [String] indented string
+      def indent(str, number_of_spaces)
+        str.split("\n").join("\n#{' ' * number_of_spaces}")
+      end
+    end
+
+    private_constant :Log
+
+    # Global logger for pandocomatic
+    LOG = Log.new
+
+    # Feature toggles supported by pandocomatic
+    FEATURES = [:pandoc_verbose].freeze
+
     # Pandocomatic error status codes start from ERROR_STATUS
     ERROR_STATUS = 1266 # This is the sum of the ASCII values of the characters in 'pandocomatic'
 
@@ -55,8 +148,12 @@ module Pandocomatic
     #
     # @param args [String[]] list of options to configure pandocomatic
     def self.run(args)
+      LOG.pandocomatic_called_with args
       start_time = Time.now
-      configuration = CLI.parse args
+
+      # Depending on given command-line arguments, CLI#parse! also
+      # installs a file logger in LOG.
+      configuration = CLI.parse! args
 
       if configuration.show_version?
         # The version option has precedence over all other options; if
@@ -75,6 +172,12 @@ module Pandocomatic
           exit ERROR_STATUS
         end
 
+        if configuration.dry_run?
+          LOG.debug 'Start dry-run conversion:'
+        else
+          LOG.debug 'Start conversion:'
+        end
+
         # Run the pandocomatic converter configured according to the options
         # given.
         #
@@ -115,10 +218,11 @@ module Pandocomatic
     rescue StandardError => e
       # An unexpected error has occurred; break off the program drastically
       # for now. This is likely a bug: ask the user to report it.
-      warn '[UNEXPECTED ERROR] An unexpected error has occurred. You can report this bug via https://github.com/htdebeer/pandocomatic/issues/new.'
-      raise e
+      UnknownErrorPrinter.new(e).print
+      exit ERROR_STATUS + 2
     ensure
       configuration&.clean_up!
+      LOG.info "------------  END  ---------------\n"
     end
   end
 

data/lib/pandocomatic/pandocomatic_yaml.rb

@@ -61,7 +61,7 @@ module Pandocomatic
       str.gsub(VAR_PATTERN) do |_match|
         key = Regexp.last_match(1)
 
-        raise TemplateError.new(:environment_variable_does_not_exist, { key: key, path: path }) unless ENV.key? key
+        raise TemplateError.new(:environment_variable_does_not_exist, { key:, path: }) unless ENV.key? key
 
         ENV.fetch(key, nil)
       end

data/lib/pandocomatic/printer/command_printer.rb

@@ -25,7 +25,7 @@ module Pandocomatic
   class CommandPrinter < Printer
     # Create a new CommandPrinter
     def initialize(command)
-      super 'command.txt'
+      super('command.txt')
       @command = command
     end
   end

data/lib/pandocomatic/printer/configuration_errors_printer.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #--
-# Copyright 2017, Huub de Beer <Huub@heerdebeer.org>
+# Copyright 2017—2024, Huub de Beer <Huub@heerdebeer.org>
 #
 # This file is part of pandocomatic.
 #
@@ -25,8 +25,14 @@ module Pandocomatic
   class ConfigurationErrorsPrinter < Printer
     # Create a new ConfigurationErrorsPrinter
     def initialize(errors)
-      super 'configuration_errors.txt'
+      super('configuration_errors.txt')
       @errors = errors
     end
+
+    # Print configuration errors to STDOUT
+    def print
+      Pandocomatic::LOG.warn self
+      warn self
+    end
   end
 end

data/lib/pandocomatic/printer/error_printer.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #--
-# Copyright 2017, Huub de Beer <Huub@heerdebeer.org>
+# Copyright 2017—2024, Huub de Beer <Huub@heerdebeer.org>
 #
 # This file is part of pandocomatic.
 #
@@ -30,12 +30,13 @@ module Pandocomatic
                  else
                    'error.txt'
                  end
-      super template
+      super(template)
       @error = error
     end
 
     # Print an Error to STDERR rather than STDOUT
     def print
+      Pandocomatic::LOG.error self
       warn self
     end
   end

data/lib/pandocomatic/printer/finish_printer.rb

@@ -33,7 +33,7 @@ module Pandocomatic
     # pandocomatic invokation
     # @param start_time [Time] the time the command was started
     def initialize(command, configuration, start_time)
-      super command, configuration
+      super(command, configuration)
       template 'finish.txt'
 
       @start_time = start_time

data/lib/pandocomatic/printer/help_printer.rb

@@ -25,7 +25,7 @@ module Pandocomatic
   class HelpPrinter < Printer
     # Create a new HelpPrinter
     def initialize
-      super 'help.txt'
+      super('help.txt')
     end
   end
 end

data/lib/pandocomatic/printer/printer.rb

@@ -49,6 +49,7 @@ module Pandocomatic
 
     # Print to STDOUT
     def print
+      Pandocomatic::LOG.info self
       puts self
     end
   end

data/lib/pandocomatic/printer/summary_printer.rb

@@ -29,7 +29,7 @@ module Pandocomatic
     # @param configuration [Configuration] the configuration of the
     # pandocomatic invokation
     def initialize(command, configuration)
-      super 'summary.txt'
+      super('summary.txt')
       @command = command
       @input = configuration.input.to_s
       @output = if configuration.stdout?

data/lib/pandocomatic/printer/unknown_error_printer.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+#--
+# Copyright 2024, Huub de Beer <Huub@heerdebeer.org>
+#
+# This file is part of pandocomatic.
+#
+# Pandocomatic is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by the
+# Free Software Foundation, either version 3 of the License, or (at your
+# option) any later version.
+#
+# Pandocomatic is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+# or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# for more details.
+#
+# You should have received a copy of the GNU General Public License along
+# with pandocomatic.  If not, see <http://www.gnu.org/licenses/>.
+#++
+module Pandocomatic
+  require_relative 'printer'
+
+  # Printer for Errors in non-quiet mode
+  class UnknownErrorPrinter < Printer
+    # Create a new ErrorPrinter
+    def initialize(error)
+      template = 'unknown_error.txt'
+      super(template)
+      @error = error
+    end
+
+    # Print an Error to STDERR rather than STDOUT
+    def print
+      Pandocomatic::LOG.error self
+      warn self
+    end
+  end
+end

data/lib/pandocomatic/printer/version_printer.rb

@@ -25,7 +25,7 @@ module Pandocomatic
   class VersionPrinter < Printer
     # Create a new VersionPrinter
     def initialize(version)
-      super 'version.txt'
+      super('version.txt')
       @version = version
     end
   end

data/lib/pandocomatic/printer/views/cli_error.txt

@@ -17,6 +17,9 @@ Using `--stdout/-s` with an input directory is not allowed.
 <% when :cannot_use_both_output_and_stdout %>
 Using both `--output/-o` and `--stdout/-s` is not allowed.
 Use eiter a specific output file or directory, or standard out, not both.
+<% when :feature_toggle_does_not_exist %>
+'<%= @error.data %>'. 
+Pandocomatic supports the following feature toggles: <%= Pandocomatic::FEATURES.map{|f| f.to_s}.join(", ") %>.
 <% else %>
 '<%= @error.data %>'.
 <% end %>

data/lib/pandocomatic/printer/views/help.txt

@@ -105,26 +105,43 @@ OPTIONS
                   Default is FALSE.
 
   -V, --verbose   Run pandocomatic verbosely. Default is FALSE. Pandocomatic
-                  runs quietly unless the verbose, debug, or dry-run options
-                  are given.
-
-  -b, --debug     Run pandocomatic in debug mode: show the pandoc invocations
-                  before each conversion. Default is FALSE. In debug mode,
-                  pandocomatic runs verbosely.
+                  runs quietly unless the verbose, or dry-run options are given.
 
   -y, --dry-run   Configure pandocomatic to run the conversion process, but do
                   not actually run it. Default is FALSE. When using this
                   dry-run option, pandocomatic runs verbosely.
   
-
-  Experimental:
-
   -r PATH, --root-path PATH  
                   Set the root path to use with paths that are specified as
                   relative to that root path. It is used mostly with the 
                   --css pandoc option. It defaults to the directory of the
                   specified output.
 
+  -e FEATURE, --enable FEATURE
+                  Enable FEATURE in pandocomatic. Pandocomatic supports the
+                  following feature toggles:
+
+                  - "pandoc-verbose" to enable using pandoc's verbose option.
+                    By default pandocomatic removes that verbose option
+                    because it can interfere with running pandoc filters or
+                    pandocomatic processors.
+
+  Logging:
+
+  -l [FILE], --log [FILE]
+
+                  Let pandocomatic log what it is doing to FILE. If FILE is
+                  not given, pandocomatic uses 'pandocomatic.log'. Control
+                  detail of logging with option '--log-level'.
+
+  --log-level [LEVEL]
+
+                  Let pandocomatic log with detail LEVEL. LEVEL should be one
+                  of 'fatal', 'error', 'warn', 'info', or 'debug'. By default, 
+                  pandocomatic logs at detail level info. Choose level 'debug'
+                  to see all steps pandocomatic takes to convert every
+                  directory and file.
+
 
   Common:
 

data/lib/pandocomatic/printer/views/pandoc_metadata_error.txt

@@ -1,4 +1,4 @@
-Expected to extract YAML metadata blocks from file '<%= @error.data %>', but did not succeed. Check YAML syntax of all metadata blocks; make sure that all horizontal lines have at least four (4) dashes.
+Expected to extract YAML metadata blocks from file '<%= @error.data %>', but did not succeed. Make sure '<%= @error.data %>' is a pandoc markdown file. Check YAML syntax of all metadata blocks; make sure that all horizontal lines have at least four (4) dashes.
 
 <% if @error.error? %>Reported cause(s):
   <%= @error.error.to_s %><% end %>

data/lib/pandocomatic/printer/views/unknown_error.txt

@@ -0,0 +1,2 @@
+[UNEXPECTED ERROR] An unexpected error has occurred. You can report this bug via https://github.com/htdebeer/pandocomatic/issues/new.
+Cause: <%= @error %>

data/lib/pandocomatic/printer/warning_printer.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #--
-# Copyright 2017, Huub de Beer <Huub@heerdebeer.org>
+# Copyright 2017—2024, Huub de Beer <Huub@heerdebeer.org>
 #
 # This file is part of pandocomatic.
 #
@@ -28,12 +28,13 @@ module Pandocomatic
     # @param warning [Warning] the warning to print
     def initialize(warning)
       template = 'warning.txt'
-      super template
+      super(template)
       @warning = warning
     end
 
     # Print warnings to STDERR rather than STDOUT
     def print
+      Pandocomatic::LOG.warn self
       warn self
     end
   end

data/lib/pandocomatic/processors/fileinfo_preprocessor.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #--
-# Copyright 2014, 2015, 2016, 2017, Huub de Beer <Huub@heerdebeer.org>
+# Copyright 2014—2024, Huub de Beer <Huub@heerdebeer.org>
 #
 # This file is part of pandocomatic.
 #
@@ -37,17 +37,22 @@ module Pandocomatic
     def self.run(input, path, src_path, options)
       created_at = File.stat(path).ctime
       modified_at = File.stat(path).mtime
-      output = input
-      output << "\n\n---\n"
-      output << "pandocomatic-fileinfo:\n"
-      output << "  from: #{options['from']}\n" if options.key? 'from'
-      output << "  to: #{options['to']}\n" if options.key? 'to'
-      output << "  template: #{options['template']}\n" if options.key? 'template'
-      output << "  path: '#{path}'\n"
-      output << "  src_path: '#{src_path}'\n"
-      output << "  created: #{created_at.strftime '%Y-%m-%d'}\n"
-      output << "  modified: #{modified_at.strftime '%Y-%m-%d'}\n"
-      output << "...\n\n"
+
+      file_info = "\npandocomatic-fileinfo:\n"
+      file_info += "  from: #{options['from']}\n" if options.key? 'from'
+      file_info += "  to: #{options['to']}\n" if options.key? 'to'
+      file_info += "  template: #{options['template']}\n" if options.key? 'template'
+      file_info += "  path: '#{path}'\n"
+      file_info += "  src_path: '#{src_path}'\n"
+      file_info += "  created: #{created_at.strftime '%Y-%m-%d'}\n"
+      file_info += "  modified: #{modified_at.strftime '%Y-%m-%d'}"
+
+      Pandocomatic::LOG.debug '     | FileInfoPreprocessor. Adding file information to metadata:' \
+        "#{Pandocomatic::LOG.indent(
+          file_info, 37
+        )}"
+
+      "#{input}\n\n---#{file_info}\n...\n\n"
     end
 
     # rubocop:enable Metrics/AbcSize

data/lib/pandocomatic/processors/metadata_preprocessor.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #--
-# Copyright 2017, Huub de Beer <Huub@heerdebeer.org>
+# Copyright 2017—2024, Huub de Beer <Huub@heerdebeer.org>
 #
 # This file is part of pandocomatic.
 #
@@ -32,10 +32,12 @@ module Pandocomatic
     #   preprocessed
     # @param metadata [Hash = {}] the metadata to mix-in
     def self.run(input, metadata = {})
-      output = input
-      output << "\n\n"
-      output << YAML.dump(metadata)
-      output << "...\n\n"
+      yaml = YAML.dump(metadata)
+      Pandocomatic::LOG.debug '     | MetadataPreprocessor. Adding mined YAML blocks to metadata:' \
+        "#{Pandocomatic::LOG.indent(
+          yaml.sub('---', ''), 37
+        )}"
+      "#{input}\n\n#{yaml}...\n\n"
     end
   end
 end

data/lib/pandocomatic/template.rb

@@ -57,7 +57,7 @@ module Pandocomatic
         section sec
       end
 
-      define_method("#{sec.downcase}?".to_sym) do
+      define_method(:"#{sec.downcase}?") do
         section? sec
       end
     end

data/lib/pandocomatic/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #--
-# Copyright 2023, Huub de Beer <Huub@heerdebeer.org>
+# Copyright 2023—2024 Huub de Beer <Huub@heerdebeer.org>
 #
 # This file is part of pandocomatic.
 #
@@ -20,5 +20,5 @@
 #++
 module Pandocomatic
   # Pandocomatic's current version.
-  VERSION = [1, 1, 3].freeze
+  VERSION = [2, 0, 0].freeze
 end