defmastership 1.0.19 → 1.1.1

data/lib/defmastership/export/csv/formatter.rb

@@ -0,0 +1,64 @@
+# Copyright (c) 2020 Jerome Arbez-Gindre
+# frozen_string_literal: true
+
+require('csv')
+require('defmastership/export/body_formatter')
+require('defmastership/export/header_formatter')
+
+module Defmastership
+  # Module to host export classes
+  module Export
+    # Module to host CSV export classes
+    module CSV
+      # to export a CSV file
+      class Formatter
+        # @param doc [Document] the document to export
+        # @param sep [String] the CSV separator
+        def initialize(doc, sep)
+          @doc = doc
+          @sep = sep
+        end
+
+        # Export the document to a CSV file
+        #
+        # @param output_file [Strinf] filename for the export
+        def export_to(output_file)
+          column_list = build_column_list
+          ::CSV.open(output_file, 'w:ISO-8859-1', col_sep: @sep) do |csv|
+            csv << header(column_list)
+            export_definitions_in(csv, column_list)
+          end
+        end
+
+        private
+
+        def export_definitions_in(csv, column_list)
+          @doc.definitions.each { |definition| csv << body(definition, column_list) }
+        end
+
+        def header(column_list)
+          header_formatter = HeaderFormatter.new(@doc)
+          header_line = column_list.map { |part| header_formatter.public_send(part) }
+          header_line.flatten
+        end
+
+        def body(definition, column_list)
+          body_formatter = BodyFormatter.new(@doc, definition)
+          body_line = column_list.map { |part| body_formatter.public_send(part) }
+          body_line.flatten
+        end
+
+        def build_column_list
+          [
+            [:wrong_explicit_checksum, @doc.wrong_explicit_checksum?],
+            [:explicit_version, @doc.explicit_version?],
+            [:labels, !@doc.labels.empty?],
+            [:eref, !@doc.eref.empty?],
+            [:iref, @doc.iref],
+            [:attributes, !@doc.attributes.empty?]
+          ].reduce([:fixed]) { |acc, elem| acc + (elem.fetch(1) ? [elem.first] : []) }
+        end
+      end
+    end
+  end
+end

data/lib/defmastership/export/header_formatter.rb

@@ -0,0 +1,51 @@
+# Copyright (c) 2020 Jerome Arbez-Gindre
+# frozen_string_literal: true
+
+require('csv')
+
+module Defmastership
+  module Export
+    # format CSV header (first line) for one document
+    class HeaderFormatter
+      # @param doc [Document] the document to export
+      def initialize(doc)
+        @doc = doc
+      end
+
+      # @return [Array<String>] list of always available columns
+      def fixed
+        %w[Type Reference Value Checksum]
+      end
+
+      # @return [Array<String>] Optional wrong_explicit_checksum column caption
+      def wrong_explicit_checksum
+        @doc.wrong_explicit_checksum? ? ['Wrong explicit checksum'] : []
+      end
+
+      # @return [Array<String>] Optional version column captions
+      def explicit_version
+        @doc.explicit_version? ? ['Version'] : []
+      end
+
+      # @return [Array<String>] Optional labels columns captions
+      def labels
+        @doc.labels.empty? ? [] : %w[Labels]
+      end
+
+      # @return [Array<String>] Optional external refs columns captions
+      def eref
+        @doc.eref.map { |_, ref| ref.fetch(:prefix) }
+      end
+
+      # @return [Array<String>] Optional internal refs column caption
+      def iref
+        @doc.iref ? ['Internal links'] : []
+      end
+
+      # @return [Array<String>] Optional attributes columns captions
+      def attributes
+        @doc.attributes.map { |_, value| value }
+      end
+    end
+  end
+end

data/lib/defmastership/filters.rb

@@ -1,23 +1,26 @@
 # Copyright (c) 2020 Jerome Arbez-Gindre
 # frozen_string_literal: true
 
