term_utils 0.4.0 → 0.5.0

data/doc/top-level-namespace.html

@@ -6,7 +6,7 @@
 <title>
   Top Level Namespace
   
-    &mdash; Documentation by YARD 0.9.25
+    &mdash; Documentation by YARD 0.9.34
   
 </title>
 
@@ -100,9 +100,9 @@
 </div>
 
       <div id="footer">
-  Generated on Sun Aug  2 18:35:09 2020 by
-  <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
-  0.9.25 (ruby-2.6.5).
+  Generated on Wed Aug  9 17:34:25 2023 by
+  <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
+  0.9.34 (ruby-3.2.2).
 </div>
 
     </div>

data/lib/term_utils/ap/article.rb

@@ -1,6 +1,6 @@
-# frozen-string-literal: true
+# frozen_string_literal: true
 
-# Copyright (C) 2020 Thomas Baron
+# Copyright (C) 2023 Thomas Baron
 #
 # This file is part of term_utils.
 #

data/lib/term_utils/ap/flag.rb

@@ -1,6 +1,6 @@
-# frozen-string-literal: true
+# frozen_string_literal: true
 
-# Copyright (C) 2020 Thomas Baron
+# Copyright (C) 2023 Thomas Baron
 #
 # This file is part of term_utils.
 #

data/lib/term_utils/ap/parameter.rb

@@ -1,6 +1,6 @@
-# frozen-string-literal: true
+# frozen_string_literal: true
 
-# Copyright (C) 2020 Thomas Baron
+# Copyright (C) 2023 Thomas Baron
 #
 # This file is part of term_utils.
 #

data/lib/term_utils/ap/parser.rb

@@ -1,6 +1,6 @@
-# frozen-string-literal: true
+# frozen_string_literal: true
 
-# Copyright (C) 2020 Thomas Baron
+# Copyright (C) 2023 Thomas Baron
 #
 # This file is part of term_utils.
 #
@@ -27,7 +27,8 @@ module TermUtils
       # Parses a given list of arguments.
       # @param syntax [Syntax]
       # @param arguments [Array<String>]
-      # @param opts [Hash]
+      # @param opts [Hash<Symbol, Object>]
+      # @option opts [Boolean] :strict Whether the Syntax must be considered as strict.
       # @return [Result]
       # @raise [ParseError]
       # @raise [SyntaxError]
@@ -52,7 +53,7 @@ module TermUtils
         shortcut_flags.each do |label, flag|
           next unless arg.start_with? label
 
-          return [flag.label, arg[label.length..-1]]
+          return [flag.label, arg[label.length..]]
         end
 
         nil
@@ -96,7 +97,7 @@ module TermUtils
             unless flagged_params.key? arguments.first
               # Unknown flag
               # End of parsing
-              raise TermUtils::AP::ParseError, 'flagged parameter unexpected' if opts.fetch(:strict, false)
+              raise TermUtils::AP::ParseError.new(message: 'flagged parameter unexpected', fault: arguments.first) if opts.fetch(:strict, false)
 
               break
             end
@@ -104,7 +105,7 @@ module TermUtils
             param = flagged_params[arguments.first]
             if param.occur_bounded? && (fp_occ[param.id] >= param.max_occurs)
               # Max occurs reached
-              raise TermUtils::AP::ParseError, "occur limit reached (#{param.id})" if opts.fetch(:strict, false)
+              raise TermUtils::AP::ParseError.new(message: 'occur limit reached', parameter: param.id, fault: arguments.first) if opts.fetch(:strict, false)
 
               break
             end
@@ -117,7 +118,7 @@ module TermUtils
             # Unflagged
             if unflagged_params.empty?
               # End of parsing
-              raise TermUtils::AP::ParseError, 'unflagged parameter unexpected' if opts.fetch(:strict, false)
+              raise TermUtils::AP::ParseError.new(message: 'unflagged parameter unexpected', fault: arguments.first) if opts.fetch(:strict, false)
 
               break
             end
@@ -125,7 +126,7 @@ module TermUtils
             param = unflagged_params.first
             if arguments.first == '--'
               # End of parameter
