recls-ruby 2.6.4

data/lib/recls/filesearch.rb

@@ -0,0 +1,251 @@
+# ######################################################################### #
+# File:         recls/filesearch.rb
+#
+# Purpose:      Defines the Recls::FileSearch class for the recls.Ruby library.
+#
+# Created:      24th July 2012
+# Updated:      29th December 2015
+#
+# Author:       Matthew Wilson
+#
+# Copyright (c) 2012-2015, Matthew Wilson and Synesis Software
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# * Redistributions of source code must retain the above copyright notice,
+#   this list of conditions and the following disclaimer.
+#
+# * Redistributions in binary form must reproduce the above copyright notice,
+#   this list of conditions and the following disclaimer in the documentation
+#   and/or other materials provided with the distribution.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# 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'
+
+module Recls
+
+	class FileSearch
+
+		include Enumerable
+
+		def initialize(search_root, patterns, flags)
+
+			if not search_root
+				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]
+
+			case	patterns
+			when	NilClass
+				patterns = []
+			when	String
+				patterns = patterns.split(/[|#{Recls::Ximpl::OS::PATH_SEPARATOR}]/)
+			when	Array
+			else
+				patterns = patterns.to_a
+			end
+
+			patterns = [ Recls::WILDCARDS_ALL ] if patterns.empty?
+
+			if(0 == (Recls::TYPEMASK & flags))
+				flags |= Recls::FILES
+			end
+
+			# 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
+
+		attr_reader :search_root
+		attr_reader :patterns
+		attr_reader :flags
+
+		def each(&blk)
+
+			search_root = @search_root
+			search_root = Recls::Ximpl::absolute_path search_root
+
+			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
+
+			flags = @flags
+
+			if(Recls::Ximpl::OS::OS_IS_WINDOWS)
+				mask = (Recls::FILES | Recls::DIRECTORIES)
+			else
+				mask = (Recls::FILES | Recls::DIRECTORIES | Recls::LINKS | Recls::DEVICES)
+			end
+
+			if(mask == (mask & flags))
+				flags = flags & ~Recls::TYPEMASK
+			end
+
+			patterns = @patterns
+
+			patterns = patterns.map do |pattern|
+
+				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
+
+			FileSearch::search_directory_(search_root, search_dir, patterns, flags, &blk)
+		end
+
+		private
+		def FileSearch::is_dots(name)
+
+			case	name
+			when	'.', '..'
+				true
+			else
+				false
+			end
+		end
+
+		def FileSearch::stat_or_nil_(path, flags)
+
+			begin
+				Recls::Ximpl::FileStat.stat path
+			rescue Errno::ENOENT => x
+				nil
+			rescue SystemCallError => x
+				# TODO this should be filtered up and/or logged
+
+				if(0 != (STOP_ON_ACCESS_FAILURE & flags))
+					raise
+				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.
+
+		def FileSearch::search_directory_(search_root, dir, patterns, flags, &blk)
+
+			# array of FileStat instances
+			entries = []
+
+			patterns.each do |pattern|
+
+				Recls::Ximpl::dir_entries_maybe(dir, flags).each do |name|
+
+					next if is_dots(name)
+
+					if not name =~ /^#{pattern}$/
+						next
+					end
+
+					entry_path = File::join(dir, name)
+
+					fs = stat_or_nil_(entry_path, flags)
+
+					entries << fs
+				end
+			end
+
+			# array of FileStat instances
+			subdirectories = []
+
+			Recls::Ximpl::dir_entries_maybe(dir, flags).each do |subdir|
+
+				next if is_dots(subdir)
+
+				subdir_path = File::join(dir, subdir)
+
+				fs = stat_or_nil_(subdir_path, flags)
+
+				next if not fs
+
+				next unless fs.directory?
+
+				subdirectories << fs
+			end
+
+
+			# now filter the file-stat instances and send each
+			# remaining to the block in Entry instance
+			entries.each do |fs|
+
+				next if not fs
+
+				if(0 == (Recls::SHOW_HIDDEN & flags))
+					if fs.hidden?
+						next
+					end
+				end
+
+				match	=	false
+
+				match	||=	(0 != (Recls::FILES & flags) && fs.file?)
+				match	||=	(0 != (Recls::DIRECTORIES & flags) && fs.directory?)
+				match	||=	(0 != (Recls::DEVICES & flags) && fs.blockdev?)
+
+				next unless match
+
+				blk.call Recls::Entry.new(fs.path, fs, search_root, flags)
+			end
+
+			# sub-directories
+
+			return unless (0 != (Recls::RECURSIVE & flags))
+
+			subdirectories.each do |fs|
+
+				if(0 == (Recls::SHOW_HIDDEN & flags))
+					if fs.hidden?
+						next
+					end
+				end
+
+				if(0 == (Recls::SEARCH_THROUGH_LINKS & flags))
+					if File.symlink? fs.path
+						next
+					end
+				end
+
+				FileSearch::search_directory_(search_root, fs.path, patterns, flags, &blk)
+			end
+		end
+	end
+end
+
+# ############################## end of file ############################# #
+

data/lib/recls/flags.rb

@@ -0,0 +1,77 @@
+# ######################################################################### #
+# File:         recls/flags.rb
+#
+# Purpose:      Defines the Recls::Flags module for the recls.Ruby library.
+#
+# Created:      24th July 2012
+# Updated:      27th August 2015
+#
+# Author:       Matthew Wilson
+#
+# Copyright (c) 2012-2015, Matthew Wilson and Synesis Software
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# * Redistributions of source code must retain the above copyright notice,
+#   this list of conditions and the following disclaimer.
+#
+# * Redistributions in binary form must reproduce the above copyright notice,
+#   this list of conditions and the following disclaimer in the documentation
+#   and/or other materials provided with the distribution.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+#
+# ######################################################################### #
+
+
+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
+	TYPEMASK				=	0x000000ff
+
+	# Specifies that hidden items are to be shown and hidden directories are
+	# to be searched
+	SHOW_HIDDEN				=	0x00000100
+
+	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
+	LINK_COUNT				=	0000004000
+	NODE_INDEX				=	0x00008000
+
+	RECURSIVE				=	0x00010000
+private
+	NO_SEARCH_LINKS			=	0x00020000
+public
+	DIRECTORY_PARTS			=	0x00040000
+	DETAILS_LATER			=	0x00080000
+
+	MARK_DIRECTORIES		=	0x00200000
+
+	# Causes sub-directories that are links to be searched; default is not
+	# to search through links
+	SEARCH_THROUGH_LINKS	=	0x00100000
+end
+
+# ############################## end of file ############################# #
+

data/lib/recls/foreach.rb

@@ -0,0 +1,103 @@
+# ######################################################################### #
+# File:         recls/foreach.rb
+#
+# Purpose:      Definition of Recls::foreach() utility function
+#
+# Created:      22nd October 2014
+# Updated:      27th August 2015
+#
+# Author:       Matthew Wilson
+#
+# Copyright (c) 2012-2015, Matthew Wilson and Synesis Software
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# * Redistributions of source code must retain the above copyright notice,
+#   this list of conditions and the following disclaimer.
+#
+# * Redistributions in binary form must reproduce the above copyright notice,
+#   this list of conditions and the following disclaimer in the documentation
+#   and/or other materials provided with the distribution.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+#
+# ######################################################################### #
+
+
+require 'recls/filesearch'
+
+module Recls
+
+	private
+	class FileSearchLineEnumerator
+
+		include Enumerable
+
+		def initialize(fs)
+
+			@fs = fs
+		end
+
+		def each(&block)
+
+			@fs.each do |fe|
+
+				IO::readlines(fe).each_with_index do |line, index|
+
+					case	block.arity
+					when	1
+						yield line
+					when	2
+						yield line, index
+					when	3
+						yield line, index, fe
+					else
+						raise ArgumentError, "block must take 1, 2, or 3 parameters - #{block.arity} given. (Perhaps you have applied each_with_index, which cannot be done to Recls.foreach)"
+					end
+				end
+			end
+		end
+	end
+	public
+
+	def self.foreach(*args, &block)
+
+		fs = nil
+
+		case	args.length
+		when	1
+			raise ArgumentError "Single argument must be of type #{Recls::FileSearch}" unless args[0].kind_of? Recls::FileSearch
+
+			fs = args[0]
+		when	3
+			fs = Recls::FileSearch.new(args[0], args[1], args[2])
+		else
+			raise ArgumentError "Function requires single argument (#{Recls::FileSearch}) or three arguments (directory, patterns, flags)"
+		end
+
+		if block_given?
+
+			FileSearchLineEnumerator.new(fs).each(block)
+
+			return nil
+		else
+
+			return FileSearchLineEnumerator.new(fs)
+		end
+	end
+end
+
+# ############################## end of file ############################# #
+

data/lib/recls/recls.rb

@@ -0,0 +1,113 @@
+# ######################################################################### #
+# File:         recls/recls.rb
+#
+# Purpose:      Main source file for recls library
+#
+# Created:      19th July 2012
+# Updated:      29th December 2015
+#
+# Author:       Matthew Wilson
+#
+# Copyright (c) 2012-2015, Matthew Wilson and Synesis Software
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# * Redistributions of source code must retain the above copyright notice,
+#   this list of conditions and the following disclaimer.
+#
+# * Redistributions in binary form must reproduce the above copyright notice,
+#   this list of conditions and the following disclaimer in the documentation
+#   and/or other materials provided with the distribution.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+#
+# ######################################################################### #
+
+
+require 'recls/version'
+
+require 'recls/filesearch'
+require 'recls/foreach'
+require 'recls/stat'
+require 'recls/util'
+require 'recls/ximpl/os'
+
+module Recls
+
+	# Represents the "all" wildcards string for the ambient operating
+	# system
+	WILDCARDS_ALL = Recls::Ximpl::OS::WILDCARDS_ALL
+
+	PATH_NAME_SEPARATOR = Recls::Ximpl::OS::PATH_NAME_SEPARATOR
+
+	PATH_SEPARATOR = Recls::Ximpl::OS::PATH_SEPARATOR
+end
+
+# ######################################################################### #
+# Obsolete symbols
+
+if not defined? RECLS_NO_OBSOLETE
+
+	module Recls
+
+		def self.pathNameSeparator
+			PATH_NAME_SEPARATOR
+		end
+
+		def self.pathSeparator
+			PATH_SEPARATOR
+		end
+
+		def self.wildcardsAll
+			WILDCARDS_ALL
+		end
+
+		class FileSearch
+
+			alias_method :searchRoot, :search_root
+			alias_method :pattern, :patterns
+		end
+
+		class Entry
+
+			alias_method :uncDrive, :drive
+			alias_method :directoryPath, :directory_path
+			alias_method :directoryParts, :directory_parts
+			alias_method :file, :file_full_name
+			alias_method :shortFile, :file_short_name
+			alias_method :fileBaseName, :file_name_only
+			alias_method :fileName, :file_name_only
+			alias_method :fileExt, :file_extension
+			alias_method :searchDirectory, :search_directory
+			alias_method :searchRelativePath, :search_relative_path
+
+			alias_method :isDirectory, :directory?
+			alias_method :isFile, :file?
+			#alias_method :isLink, :link?
+			alias_method :isReadOnly, :readonly?
+			def isUNC
+
+				d = drive
+
+				d and d.size > 2
+			end
+
+			alias_method :creationTime, :modification_time
+		end
+	end
+end
+
+# ############################## end of file ############################# #
+