recls-ruby 2.11.0 → 2.11.0.2

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 +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 +47 -45
  16. data/lib/recls/foreach.rb +105 -98
  17. data/lib/recls/obsolete.rb +80 -79
  18. data/lib/recls/recls.rb +16 -15
  19. data/lib/recls/stat.rb +137 -134
  20. data/lib/recls/util.rb +95 -92
  21. data/lib/recls/version.rb +18 -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,147 +34,149 @@
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
 
47
+ # @!visibility private
45
48
  class Object; end # :nodoc:
46
49
 
47
50
  module Recls
48
51
 
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
52
+ # Equivalent to a Recls::stat() but only returns (a non-+nil+ value) if the
53
+ # path exists _and_ represents a directory
54
+ #
55
+ # This has two advantages over +File.directory?+: it obtains a
56
+ # Recls::Entry in the case where the path represents a directory; and
57
+ # it does '~' interpretation
58
+ #
59
+ # === Signature
60
+ #
61
+ # * *Parameters:*
62
+ # - +path+ (+String+, +Recls::Entry+) The path;
63
+ #
64
+ # === Return
65
+ # (+Recls::Entry+, +nil+) The entry if +path+ exists and is a directory; +nil+ otherwise.
66
+ def self.directory?(path, *args)
67
+
68
+ fe = self.stat(path, *args)
69
+
70
+ if fe
71
+
72
+ return nil unless fe.directory?
73
+ end
74
+
75
+ fe
76
+ end
77
+
78
+ # Equivalent to a Recls::stat() but only returns (a non-+nil+ value) if the
79
+ # path exists _and_ represents a file
80
+ #
81
+ # This has two advantages over +File.file?+: it obtains a
82
+ # Recls::Entry in the case where the path represents a file; and
83
+ # it does '~' interpretation
84
+ #
85
+ # === Signature
86
+ #
87
+ # * *Parameters:*
88
+ # - +path+ (+String+, +Recls::Entry+) The path;
89
+ #
90
+ # === Return
91
+ # (+Recls::Entry+, +nil+) The entry if +path+ exists and is a file; +nil+ otherwise.
92
+ def self.file?(path, *args)
93
+
94
+ fe = self.stat(path, *args)
95
+
96
+ if fe
97
+
98
+ return nil unless fe.file?
99
+ end
100
+
101
+ fe
102
+ end
103
+
104
+ # Obtains a single Recls::Entry instance from a path, according to the
105
+ # given arguments, which can be any combination of search-root and
106
+ # flags, as discussed below
107
+ #
108
+ # === Signature
109
+ #
110
+ # * *Parameters:*
111
+ # - +path+ (+String+) A path to evaluate. May not be +nil+;
112
+ # - +search_root+ (+String+, +Recls::Entry+) A directory from which the returned Entry instance's search-relative attributes are evaluated;
113
+ # - +flags+ (+Integer+) A bit-combined set of flags (such as +Recls::DIRECTORIES+, +Recls::FILES+, +Recls::RECURSIVE+, +Recls::DETAILS_LATER+, and so on);
114
+ #
115
+ # ==== Parameter Ordering
116
+ #
117
+ # The parameters may be expressed in any of the following permutations:
118
+ # - +path+
119
+ # - +path+, +flags+
120
+ # - +path+, +search_root+
121
+ # - +path+, +flags+, +search_root+
122
+ # - +path+, +search_root+, +flags+
123
+ #
124
+ # === Return
125
+ # (+Recls::Entry+) An entry representing the path on the file-system, or
126
+ # +nil+ if the path does not refer to an existing entity. If the
127
+ # +Recls::DETAILS_LATER+ flag is included, then an entry is returned
128
+ # regardless of its existence.
129
+ def self.stat(path, *args)
130
+
131
+ flags = 0
132
+ search_root = nil
133
+ message = nil
134
+
135
+ path = File.expand_path(path) if path =~ /^~[\\\/]*/
136
+
137
+ case args.size
138
+ when 0
139
+
140
+ ;
141
+ when 1
142
+
143
+ case args[0]
144
+ when ::Integer
145
+
146
+ flags = args[0]
147
+ when ::String
148
+
149
+ search_root = args[0]
150
+ else
151
+
152
+ message = "argument '#{args[0]}' (#{args[0].class}) not valid"
153
+ end
154
+ when 2
155
+
156
+ if false
157
+ elsif ::Integer === args[0] && ::String === args[1]
158
+
159
+ flags = args[0]
160
+ search_root = args[1]
161
+ elsif ::String === args[0] && ::Integer === args[1]
162
+
163
+ search_root = args[0]
164
+ flags = args[1]
165
+ else
166
+
167
+ message = "invalid combination of arguments"
168
+ end
169
+ else
170
+
171
+ message = "too many arguments"
172
+ end
173
+
174
+ raise ArgumentError, "#{message}: Recls.stat() takes one (path), two (path+flags or path+search_root), or three (path+search_root+flags) arguments" if message
175
+
176
+ Recls::Ximpl.stat_prep(path, search_root, flags)
177
+ end
175
178
  end # module Recls