-              raise TermUtils::AP::ParseError, "parameter not consumed (#{param.id})" if up_occ < param.min_occurs
+              raise TermUtils::AP::ParseError.new(message: 'parameter not consumed', parameter: param.id) if up_occ < param.min_occurs
 
               arguments.shift
               unflagged_params.shift
@@ -137,7 +138,7 @@ module TermUtils
             param_res = TermUtils::AP::ParameterResult.new(result, param)
             case parse0_param(param_res, param, arguments)
             when :esc_param
-              raise TermUtils::AP::ParseError, "parameter not consumed (#{param.id})" if up_occ < param.min_occurs
+              raise TermUtils::AP::ParseError.new(message: 'parameter not consumed', parameter: param.id) if up_occ < param.min_occurs
 
               unflagged_params.shift
               up_occ = 0
@@ -153,7 +154,7 @@ module TermUtils
         syntax.parameters.each do |p|
           next if result.find_parameters(p.id).length >= p.min_occurs
 
-          raise TermUtils::AP::ParseError, "parameter not consumed (#{p.id})"
+          raise TermUtils::AP::ParseError.new(message: 'parameter not consumed', parameter: p.id)
         end
       end
 
@@ -170,15 +171,15 @@ module TermUtils
 
           if arguments.empty?
             # End of arguments
-            raise TermUtils::AP::ParseError, 'article not consumed' if occ < arts.first.min_occurs
-            raise TermUtils::AP::ParseError, 'article not consumed' if self.class.eval_article_min_occurs(arts[1..-1]) > 0
+            raise TermUtils::AP::ParseError.new(message: 'article not consumed', parameter: param.id) if occ < arts.first.min_occurs
+            raise TermUtils::AP::ParseError.new(message: 'article not consumed', parameter: param.id) if self.class.eval_article_min_occurs(arts[1..]) > 0
 
             break
           end
 
           if arguments.first == '-'
             # End of article
-            raise TermUtils::AP::ParseError, 'article not consumed' if occ < arts.first.min_occurs
+            raise TermUtils::AP::ParseError.new(message: 'article not consumed', parameter: param.id) if occ < arts.first.min_occurs
 
             arguments.shift
             arts.shift
@@ -186,8 +187,8 @@ module TermUtils
             next
           elsif arguments.first.start_with? '-'
             # End of parameter
-            raise TermUtils::AP::ParseError, 'article not consumed' if occ < arts.first.min_occurs
-            raise TermUtils::AP::ParseError, 'article not consumed' if self.class.eval_article_min_occurs(arts[1..-1]) > 0
+            raise TermUtils::AP::ParseError.new(message: 'article not consumed', parameter: param.id) if occ < arts.first.min_occurs
+            raise TermUtils::AP::ParseError.new(message: 'article not consumed', parameter: param.id) if self.class.eval_article_min_occurs(arts[1..]) > 0
 
             if arguments.first == '--'
               arguments.shift

data/lib/term_utils/ap/result.rb

@@ -1,6 +1,6 @@
-# frozen-string-literal: true
+# frozen_string_literal: true
 
-# Copyright (C) 2020 Thomas Baron
+# Copyright (C) 2023 Thomas Baron
 #
 # This file is part of term_utils.
 #

data/lib/term_utils/ap/syntax.rb

@@ -1,6 +1,6 @@
-# frozen-string-literal: true
+# frozen_string_literal: true
 
-# Copyright (C) 2020 Thomas Baron
+# Copyright (C) 2023 Thomas Baron
 #
 # This file is part of term_utils.
 #

data/lib/term_utils/ap.rb

@@ -1,6 +1,6 @@
-# frozen-string-literal: true
+# frozen_string_literal: true
 
-# Copyright (C) 2020 Thomas Baron
+# Copyright (C) 2023 Thomas Baron
 #
 # This file is part of term_utils.
 #
@@ -16,28 +16,79 @@
 # You should have received a copy of the GNU General Public License
 # along with term_utils.  If not, see <https://www.gnu.org/licenses/>.
 
+require 'term_utils/ap/article'
+require 'term_utils/ap/flag'
+require 'term_utils/ap/parameter'
+require 'term_utils/ap/syntax'
+require 'term_utils/ap/result'
+require 'term_utils/ap/parser'
+
 module TermUtils
   # The Argument Parser module provides a way to parse arguments.
   module AP
