recls-ruby 2.11.0 → 2.11.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 +5 -5
  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 +75 -73
  11. data/lib/recls/combine_paths_1.rb +25 -23
  12. data/lib/recls/combine_paths_2plus.rb +31 -29
  13. data/lib/recls/entry.rb +276 -273
  14. data/lib/recls/file_search.rb +195 -193
  15. data/lib/recls/flags.rb +46 -45
  16. data/lib/recls/foreach.rb +103 -98
  17. data/lib/recls/obsolete.rb +80 -79
  18. data/lib/recls/recls.rb +16 -15
  19. data/lib/recls/stat.rb +136 -134
  20. data/lib/recls/util.rb +94 -92
  21. data/lib/recls/version.rb +17 -17
  22. data/lib/recls/ximpl/os.rb +45 -43
  23. data/lib/recls/ximpl/unix.rb +38 -35
  24. data/lib/recls/ximpl/util.rb +597 -596
  25. data/lib/recls/ximpl/windows.rb +139 -136
  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 +6 -6
data/lib/recls/stat.rb CHANGED
@@ -1,13 +1,14 @@
1
- # ######################################################################### #
2
- # File: recls/stat.rb
1
+ # ######################################################################## #
2
+ # File: recls/stat.rb
3
3
  #
4
- # Purpose: Defines the Recls.stat() method for the recls.Ruby library.
4
+ # Purpose: Defines the Recls.stat() method for the recls.Ruby library.
5
5
  #
6
- # Created: 24th July 2012
7
- # Updated: 14th March 2019
6
+ # Created: 24th July 2012
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) 2012-2019, Matthew Wilson and Synesis Software
12
13
  # All rights reserved.
13
14
  #
@@ -33,12 +34,13 @@
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/entry'
40
41
  require 'recls/flags'
41
42
 
43
+
42
44
  =begin
43
45
  =end
44
46
 
@@ -46,134 +48,134 @@ class Object; end # :nodoc:
46
48
 
47
49
  module Recls
48
50
 
