recls-ruby 2.11.0.3 → 2.12.0

data/lib/recls/file_search.rb

@@ -1,14 +1,13 @@
-# ######################################################################## #
-# File:     recls/file_search.rb
+# ######################################################################### #
+# File:         recls/file_search.rb
 #
-# Purpose:  Defines the Recls::FileSearch class for the recls.Ruby library.
+# Purpose:      Defines the Recls::FileSearch class for the recls.Ruby library.
 #
-# Created:  24th July 2012
-# Updated:  20th April 2024
+# Created:      24th July 2012
+# Updated:      14th April 2019
 #
-# Author:   Matthew Wilson
+# Author:       Matthew Wilson
 #
-# Copyright (c) 2019-2024, Matthew Wilson and Synesis Information Systems
 # Copyright (c) 2012-2019, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
@@ -34,295 +33,295 @@
 # ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 # POSSIBILITY OF SUCH DAMAGE.
 #
-# ######################################################################## #
+# ######################################################################### #
 
 
 require 'recls/entry'
 require 'recls/flags'
 require 'recls/ximpl/os'
 
-
 =begin
 =end
 
-# @!visibility private
 class Object; end # :nodoc:
 
 module Recls
 
-  class FileSearch # :nodoc: all
+	class FileSearch # :nodoc: all
 
-    include Enumerable
+		include Enumerable
 
-    # Initialises a +FileSearch+ instance, which acts as an +Enumerable+
-    # of +Recls::Entry+
-    #
-    # === Signature
-    #
-    # * *Parameters:*
-    #   - +search_root+ (+String+, +Recls::Entry+) The root directory of the search. May be +nil+, in which case the current directory is assumed;
-    #   - +patterns+ (+String+, +Array+) The pattern(s) for which to search. May be +nil+, in which case +Recls::WILDCARDS_ALL+ is assumed;
-    #   - +options+ (+Hash+, +Integer+) Combination of flags (with behaviour as described below for the +flags+ option), or an options hash;
-    #
-    # * *Options:*
-    #   - +flags+ (+Integer+) Combination of flags - +Recls::FILES+, +Recls::DIRECTORIES+, +Recls::RECURSIVE+, etc. If the value modulo +Recls::TYPEMASK+ is 0, then +Recls::FILES+ is assumed;
-    #
-    # === Return
-    # An instance of the class.
-    def initialize(search_root, patterns, options={})
+		# Initialises a +FileSearch+ instance, which acts as an +Enumerable+
+		# of Recls::Entry
+		#
+		# === Signature
+		#
+		# * *Parameters:*
+		#   - +search_root+ (String, Recls::Entry) The root directory of the search. May be +nil+, in which case the current directory is assumed
+		#   - +patterns+ (String, Array) The pattern(s) for which to search. May be +nil+, in which case +Recls::WILDCARDS_ALL+ is assumed
+		#   - +options+ (Hash, Integer) Combination of flags (with behaviour as described below for the +flags+ option), or an options hash
+		#
+		# * *Options:*
+		#   - +flags+ (Integer) Combination of flags - FILES, DIRECTORIES, RECURSIVE, etc. If the value modulo TYPEMASK is 0, then FILES is assumed
+		#
+		# === Return
+		#  An instance of the class
+		#
+		def initialize(search_root, patterns, options={})
 
-      # for backwards compatibility, we allow for options to
-      # be a number
+			# for backwards compatibility, we allow for options to
+			# be a number
 
-      flags = 0
+			flags	=	0
 
-      case options
-      when ::NilClass
+			case options
+			when ::NilClass
 
-        options = { flags: 0 }
-      when ::Integer
+				options	=	{ flags: 0 }
+			when ::Integer
 
-        flags   = options
-        options = { flags: flags }
-      when ::Hash
+				flags	=	options
+				options	=	{ flags: flags }
+			when ::Hash
 
-        flags = options[:flags] || 0
-      else
+				flags	=	options[:flags] || 0
+			else
 
-        raise ArgumentError, "options parameter must a #{::Hash}, nil, or an integer specifying flags - an instance of #{options.class} given"
-      end
+				raise ArgumentError, "options parameter must a #{::Hash}, nil, or an integer specifying flags - an instance of #{options.class} given"
+			end
 
 
-      if not search_root
+			if not search_root
 