-    # NoSuchValueError.
-    class NoSuchValueError < StandardError
-      def initialize(msg)
-        super
-      end
-    end
-
     # ParseError.
     class ParseError < StandardError
-      def initialize(msg)
-        super
+      # Constructs a new ParseError.
+      # @param props [Hash<Symbol, Object>]
+      def initialize(props = {})
+        super(self.class.create_message(props))
+        @props = props.dup
+      end
+
+      # Returns the properties associated to this one.
+      # @return [Hash<Symbol, Object>]
+      def props
+        @props.dup
+      end
+
+      # Returns the short message (i.e. the message without properties).
+      # @return [String] The short message.
+      def short_message
+        @props.fetch(:message)
+      end
+
+      # Tests whether this one has a syntax parameter ID.
+      # @return [Boolean]
+      def parameter?
+        @props.key?(:parameter)
+      end
+
+      # Returns the syntax parameter ID (if any).
+      # @return [Symbol, nil] The syntax parameter ID if any, `nil` otherwise.
+      def parameter
+        @props.fetch(:parameter, nil)
+      end
+
+      # Tests whether this one has a faulty argument.
+      # @return [Boolean]
+      def fault?
+        @props.key?(:fault)
+      end
+
+      # Returns the faulty argument (if any).
+      # @return [String, nil] The faulty argument if any, `nil` otherwise.
+      def fault
+        @props.fetch(:fault, nil)
+      end
+
+      # Creates a message based on given properties.
+      # @param props [Hash<Symbol, Object>]
+      # @return [String]
+      def self.create_message(props)
+        props = props.dup
+        msg = props.delete(:message) { |key| raise StandardError, "#{key} property is mandatory" }
+        return msg if props.empty?
+
+        vals = []
+        props.each do |key, val|
+          vals << "#{key}: \"#{val}\""
+        end
+        "#{msg} (#{vals.join(', ')})"
       end
     end
 
     # SyntaxError.
     class SyntaxError < StandardError
-      def initialize(msg)
-        super
-      end
     end
 
     # Creates a new Syntax.
@@ -52,7 +103,7 @@ module TermUtils
     # @param syntax [Syntax]
     # @param arguments [Array<String>]
     # @param opts [Hash]
-    # @option opts [Boolean] :strict Whether the Syntax must be considered strict.
+    # @option opts [Boolean] :strict Whether the Syntax must be considered as strict.
     # @return [Result]
     # @raise [ParseError]
     # @raise [SyntaxError]
@@ -61,10 +112,3 @@ module TermUtils
     end
   end
 end
-
-require 'term_utils/ap/article'
-require 'term_utils/ap/flag'
-require 'term_utils/ap/parameter'
-require 'term_utils/ap/syntax'
-require 'term_utils/ap/result'
-require 'term_utils/ap/parser'

data/lib/term_utils/ff/config.rb

@@ -1,6 +1,6 @@
-# frozen-string-literal: true
+# frozen_string_literal: true
 
-# Copyright (C) 2020 Thomas Baron
+# Copyright (C) 2023 Thomas Baron
 #
 # This file is part of term_utils.
 #
@@ -47,8 +47,8 @@ module TermUtils
       end
 
       def initialize_copy(other)
-        @ignore_list = other.ignore_list.dup
         super
+        @ignore_list = @ignore_list.dup
       end
     end
   end

data/lib/term_utils/ff/entry.rb

@@ -1,6 +1,6 @@
-# frozen-string-literal: true
+# frozen_string_literal: true
 
-# Copyright (C) 2020 Thomas Baron
+# Copyright (C) 2023 Thomas Baron
 #
 # This file is part of term_utils.
 #

