recls-ruby 2.8.2 → 2.11.0

data/examples/find_files_and_directories.recursive.rb

@@ -0,0 +1,19 @@
+#! /usr/bin/env ruby
+
+$:.unshift File.join(File.dirname(__FILE__), '..', 'lib')
+
+require 'recls'
+
+puts "files under current directory:"
+Recls.file_rsearch(nil, nil, Recls::FILES).each { |fe| puts "\t#{fe.search_relative_path}" }
+puts
+
+puts "directories under current directory:"
+Recls.file_rsearch(nil, nil, Recls::DIRECTORIES | Recls::MARK_DIRECTORIES).each { |fe| puts "\t#{fe.search_relative_path}" }
+puts
+
+puts "files and directories under current directory:"
+Recls.file_rsearch(nil, nil, Recls::DIRECTORIES | Recls::FILES | Recls::MARK_DIRECTORIES).each { |fe| puts "\t#{fe.search_relative_path}" }
+puts
+
+

data/examples/show_hidden_files.md

@@ -0,0 +1,39 @@
+# recls.Ruby Example - **show_hidden_files**
+
+## Summary
+
+TBC
+
+## Source
+
+```ruby
+#! /usr/bin/env ruby
+
+$:.unshift File.join(File.dirname(__FILE__), '..', 'lib')
+
+require 'recls'
+
+# To find only hidden files, need to:
+#
+# 1. Ensure that they are returned in search, by including Recls::SHOW_HIDDEN
+# 2. Filter returned entries by hidden? attribute
+Recls.file_rsearch('.', Recls::WILDCARDS_ALL, Recls::FILES | Recls::SHOW_HIDDEN).each do |fe|
+
+	puts fe.path if fe.hidden?
+end
+```
+
+## Discussion
+
+TBC
+
+## Example results
+
+```
+/Users/matthewwilson/dev/freelibs/recls/100/recls.Ruby/trunk/.gitignore
+/Users/matthewwilson/dev/freelibs/recls/100/recls.Ruby/trunk/.ruby-version
+/Users/matthewwilson/dev/freelibs/recls/100/recls.Ruby/trunk/.ruby-version-exclusions
+/Users/matthewwilson/dev/freelibs/recls/100/recls.Ruby/trunk/test/fixtures/hidden/.file-1
+/Users/matthewwilson/dev/freelibs/recls/100/recls.Ruby/trunk/test/fixtures/hidden/.file-2
+```
+

data/examples/show_hidden_files.rb

@@ -1,3 +1,4 @@
+#! /usr/bin/env ruby
 
 $:.unshift File.join(File.dirname(__FILE__), '..', 'lib')
 
@@ -7,9 +8,8 @@ require 'recls'
 #
 # 1. Ensure that they are returned in search, by including Recls::SHOW_HIDDEN
 # 2. Filter returned entries by hidden? attribute
-Recls::FileSearch.new('.', Recls::WILDCARDS_ALL, Recls::FILES | Recls::RECURSIVE | Recls::SHOW_HIDDEN).each do |fe|
+Recls.file_rsearch('.', Recls::WILDCARDS_ALL, Recls::FILES | Recls::SHOW_HIDDEN).each do |fe|
 
 	puts fe.path if fe.hidden?
-
 end
 

data/examples/show_readonly_files.md

@@ -0,0 +1,35 @@
+# recls.Ruby Example - **show_hidden_files**
+
+## Summary
+
+TBC
+
+## Source
+
+```ruby
+#! /usr/bin/env ruby
+
+$:.unshift File.join(File.dirname(__FILE__), '..', 'lib')
+
+require 'recls'
+
+# To find only readonly files, need to:
+#
+# 1. Filter returned entries by readonly? attribute
+Recls.file_rsearch('.', Recls::WILDCARDS_ALL, Recls::FILES).each do |fe|
+
+	puts fe.path if fe.readonly?
+end
+```
+
+## Discussion
+
+TBC
+
+## Example results
+
+```
+/Users/matthewwilson/dev/freelibs/recls/100/recls.Ruby/trunk/test/fixtures/readonly/file-1
+/Users/matthewwilson/dev/freelibs/recls/100/recls.Ruby/trunk/test/fixtures/readonly/file-2
+```
+

