term_utils 0.3.2 → 0.5.0

data/lib/term_utils/ap.rb

@@ -1,4 +1,6 @@
-# Copyright (C) 2019 Thomas Baron
+# frozen_string_literal: true
+
+# Copyright (C) 2023 Thomas Baron
 #
 # This file is part of term_utils.
 #
@@ -13,21 +15,82 @@
 #
 # 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/property_tree_node'
-require 'term_utils/ap/no_such_value_error'
-require 'term_utils/ap/parse_error'
-require 'term_utils/ap/syntax_error'
+
 require 'term_utils/ap/article'
 require 'term_utils/ap/flag'
-require 'term_utils/ap/element'
-require 'term_utils/ap/level'
 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 command arguments.
+  # The Argument Parser module provides a way to parse arguments.
   module AP
+    # ParseError.
+    class ParseError < StandardError
+      # 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
+    end
+
     # Creates a new Syntax.
     # @return [TermUtils::AP::Syntax]
     def self.create_syntax(&block)
@@ -35,25 +98,17 @@ module TermUtils
       block.call(new_syntax) if block
       new_syntax
     end
-    # Parses a given command.
-    # @param syntax [TermUtils::AP::Syntax]
-    # @param command [String]
-    # @param opts [Hash]
-    # @return [TermUtils::AP::Result]
-    # @raise [TermUtils::AP::ParseError]
-    # @raise [TermUtils::AP::SyntaxError]
-    def self.parse_command(syntax, command, opts = {})
-      TermUtils::AP::Parser.new.parse_command(syntax, command, opts)
-    end
+
     # Parses a given list of arguments.
-    # @param syntax [TermUtils::AP::Syntax]
+    # @param syntax [Syntax]
     # @param arguments [Array<String>]
     # @param opts [Hash]
-    # @return [TermUtils::AP::Result]
-    # @raise [TermUtils::AP::ParseError]
-    # @raise [TermUtils::AP::SyntaxError]
-    def self.parse_arguments(syntax, arguments, opts = {})
-      TermUtils::AP::Parser.new.parse_arguments(syntax, arguments, opts)
+    # @option opts [Boolean] :strict Whether the Syntax must be considered as strict.
+    # @return [Result]
+    # @raise [ParseError]
+    # @raise [SyntaxError]
+    def self.parse_arguments(syntax, arguments, opts = {}, &block)
+      TermUtils::AP::Parser.new.parse_arguments(syntax, arguments, opts, &block)
     end
   end
 end

data/lib/term_utils/ff/config.rb

@@ -1,6 +1,6 @@
-# frozen-string-literal: true
-#
-# Copyright (C) 2019 Thomas Baron
+# frozen_string_literal: true
+
+# Copyright (C) 2023 Thomas Baron
 #
 # This file is part of term_utils.
 #
@@ -15,28 +15,40 @@
 #
 # 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
-  # The ff module provides a way to find files.
   module FF
     # Represents a query configuration.
     class Config
       # @return [Array<Regexp>]
       attr_accessor :ignore_list
-      # @return [Integer]
+      # @return [Integer, nil]
       attr_accessor :min_depth
-      # @return [Integer]
+      # @return [Integer, nil]
       attr_accessor :max_depth
-      # @return [Boolean]
-      attr_accessor :sorted
+      # @return [Symbol, nil] Either `:forward`, `:reverse` or `nil` (default).
+      attr_accessor :sorting_mode
+      # @return [Proc, nil]
+      attr_accessor :sorting_compare
+
+      # Constructs a new Config.
       def initialize
         @ignore_list = []
         @min_depth = nil
         @max_depth = nil
-        @sorted = false
+        @sorting_mode = nil
+        @sorting_compare = nil
+      end
+
+      # Returns whether the search is ordered.
+      # @return [Boolean]
+      def sorted?
+        (@sorting_mode == :forward) || (@sorting_mode == :reverse)
       end
+
       def initialize_copy(other)
-        @ignore_list = other.ignore_list.dup
         super
+        @ignore_list = @ignore_list.dup
       end
     end
   end

data/lib/term_utils/{ap/no_such_value_error.rb → ff/entry.rb}

@@ -1,6 +1,6 @@
-# frozen-string-literal: true
-#
-# Copyright (C) 2019 Thomas Baron
+# frozen_string_literal: true
+
+# Copyright (C) 2023 Thomas Baron
 #
 # This file is part of term_utils.
 #
@@ -15,12 +15,30 @@
 #
 # 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 AP
-    # No such value error.
-    class NoSuchValueError < StandardError
-      def initialize(msg)
-        super
+  module FF
+    # Represents an Entry of a Query result.
+    class Entry
+      # @return [Integer]
+      attr_accessor :index
+      # @return [String]
+      attr_accessor :name
+      # @return [Array<String>]
+      attr_accessor :relative_path_comps
+      # @return [String]
+      attr_accessor :path
+
+      def initialize
+        @index = nil
+        @name = nil
+        @relative_path_comps = nil
+        @path = nil
+      end
+
+      # @return [Integer]
+      def depth
+        @relative_path_comps.length
       end
     end
   end

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
-#
-# Copyright (C) 2019 Thomas Baron
+# frozen_string_literal: true
+
+# Copyright (C) 2023 Thomas Baron
 #
 # This file is part of term_utils.
 #