data/lib/term_utils/ff/finder.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+# Copyright (C) 2023 Thomas Baron
+#
+# This file is part of term_utils.
+#
+# term_utils 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, version 3 of the License.
+#
+# term_utils 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 term_utils.  If not, see <https://www.gnu.org/licenses/>.
+
+module TermUtils
+  module FF
+    # Represents filesystem Entry.
+    class FinderEntry
+      # @return [Integer]
+      attr_accessor :index
+      # @return [String]
+      attr_accessor :name
+      # Identifies the type of stat. The return string is one of: “file”,
+      # “directory”, “characterSpecial”, “blockSpecial”, “fifo”, “link”,
+      # “socket”, or “unknown”.
+      # @return [String]
+      attr_accessor :kind
+      # Returns the numeric user id of the owner of stat.
+      # @return [Integer]
+      attr_accessor :uid
+      # Returns the numeric group id of the owner of stat.
+      # @return [Integer]
+      attr_accessor :gid
+      # Returns an integer representing the permission bits of stat. The meaning
+      # of the bits is platform dependent.
+      # @return [Integer]
+      attr_accessor :mode
+      # Returns the size of stat in bytes.
+      # @return [Integer]
+      attr_accessor :size
+      # @return [Array<String>]
+      attr_accessor :path_parts
+      # @return [String]
+      attr_accessor :path
+
+      def initialize
+        @index = nil
+        @name = nil
+        @kind = nil
+        @path_parts = nil
+        @path = nil
+      end
+
+      def directory?
+        @kind == 'directory'
+      end
+
+      def file?
+        @kind == 'file'
+      end
+
+      # @return [Integer]
+      def depth
+        @path_parts.length
+      end
+    end
+
+    # Represents a Query.
+    class FinderQuery
+      # @return [Integer]
+      attr_accessor :min_depth
+      # @return [Integer, nil]
+      attr_accessor :max_depth
+      # @return [Boolean]
+      attr_accessor :use_stat
+      # @return [String, Array<String>, nil]
+      attr_accessor :entry_kind
+
+      def initialize
+        @min_depth = 0
+        @max_depth = nil
+        @use_stat = false
+        @entry_kind = nil
+        @filters = []
+      end
+
+      def filter(kind, &block)
+        raise StandardError, 'wrong filter kind' unless %i[enter skip include exclude].include?(kind)
+        raise StandardError, "missing #{kind} block" if block.nil?
+
+        @filters << { kind: kind, block: block }
+      end
+
+      # Wether to enter a directory.
+      def enter_directory(&block)
+        filter(:enter, &block)
+      end
+
+      # Wether not to enter a directory.
+      def skip_directory(&block)
+        filter(:skip, &block)
+      end
+
+      # Wether to include an entry into the results.
+      def include_entry(&block)
+        filter(:include, &block)
+      end
+
+      # Wether to exclue an entry from the results.
+      def exclude_entry(&block)
+        filter(:exclude, &block)
+      end
+
+      def each_filter(&block)
+        @filters.each(&block)
+      end
+    end
+
+    # Represents the find method engine.
+    class Finder
+      attr_reader :query
+
+      def initialize(paths)
+        @paths = paths.dup
+        @query = FinderQuery.new
+      end
+
+      def exec
+        @paths.each_with_object([]) do |path, obj|
+          ctx = { entries: obj, basedir: path }
+          list_start(ctx)
+        end
+      end
+
+      def list_start(ctx)
+        entry = FinderEntry.new.tap do |e|
+          e.index = ctx[:entries].length
+          e.name = File.basename(ctx[:basedir])
+          if @query.use_stat
+            st = File.stat(ctx[:basedir])
+            e.kind = st.ftype
+            e.uid = st.uid
+            e.gid = st.gid
+            e.mode = st.mode
+            e.size = st.size
+          end
+          e.path_parts = []
+          e.path = ctx[:basedir]
+        end
+        ctx[:entries] << entry if match?(entry) && include?(entry)
+        return unless enter?(entry)
+
+        list(ctx)
+      end
+
+      def list(ctx)
+        path_parts = ctx.fetch(:path_parts, [])
+        absolute_path =
+          if path_parts.empty?
+            ctx[:basedir]
+          else
+            "#{ctx[:basedir]}/#{path_parts.join('/')}"
+          end
+        entries = Dir.entries(absolute_path)
+        entries.each do |name|
+          next if %w[. ..].include?(name)
+
+          entry = FinderEntry.new.tap do |e|
+            e.index = ctx[:entries].length
+            e.name = name
+            if @query.use_stat
+              st = File.stat("#{absolute_path}/#{name}")
+              e.kind = st.ftype
+              e.uid = st.uid
+              e.gid = st.gid
+              e.mode = st.mode
+              e.size = st.size
+            end
+            e.path_parts = path_parts.dup + [name]
+            e.path = "#{ctx[:basedir]}/#{e.path_parts.join('/')}"
+          end
+          ctx[:entries] << entry if match?(entry) && include?(entry)
+          if enter?(entry)
+            list(ctx.merge({ path_parts: entry.path_parts }))
+          end
+        end
+      end
+
+      def match?(entry)
+        # (1of2) Depth
+        return false if entry.depth < @query.min_depth
+        return false if !@query.max_depth.nil? && entry.depth > @query.max_depth
+
+        # (2of2) Entry kind.
+        if @query.entry_kind.nil?
+          true
+        elsif @query.entry_kind.is_a?(String)
+          entry.kind == @query.entry_kind
+        elsif @query.entry_kind.is_a?(Array)
+          @query.entry_kind.include?(entry.kind)
+        else
+          false
+        end
+      end
+
+      def enter?(entry)
+        unless @query.use_stat
+          return File.directory?(entry.path)
+        end
+
+        return false unless entry.directory?
+
+        @query.each_filter do |f|
+          case f[:kind]
+          when :enter
+            return true if f[:block].call(entry)
+          when :skip
+            return false if f[:block].call(entry)
+          end
+        end
+        true
+      end
+
+      def include?(entry)
+        @query.each_filter do |f|
+          case f[:kind]
+          when :include
+            return true if f[:block].call(entry)
+          when :exclude
+            return false if f[:block].call(entry)
+          end
+        end
+        true
+      end
+    end
+
+    # Finds files.
+    # @param paths [Array<String>]
+    # @return [Array<Hash>]
+    def self.find(*paths, &block)
+      fdr =
+        if paths.empty?
+          TermUtils::FF::Finder.new(['.'])
+        else
+          TermUtils::FF::Finder.new(paths)
+        end
+      block&.call(fdr.query)
+      fdr.exec
+    end
+  end
+end