49
- # Equivalent to a Recls::stat() but only returns (a non-+nil+ value) if the
50
- # path exists _and_ represents a directory
51
- #
52
- # This has two advantages over +File.directory?+: it obtains a
53
- # Recls::Entry in the case where the path represents a directory; and
54
- # it does '~' interpretation
55
- #
56
- # === Signature
57
- #
58
- # * *Parameters:*
59
- # - +path+ (String, Recls::Entry) The path
60
- #
61
- # === Return
62
- # (Recls::Entry, nil) The entry if +path+ exists and is a directory; +nil+ otherwise
63
- def self.directory?(path, *args)
64
-
65
- fe = self.stat(path, *args)
66
-
67
- if fe
68
-
69
- return nil unless fe.directory?
70
- end
71
-
72
- fe
73
- end
74
-
75
- # Equivalent to a Recls::stat() but only returns (a non-+nil+ value) if the
76
- # path exists _and_ represents a file
77
- #
78
- # This has two advantages over +File.file?+: it obtains a
79
- # Recls::Entry in the case where the path represents a file; and
80
- # it does '~' interpretation
81
- #
82
- # === Signature
83
- #
84
- # * *Parameters:*
85
- # - +path+ (String, Recls::Entry) The path
86
- #
87
- # === Return
88
- # (Recls::Entry, nil) The entry if +path+ exists and is a file; +nil+ otherwise
89
- def self.file?(path, *args)
90
-
91
- fe = self.stat(path, *args)
92
-
93
- if fe
94
-
95
- return nil unless fe.file?
96
- end
97
-
98
- fe
99
- end
100
-
101
- # Obtains a single Recls::Entry instance from a path, according to the
102
- # given arguments, which can be any combination of search-root and
103
- # flags, as discussed below
104
- #
105
- # === Signature
106
- #
107
- # * *Parameters:*
108
- # - +path+ (String) A path to evaluate. May not be +nil+
109
- # - +search_root+ (String, Recls::Entry) A directory from which the returned Entry instance's search-relative attributes are evaluated
110
- # - +flags+ (Integer) A bit-combined set of flags (such as Recls::DIRECTORIES, Recls::FILES, Recls::RECURSIVE, Recls::DETAILS_LATER, and so on)
111
- #
112
- # ==== Parameter Ordering
113
- #
114
- # The parameters may be expressed in any of the following permutations:
115
- # - +path+
116
- # - +path+, +flags+
117
- # - +path+, +search_root+
118
- # - +path+, +flags+, +search_root+
119
- # - +path+, +search_root+, +flags+
120
- #
121
- # === Return
122
- # (Recls::Entry) An entry representing the path on the file-system, or
123
- # +nil+ if the path does not refer to an existing entity. If the
124
- # Recls::DETAILS_LATER flag is included, then an entry is returned
125
- # regardless of its existence
126
- def self.stat(path, *args)
127
-
128
- flags = 0
129
- search_root = nil
130
- message = nil
131
-
132
- path = File.expand_path(path) if path =~ /^~[\\\/]*/
133
-
134
- case args.size
135
- when 0
136
-
137
- ;
138
- when 1
139
-
140
- case args[0]
141
- when ::Integer
142
-
143
- flags = args[0]
144
- when ::String
145
-
146
- search_root = args[0]
147
- else
148
-
149
- message = "argument '#{args[0]}' (#{args[0].class}) not valid"
150
- end
151
- when 2
152
-
153
- if false
154
- elsif ::Integer === args[0] && ::String === args[1]
155
-
156
- flags = args[0]
157
- search_root = args[1]
158
- elsif ::String === args[0] && ::Integer === args[1]
159
-
160
- search_root = args[0]
161
- flags = args[1]
162
- else
163
-
164
- message = "invalid combination of arguments"
165
- end
166
- else
167
-
168
- message = "too many arguments"
169
- end
170
-
171
- raise ArgumentError, "#{message}: Recls.stat() takes one (path), two (path+flags or path+search_root), or three (path+search_root+flags) arguments" if message
172
-
173
- Recls::Ximpl.stat_prep(path, search_root, flags)
174
- end
51
+ # Equivalent to a Recls::stat() but only returns (a non-+nil+ value) if the
52
+ # path exists _and_ represents a directory
53
+ #
54
+ # This has two advantages over +File.directory?+: it obtains a
55
+ # Recls::Entry in the case where the path represents a directory; and
56
+ # it does '~' interpretation
57
+ #
58
+ # === Signature
59
+ #
60
+ # * *Parameters:*
61
+ # - +path+ (String, Recls::Entry) The path
62
+ #
63
+ # === Return
64
+ # (Recls::Entry, nil) The entry if +path+ exists and is a directory; +nil+ otherwise
65
+ def self.directory?(path, *args)
66
+
67
+ fe = self.stat(path, *args)
68
+
69
+ if fe
70
+
71
+ return nil unless fe.directory?
72
+ end
73
+
74
+ fe
75
+ end
76
+
77
+ # Equivalent to a Recls::stat() but only returns (a non-+nil+ value) if the
78
+ # path exists _and_ represents a file
79
+ #
80
+ # This has two advantages over +File.file?+: it obtains a
81
+ # Recls::Entry in the case where the path represents a file; and
82
+ # it does '~' interpretation
83
+ #
84
+ # === Signature
85
+ #
86
+ # * *Parameters:*
87
+ # - +path+ (String, Recls::Entry) The path
88
+ #
89
+ # === Return
90
+ # (Recls::Entry, nil) The entry if +path+ exists and is a file; +nil+ otherwise
91
+ def self.file?(path, *args)
92
+
93
+ fe = self.stat(path, *args)
94
+
95
+ if fe
96
+
97
+ return nil unless fe.file?
98
+ end
99
+
100
+ fe
101
+ end
102
+
103
+ # Obtains a single Recls::Entry instance from a path, according to the
104
+ # given arguments, which can be any combination of search-root and
105
+ # flags, as discussed below
106
+ #
107
+ # === Signature
108
+ #
109
+ # * *Parameters:*
110
+ # - +path+ (String) A path to evaluate. May not be +nil+
111
+ # - +search_root+ (String, Recls::Entry) A directory from which the returned Entry instance's search-relative attributes are evaluated
112
+ # - +flags+ (Integer) A bit-combined set of flags (such as Recls::DIRECTORIES, Recls::FILES, Recls::RECURSIVE, Recls::DETAILS_LATER, and so on)
113
+ #
114
+ # ==== Parameter Ordering
115
+ #
116
+ # The parameters may be expressed in any of the following permutations:
117
+ # - +path+
118
+ # - +path+, +flags+
119
+ # - +path+, +search_root+
120
+ # - +path+, +flags+, +search_root+
121
+ # - +path+, +search_root+, +flags+
122
+ #
123
+ # === Return
124
+ # (Recls::Entry) An entry representing the path on the file-system, or
125
+ # +nil+ if the path does not refer to an existing entity. If the
126
+ # Recls::DETAILS_LATER flag is included, then an entry is returned
127
+ # regardless of its existence
128
+ def self.stat(path, *args)
129
+
130
+ flags = 0
131
+ search_root = nil
132
+ message = nil
133
+
134
+ path = File.expand_path(path) if path =~ /^~[\\\/]*/
135
+
136
+ case args.size
137
+ when 0
138
+
139
+ ;
140
+ when 1
141
+
142
+ case args[0]
143
+ when ::Integer
144
+
145
+ flags = args[0]
146
+ when ::String
147
+
148
+ search_root = args[0]
149
+ else
150
+
151
+ message = "argument '#{args[0]}' (#{args[0].class}) not valid"
152
+ end
153
+ when 2
154
+
155
+ if false
156
+ elsif ::Integer === args[0] && ::String === args[1]
157
+
158
+ flags = args[0]
159
+ search_root = args[1]
160
+ elsif ::String === args[0] && ::Integer === args[1]
161
+
162
+ search_root = args[0]
163
+ flags = args[1]
164
+ else
165
+
166
+ message = "invalid combination of arguments"
167
+ end
168
+ else
169
+
170
+ message = "too many arguments"
171
+ end
172
+
173
+ raise ArgumentError, "#{message}: Recls.stat() takes one (path), two (path+flags or path+search_root), or three (path+search_root+flags) arguments" if message
174
+
175
+ Recls::Ximpl.stat_prep(path, search_root, flags)
176
+ end
175
177
  end # module Recls