-        search_root = '.'
-      else
+				search_root = '.'
+			else
 
-        search_root = search_root.to_s
-      end
-      search_root = '.' if search_root.empty?
-      search_root = File.expand_path(search_root) if '~' == search_root[0]
+				search_root = search_root.to_s
+			end
+			search_root = '.' if search_root.empty?
+			search_root = File.expand_path(search_root) if '~' == search_root[0]
 
-      case patterns
-      when NilClass
+			case	patterns
+			when	NilClass
 
-        patterns = []
-      when String
+				patterns = []
+			when	String
 
-        patterns = patterns.split(/[|#{Recls::Ximpl::OS::PATH_SEPARATOR}]/)
-      when Array
-      else
+				patterns = patterns.split(/[|#{Recls::Ximpl::OS::PATH_SEPARATOR}]/)
+			when	Array
+			else
 
-        patterns = patterns.to_a
-      end
+				patterns = patterns.to_a
+			end
 
-      patterns = [ Recls::WILDCARDS_ALL ] if patterns.empty?
+			patterns = [ Recls::WILDCARDS_ALL ] if patterns.empty?
 
-      if(0 == (Recls::TYPEMASK & flags))
+			if(0 == (Recls::TYPEMASK & flags))
 
-        flags |= Recls::FILES
-      end
+				flags |= Recls::FILES
+			end
 
-      # now de-dup the patterns, to avoid duplicates in search
-      patterns      = patterns.flatten
-      patterns      = patterns.uniq
+			# now de-dup the patterns, to avoid duplicates in search
+			patterns		=	patterns.flatten
+			patterns		=	patterns.uniq
 
-      @search_root  = search_root
-      @patterns     = patterns
-      @flags        = flags
-    end
+			@search_root	=	search_root
+			@patterns		=	patterns
+			@flags			=	flags
+		end
 
-    # (+String+) The search root
-    attr_reader :search_root
-    # (+String+) The search patterns
-    attr_reader :patterns
-    # (+Integer+) The search flags
-    attr_reader :flags
+		# (String) The search root
+		attr_reader :search_root
+		# (String) The search patterns
+		attr_reader :patterns
+		# (Integer) The search flags
+		attr_reader :flags
 
-    # Calls the block once for each found file, passing a single
-    # parameter that is a Recls::Entry instance
-    #
-    # @!visibility private
-    def each(&blk) # :nodoc:
+		# Calls the block once for each found file, passing a single
+		# parameter that is a Recls::Entry instance
+		#
+		# @!visibility private
+		def each(&blk) # :nodoc:
 
-      search_root = @search_root
-      search_root = Recls::Ximpl::absolute_path search_root
+			search_root = @search_root
+			search_root = Recls::Ximpl::absolute_path search_root
 
-      search_root = search_root.gsub(/\\/, '/') if Recls::Ximpl::OS::OS_IS_WINDOWS
+			search_root = search_root.gsub(/\\/, '/') if Recls::Ximpl::OS::OS_IS_WINDOWS
 
-      # set the (type part of the) flags to zero if we want
-      # everything, to facilitate later optimisation
+			# set the (type part of the) flags to zero if we want
+			# everything, to facilitate later optimisation
 
-      flags = @flags
+			flags = @flags
 
-      if(Recls::Ximpl::OS::OS_IS_WINDOWS)
+			if(Recls::Ximpl::OS::OS_IS_WINDOWS)
 
-        mask = (Recls::FILES | Recls::DIRECTORIES)
-      else
+				mask = (Recls::FILES | Recls::DIRECTORIES)
+			else
 
-        mask = (Recls::FILES | Recls::DIRECTORIES | Recls::LINKS | Recls::DEVICES)
-      end
+				mask = (Recls::FILES | Recls::DIRECTORIES | Recls::LINKS | Recls::DEVICES)
+			end
 
-      if(mask == (mask & flags))
+			if(mask == (mask & flags))
 
-        flags = flags & ~Recls::TYPEMASK
-      end
+				flags = flags & ~Recls::TYPEMASK
+			end
 
-      patterns = @patterns
+			patterns = @patterns
 
-      patterns = patterns.map do |pattern|
+			patterns = patterns.map do |pattern|
 
-        pattern = pattern.gsub(/\./, '\\.')
-        pattern = pattern.gsub(/\?/, '.')
-        pattern = pattern.gsub(/\*/, '.*')
-        pattern
-      end
+				pattern = pattern.gsub(/\./, '\\.')
+				pattern = pattern.gsub(/\?/, '.')
+				pattern = pattern.gsub(/\*/, '.*')
+				pattern
+			end
 
-      search_dir  = search_root
-      search_root = Recls::Ximpl::Util.append_trailing_slash search_root
+			search_dir	=	search_root
+			search_root	=	Recls::Ximpl::Util.append_trailing_slash search_root
 
-      FileSearch::search_directory_(search_root, search_dir, patterns, flags, &blk)
-    end
+			FileSearch::search_directory_(search_root, search_dir, patterns, flags, &blk)
+		end
 
-    private
-    # @!visibility private
-    def FileSearch.is_dots(name) # :nodoc:
+		private
+		# @!visibility private
+		def FileSearch.is_dots(name) # :nodoc:
 
-      case name
-      when '.', '..'
-        true
-      else
-        false
-      end
-    end
+			case	name
+			when	'.', '..'
+				true
+			else
+				false
+			end
+		end
 
-    # @!visibility private
-    def FileSearch.stat_or_nil_(path, flags) # :nodoc:
+		# @!visibility private
+		def FileSearch.stat_or_nil_(path, flags) # :nodoc:
 
-      begin
+			begin
 
-        Recls::Ximpl::FileStat.stat path
-      rescue Errno::ENOENT, Errno::ENXIO
+				Recls::Ximpl::FileStat.stat path
+			rescue Errno::ENOENT, Errno::ENXIO
 
-        nil
-      rescue SystemCallError => x
+				nil
+			rescue SystemCallError => x
 
-        # TODO this should be filtered up and/or logged
+				# TODO this should be filtered up and/or logged
 
-        if(0 != (STOP_ON_ACCESS_FAILURE & flags))
+				if(0 != (STOP_ON_ACCESS_FAILURE & flags))
 
-          raise
-        end
+					raise
+				end
 
-        nil
-      end
-    end
+				nil
+			end
+		end
 
-    # searches all entries - files, directories, links, devices - that match
-    # the given +patterns+ in the given directory (+dir+) according to the
-    # given +flags+, invoking the given block (+blk+). The search directory
-    # (+search_root+) is passed in order to allow calculation of
-    # +#search_relative_path+ in the entry.
+		# searches all entries - files, directories, links, devices
+		# - that match the given (patterns) in the given directory
+		# (dir) according to the given (flags), invoking the given
+		# block (blk). The search directory (search_root) is passed in
+		# order to allow calculation of search_relative_path in the
+		# entry.
 
-    # @!visibility private
-    def FileSearch.search_directory_(search_root, dir, patterns, flags, &blk) # :nodoc:
+		# @!visibility private
+		def FileSearch.search_directory_(search_root, dir, patterns, flags, &blk) # :nodoc:
 
-      # array of FileStat instances
-      entries = []
+			# array of FileStat instances
+			entries = []
 
-      patterns.each do |pattern|
+			patterns.each do |pattern|
 
-        Recls::Ximpl::dir_entries_maybe(dir, flags).each do |name|
+				Recls::Ximpl::dir_entries_maybe(dir, flags).each do |name|
 
-          next if is_dots(name)
+					next if is_dots(name)
 
-          if not name =~ /^#{pattern}$/
+					if not name =~ /^#{pattern}$/
 
-            next
-          end
+						next
+					end
 
-          entry_path = File::join(dir, name)
+					entry_path = File::join(dir, name)
 
-          fs = stat_or_nil_(entry_path, flags)
+					fs = stat_or_nil_(entry_path, flags)
 
-          entries << fs
-        end
-      end
+					entries << fs
+				end
+			end
 
-      # array of FileStat instances
-      subdirectories = []
+			# array of FileStat instances
+			subdirectories = []
 
-      Recls::Ximpl::dir_entries_maybe(dir, flags).each do |subdir|
+			Recls::Ximpl::dir_entries_maybe(dir, flags).each do |subdir|
 
-        next if is_dots(subdir)
+				next if is_dots(subdir)
 
-        subdir_path = File::join(dir, subdir)
+				subdir_path = File::join(dir, subdir)
 
-        fs = stat_or_nil_(subdir_path, flags)
+				fs = stat_or_nil_(subdir_path, flags)
 
-        next if not fs
+				next if not fs
 
-        next unless fs.directory?
+				next unless fs.directory?
 
-        subdirectories << fs
-      end
+				subdirectories << fs
+			end
 
 
-      # now filter the file-stat instances and send each
-      # remaining to the block in Entry instance
-      entries.each do |fs|
+			# now filter the file-stat instances and send each
+			# remaining to the block in Entry instance
+			entries.each do |fs|
 
-        next if not fs
+				next if not fs
 
-        if(0 == (Recls::SHOW_HIDDEN & flags))
+				if(0 == (Recls::SHOW_HIDDEN & flags))
 
-          if fs.hidden?
+					if fs.hidden?
 
-            next
-          end
-        end
+						next
+					end
+				end
 
-        match = false
+				match	=	false
 
-        match ||= (0 == (Recls::TYPEMASK & flags))
+				match	||=	(0 == (Recls::TYPEMASK & flags))
 
-        match ||= (0 != (Recls::FILES & flags) && fs.file?)
-        match ||= (0 != (Recls::DIRECTORIES & flags) && fs.directory?)
-        match ||= (0 != (Recls::DEVICES & flags) && fs.blockdev?)
+				match	||=	(0 != (Recls::FILES & flags) && fs.file?)
+				match	||=	(0 != (Recls::DIRECTORIES & flags) && fs.directory?)
+				match	||=	(0 != (Recls::DEVICES & flags) && fs.blockdev?)
 
-        next unless match
+				next unless match
 
-        blk.call Recls::Entry.new(fs.path, fs, search_root, flags)
-      end
+				blk.call Recls::Entry.new(fs.path, fs, search_root, flags)
+			end
 
-      # sub-directories
+			# sub-directories
 
-      return unless (0 != (Recls::RECURSIVE & flags))
+			return unless (0 != (Recls::RECURSIVE & flags))
 
-      subdirectories.each do |fs|
+			subdirectories.each do |fs|
 
-        if(0 == (Recls::SHOW_HIDDEN & flags))
+				if(0 == (Recls::SHOW_HIDDEN & flags))
 
-          if fs.hidden?
+					if fs.hidden?
 
-            next
-          end
-        end
+						next
+					end
+				end
 
-        if(0 == (Recls::SEARCH_THROUGH_LINKS & flags))
+				if(0 == (Recls::SEARCH_THROUGH_LINKS & flags))
 
-          if File.symlink? fs.path
+					if File.symlink? fs.path
 
-            next
-          end
-        end
+						next
+					end
+				end
 
-        FileSearch::search_directory_(search_root, fs.path, patterns, flags, &blk)
-      end
-    end
-  end # class FileSearch
+				FileSearch::search_directory_(search_root, fs.path, patterns, flags, &blk)
+			end
+		end
+	end # class FileSearch
 end # module Recls
 
-
 # ############################## end of file ############################# #
 
+

data/lib/recls/flags.rb

@@ -1,14 +1,13 @@
-# ######################################################################## #
-# File:     recls/flags.rb
+# ######################################################################### #
+# File:         recls/flags.rb
 #
-# Purpose:  Defines the Recls::Flags module for the recls.Ruby library.
+# Purpose:      Defines the Recls::Flags module for the recls.Ruby library.
 #
-# Created:  24th July 2012
-# Updated:  20th April 2024
+# Created:      24th July 2012
+# Updated:      14th April 2019
 #
-# Author:   Matthew Wilson
+# Author:       Matthew Wilson
 #
-# Copyright (c) 2019-2024, Matthew Wilson and Synesis Information Systems
 # Copyright (c) 2012-2019, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
@@ -34,64 +33,62 @@
 # ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 # POSSIBILITY OF SUCH DAMAGE.
 #
-# ######################################################################## #
+# ######################################################################### #
 
 
 =begin
 =end
 
-# @!visibility private
 class Object; end # :nodoc:
 
 module Recls
 
-  # Specifies that files are to be listed
-  FILES                   = 0x00000001
-  # Specifies that directories are to be listed
-  DIRECTORIES             = 0x00000002
-  # Specifies that links are to be listed (and not followed)
-  LINKS                   = 0x00000004
-  # Specifies that devices are to be listed
-  DEVICES                 = 0x00000008
-  # Type mask (combination of +Recls::FILES+, +Recls::DIRECTORIES+, +Recls::LINKS+, +Recls::DEVICES+)
-  TYPEMASK                = 0x000000ff
+	# Specifies that files are to be listed
+	FILES					=	0x00000001
+	# Specifies that directories are to be listed
+	DIRECTORIES				=	0x00000002
+	# Specifies that links are to be listed (and not followed)
+	LINKS					=	0x00000004
+	# Specifies that devices are to be listed
+	DEVICES					=	0x00000008
+	# Type mask (combination of Recls::FILES, Recls::DIRECTORIES, Recls::LINKS, Recls::DEVICES)
+	TYPEMASK				=	0x000000ff
 
-  # Specifies that hidden items are to be shown and hidden directories are
-  # to be searched
-  SHOW_HIDDEN             = 0x00000100
+	# Specifies that hidden items are to be shown and hidden directories are
+	# to be searched
+	SHOW_HIDDEN				=	0x00000100
 
-  # [IGNORED] This for compatibility with *recls* libraries written in other languages
-  DIR_PROGRESS            = 0x00001000
-  # Causes search to terminate if a directory cannot be entered or an
-  # entry's information cannot be +stat()+'d
-  STOP_ON_ACCESS_FAILURE  = 0x00002000
-  # [IGNORED] This for compatibility with *recls* libraries written in other languages
-  LINK_COUNT              = 0000004000
-  # [IGNORED] This for compatibility with *recls* libraries written in other languages
-  NODE_INDEX              = 0x00008000
+	# [IGNORED] This for compatibility with *recls* libraries written in other languages
+	DIR_PROGRESS			=	0x00001000
+	# Causes search to terminate if a directory cannot be entered or an
+	# entry's information cannot be stat()'d
+	STOP_ON_ACCESS_FAILURE	=	0x00002000
+	# [IGNORED] This for compatibility with *recls* libraries written in other languages
+	LINK_COUNT				=	0000004000
+	# [IGNORED] This for compatibility with *recls* libraries written in other languages
+	NODE_INDEX				=	0x00008000
 
-  # Causes search to operate recursively
-  RECURSIVE               = 0x00010000
+	# Causes search to operate recursively
+	RECURSIVE				=	0x00010000
 private
-  # @!visibility private
-  NO_SEARCH_LINKS         = 0x00020000 # :nodoc:
+	NO_SEARCH_LINKS			=	0x00020000 # :nodoc:
 public
-  # [IGNORED] In previous versions the Recls::Entry#directory_parts property was not obtained (for performance reasons) unless this flag was specified. In current version the parts are always obtained
-  DIRECTORY_PARTS         = 0x00040000
-  # Causes operations (such as +Recls::stat()+) to obtain a result even when
-  # no corresponding file-system entity does not exist
-  DETAILS_LATER           = 0x00080000
+	# [IGNORED] In previous versions the Recls::Entry#directory_parts property was not obtained (for performance reasons) unless this flag was specified. In current version the parts are always obtained
+	DIRECTORY_PARTS			=	0x00040000
+	# Causes operations (such as Recls::stat()) to obtain a result even when
+	# no corresponding file-system entity does not exist
+	DETAILS_LATER			=	0x00080000
 
-  # Causes the +Recls::Entry#path+ and +Recls::Entry#search_relative_path+
-  # attributes to contain a trailing path-name-separator for directory
-  # entries
-  MARK_DIRECTORIES        = 0x00200000
+	# Causes the Recls::Entry#path and Recls::Entry#search_relative_path
+	# attributes to contain a trailing path-name-separator for directory
+	# entries
+	MARK_DIRECTORIES		=	0x00200000
 
-  # Causes sub-directories that are links to be searched; default is not
-  # to search through links
-  SEARCH_THROUGH_LINKS    = 0x00100000
+	# Causes sub-directories that are links to be searched; default is not
+	# to search through links
+	SEARCH_THROUGH_LINKS	=	0x00100000
 end # module Recls
 
-
 # ############################## end of file ############################# #
 
+