data/lib/term_utils/ff/query.rb

@@ -1,6 +1,6 @@
-# frozen-string-literal: true
+# frozen_string_literal: true
 
-# Copyright (C) 2020 Thomas Baron
+# Copyright (C) 2023 Thomas Baron
 #
 # This file is part of term_utils.
 #
@@ -28,11 +28,11 @@ module TermUtils
       end
 
       def initialize_copy(other)
-        @config = other.config.dup
         super
+        @config = @config.dup
       end
 
-      # Adds a Regexp to ignore.
+      # Adds a Regexp for ignoring file names.
       # @param regexp [Regexp]
       # @return [Query]
       def ignore(regexp)
@@ -133,10 +133,8 @@ module TermUtils
       # @param name [String]
       # @return [Boolean]
       def self.accept_entry_name?(ctx, name)
-        ctx.config.ignore_list.each do |i|
-          if i.match? name
-            return false
-          end
+        ctx.config.ignore_list.each do |e|
+          return false if e.match?(name)
         end
         true
       end

data/lib/term_utils/ff.rb

@@ -1,6 +1,6 @@
-# frozen-string-literal: true
+# frozen_string_literal: true
 
-# Copyright (C) 2020 Thomas Baron
+# Copyright (C) 2023 Thomas Baron
 #
 # This file is part of term_utils.
 #
@@ -17,7 +17,7 @@
 # along with term_utils.  If not, see <https://www.gnu.org/licenses/>.
 
 module TermUtils
-  # Provides a way to find files.
+  # Provides ways to find files.
   module FF
   end
 end
@@ -25,3 +25,4 @@ end
 require 'term_utils/ff/config'
 require 'term_utils/ff/entry'
 require 'term_utils/ff/query'
+require 'term_utils/ff/finder'

data/lib/term_utils/property_tree_node.rb

@@ -1,6 +1,6 @@
-# frozen-string-literal: true
+# frozen_string_literal: true
 
-# Copyright (C) 2020 Thomas Baron
+# Copyright (C) 2023 Thomas Baron
 #
 # This file is part of term_utils.
 #
@@ -191,7 +191,7 @@ module TermUtils
     # @return [PropertyTreeNode]
     def find_node(path)
       catch :found do
-        each_node(path: path) do |n|
+        each_node(path: path) do |n| # rubocop:disable Lint/UnreachableLoop
           throw :found, n
         end
         nil