176
179
 
177
- # ############################## end of file ############################# #
178
180
 
181
+ # ############################## end of file ############################# #
179
182
 
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,116 +34,118 @@
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
 
48
+ # @!visibility private
46
49
  class Object; end # :nodoc:
47
50
 
48
51
  module Recls
49
52
 
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
53
+ # Obtains the absolute form of the given path
54
+ #
55
+ # === Signature
56
+ #
57
+ # * *Parameters:*
58
+ # - +path+ (+String+, +Recls::Entry+) The path;
59
+ #
60
+ # === Return
61
+ # (+String+) The absolute form of the path.
62
+ def self.absolute_path(path)
63
+
64
+ return path.path if 'Recls::Entry' === path.class.to_s
65
+
66
+ Recls::Ximpl.absolute_path path
67
+ end
68
+
69
+ # Canonicalises the given path, by removing dots ('.' and '..')
70
+ # directories
71
+ #
72
+ # === Signature
73
+ #
74
+ # * *Parameters:*
75
+ # - +path+ (+String+, +Recls::Entry+) The path;
76
+ #
77
+ # === Return
78
+ # (+String+) The canonical form of the path.
79
+ def self.canonicalise_path(path)
80
+
81
+ path = path.path if 'Recls::Entry' === path.class.to_s
82
+
83
+ Recls::Ximpl.canonicalise_path path
84
+ end
85
+
86
+ # Derives a given path relative to an origin, unless the path is
87
+ # absolute
88
+ #
89
+ # === Signature
90
+ #
91
+ # * *Parameters:*
92
+ # - +origin+ (+String+, +Recls::Entry+) The path against which +path+ will be evaluated;
93
+ # - +path+ (+String+, +Recls::Entry+) The path to evaluate;
94
+ #
95
+ # === Return
96
+ # (+String+) The relative form of the path.
97
+ def self.derive_relative_path(origin, path)
98
+
99
+ Recls::Ximpl.derive_relative_path origin, path
100
+ end
98
101
  end # module Recls
99
102
 
100
103
  if RUBY_VERSION >= '2'
101
104
 
102
- require 'recls/combine_paths_2plus'
105
+ require 'recls/combine_paths_2plus'
103
106
  else
104
107
 
105
- require 'recls/combine_paths_1'
108
+ require 'recls/combine_paths_1'
106
109
  end
107
110
 
108
111
  module Recls
109
112
 
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
113
+ # Indicates whether the given path exists, obtaining a Recls::Entry
114
+ # instance if so
115
+ #
116
+ # === Signature
117
+ #
118
+ # * *Parameters:*
119
+ # - +path+ (+String+, +Recls::Entry+) The path;
120
+ #
121
+ # === Return
122
+ # (+Recls::Entry+, +nil+) The entry if +path+ exists; +nil+ otherwise.
123
+ def self.exist?(path)
124
+
125
+ return nil if path.nil?
126
+
127
+ Recls.stat(path)
128
+ end
129
+
130
+ # Indicates whether the given path is absolute
131
+ #
132
+ # === Signature
133
+ #
134
+ # * *Parameters:*
135
+ # - +path+ (+String+, +Recls::Entry+) The path;
136
+ #
137
+ # === Return
138
+ # (boolean) +true+ if +path+ is absolute; +false+ otherwise.
139
+ def self.absolute_path?(path)
140
+
141
+ return nil if path.nil?
142
+
143
+ return true if 'Recls::Entry' === path.class.to_s
144
+
145
+ Recls::Ximpl.absolute_path? path
146
+ end
144
147
  end # module Recls
145
148
 
146
- # ############################## end of file ############################# #
147
149
 
150
+ # ############################## end of file ############################# #
148
151
 
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,27 +34,28 @@
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
41
41
  =end
42
42
 
43
+ # @!visibility private
43
44
  class Object; end # :nodoc:
44
45
 
45
46
  module Recls
46
47
 
47
- # Current version of the recls.Ruby library
48
- VERSION = '2.11.0'
48
+ # Current version of the recls.Ruby library
49
+ VERSION = '2.11.0.2'
49
50
 
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:
51
+ private
52
+ VERSION_PARTS_ = VERSION.split(/[.]/).collect { |n| n.to_i } # :nodoc:
53
+ public
54
+ VERSION_MAJOR = VERSION_PARTS_[0] # :nodoc:
55
+ VERSION_MINOR = VERSION_PARTS_[1] # :nodoc:
56
+ VERSION_REVISION = VERSION_PARTS_[2] # :nodoc:
56
57
  end # module Recls
57
58
 
58
- # ############################## end of file ############################# #
59
59
 
60
+ # ############################## end of file ############################# #
60
61