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/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,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/file_search'
40
41
  require 'recls/flags'
41
42
 
43
+
42
44
  =begin
43
45
  =end
44
46
 
@@ -46,73 +48,73 @@ class Object; end # :nodoc:
46
48
 
47
49
  module Recls
48
50
 
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
51
+ # [DEPRECATED] Use Recls::file_search()
52
+ def self.FileSearch(search_root, patterns, options = {})
53
+
54
+ Recls::FileSearch.new(search_root, patterns, options)
55
+ end
56
+
57
+ # Initialises a +FileSearch+ instance, which acts recursively, as an
58
+ # +Enumerable+ of Recls::Entry
59
+ #
60
+ # === Signature
61
+ #
62
+ # * *Parameters:*
63
+ # - +search_root+ (String, Recls::Entry) The root directory of the search. May be +nil+, in which case the current directory is assumed
64
+ # - +patterns+ (String, Array) The pattern(s) for which to search. May be +nil+, in which case Recls::WILDCARDS_ALL is assumed
65
+ # - +options+ (Hash, Integer) Combination of flags (with behaviour as described below for the +flags+ option), or an options hash
66
+ #
67
+ # * *Options:*
68
+ # - +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
69
+ #
70
+ # === Return
71
+ # An instance of a class implementing ::Enumerable whose value type is
72
+ # Recls::Entry
73
+ def self.file_rsearch(search_root, patterns, options = {})
74
+
75
+ case options
76
+ when ::NilClass
77
+
78
+ options = { flags: RECURSIVE }
79
+ when ::Integer
80
+
81
+ options |= RECURSIVE
82
+ when ::Hash
83
+
84
+ flags = options[:flags] || 0
85
+ flags |= RECURSIVE
86
+
87
+ options[:flags] = flags
88
+ else
89
+
90
+ # this is handled by the FileSearch initialiser
91
+ end
92
+
93
+ Recls::FileSearch.new(search_root, patterns, options)
94
+ end
95
+
96
+ # Initialises a +FileSearch+ instance, which acts as an +Enumerable+
97
+ # of Recls::Entry
98
+ #
99
+ # === Signature
100
+ #
101
+ # * *Parameters:*
102
+ # - +search_root+ (String, Recls::Entry) The root directory of the search. May be +nil+, in which case the current directory is assumed
103
+ # - +patterns+ (String, Array) The pattern(s) for which to search. May be +nil+, in which case Recls::WILDCARDS_ALL is assumed
104
+ # - +options+ (Hash, Integer) Combination of flags (with behaviour as described below for the +flags+ option), or an options hash
105
+ #
106
+ # * *Options:*
107
+ # - +flags+ (Integer) Combination of flags - FILES, DIRECTORIES, RECURSIVE, etc. If the value modulo TYPEMASK is 0, then FILES is assumed
108
+ #
109
+ # === Return
110
+ # An instance of a class implementing ::Enumerable whose value type is
111
+ # Recls::Entry
112
+ def self.file_search(search_root, patterns, options = {})
113
+
114
+ Recls::FileSearch.new(search_root, patterns, options)
115
+ end
114
116
  end # module Recls
115
117
 
116
- # ############################## end of file ############################# #
117
118
 
119
+ # ############################## end of file ############################# #
118
120
 
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,11 +34,12 @@
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
 
@@ -45,26 +47,26 @@ class Object; end # :nodoc:
45
47
 
46
48
  module Recls
47
49
 
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)
50
+ # Combines paths
51
+ #
52
+ # === Signature
53
+ #
54
+ # * *Parameters:*
55
+ # - +paths+ ([ (::String, ::Recls::Entry) ]) Array of 1 or more path elements to be combined
56
+ #
57
+ # === Return
58
+ # (String) The combined path
59
+ def self.combine_paths(*paths)
58
60
 
59
- paths = paths.reject { |p| p.nil? }
60
- paths = paths.map { |p| 'Recls::Entry' == p.class.to_s ? p.path : p }
61
+ paths = paths.reject { |p| p.nil? }
62
+ paths = paths.map { |p| 'Recls::Entry' == p.class.to_s ? p.path : p }
61
63
 
62
- raise ArgumentError, 'must specify one or more path elements' if paths.empty?
64
+ raise ArgumentError, 'must specify one or more path elements' if paths.empty?
63
65
 
64
- return Recls::Ximpl.combine_paths paths, {}
65
- end
66
+ return Recls::Ximpl.combine_paths paths, {}
67
+ end
66
68
  end # module Recls
67
69
 
68
- # ############################## end of file ############################# #
69
70
 
71
+ # ############################## end of file ############################# #
70
72
 
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,11 +34,12 @@
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
 
@@ -45,32 +47,32 @@ class Object; end # :nodoc:
45
47
 
46
48
  module Recls
47
49
 
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)
50
+ # Combines paths, optionally canonicalising them
51
+ #
52
+ # === Signature
53
+ #
54
+ # * *Parameters:*
55
+ # - +paths+ ([ (::String, ::Recls::Entry) ]) Array of 1 or more path elements to be combined
56
+ # - +options+ (::Hash) Options that moderate the combination
57
+ #
58
+ # * *Options:*
59
+ # - +:canonicalise+ (boolean) Causes the evaluated path to be canonicalised - with +Recls.canonicalise_path+ - before it is returned
60
+ # - +:clean+ (boolean) Causes the evaluated path to be cleaned (i.e. sent to +cleanpath+) before it is returned. Ignored if +:canonicalise+ is specified
61
+ # - +:clean_path+ (boolean) Equivalent to +:clean+, but deprecated and may be removed in a future version
62
+ #
63
+ # === Return
64
+ # (String) The combined path
65
+ def self.combine_paths(*paths, **options)
64
66
 
65
- paths = paths.reject { |p| p.nil? }
66
- paths = paths.map { |p| 'Recls::Entry' == p.class.to_s ? p.path : p }
67
+ paths = paths.reject { |p| p.nil? }
68
+ paths = paths.map { |p| 'Recls::Entry' == p.class.to_s ? p.path : p }
67
69
 
68
- raise ArgumentError, 'must specify one or more path elements' if paths.empty?
70
+ raise ArgumentError, 'must specify one or more path elements' if paths.empty?
69
71
 
70
- return Recls::Ximpl.combine_paths paths, options
71
- end
72
+ return Recls::Ximpl.combine_paths paths, options
73
+ end
72
74
  end # module Recls
73
75
 
74
- # ############################## end of file ############################# #
75
76
 
77
+ # ############################## end of file ############################# #
76
78