-module DefMastership
+require('defmastership/core/constants')
+
+# Main module of the application
+module Defmastership
   # Contains regexp / action couples
   Filter = Struct.new(:regexp, :event, :consumed_line)
   private_constant :Filter
 
   FILTERS = [
-    Filter.new(DMRegexp::VARIABLE_DEF,  :new_variable_def,     false),
-    Filter.new(DMRegexp::VARIABLE_USE,  :new_variable_use,     false),
-    Filter.new(DMRegexp::DEFINITION,    :new_definition,       true),
-    Filter.new(DMRegexp::EREF_CONFIG,   :new_eref_setup,       true),
-    Filter.new(DMRegexp::EREF_DEF,      :new_eref_def,         false),
-    Filter.new(DMRegexp::IREF_DEF,      :new_iref_def,         false),
-    Filter.new(DMRegexp::ATTR_CONFIG,   :new_attribute_conf,   true),
-    Filter.new(DMRegexp::ATTR_SET,      :new_attribute_value,  false),
-    Filter.new(DMRegexp::BLOCK,         :block_delimiter,      true),
-    Filter.new(DMRegexp::EMPTY_LINE,    :empty_line,           false),
-    Filter.new(DMRegexp::WHATEVER,      :new_line,             true)
+    Filter.new(Core::DMRegexp::VARIABLE_DEF,  :new_variable_def,     false),
+    Filter.new(Core::DMRegexp::VARIABLE_USE,  :new_variable_use,     false),
+    Filter.new(Core::DMRegexp::DEFINITION,    :new_definition,       true),
+    Filter.new(Core::DMRegexp::EREF_CONFIG,   :new_eref_setup,       true),
+    Filter.new(Core::DMRegexp::EREF_DEF,      :new_eref_def,         false),
+    Filter.new(Core::DMRegexp::IREF_DEF,      :new_iref_def,         false),
+    Filter.new(Core::DMRegexp::ATTR_CONFIG,   :new_attribute_conf,   true),
+    Filter.new(Core::DMRegexp::ATTR_SET,      :new_attribute_value,  false),
+    Filter.new(Core::DMRegexp::BLOCK,         :block_delimiter,      true),
+    Filter.new(Core::DMRegexp::EMPTY_LINE,    :empty_line,           false),
+    Filter.new(Core::DMRegexp::WHATEVER,      :new_line,             true)
   ].freeze
   private_constant :FILTERS
 end

data/lib/defmastership/matching_line.rb

@@ -1,10 +1,11 @@
 # Copyright (c) 2020 Jerome Arbez-Gindre
 # frozen_string_literal: true
 
-module DefMastership
-  # a composite class
+module Defmastership
+  # a composite class storing a line and the corresponding match
   MatchingLine =
     Struct.new(:match, :line) do
+      # Act as a Hasg and delegate to the Match
       def [](key)
         value = match[key]
         return value if value

data/lib/defmastership/modifier/change_ref.rb

