recls-ruby 2.12.0 → 2.12.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. checksums.yaml +4 -4
  2. data/LICENSE +27 -24
  3. data/README.md +242 -1
  4. data/examples/find_files_and_directories.md +33 -30
  5. data/examples/find_files_and_directories.recursive.md +255 -254
  6. data/examples/show_hidden_files.md +4 -1
  7. data/examples/show_hidden_files.rb +1 -1
  8. data/examples/show_readonly_files.md +4 -1
  9. data/examples/show_readonly_files.rb +1 -1
  10. data/lib/recls/api.rb +76 -73
  11. data/lib/recls/combine_paths_1.rb +26 -23
  12. data/lib/recls/combine_paths_2plus.rb +32 -29
  13. data/lib/recls/entry.rb +277 -273
  14. data/lib/recls/file_search.rb +194 -193
  15. data/lib/recls/flags.rb +48 -45
  16. data/lib/recls/foreach.rb +105 -98
  17. data/lib/recls/obsolete.rb +85 -79
  18. data/lib/recls/recls.rb +19 -24
  19. data/lib/recls/stat.rb +137 -134
  20. data/lib/recls/util.rb +95 -92
  21. data/lib/recls/version.rb +22 -17
  22. data/lib/recls/ximpl/os.rb +49 -48
  23. data/lib/recls/ximpl/unix.rb +41 -38
  24. data/lib/recls/ximpl/util.rb +600 -599
  25. data/lib/recls/ximpl/windows.rb +142 -139
  26. data/lib/recls.rb +10 -9
  27. data/test/scratch/test_display_parts.rb +33 -33
  28. data/test/scratch/test_entry.rb +6 -6
  29. data/test/scratch/test_files_and_directories.rb +8 -8
  30. data/test/scratch/test_foreach.rb +10 -10
  31. data/test/scratch/test_module_function.rb +33 -33
  32. data/test/scratch/test_pattern_arrays.rb +5 -5
  33. data/test/scratch/test_show_dev_and_ino.rb +1 -1
  34. data/test/scratch/test_show_hidden.rb +3 -3
  35. data/test/unit/tc_recls_entries.rb +31 -31
  36. data/test/unit/tc_recls_entry.rb +19 -19
  37. data/test/unit/tc_recls_file_search.rb +32 -32
  38. data/test/unit/tc_recls_module.rb +25 -25
  39. data/test/unit/tc_recls_util.rb +161 -161
  40. data/test/unit/tc_recls_ximpl_util.rb +676 -676
  41. data/test/unit/test_all_separately.sh +1 -1
  42. data/test/unit/ts_all.rb +4 -4
  43. metadata +7 -7
data/lib/recls/api.rb CHANGED
@@ -1,13 +1,14 @@
1
- # ######################################################################### #
2
- # File: recls/api.rb
1
+ # ######################################################################## #
2
+ # File: recls/api.rb
3
3
  #
4
- # Purpose: Defines Recls module search functions
4
+ # Purpose: Defines Recls module search functions
5
5
  #
6
- # Created: 9th June 2016
7
- # Updated: 14th April 2019
6
+ # Created: 9th June 2016
7
+ # Updated: 20th April 2024
8
8
  #
9
- # Author: Matthew Wilson
9
+ # Author: Matthew Wilson
10
10
  #
11
+ # Copyright (c) 2019-2024, Matthew Wilson and Synesis Information Systems
11
12
  # Copyright (c) 2016-2019, Matthew Wilson and Synesis Software
12
13
  # All rights reserved.
13
14
  #
@@ -33,86 +34,88 @@
33
34
  # ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
34
35
  # POSSIBILITY OF SUCH DAMAGE.
35
36
  #
36
- # ######################################################################### #
37
+ # ######################################################################## #
37
38
 
38
39
 
39
40
  require 'recls/file_search'
40
41
  require 'recls/flags'
41
42
 
43
+
42
44
  =begin
43
45
  =end
44
46
 
47
+ # @!visibility private
45
48
  class Object; end # :nodoc:
46
49
 
47
50
  module Recls
48
51
 
