recls-ruby 2.11.0.3 → 2.12.0

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 +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
+
data/lib/recls/combine_paths_1.rb CHANGED
@@ -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
+
data/lib/recls/combine_paths_2plus.rb CHANGED
@@ -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
+