@@ -0,0 +1,117 @@
+# Copyright (c) 2020 Jerome Arbez-Gindre
+# frozen_string_literal: true
+
+require 'defmastership/core/constants'
+require('defmastership/core/parsing_state')
+require 'defmastership/modifier/modifier_common'
+
+module Defmastership
+  module Modifier
+    # Change references from temporary to definitive with multiple RefChangers
+    class ChangeRef
+      include ModifierCommon
+
+      REGEXP_FROM = {
+        definition: {
+          before: Core::DMRegexp::DEF_BEFORE_REF,
+          after: Core::DMRegexp::DEF_AFTER_REF
+        },
+        iref: {
+          before: Core::DMRegexp::IREF_DEF_BEF,
+          after: Core::DMRegexp::IREF_DEF_AFT
+        }
+      }.freeze
+
+      private_constant :REGEXP_FROM
+
+      # Methods's symbols will be called in sequence to perform the document modifications
+      #
+      # @return [Array<Symbol>] the two symbols of replacement methods
+      def self.replacement_methods
+        %i[replace_refdef replace_irefs]
+      end
+
+      # @return [Hash{Symbol => Object}] the default configuration
+      def self.default_config
+        {
+          from_regexp: '',
+          to_template: '',
+          next_ref: 0
+        }
+      end
+
+      # @param config [YAML] the modifier's provided configurations
+      def initialize(config)
+        @parsing_state = Core::ParsingState.new
+
+        setup_modifier_module(config)
+      end
+
+      # Replace the definition's ref in the line if relevant
+      #
+      # @param line [String] the current line
+      # @return [String] the modified line
+      def replace_refdef(line)
+        if @parsing_state.enabled?(line)
+          do_replace_refdef(line)
+        else
+          line
+        end
+      end
+
+      # Replace the definition's refs in intenal refs
+      #
+      # @param line [String] the current line
+      # @return [String] the modified line
+      def replace_irefs(line)
+        changes.reduce(line) do |res_line, (from, to)|
+          res_line.gsub(Helper.regexp_from(:iref, from)) do
+            Helper.text_with(Regexp.last_match, to)
+          end
+        end
+      end
+
+      private
+
+      def do_replace_refdef(line)
+        line.sub(Helper.regexp_from(:definition, from_regexp)) do
+          replacement_from(Regexp.last_match)
+        end
+      end
+
+      def replacement_from(match)
+        replacement = to_template % hmerge(match)
+        changes << [match[:from], replacement]
+        config[:next_ref] += 1
+        Helper.text_with(match, replacement)
+      end
+
+      def hmerge(match)
+        config.merge(match.named_captures.transform_keys(&:to_sym))
+      end
+
+      # Helper functions
+      module Helper
+        # @param  const [Symbol] the key to retrieve preamble and post-amble
+        # @param  from [Symbol] the piece of text to be replaced
+        # @return [Regexp] a built regexp
+        def self.regexp_from(const, from)
+          regexps = REGEXP_FROM.fetch(const)
+          regexp_str =
+            "(?<before>#{regexps[:before]})" \
+            "(?<from>#{from})" \
+            "#{Core::DMRegexp::DEF_VERSION_AND_CHECKSUM}" \
+            "(?<after>#{regexps[:after]})"
+          Regexp.new(regexp_str, Regexp::EXTENDED)
+        end
+
+        # @param  match [MatchData] The match form Regepxp match
+        # @param  replacement [String] the reference replacement text
+        # @return [String] the overall replaced text
+        def self.text_with(match, replacement)
+          match[:before] + replacement + (match[:version_and_checksum] || '') + match[:after]
+        end
+      end
+    end
+  end
+end

data/lib/defmastership/modifier/factory.rb

@@ -0,0 +1,17 @@
+# Copyright (c) 2023 Jerome Arbez-Gindre
+# frozen_string_literal: true
+
+module Defmastership
+  module Modifier
+    # build modifiers from a piece of configuration
+    module Factory
+      # Build a concrete class from config 'type' field
+      #
+      # @param config [YAML] piece of configuration for this Modifier
+      def self.from_config(config)
+        class_name = config.fetch(:type).split('_').map(&:capitalize).join
+        Modifier.const_get(class_name).new(config.fetch(:config))
+      end
+    end
+  end
+end

data/lib/defmastership/modifier/modifier_common.rb