49
- # [DEPRECATED] Use Recls::file_search()
50
- def self.FileSearch(search_root, patterns, options = {})
51
-
52
- Recls::FileSearch.new(search_root, patterns, options)
53
- end
54
-
55
- # Initialises a +FileSearch+ instance, which acts recursively, as an
56
- # +Enumerable+ of Recls::Entry
57
- #
58
- # === Signature
59
- #
60
- # * *Parameters:*
61
- # - +search_root+ (String, Recls::Entry) The root directory of the search. May be +nil+, in which case the current directory is assumed
62
- # - +patterns+ (String, Array) The pattern(s) for which to search. May be +nil+, in which case Recls::WILDCARDS_ALL is assumed
63
- # - +options+ (Hash, Integer) Combination of flags (with behaviour as described below for the +flags+ option), or an options hash
64
- #
65
- # * *Options:*
66
- # - +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
67
- #
68
- # === Return
69
- # An instance of a class implementing ::Enumerable whose value type is
70
- # Recls::Entry
71
- def self.file_rsearch(search_root, patterns, options = {})
72
-
73
- case options
74
- when ::NilClass
75
-
76
- options = { flags: RECURSIVE }
77
- when ::Integer
78
-
79
- options |= RECURSIVE
80
- when ::Hash
81
-
82
- flags = options[:flags] || 0
83
- flags |= RECURSIVE
84
-
85
- options[:flags] = flags
86
- else
87
-
88
- # this is handled by the FileSearch initialiser
89
- end
90
-
91
- Recls::FileSearch.new(search_root, patterns, options)
92
- end
93
-
94
- # Initialises a +FileSearch+ instance, which acts as an +Enumerable+
95
- # of Recls::Entry
96
- #
97
- # === Signature
98
- #
99
- # * *Parameters:*
100
- # - +search_root+ (String, Recls::Entry) The root directory of the search. May be +nil+, in which case the current directory is assumed
101
- # - +patterns+ (String, Array) The pattern(s) for which to search. May be +nil+, in which case Recls::WILDCARDS_ALL is assumed
102
- # - +options+ (Hash, Integer) Combination of flags (with behaviour as described below for the +flags+ option), or an options hash
103
- #
104
- # * *Options:*
105
- # - +flags+ (Integer) Combination of flags - FILES, DIRECTORIES, RECURSIVE, etc. If the value modulo TYPEMASK is 0, then FILES is assumed
106
- #
107
- # === Return
108
- # An instance of a class implementing ::Enumerable whose value type is
109
- # Recls::Entry
110
- def self.file_search(search_root, patterns, options = {})
111
-
112
- Recls::FileSearch.new(search_root, patterns, options)
113
- end
52
+ # [DEPRECATED] Use +Recls::file_search()+
53
+ def self.FileSearch(search_root, patterns, options = {})
54
+
55
+ Recls::FileSearch.new(search_root, patterns, options)
56
+ end
57
+
58
+ # Initialises a +FileSearch+ instance, which acts recursively, as an
59
+ # +Enumerable+ of +Recls::Entry+
60
+ #
61
+ # === Signature
62
+ #
63
+ # * *Parameters:*
64
+ # - +search_root+ (+String+, +Recls::Entry+) The root directory of the search. May be +nil+, in which case the current directory is assumed;
65
+ # - +patterns+ (+String+, +Array+) The pattern(s) for which to search. May be +nil+, in which case +Recls::WILDCARDS_ALL+ is assumed;
66
+ # - +options+ (+Hash+, +Integer+) Combination of flags (with behaviour as described below for the +flags+ option), or an options hash;
67
+ #
68
+ # * *Options:*
69
+ # - +flags+ (+Integer+) Combination of flags - +Recls::FILES+, +Recls::DIRECTORIES+, etc. If the value modulo +Recls::TYPEMASK+ is 0, then +Recls::FILES+ is assumed. The value +Recls::RECURSIVE+ is added by the function, and so need not be added by the caller; it cannot be removed
70
+ #
71
+ # === Return
72
+ # An instance of a class implementing +Enumerable+ whose value type is
73
+ # +Recls::Entry+.
74
+ def self.file_rsearch(search_root, patterns, options = {})
75
+
76
+ case options
77
+ when ::NilClass
78
+
79
+ options = { flags: RECURSIVE }
80
+ when ::Integer
81
+
82
+ options |= RECURSIVE
83
+ when ::Hash
84
+
85
+ flags = options[:flags] || 0
86
+ flags |= RECURSIVE
87
+
88
+ options[:flags] = flags
89
+ else
90
+
91
+ # this is handled by the FileSearch initialiser
92
+ end
93
+
94
+ Recls::FileSearch.new(search_root, patterns, options)
95
+ end
96
+
97
+ # Initialises a +FileSearch+ instance, which acts as an +Enumerable+
98
+ # of +Recls::Entry+
99
+ #
100
+ # === Signature
101
+ #
102
+ # * *Parameters:*
103
+ # - +search_root+ (+String+, +Recls::Entry+) The root directory of the search. May be +nil+, in which case the current directory is assumed;
104
+ # - +patterns+ (+String+, +Array+) The pattern(s) for which to search. May be +nil+, in which case +Recls::WILDCARDS_ALL+ is assumed;
105
+ # - +options+ (+Hash+, +Integer+) Combination of flags (with behaviour as described below for the +flags+ option), or an options hash;
106
+ #
107
+ # * *Options:*
108
+ # - +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
109
+ #
110
+ # === Return
111
+ # An instance of a class implementing +Enumerable+ whose value type is
112
+ # +Recls::Entry+.
113
+ def self.file_search(search_root, patterns, options = {})
114
+
115
+ Recls::FileSearch.new(search_root, patterns, options)
116
+ end
114
117
  end # module Recls
