defmastership 1.0.18 → 1.1.0

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

data/lib/defmastership/modifier/update_def_version.rb

@@ -0,0 +1,110 @@
+# Copyright (c) 2020 Jerome Arbez-Gindre
+# frozen_string_literal: true
+
+require 'defmastership/modifier/update_def'
+require 'git'
+require 'tmpdir'
+
+module Defmastership
+  module Modifier
+    # modify one line after another
+    class UpdateDefVersion < UpdateDef
+      # @return [Hash{Symbol => Object}] the default configuration
+      def self.default_config
+        {
+          def_type: '',
+          ref_document: [],
+          ref_tag: '',
+          ref_repo: '.',
+          first_version: ''
+        }
+      end
+
+      # @param config [YAML] the modifier's provided configurations
+      def initialize(config)
+        @ref_document = Document.new
+
+        Helper.normalilize_config!(config) if config.key?(:ref_document)
+
+        super
+      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)
+        if ref_tag == ''
+          ref_document.each { |ref_doc| @ref_document.parse_file_with_preprocessor(ref_doc) }
+        else
+          Dir.mktmpdir('defmastership') do |tmpdir|
+            parse_ref_files_from_git(adoc_sources, tmpdir)
+          end
+        end
+
+        super
+      end
+
+      private
+
+      def parse_ref_files_from_git(adoc_sources, tmpdir)
+        Git.clone(ref_repo, tmpdir, branch: ref_tag)
+        ref_sources = ref_document.empty? ? adoc_sources.keys : ref_document
+        ref_sources.each do |adoc_file|
+          @ref_document.parse_file_with_preprocessor("#{tmpdir}/#{adoc_file}")
+        end
+      end
+
+      def reference_replacement(reference, match)
+        "#{reference}#{version_and_checksum_str(match)}"
+      end
+
+      def version_and_checksum_str(match)
+        explicit_checksum = match[:explicit_checksum]
+        version = version_string(match)
+        return unless explicit_checksum || version
+
+        "(#{version}#{explicit_checksum})"
+      end
+
+      def version_string(match)
+        ref_definition = Helper.def_from_match(@ref_document, match)
+        definition = Helper.def_from_match(document, match)
+        return unless ref_definition
+
+        Helper.ref_version(ref_definition, definition, first_version)
+      end
+
+      # Helper functions
+      module Helper
+        # @param doc [Document] the document with defintions
+        # @param match [MatchData] Regexp match matching a reference
+        # @return [Definition] the definition from a +Document+ with a matching reference
+        def self.def_from_match(doc, match)
+          doc.ref_to_def(match[:reference])
+        end
+
+        # @param ref_definition [Definition] the definition from the reference document
+        # @param definition [Definition] the definition from the current document
+        # @param first_version [String] first version from configuration
+        # @return [String] the current definition version
+        def self.ref_version(ref_definition, definition, first_version)
+          new_ref_version = ref_definition.explicit_version
+          return new_ref_version if definition.sha256_short == ref_definition.sha256_short
+
+          new_ref_version ? new_ref_version.next : first_version
+        end
+
+        # Make sure that ref_document configuration is an Array
+        #
+        # @param config [YAML] the definition from the reference document
+        def self.normalilize_config!(config)
+          ref_docs = config.fetch(:ref_document)
+          config[:ref_document] = [ref_docs] if ref_docs.instance_of?(String)
+        end
+      end
+    end
+  end
+end

data/lib/defmastership/set_join_hack.rb

@@ -4,6 +4,8 @@
 if RUBY_VERSION < '3.0'
   # Ruby 2.7 do not implement join for Set
   class Set
+    # @param args [String] the separator (default: '')
+    # @return [String] join value of the set elements
     def join(*args)
       to_a.join(*args)
     end

data/lib/defmastership/version.rb

@@ -1,7 +1,8 @@
 # Copyright (c) 2020 Jerome Arbez-Gindre
 # frozen_string_literal: true
 
-module DefMastership
-  VERSION = '1.0.18'
+module Defmastership
+  # [String] Gem version
+  VERSION = '1.1.0'
   public_constant :VERSION
 end

data/lib/defmastership.rb

@@ -6,16 +6,14 @@ require('defmastership/version')
 # Add requires for other files you add to your project here, so
 # you just need to require this one file in your bin file
 require('defmastership/batch_modifier')
-require('defmastership/change_ref_modifier')
 require('defmastership/comment_filter')
-require('defmastership/constants')
-require('defmastership/csv_formatter')
 require('defmastership/definition')
 require('defmastership/definition_parser')
 require('defmastership/document')
+require('defmastership/export/csv/formatter')
 require('defmastership/filters')
-require('defmastership/modifier_factory')
-require('defmastership/parsing_state')
-require('defmastership/rename_included_files_modifier')
-require('defmastership/update_def_checksum_modifier')
-require('defmastership/update_def_version_modifier')
+require('defmastership/modifier/change_ref')
+require('defmastership/modifier/factory')
+require('defmastership/modifier/rename_included_files')
+require('defmastership/modifier/update_def_checksum')
+require('defmastership/modifier/update_def_version')