@@ -0,0 +1,71 @@
+# Copyright (c) 2020 Jerome Arbez-Gindre
+# frozen_string_literal: true
+
+module Defmastership
+  module Modifier
+    # Defines common methods and attributes for line modifiers
+    #
+    # @abstract Include and define +self.replacement_methods+ and +self.default_config+
+    module ModifierCommon
+      # Stores the configuration of this modifier
+      # @return [YAML] configuration as eventualy modified
+      attr_reader :config
+      # Provides the list of performed modifications
+      # @return [Array<Array<String>>] List of performed modifications
+      # (each line: [Modifier, Was, Becomes])
+      attr_reader :changes
+
+      # Setup config from class's default config and provided config
+      #
+      # @param config [YAML] the modifier's provided configurations
+      def setup_modifier_module(config)
+        @config = self.class.default_config.merge(config)
+        @changes = []
+      end
+
+      # Allow to view config items as methods
+      #
+      # @param method_name [Symbol] the name of the method
+      # @param args[Array<Object>] the arguments of the method
+      def method_missing(method_name, *args)
+        config_method_name = config[method_name]
+        return config_method_name if config_method_name
+
+        super
+      end
+
+      # Allow to check if a config item is available
+      #
+      # @param method_name [Symbol] the name of the method
+      # @param args[Array<Object>] the arguments of the method
+      def respond_to_missing?(method_name, *args)
+        config.key?(method_name) || super
+      end
+
+      # Apply the modifier on all provided asciidoc sources based on modifier's
+      # +replacement_methods+ list
+      #
+      # @param adoc_sources [Hash{String => String}] asciidoc sources
+      #  * :key filename
+      #  * :value file content
+      def do_modifications(adoc_sources)
+        self.class.replacement_methods.reduce(adoc_sources) do |texts, method|
+          apply_to_all(texts, method)
+        end
+      end
+
+      private
+
+      def apply_to_all(texts, method)
+        texts.transform_values do |text|
+          apply_to_one(text, method)
+        end
+      end
+
+      def apply_to_one(text, method)
+        text.lines.map { |line| public_send(method, line) }
+            .join
+      end
+    end
+  end
+end

data/lib/defmastership/modifier/rename_included_files.rb

