recls-ruby 2.11.0 → 2.11.0.1

Sign up to get free protection for your applications and to get access to all the features.
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