176
178
 
177
- # ############################## end of file ############################# #
178
179
 
180
+ # ############################## end of file ############################# #
179
181
 
data/lib/recls/util.rb CHANGED
@@ -1,13 +1,14 @@
1
- # ######################################################################### #
2
- # File: recls/util.rb
1
+ # ######################################################################## #
2
+ # File: recls/util.rb
3
3
  #
4
- # Purpose: Utility module functions for recls library
4
+ # Purpose: Utility module functions for recls library
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) 2012-2019, Matthew Wilson and Synesis Software
12
13
  # All rights reserved.
13
14
  #
@@ -33,13 +34,14 @@
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/stat'
40
41
  require 'recls/ximpl/util'
41
42
  require 'recls/ximpl/os'
42
43
 
44
+
43
45
  =begin
44
46
  =end
45
47
 
@@ -47,102 +49,102 @@ class Object; end # :nodoc:
47
49
 
48
50
  module Recls
49
51
 
50
- # Obtains the absolute form of the given path
51
- #
52
- # === Signature
53
- #
54
- # * *Parameters:*
55
- # - +path+ (String, Recls::Entry) The path
56
- #
57
- # === Return
58
- # (String) The absolute form of the path
59
- def self.absolute_path(path)
60
-
61
- return path.path if 'Recls::Entry' === path.class.to_s
62
-
63
- Recls::Ximpl.absolute_path path
64
- end
65
-
66
- # Canonicalises the given path, by removing dots ('.' and '..')
67
- # directories
68
- #
69
- # === Signature
70
- #
71
- # * *Parameters:*
72
- # - +path+ (String, Recls::Entry) The path
73
- #
74
- # === Return
75
- # (String) The canonical form of the path
76
- def self.canonicalise_path(path)
77
-
78
- path = path.path if 'Recls::Entry' === path.class.to_s
79
-
80
- Recls::Ximpl.canonicalise_path path
81
- end
82
-
83
- # Derives a given path relative to an origin, unless the path is
84
- # absolute
85
- #
86
- # === Signature
87
- #
88
- # * *Parameters:*
89
- # - +origin+ (String, Recls::Entry) The path against which +path+ will be evaluated
90
- # - +path+ (String, Recls::Entry) The path to evaluate
91
- #
92
- # === Return
93
- # (String) The relative form of the path
94
- def self.derive_relative_path(origin, path)
95
-
96
- Recls::Ximpl.derive_relative_path origin, path
97
- end
52
+ # Obtains the absolute form of the given path
53
+ #
54
+ # === Signature
55
+ #
56
+ # * *Parameters:*
57
+ # - +path+ (String, Recls::Entry) The path
58
+ #
59
+ # === Return
60
+ # (String) The absolute form of the path
61
+ def self.absolute_path(path)
62
+
63
+ return path.path if 'Recls::Entry' === path.class.to_s
64
+
65
+ Recls::Ximpl.absolute_path path
66
+ end
67
+
68
+ # Canonicalises the given path, by removing dots ('.' and '..')
69
+ # directories
70
+ #
71
+ # === Signature
72
+ #
73
+ # * *Parameters:*
74
+ # - +path+ (String, Recls::Entry) The path
75
+ #
76
+ # === Return
77
+ # (String) The canonical form of the path
78
+ def self.canonicalise_path(path)
79
+
80
+ path = path.path if 'Recls::Entry' === path.class.to_s
81
+
82
+ Recls::Ximpl.canonicalise_path path
83
+ end
84
+
85
+ # Derives a given path relative to an origin, unless the path is
86
+ # absolute
87
+ #
88
+ # === Signature
89
+ #
90
+ # * *Parameters:*
91
+ # - +origin+ (String, Recls::Entry) The path against which +path+ will be evaluated
92
+ # - +path+ (String, Recls::Entry) The path to evaluate
93
+ #
94
+ # === Return
95
+ # (String) The relative form of the path
96
+ def self.derive_relative_path(origin, path)
97
+
98
+ Recls::Ximpl.derive_relative_path origin, path
99
+ end
98
100
  end # module Recls