@@ -0,0 +1,223 @@
+# Copyright (c) 2020 Jerome Arbez-Gindre
+# frozen_string_literal: true
+
+require('defmastership/core/constants')
+require('defmastership/matching_line')
+require('defmastership/modifier/modifier_common')
+
+module Defmastership
+  # defintion of the Rename Included Files Modifier
+  module Modifier
+    LOCAL_FILTERS = [
+      Filter.new(Core::DMRegexp::VARIABLE_DEF,  :new_variable_def),
+      Filter.new(Core::DMRegexp::DEFINITION,    :new_definition),
+      Filter.new(Core::DMRegexp::BLOCK,         :block_delimiter),
+      Filter.new(Core::DMRegexp::EMPTY_LINE,    :empty_line),
+      Filter.new(Core::DMRegexp::WHATEVER,      :new_line)
+    ].freeze
+    private_constant :LOCAL_FILTERS
+
+    # Change included filenames on one line at a time
+    class RenameIncludedFiles
+      include ModifierCommon
+
+      PARSER_ACTIONS = {
+        new_variable_def: lambda { |matching_line|
+          @variables.merge!(Helper.variable_def_hash(matching_line.match))
+        },
+        add_line: proc { |_| },
+        add_new_definition: lambda { |matching_line|
+          config[:reference] = matching_line.match[:reference]
+        }
+      }.freeze
+
+      private_constant :PARSER_ACTIONS
+
+      # @return [Array<Symbol>] the only replacement method symbol
+      def self.replacement_methods
+        %i[replace]
+      end
+
+      # @return [Hash{Symbol => Object}] the default configuration
+      def self.default_config
+        {
+          from_regexp: '',
+          to_template: ''
+        }
+      end
+
+      # @param config [YAML] the modifier's provided configurations
+      def initialize(config)
+        @variables = {}
+        @definition_parser = DefinitionParser.new(self)
+
+        setup_modifier_module(config)
+      end
+
+      # Allow to add methods from parser actions
+      #
+      # @param method_name [Symbol] the name of the method
+      # @param args[Array<Object>] the arguments of the method
+      def method_missing(method_name, *args)
+        action = PARSER_ACTIONS[method_name]
+        return instance_exec(*args, &action) if action
+
+        super
+      end
+
+      # Allow to check if a parser action is available
+      #
+      # @param method_name [Symbol] the name of the method
+      # @param args[Array<Object>] the arguments of the method
+      def respond_to_missing?(method_name, *args)
+        PARSER_ACTIONS.key?(method_name) || super
+      end
+
+      # Modify line if it match
+      #
+      # @return [String] the modified line
+      def replace(line)
+        match = matched?(line)
+
+        return line unless match
+
+        new_line = build_new_include_line(match, line)
+
+        rename_file(line, new_line)
+
+        new_line
+      end
+
+      private
+
+      def build_new_include_line(match, line)
+        line.sub(Helper.complete_regexp_from(from_regexp)) do
+          Helper.text_with(match, to_template % Helper.hmerge(config, match))
+        end
+      end
+
+      def matched?(line)
+        return false unless concerned_line?(line)
+        return false unless line =~ Helper.complete_regexp_from(from_regexp)
+
+        match = Regexp.last_match
+
+        return false if config.key?(:cancel_if_match) && match[:filename].match?(cancel_if_match)
+
+        match
+      end
+
+      def concerned_line?(line)
+        return false if line.commented?
+
+        parse(line)
+
+        return false if @definition_parser.idle?
+
+        true
+      end
+
+      def parse(line)
+        Helper.apply_filters_until_consumed(line) do |event, match|
+          generate_event(event, MatchingLine.new(match))
+        end
+      end
+
+      def rename_file(from, to)
+        filename_from = Helper.extract_filename(from, @variables)
+        filename_to = Helper.extract_filename(to, @variables)
+        changes << [filename_from, filename_to]
+        File.rename(filename_from, filename_to)
+      end
+
+      def generate_event(event, matching_line)
+        if PARSER_ACTIONS.key?(event)
+          public_send(event, matching_line)
+        else
+          @definition_parser.public_send(event, matching_line)
+        end
+      end
+
+      # Helper functions
+      module Helper
+        # @param include_statement [String] the overall include statement
+        # @param variables [Hash{Symbol => String}] asciidoc variables for replacement
+        # @return [String] the path+filename from 'include' statement
+        def self.extract_filename(include_statement, variables)
+          filename = filename_from_include_statement(include_statement)
+
+          filename_replace_all_variables(filename, variables).chomp
+        end
+
+        # @param include_statement [String] the overall include statement
+        # @return [String] the path+filename from 'include' statement
+        def self.filename_from_include_statement(include_statement)
+          include_statement
+            .sub(Regexp.new(Core::DMRegexp::INCLUDE_KEYWORD), '')
+            .sub(Regexp.new(Core::DMRegexp::INCLUDE_OPTIONS), '')
+        end
+
+        # @param filename [String] the path+filename from 'include' statement
+        # @param variables [Hash{Symbol => String}] asciidoc variables for replacement
+        # @return [String] the path+filename from 'include' statement with replaced variables
+        def self.filename_replace_all_variables(filename, variables)
+          filename.scan(Core::DMRegexp::VARIABLE_USE) do
+            varname = Regexp.last_match[:varname]
+            value = variables.fetch(varname.to_sym)
+            filename = filename_replace_one_variable(filename, varname, value)
+          end
+          filename
+        end
+
+        # @param filename [String] the path+filename from 'include' statement
+        # @param varname [Symbol] asciidoc variable symbol
+        # @param value [Symbol] asciidoc variable value
+        # @return [String] the path+filename from 'include' statement with one replace variable
+        def self.filename_replace_one_variable(filename, varname, value)
+          filename.sub("{#{varname}}", value)
+        end
+
+        # @param from [String] the piece of regexp to match the filename
+        # @return [Regexp] the regexp to match overal include statement
+        def self.complete_regexp_from(from)
+          Regexp.new(
+            Core::DMRegexp::INCLUDE_KEYWORD + Core::DMRegexp::INCLUDE_PATH +
+            "(?<filename>#{from})" + Core::DMRegexp::INCLUDE_OPTIONS
+          )
+        end
+
+        # @param match [MatchData] from a Regexp match
+        # @param to [String] the replacement text
+        # @return [String] the include statement with replaced filenames
+        def self.text_with(match, to)
+          "include::#{match[:path]}#{to}[#{match[:options]}]"
+        end
+
+        # @param config [Hash{Symbol => Object}] the provided configuration
+        # @param match [MatchData] the match from a regexp with named back refs
+        # @return [Hash{Symbol => String}] config hash merged with match data
+        def self.hmerge(config, match)
+          config.merge(match.names.map(&:to_sym).zip(match.captures).to_h)
+        end
+
+        # @param match [MatchData] the match from a regexp with 'varname' named back refs
+        # @return [Hash{Symbol => String}] a hash with only one key from 'varname'
+        def self.variable_def_hash(match)
+          { match[:varname].to_sym => match[:value] }
+        end
+
+        # Helper function: apply all filters
+        #
+        # @param line [String] the line
+        def self.apply_filters_until_consumed(line)
+          LOCAL_FILTERS.each do |filter|
+            next unless line.match(filter.regexp)
+
+            yield(filter.event, Regexp.last_match)
+            break
+          end
+        end
+      end
+    end
+  end
+end

