recls-ruby 2.11.0.3 → 2.12.0

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 +4 -4
  2. data/LICENSE +24 -27
  3. data/README.md +1 -242
  4. data/examples/find_files_and_directories.md +30 -33
  5. data/examples/find_files_and_directories.recursive.md +254 -255
  6. data/examples/show_hidden_files.md +1 -4
  7. data/examples/show_hidden_files.rb +1 -1
  8. data/examples/show_readonly_files.md +1 -4
  9. data/examples/show_readonly_files.rb +1 -1
  10. data/lib/recls/api.rb +73 -76
  11. data/lib/recls/combine_paths_1.rb +23 -26
  12. data/lib/recls/combine_paths_2plus.rb +29 -32
  13. data/lib/recls/entry.rb +273 -277
  14. data/lib/recls/file_search.rb +193 -194
  15. data/lib/recls/flags.rb +45 -48
  16. data/lib/recls/foreach.rb +98 -105
  17. data/lib/recls/obsolete.rb +79 -80
  18. data/lib/recls/recls.rb +22 -16
  19. data/lib/recls/stat.rb +134 -137
  20. data/lib/recls/util.rb +92 -95
  21. data/lib/recls/version.rb +17 -22
  22. data/lib/recls/ximpl/os.rb +44 -46
  23. data/lib/recls/ximpl/unix.rb +35 -39
  24. data/lib/recls/ximpl/util.rb +596 -598
  25. data/lib/recls/ximpl/windows.rb +137 -141
  26. data/lib/recls.rb +9 -10
  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,14 +1,13 @@
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: 20th April 2024
6
+ # Created: 9th June 2016
7
+ # Updated: 14th April 2019
8
8
  #
9
- # Author: Matthew Wilson
9
+ # Author: Matthew Wilson
10
10
  #
11
- # Copyright (c) 2019-2024, Matthew Wilson and Synesis Information Systems
12
11
  # Copyright (c) 2016-2019, Matthew Wilson and Synesis Software
13
12
  # All rights reserved.
14
13
  #
@@ -34,88 +33,86 @@
34
33
  # ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
35
34
  # POSSIBILITY OF SUCH DAMAGE.
36
35
  #
37
- # ######################################################################## #
36
+ # ######################################################################### #
38
37
 
39
38
 
40
39
  require 'recls/file_search'
41
40
  require 'recls/flags'
42
41
 
43
-
44
42
  =begin
45
43
  =end
46
44
 
47
- # @!visibility private
48
45
  class Object; end # :nodoc:
49
46
 
50
47
  module Recls
51
48
 
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
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
117
114
  end # module Recls
118
115
 
119
-
120
116
  # ############################## end of file ############################# #
121
117
 
118
+
@@ -1,14 +1,13 @@
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: 20th April 2024
6
+ # Created: 17th February 2014
7
+ # Updated: 14th April 2019
8
8
  #
9
- # Author: Matthew Wilson
9
+ # Author: Matthew Wilson
10
10
  #
11
- # Copyright (c) 2019-2024, Matthew Wilson and Synesis Information Systems
12
11
  # Copyright (c) 2014-2019, Matthew Wilson and Synesis Software
13
12
  # All rights reserved.
14
13
  #
@@ -34,40 +33,38 @@
34
33
  # ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
35
34
  # POSSIBILITY OF SUCH DAMAGE.
36
35
  #
37
- # ######################################################################## #
36
+ # ######################################################################### #
38
37
 
39
38
 
40
39
  require 'recls/ximpl/util'
41
40
 
42
-
43
41
  =begin
44
42
  =end
45
43
 
46
- # @!visibility private
47
44
  class Object; end # :nodoc:
48
45
 
49
46
  module Recls
50
47
 
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)
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)
61
58
 
62
- paths = paths.reject { |p| p.nil? }
63
- paths = paths.map { |p| 'Recls::Entry' == p.class.to_s ? p.path : p }
59
+ paths = paths.reject { |p| p.nil? }
60
+ paths = paths.map { |p| 'Recls::Entry' == p.class.to_s ? p.path : p }
64
61
 
65
- raise ArgumentError, 'must specify one or more path elements' if paths.empty?
62
+ raise ArgumentError, 'must specify one or more path elements' if paths.empty?
66
63
 
67
- return Recls::Ximpl.combine_paths paths, {}
68
- end
64
+ return Recls::Ximpl.combine_paths paths, {}
65
+ end
69
66
  end # module Recls
70
67
 
71
-
72
68
  # ############################## end of file ############################# #
73
69
 
70
+
@@ -1,14 +1,13 @@
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: 20th April 2024
6
+ # Created: 17th February 2014
7
+ # Updated: 14th April 2019
8
8
  #
9
- # Author: Matthew Wilson
9
+ # Author: Matthew Wilson
10
10
  #
11
- # Copyright (c) 2019-2024, Matthew Wilson and Synesis Information Systems
12
11
  # Copyright (c) 2014-2019, Matthew Wilson and Synesis Software
13
12
  # All rights reserved.
14
13
  #
@@ -34,46 +33,44 @@
34
33
  # ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
35
34
  # POSSIBILITY OF SUCH DAMAGE.
36
35
  #
37
- # ######################################################################## #
36
+ # ######################################################################### #
38
37
 
39
38
 
40
39
  require 'recls/ximpl/util'
41
40
 
42
-
43
41
  =begin
44
42
  =end
45
43
 
46
- # @!visibility private
47
44
  class Object; end # :nodoc:
48
45
 
49
46
  module Recls
50
47
 
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)
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)
67
64
 
68
- paths = paths.reject { |p| p.nil? }
69
- paths = paths.map { |p| 'Recls::Entry' == p.class.to_s ? p.path : p }
65
+ paths = paths.reject { |p| p.nil? }
66
+ paths = paths.map { |p| 'Recls::Entry' == p.class.to_s ? p.path : p }
70
67
 
71
- raise ArgumentError, 'must specify one or more path elements' if paths.empty?
68
+ raise ArgumentError, 'must specify one or more path elements' if paths.empty?
72
69
 
73
- return Recls::Ximpl.combine_paths paths, options
74
- end
70
+ return Recls::Ximpl.combine_paths paths, options
71
+ end
75
72
  end # module Recls
76
73
 
77
-
78
74
  # ############################## end of file ############################# #
79
75
 
76
+