99
101
 
100
102
  if RUBY_VERSION >= '2'
101
103
 
102
- require 'recls/combine_paths_2plus'
104
+ require 'recls/combine_paths_2plus'
103
105
  else
104
106
 
105
- require 'recls/combine_paths_1'
107
+ require 'recls/combine_paths_1'
106
108
  end
107
109
 
108
110
  module Recls
109
111
 
110
- # Indicates whether the given path exists, obtaining a Recls::Entry
111
- # instance if so
112
- #
113
- # === Signature
114
- #
115
- # * *Parameters:*
116
- # - +path+ (String, Recls::Entry) The path
117
- #
118
- # === Return
119
- # (Recls::Entry, nil) The entry if +path+ exists; +nil+ otherwise
120
- def self.exist?(path)
121
-
122
- return nil if path.nil?
123
-
124
- Recls.stat(path)
125
- end
126
-
127
- # Indicates whether the given path is absolute
128
- #
129
- # === Signature
130
- #
131
- # * *Parameters:*
132
- # - +path+ (String, Recls::Entry) The path
133
- #
134
- # === Return
135
- # (boolean) +true+ if +path+ is absolute; +false+ otherwise
136
- def self.absolute_path?(path)
137
-
138
- return nil if path.nil?
139
-
140
- return true if 'Recls::Entry' === path.class.to_s
141
-
142
- Recls::Ximpl.absolute_path? path
143
- end
112
+ # Indicates whether the given path exists, obtaining a Recls::Entry
113
+ # instance if so
114
+ #
115
+ # === Signature
116
+ #
117
+ # * *Parameters:*
118
+ # - +path+ (String, Recls::Entry) The path
119
+ #
120
+ # === Return
121
+ # (Recls::Entry, nil) The entry if +path+ exists; +nil+ otherwise
122
+ def self.exist?(path)
123
+
124
+ return nil if path.nil?
125
+
126
+ Recls.stat(path)
127
+ end
128
+
129
+ # Indicates whether the given path is absolute
130
+ #
131
+ # === Signature
132
+ #
133
+ # * *Parameters:*
134
+ # - +path+ (String, Recls::Entry) The path
135
+ #
136
+ # === Return
137
+ # (boolean) +true+ if +path+ is absolute; +false+ otherwise
138
+ def self.absolute_path?(path)
139
+
140
+ return nil if path.nil?
141
+
142
+ return true if 'Recls::Entry' === path.class.to_s
143
+
144
+ Recls::Ximpl.absolute_path? path
145
+ end
144
146
  end # module Recls
