recls-ruby 2.9.0 → 2.12.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/api.rb

@@ -4,7 +4,7 @@
 # Purpose:      Defines Recls module search functions
 #
 # Created:      9th June 2016
-# Updated:      21st March 2019
+# Updated:      14th April 2019
 #
 # Author:       Matthew Wilson
 #
@@ -39,11 +39,14 @@
 require 'recls/file_search'
 require 'recls/flags'
 
+=begin
+=end
+
+class Object; end # :nodoc:
+
 module Recls
 
-	# [DEPRECATED] Use +Recls.file_search()+
-	#
-	# @deprecated
+	# [DEPRECATED] Use Recls::file_search()
 	def self.FileSearch(search_root, patterns, options = {})
 
 		Recls::FileSearch.new(search_root, patterns, options)
@@ -55,26 +58,16 @@ module Recls
 	# === 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
+	#   - +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
+	#   - +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 +::Recls::FileSearch+
-	#
+	# An instance of a class implementing ::Enumerable whose value type is
+	# Recls::Entry
 	def self.file_rsearch(search_root, patterns, options = {})
 
 		case options
@@ -104,29 +97,21 @@ module Recls
 	# === 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
+	#   - +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
+	#   - +flags+ (Integer) Combination of flags - FILES, DIRECTORIES, RECURSIVE, etc. If the value modulo TYPEMASK is 0, then FILES is assumed
 	#
 	# === Return
-	#  An instance of +::Recls::FileSearch+
-	#
+	# 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
+end # module Recls
 
 # ############################## end of file ############################# #
 

data/lib/recls/combine_paths_1.rb

@@ -4,7 +4,7 @@
 # Purpose:      Definition of Recls::compare_paths() for Ruby 1.x
 #
 # Created:      17th February 2014
-# Updated:      21st March 2019
+# Updated:      14th April 2019
 #
 # Author:       Matthew Wilson
 #
@@ -38,6 +38,11 @@
 
 require 'recls/ximpl/util'
 
+=begin
+=end
+
+class Object; end # :nodoc:
+
 module Recls
 
 	# Combines paths
@@ -45,11 +50,10 @@ module Recls
 	# === Signature
 	#
 	# * *Parameters:*
-	#   - +paths+:: ([ (::String, ::Recls::Entry( ]) Array of 1 or more path
-	#     elements to be combined
+	#   - +paths+ ([ (::String, ::Recls::Entry) ]) Array of 1 or more path elements to be combined
 	#
 	# === Return
-	#  The combined path
+	# (String) The combined path
 	def self.combine_paths(*paths)
 
 		paths	=	paths.reject { |p| p.nil? }

data/lib/recls/combine_paths_2plus.rb

@@ -4,7 +4,7 @@
 # Purpose:      Definition of Recls::compare_paths() for Ruby 2+
 #
 # Created:      17th February 2014
-# Updated:      21st March 2019
+# Updated:      14th April 2019
 #
 # Author:       Matthew Wilson
 #
@@ -38,6 +38,11 @@
 
 require 'recls/ximpl/util'
 
+=begin
+=end
+
+class Object; end # :nodoc:
+
 module Recls
 
 	# Combines paths, optionally canonicalising them
@@ -45,22 +50,16 @@ module Recls
 	# === Signature
 	#
 	# * *Parameters:*
-	#   - +paths+:: ([ (::String, ::Recls::Entry( ]) Array of 1 or more path
-	#     elements to be combined
-	#   - +options+:: (::Hash) Options that moderate the combination
+	#   - +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
+	#   - +: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
-	#  The combined path
+	# (String) The combined path
 	def self.combine_paths(*paths, **options)
 
 		paths	=	paths.reject { |p| p.nil? }

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,8 @@ module Recls
 
 			path
 		end
-	end
-end
+	end # class Entry
+end # module Recls
 
 # ############################## end of file ############################# #