data/lib/defmastership/modifier/update_def.rb

@@ -0,0 +1,72 @@
+# Copyright (c) 2024 Jerome Arbez-Gindre
+# frozen_string_literal: true
+
+require('defmastership/core/constants')
+
+module Defmastership
+  module Modifier
+    # @abstract Subclass and define +reference_replacement+ to implement a
+    # custom reference replacement class
+    class UpdateDef
+      include ModifierCommon
+
+      attr_reader :document
+
+      # @return [Hash{Symbol => Object}] the default configuration
+      def self.default_config
+        {
+          def_type: ''
+        }
+      end
+
+      # @return [Array<Symbol>] the methods's symbols that will be called in sequence for modifications
+      def self.replacement_methods
+        %i[replace_reference]
+      end
+
+      # Builds a Regexp to match a particular reference defintion (with its
+      # optional version and checksum)
+      #
+      # @param reference [String] the reference
+      # @return [Regexp] the built Regexp
+      def self.reference_regexp(reference)
+        Regexp.new("#{reference}#{Core::DMRegexp::DEF_VERSION_AND_CHECKSUM}")
+      end
+
+      # @param config [YAML] the modifier's provided configurations
+      def initialize(config)
+        @document = Document.new
+
+        setup_modifier_module(config)
+      end
+
+      # Apply the modifier on all provided asciidoc sources based on modifier's
+      # +self.replacement_methods+ list
+      #
+      # @param adoc_sources [Hash{String => String}] asciidoc sources
+      #  * :key filename
+      #  * :value file content
+      def do_modifications(adoc_sources)
+        adoc_sources.each_key do |adoc_file|
+          document.parse_file_with_preprocessor(adoc_file)
+        end
+
+        super
+      end
+
+      # Called on each line for an opportunity for text replacement
+      #
+      # @param line [String] line from asciidoc sources files
+      # @return [String] the modified line
+      def replace_reference(line)
+        match = line.match(Core::DMRegexp::DEFINITION)
+
+        return line unless match
+        return line unless match[:type] == def_type
+
+        reference = match[:reference]
+        line.sub(self.class.reference_regexp(reference), reference_replacement(reference, match))
+      end
+    end
+  end
+end

data/lib/defmastership/modifier/update_def_checksum.rb

@@ -0,0 +1,17 @@
+# Copyright (c) 2020 Jerome Arbez-Gindre
+# frozen_string_literal: true
+
+require 'defmastership/modifier/update_def'
+
+module Defmastership
+  module Modifier
+    # modify one line after another
+    class UpdateDefChecksum < UpdateDef
+      private
+
+      def reference_replacement(reference, match)
+        "#{reference}(#{match[:explicit_version]}#{document.ref_to_def(reference).sha256_short})"
+      end
+    end
+  end
+end