145
147
 
146
- # ############################## end of file ############################# #
147
148
 
149
+ # ############################## end of file ############################# #
148
150
 
data/lib/recls/version.rb CHANGED
@@ -1,14 +1,14 @@
1
- # ######################################################################### #
2
- # File: recls/version.rb
1
+ # ######################################################################## #
2
+ # File: recls/version.rb
3
3
  #
4
- # Purpose: Version for recls library
4
+ # Purpose: Version for recls library
5
5
  #
6
- # Created: 14th February 2014
7
- # Updated: 25th May 2020
6
+ # Created: 14th February 2014
7
+ # Updated: 20th April 2024
8
8
  #
9
- # Author: Matthew Wilson
9
+ # Author: Matthew Wilson
10
10
  #
11
- # Copyright (c) 2019-2020, Matthew Wilson and Synesis Information Systems
11
+ # Copyright (c) 2019-2024, Matthew Wilson and Synesis Information Systems
12
12
  # Copyright (c) 2012-2019, Matthew Wilson and Synesis Software
13
13
  # All rights reserved.
14
14
  #
@@ -34,7 +34,7 @@
34
34
  # ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
35
35
  # POSSIBILITY OF SUCH DAMAGE.
36
36
  #
37
- # ######################################################################### #
37
+ # ######################################################################## #
38
38
 
39
39
 
40
40
  =begin
@@ -44,17 +44,17 @@ class Object; end # :nodoc:
44
44
 
45
45
  module Recls
46
46
 
47
- # Current version of the recls.Ruby library
48
- VERSION = '2.11.0'
47
+ # Current version of the recls.Ruby library
48
+ VERSION = '2.11.0.1'
49
49
 
50
- private
51
- VERSION_PARTS_ = VERSION.split(/[.]/).collect { |n| n.to_i } # :nodoc:
52
- public
53
- VERSION_MAJOR = VERSION_PARTS_[0] # :nodoc:
54
- VERSION_MINOR = VERSION_PARTS_[1] # :nodoc:
55
- VERSION_REVISION = VERSION_PARTS_[2] # :nodoc:
50
+ private
51
+ VERSION_PARTS_ = VERSION.split(/[.]/).collect { |n| n.to_i } # :nodoc:
52
+ public
53
+ VERSION_MAJOR = VERSION_PARTS_[0] # :nodoc:
54
+ VERSION_MINOR = VERSION_PARTS_[1] # :nodoc:
55
+ VERSION_REVISION = VERSION_PARTS_[2] # :nodoc:
56
56
  end # module Recls
57
57
 
58
- # ############################## end of file ############################# #
59
58
 
59
+ # ############################## end of file ############################# #
60
60