recls-ruby 2.12.0 → 2.12.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 +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