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/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