data/examples/show_readonly_files.rb

@@ -1,3 +1,4 @@
+#! /usr/bin/env ruby
 
 $:.unshift File.join(File.dirname(__FILE__), '..', 'lib')
 
@@ -6,9 +7,8 @@ require 'recls'
 # To find only readonly files, need to:
 #
 # 1. Filter returned entries by readonly? attribute
-Recls::FileSearch.new('.', Recls::WILDCARDS_ALL, Recls::FILES | Recls::RECURSIVE).each do |fe|
+Recls.file_rsearch('.', Recls::WILDCARDS_ALL, Recls::FILES).each do |fe|
 
 	puts fe.path if fe.readonly?
-
 end
 

data/lib/recls.rb

@@ -39,3 +39,5 @@
 require 'recls/recls'
 
 # ############################## end of file ############################# #
+
+

data/lib/recls/api.rb

@@ -4,11 +4,11 @@
 # Purpose:      Defines Recls module search functions
 #
 # Created:      9th June 2016
-# Updated:      9th June 2016
+# Updated:      14th April 2019
 #
 # Author:       Matthew Wilson
 #
-# Copyright (c) 2016, Matthew Wilson and Synesis Software
+# Copyright (c) 2016-2019, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without
@@ -37,14 +37,81 @@
 
 
 require 'recls/file_search'
+require 'recls/flags'
+
+=begin
+=end
+
+class Object; end # :nodoc:
 
 module Recls
 
+	# [DEPRECATED] Use Recls::file_search()
 	def self.FileSearch(search_root, patterns, options = {})
 
 		Recls::FileSearch.new(search_root, patterns, options)
 	end
-end
+
+	# Initialises a +FileSearch+ instance, which acts recursively, 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, etc. If the value modulo TYPEMASK is 0, then FILES is assumed. The value RECURSIVE is added by the function, and so need not be added by the caller; it cannot be removed
+	#
+	# === Return
+	# An instance of a class implementing ::Enumerable whose value type is
+	# Recls::Entry
+	def self.file_rsearch(search_root, patterns, options = {})
+
+		case options
+		when ::NilClass
+
+			options	=	{ flags: RECURSIVE }
+		when ::Integer
+
+			options	|=	RECURSIVE
+		when ::Hash
+
+			flags	=	options[:flags] || 0
+			flags	|=	RECURSIVE
+
+			options[:flags]	= flags
+		else
+
+			# this is handled by the FileSearch initialiser
+		end
+
+		Recls::FileSearch.new(search_root, patterns, options)
+	end
+
+	# 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 a class implementing ::Enumerable whose value type is
+	# Recls::Entry
+	def self.file_search(search_root, patterns, options = {})
+
+		Recls::FileSearch.new(search_root, patterns, options)
+	end
+end # module Recls
 
 # ############################## end of file ############################# #
 

data/lib/recls/combine_paths_1.rb

@@ -0,0 +1,70 @@
+# ######################################################################### #
+# File:         recls/compare_paths_1.rb
+#
+# Purpose:      Definition of Recls::compare_paths() for Ruby 1.x
+#
+# Created:      17th February 2014
+# Updated:      14th April 2019
+#
+# Author:       Matthew Wilson
+#
+# Copyright (c) 2014-2019, 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/ximpl/util'
+
+=begin
+=end
+
+class Object; end # :nodoc:
+
+module Recls
+
+	# Combines paths
+	#
+	# === Signature
+	#
+	# * *Parameters:*
+	#   - +paths+ ([ (::String, ::Recls::Entry) ]) Array of 1 or more path elements to be combined
+	#
+	# === Return
+	# (String) The combined path
+	def self.combine_paths(*paths)
+
+		paths	=	paths.reject { |p| p.nil? }
+		paths	=	paths.map { |p| 'Recls::Entry' == p.class.to_s ? p.path : p }
+
+		raise ArgumentError, 'must specify one or more path elements' if paths.empty?
+
+		return Recls::Ximpl.combine_paths paths, {}
+	end
+end # module Recls
+
+# ############################## end of file ############################# #
+
+