115
118
 
116
- # ############################## end of file ############################# #
117
119
 
120
+ # ############################## end of file ############################# #
118
121
 
data/lib/recls/combine_paths_1.rb CHANGED
@@ -1,13 +1,14 @@
1
- # ######################################################################### #
2
- # File: recls/compare_paths_1.rb
1
+ # ######################################################################## #
2
+ # File: recls/compare_paths_1.rb
3
3
  #
4
- # Purpose: Definition of Recls::compare_paths() for Ruby 1.x
4
+ # Purpose: Definition of Recls::compare_paths() for Ruby 1.x
5
5
  #
6
- # Created: 17th February 2014
7
- # Updated: 14th April 2019
6
+ # Created: 17th February 2014
7
+ # Updated: 20th April 2024
8
8
  #
9
- # Author: Matthew Wilson
9
+ # Author: Matthew Wilson
10
10
  #
11
+ # Copyright (c) 2019-2024, Matthew Wilson and Synesis Information Systems
11
12
  # Copyright (c) 2014-2019, Matthew Wilson and Synesis Software
12
13
  # All rights reserved.
13
14
  #
@@ -33,38 +34,40 @@
33
34
  # ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
34
35
  # POSSIBILITY OF SUCH DAMAGE.
35
36
  #
36
- # ######################################################################### #
37
+ # ######################################################################## #
37
38
 
38
39
 
39
40
  require 'recls/ximpl/util'
40
41
 
42
+
41
43
  =begin
42
44
  =end
43
45
 
46
+ # @!visibility private
44
47
  class Object; end # :nodoc:
45
48
 
46
49
  module Recls
47
50
 
48
- # Combines paths
49
- #
50
- # === Signature
51
- #
52
- # * *Parameters:*
53
- # - +paths+ ([ (::String, ::Recls::Entry) ]) Array of 1 or more path elements to be combined
54
- #
55
- # === Return
56
- # (String) The combined path
57
- def self.combine_paths(*paths)
51
+ # Combines paths
52
+ #
53
+ # === Signature
54
+ #
55
+ # * *Parameters:*
56
+ # - +paths+ (+[ String, Recls::Entry ]+) Array of 1 or more path elements to be combined;
57
+ #
58
+ # === Return
59
+ # (+String+) The combined path.
60
+ def self.combine_paths(*paths)
58
61
 
59
- paths = paths.reject { |p| p.nil? }
60
- paths = paths.map { |p| 'Recls::Entry' == p.class.to_s ? p.path : p }
62
+ paths = paths.reject { |p| p.nil? }
63
+ paths = paths.map { |p| 'Recls::Entry' == p.class.to_s ? p.path : p }
61
64
 
62
- raise ArgumentError, 'must specify one or more path elements' if paths.empty?
65
+ raise ArgumentError, 'must specify one or more path elements' if paths.empty?
63
66
 
64
- return Recls::Ximpl.combine_paths paths, {}
65
- end
67
+ return Recls::Ximpl.combine_paths paths, {}
68
+ end
66
69
  end # module Recls
67
70
 