@@ -15,51 +15,128 @@
 #
 # 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
-  # The ff module provides a way to find files.
   module FF
+    # Query search context.
+    Context = Struct.new('Context', :config, :base_path, :block, :index_seq, :result)
     # Represents a file system query.
     class Query
+      # Constructs a new Query.
       def initialize
         @config = TermUtils::FF::Config.new
       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 [TermUtils::FF::Query]
+      # @return [Query]
       def ignore(regexp)
         @config.ignore_list << regexp
         self
       end
+
       # Sets a minimum depth.
       # @param depth [Integer]
-      # @return [TermUtils::FF::Query]
+      # @return [Query]
       def min_depth(depth)
         @config.min_depth = depth
         self
       end
+
       # Sets a maximum depth.
       # @param depth [Integer]
-      # @return [TermUtils::FF::Query]
+      # @return [Query]
       def max_depth(depth)
         @config.max_depth = depth
         self
       end
-      # Sets whether results shall be sorted.
-      # @param sorted [Boolean]
-      # @return [TermUtils::FF::Query]
-      def sort(sorted = true)
-        @config.sorted = sorted
+
+      # Sets the sorting mode.
+      # @param mode [Symbol] Either `:forward`, `:reverse` or `nil` (default).
+      # @return [Query]
+      def sort(mode = :forward, &block)
+        @config.sorting_mode = mode
+        @config.sorting_compare = block
         self
       end
+
       # Executes this one.
       # @param path [String]
-      # @return [TermUtils::FF::Cursor]
-      def exec(path)
-        TermUtils::FF::Cursor.new(@config.dup, path).bootstrap
+      # @return [Array<Entry>]
+      def exec(path, &block)
+        ctx = Context.new
+        ctx.config = @config.dup
+        ctx.config.min_depth = 0 if ctx.config.min_depth.nil?
+        ctx.base_path = path
+        ctx.block = block
+        ctx.index_seq = 0
+        ctx.result = []
+        first_entry = TermUtils::FF::Entry.new
+        first_entry.name = path
+        first_entry.relative_path_comps = []
+        first_entry.path = path
+        if ctx.config.min_depth == 0
+          first_entry.index = ctx.index_seq
+          ctx.index_seq += 1
+          ctx.block.call(first_entry) if ctx.block
+          ctx.result << first_entry
+        end
+        if File.directory?(first_entry.path) && (ctx.config.max_depth.nil? || ctx.config.max_depth > 0)
+          TermUtils::FF::Query.search(ctx, first_entry)
+        end
+        ctx.result
+      end
+
+      # Searches a directory.
+      # @param ctx [Context]
+      # @param parent_entry [entry]
+      # @return [nil]
+      def self.search(ctx, parent_entry)
+        entries = Dir.entries(parent_entry.path)
+        unless ctx.config.sorting_mode.nil?
+          if ctx.config.sorting_compare.nil?
+            entries.sort!
+          else
+            entries.sort!(&ctx.config.sorting_compare)
+          end
+          if ctx.config.sorting_mode == :reverse
+            entries.reverse!
+          end
+        end
+        entries.each do |name|
+          next if %w[. ..].include? name
+          next unless accept_entry_name?(ctx, name)
+
+          new_entry = TermUtils::FF::Entry.new
+          new_entry.name = name
+          new_entry.relative_path_comps = parent_entry.relative_path_comps.dup.push(name)
+          new_entry.path = "#{ctx.base_path}/#{new_entry.relative_path_comps.join('/')}"
+          if ctx.config.min_depth <= new_entry.depth
+            new_entry.index = ctx.index_seq
+            ctx.index_seq += 1
+            ctx.block.call(new_entry) if ctx.block
+            ctx.result << new_entry
+          end
+          if File.directory?(new_entry.path) && (ctx.config.max_depth.nil? || ctx.config.max_depth > new_entry.depth)
+            TermUtils::FF::Query.search(ctx, new_entry)
+          end
+        end
+      end
+
+      # Tests whether a given entry should be accepted.
+      # @param ctx [Context]
+      # @param name [String]
+      # @return [Boolean]
+      def self.accept_entry_name?(ctx, name)
+        ctx.config.ignore_list.each do |e|
+          return false if e.match?(name)
+        end
+        true
       end
     end
   end

data/lib/term_utils/ff.rb

@@ -1,4 +1,6 @@
-# Copyright (C) 2019 Thomas Baron
+# frozen_string_literal: true
+
+# Copyright (C) 2023 Thomas Baron
 #
 # This file is part of term_utils.
 #
@@ -13,6 +15,14 @@
 #
 # 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
+  # Provides ways to find files.
+  module FF
+  end
+end
+
 require 'term_utils/ff/config'
-require 'term_utils/ff/cursor'
+require 'term_utils/ff/entry'
 require 'term_utils/ff/query'
+require 'term_utils/ff/finder'