data/lib/recls/combine_paths_2plus.rb

@@ -0,0 +1,76 @@
+# ######################################################################### #
+# File:         recls/compare_paths_2plus.rb
+#
+# Purpose:      Definition of Recls::compare_paths() for Ruby 2+
+#
+# Created:      17th February 2014
+# Updated:      14th April 2019
+#
+# Author:       Matthew Wilson
+#
+# Copyright (c) 2014-2019, 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/ximpl/util'
+
+=begin
+=end
+
+class Object; end # :nodoc:
+
+module Recls
+
+	# Combines paths, optionally canonicalising them
+	#
+	# === Signature
+	#
+	# * *Parameters:*
+	#   - +paths+ ([ (::String, ::Recls::Entry) ]) Array of 1 or more path elements to be combined
+	#   - +options+ (::Hash) Options that moderate the combination
+	#
+	# * *Options:*
+	#   - +:canonicalise+ (boolean) Causes the evaluated path to be canonicalised - with +Recls.canonicalise_path+ - before it is returned
+	#   - +:clean+ (boolean) Causes the evaluated path to be cleaned (i.e. sent to +cleanpath+) before it is returned. Ignored if +:canonicalise+ is specified
+	#   - +:clean_path+ (boolean) Equivalent to +:clean+, but deprecated and may be removed in a future version
+	#
+	# === Return
+	# (String) The combined path
+	def self.combine_paths(*paths, **options)
+
+		paths	=	paths.reject { |p| p.nil? }
+		paths	=	paths.map { |p| 'Recls::Entry' == p.class.to_s ? p.path : p }
+
+		raise ArgumentError, 'must specify one or more path elements' if paths.empty?
+
+		return Recls::Ximpl.combine_paths paths, options
+	end
+end # module Recls
+
+# ############################## end of file ############################# #
+
+

data/lib/recls/entry.rb

@@ -4,11 +4,12 @@
 # Purpose:      Defines the Recls::Entry class for the recls.Ruby library.
 #
 # Created:      24th July 2012
-# Updated:      11th July 2016
+# Updated:      25th May 2020
 #
 # Author:       Matthew Wilson
 #
-# Copyright (c) 2012-2016, Matthew Wilson and Synesis Software
+# Copyright (c) 2019-2020, Matthew Wilson and Synesis Information Systems
+# Copyright (c) 2012-2019, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without
@@ -41,11 +42,18 @@ require 'recls/ximpl/' + (Recls::Ximpl::OS::OS_IS_WINDOWS ? 'windows' : 'unix')
 require 'recls/ximpl/util'
 require 'recls/flags'
 
+=begin
+=end
+
+class Object; end # :nodoc:
+
 module Recls
 
+	# A file-system entry
 	class Entry
 
 		private
+		# @!visibility private
 		def self.get_compare_path_(path)
 			return path.upcase if Recls::Ximpl::OS::OS_IS_WINDOWS
 			path
@@ -90,6 +98,7 @@ module Recls
 			@nlink	=	@file_stat.nlink if @file_stat
 
 			if Recls::Ximpl::OS::OS_IS_WINDOWS && @file_stat
+
 				@dev				=	@file_stat.by_handle_information.volume_id
 				@ino				=	@file_stat.by_handle_information.file_index
 				@nlink				=	@file_stat.by_handle_information.num_links
@@ -102,26 +111,43 @@ module Recls
 		# ##########################
 		# Name-related attributes
 
+		# (String) A normalised form of #path that can be used in comparisons
 		attr_reader :compare_path
 