68
- # ############################## end of file ############################# #
69
71
 
72
+ # ############################## end of file ############################# #
70
73
 
data/lib/recls/combine_paths_2plus.rb CHANGED
@@ -1,13 +1,14 @@
1
- # ######################################################################### #
2
- # File: recls/compare_paths_2plus.rb
1
+ # ######################################################################## #
2
+ # File: recls/compare_paths_2plus.rb
3
3
  #
4
- # Purpose: Definition of Recls::compare_paths() for Ruby 2+
4
+ # Purpose: Definition of Recls::compare_paths() for Ruby 2+
5
5
  #
6
- # Created: 17th February 2014
7
- # Updated: 14th April 2019
6
+ # Created: 17th February 2014
7
+ # Updated: 20th April 2024
8
8
  #
9
- # Author: Matthew Wilson
9
+ # Author: Matthew Wilson
10
10
  #
11
+ # Copyright (c) 2019-2024, Matthew Wilson and Synesis Information Systems
11
12
  # Copyright (c) 2014-2019, Matthew Wilson and Synesis Software
12
13
  # All rights reserved.
13
14
  #
@@ -33,44 +34,46 @@
33
34
  # ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
34
35
  # POSSIBILITY OF SUCH DAMAGE.
35
36
  #
36
- # ######################################################################### #
37
+ # ######################################################################## #
37
38
 
38
39
 
39
40
  require 'recls/ximpl/util'
40
41
 
42
+
41
43
  =begin
42
44
  =end
43
45
 
46
+ # @!visibility private
44
47
  class Object; end # :nodoc:
45
48
 
46
49
  module Recls
47
50
 
48
- # Combines paths, optionally canonicalising them
49
- #
50
- # === Signature
51
- #
52
- # * *Parameters:*
53
- # - +paths+ ([ (::String, ::Recls::Entry) ]) Array of 1 or more path elements to be combined
54
- # - +options+ (::Hash) Options that moderate the combination
55
- #
56
- # * *Options:*
57
- # - +:canonicalise+ (boolean) Causes the evaluated path to be canonicalised - with +Recls.canonicalise_path+ - before it is returned
58
- # - +:clean+ (boolean) Causes the evaluated path to be cleaned (i.e. sent to +cleanpath+) before it is returned. Ignored if +:canonicalise+ is specified
59
- # - +:clean_path+ (boolean) Equivalent to +:clean+, but deprecated and may be removed in a future version
60
- #
61
- # === Return
62
- # (String) The combined path
63
- def self.combine_paths(*paths, **options)
51
+ # Combines paths, optionally canonicalising them
52
+ #
53
+ # === Signature
54
+ #
55
+ # * *Parameters:*
56
+ # - +paths+ (+[ String, Recls::Entry ]+) Array of 1 or more path elements to be combined;
57
+ # - +options+ (+Hash+) Options that moderate the combination;
58
+ #
59
+ # * *Options:*
60
+ # - +:canonicalise+ (boolean) Causes the evaluated path to be canonicalised - with +Recls.canonicalise_path+ - before it is returned;
61
+ # - +:clean+ (boolean) Causes the evaluated path to be cleaned (i.e. sent to +cleanpath+) before it is returned. Ignored if +:canonicalise+ is specified;
62
+ # - +:clean_path+ (boolean) Equivalent to +:clean+, but deprecated and may be removed in a future version;
63
+ #
64
+ # === Return
65
+ # (+String+) The combined path.
66
+ def self.combine_paths(*paths, **options)
64
67
 
65
- paths = paths.reject { |p| p.nil? }
66
- paths = paths.map { |p| 'Recls::Entry' == p.class.to_s ? p.path : p }
68
+ paths = paths.reject { |p| p.nil? }
69
+ paths = paths.map { |p| 'Recls::Entry' == p.class.to_s ? p.path : p }
67
70
 
68
- raise ArgumentError, 'must specify one or more path elements' if paths.empty?
71
+ raise ArgumentError, 'must specify one or more path elements' if paths.empty?
69
72
 
70
- return Recls::Ximpl.combine_paths paths, options
71
- end
73
+ return Recls::Ximpl.combine_paths paths, options
74
+ end
72
75
  end # module Recls
73
76
 
74
- # ############################## end of file ############################# #
75
77
 
78
+ # ############################## end of file ############################# #
76
79