+		# (String) The full-path of the instance
 		attr_reader :path
+		# (String) The (Windows) short-form of #path, or +nil+ if not on Windows
 		attr_reader :short_path
+		# (String) The (Windows) drive. +nil+ if does not exist
 		attr_reader :drive
+		# (String) The full path of the entry's directory (taking into account the
+		# #drive if on Windows)
 		attr_reader :directory_path
 		alias_method :dirname, :directory_path
+		# (String) The entry's directory (excluding the #drive if on Windows)
 		attr_reader :directory
+		# ([String]) An array of directory parts, where each part ends in Recls::PATH_NAME_SEPARATOR
 		attr_reader :directory_parts
+		# (String) The entry's file name (combination of #stem + #extension)
 		attr_reader :file_full_name
+		# (String) The (Windows) short-form of #basename, or +nil+ if not on Windows
 		attr_reader :file_short_name
 		alias_method :basename, :file_full_name
+		# (String) The entry's file stem
 		attr_reader :file_name_only
 		alias_method :stem, :file_name_only
+		# (String) The entry's file extension
 		attr_reader :file_extension
 		alias_method :extension, :file_extension
+		# (String) The search directory if specified; +nil+ otherwise
 		attr_reader :search_directory
+		# (String) The #path relative to #search_directory; +nil+ if no search directory specified
 		attr_reader :search_relative_path
+		# (String) The #directory relative to #search_directory; +nil+ if no search directory specified
 		attr_reader :search_relative_directory
+		# (String) The #directory_path relative to #search_directory; +nil+ if no search directory specified
 		attr_reader :search_relative_directory_path
+		# ([String]) The #directory_parts relative to #search_directory; +nil+ if no search directory specified
 		attr_reader :search_relative_directory_parts
 
 		# ##########################
@@ -157,6 +183,7 @@ module Recls
 
 	if Recls::Ximpl::OS::OS_IS_WINDOWS
 
+		# [WINDOWS-ONLY] Indicates whether the entry has the *system* bit
 		def system?
 
 			return false if @file_stat.nil?
@@ -164,6 +191,7 @@ module Recls
 			@file_stat.system?
 		end
 
+		# [WINDOWS-ONLY] Indicates whether the entry has the *archive* bit
 		def archive?
 
 			return false if @file_stat.nil?
@@ -171,6 +199,7 @@ module Recls
 			@file_stat.archive?
 		end
 
+		# [WINDOWS-ONLY] Indicates whether the entry is a device
 		def device?
 
 			return false if @file_stat.nil?
@@ -178,6 +207,7 @@ module Recls
 			@file_stat.device?
 		end
 
+		# [WINDOWS-ONLY] Indicates whether the entry is *normal*
 		def normal?
 
 			return false if @file_stat.nil?
@@ -185,6 +215,7 @@ module Recls
 			@file_stat.normal?
 		end
 
+		# [WINDOWS-ONLY] Indicates whether the entry has the *temporary* bit
 		def temporary?
 
 			return false if @file_stat.nil?
@@ -192,6 +223,7 @@ module Recls
 			@file_stat.temporary?
 		end
 
+		# [WINDOWS-ONLY] Indicates whether the entry has the *compressed* bit
 		def compressed?
 
 			return false if @file_stat.nil?
@@ -199,6 +231,7 @@ module Recls
 			@file_stat.compressed?
 		end
 
+		# [WINDOWS-ONLY] Indicates whether the entry has the *encrypted* bit
 		def encrypted?
 
 			return false if @file_stat.nil?
@@ -215,6 +248,8 @@ module Recls
 			@file_stat.directory?
 		end
 
+		alias_method :dir?, :directory?
+
 		# indicates whether the given entry represents a file
 		def file?
 
@@ -355,8 +390,9 @@ module Recls
 
 			path
 		end
-	end
-end
+	end # class Entry
+end # module Recls
 
 # ############################## end of file ############################# #
 
+