recls-ruby 2.12.0 → 2.12.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 +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/foreach.rb CHANGED
@@ -1,13 +1,14 @@
1
- # ######################################################################### #
2
- # File: recls/foreach.rb
1
+ # ######################################################################## #
2
+ # File: recls/foreach.rb
3
3
  #
4
- # Purpose: Definition of Recls::foreach() utility function
4
+ # Purpose: Definition of Recls::foreach() utility function
5
5
  #
6
- # Created: 22nd October 2014
7
- # Updated: 26th May 2020
6
+ # Created: 22nd October 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) 2012-2019, Matthew Wilson and Synesis Software
12
13
  # All rights reserved.
13
14
  #
@@ -33,110 +34,116 @@
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
 
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
- private
49
- # @!visibility private
50
- class FileSearchLineEnumerator # :nodoc: all
51
-
52
- include Enumerable
53
-
54
- # @!visibility private
55
- def initialize(fs)
56
-
57
- @fs = fs
58
- end
59
-
60
- # @!visibility private
61
- def each(&block)
62
-
63
- @fs.each do |fe|
64
-
65
- IO.readlines(fe).each_with_index do |line, index|
66
-
67
- case block.arity
68
- when 1
69
- yield line
70
- when 2
71
- yield line, index
72
- when 3
73
- yield line, index, fe
74
- else
75
- raise ArgumentError, "block must take 1, 2, or 3 parameters - #{block.arity} given. (Perhaps you have applied each_with_index, which cannot be done to Recls.foreach)"
76
- end
77
- end
78
- end
79
- end
80
- end # class FileSearchLineEnumerator
81
- public
82
-
83
- # Performs a recursive search and enumerates the lines of all files
84
- # found
85
- #
86
- # === Signature
87
- #
88
- # * *Parameters:*
89
- # - +searchable+ A searchable instance obtained from Recls::file_search() or Recls::file_rsearch()
90
- # - +search_root+ (String, Recls::Entry) The root directory of the search. May be +nil+, in which case the current directory is assumed
91
- # - +patterns+ (String, Array) The pattern(s) for which to search. May be +nil+, in which case Recls::WILDCARDS_ALL is assumed
92
- # - +options+ (Hash) An options hash
93
- # - +flags+ (Integer) Combination of flags (with behaviour as described below for the +flags+ option)
94
- #
95
- # * *Block:*
96
- # An optional block that will be executed once for each line in each file
97
- # found, where the block must take 1, 2, or 3 parameters, representing the
98
- # line [ + file-line-index [ + entry ]]. If no block is given, an
99
- # enumerator is returned.
100
- #
101
- # ==== Parameter Ordering
102
- #
103
- # The parameters may be expressed in any of the following permutations:
104
- # - +searchable+
105
- # - +search_root+, +patterns+, +flags+
106
- # - +search_root+, +patterns+, +options+
107
- #
108
- # === Return
109
- #
110
- def self.foreach(*args, &block)
111
-
112
- fs = nil
113
-
114
- case args.length
115
- when 1
116
-
117
- raise ArgumentError "Single argument must be of type #{Recls::FileSearch}" unless args[0].kind_of? Recls::FileSearch
118
-
119
- fs = args[0]
120
- when 3
121
-
122
- fs = Recls::FileSearch.new(args[0], args[1], args[2])
123
- else
124
-
125
- raise ArgumentError "Function requires single argument (#{Recls::FileSearch}) or three arguments (directory, patterns, flags)"
126
- end
127
-
128
- if block_given?
129
-
130
- FileSearchLineEnumerator.new(fs).each(block)
131
-
132
- return nil
133
- else
134
-
135
- return FileSearchLineEnumerator.new(fs)
136
- end
137
- end
51
+ private
52
+ # @!visibility private
53
+ class FileSearchLineEnumerator # :nodoc: all
54
+
55
+ include Enumerable
56
+
57
+ # @!visibility private
58
+ def initialize(fs)
59
+
60
+ @fs = fs
61
+ end
62
+
63
+ # @!visibility private
64
+ def each(&block)
65
+
66
+ @fs.each do |fe|
67
+
68
+ IO.readlines(fe).each_with_index do |line, index|
69
+
70
+ case block.arity
71
+ when 1
72
+
73
+ yield line
74
+ when 2
75
+
76
+ yield line, index
77
+ when 3
78
+
79
+ yield line, index, fe
80
+ else
81
+
82
+ raise ArgumentError, "block must take 1, 2, or 3 parameters - #{block.arity} given. (Perhaps you have applied each_with_index, which cannot be done to Recls.foreach)"
83
+ end
84
+ end
85
+ end
86
+ end
87
+ end # class FileSearchLineEnumerator
88
+ public
89
+
90
+ # Performs a recursive search and enumerates the lines of all files
91
+ # found
92
+ #
93
+ # === Signature
94
+ #
95
+ # * *Parameters:*
96
+ # - +searchable+ A searchable instance obtained from +Recls::file_search()+ or +Recls::file_rsearch()+;
97
+ # - +search_root+ (+String+, +Recls::Entry+) The root directory of the search. May be +nil+, in which case the current directory is assumed;
98
+ # - +patterns+ (+String+, +Array+) The pattern(s) for which to search. May be +nil+, in which case +Recls::WILDCARDS_ALL+ is assumed;
99
+ # - +options+ (+Hash+) An options hash;
100
+ # - +flags+ (+Integer+) Combination of flags (with behaviour as described below for the +flags+ option);
101
+ #
102
+ # * *Block:*
103
+ # An optional block that will be executed once for each line in each file
104
+ # found, where the block must take 1, 2, or 3 parameters, representing the
105
+ # line [ + file-line-index [ + entry ]]. If no block is given, an
106
+ # enumerator is returned.
107
+ #
108
+ # ==== Parameter Ordering
109
+ #
110
+ # The parameters may be expressed in any of the following permutations:
111
+ # - +searchable+
112
+ # - +search_root+, +patterns+, +flags+
113
+ # - +search_root+, +patterns+, +options+
114
+ #
115
+ # === Return
116
+ # +nil+ if a block is given; otherwise, an instance of the +FileSearchLineEnumerator+.
117
+ def self.foreach(*args, &block)
118
+
119
+ fs = nil
120
+
121
+ case args.length
122
+ when 1
123
+
124
+ raise ArgumentError "Single argument must be of type #{Recls::FileSearch}" unless args[0].kind_of? Recls::FileSearch
125
+
126
+ fs = args[0]
127
+ when 3
128
+
129
+ fs = Recls::FileSearch.new(args[0], args[1], args[2])
130
+ else
131
+
132
+ raise ArgumentError "Function requires single argument (#{Recls::FileSearch}) or three arguments (directory, patterns, flags)"
133
+ end
134
+
135
+ if block_given?
136
+
137
+ FileSearchLineEnumerator.new(fs).each(block)
138
+
139
+ return nil
140
+ else
141
+
142
+ return FileSearchLineEnumerator.new(fs)
143
+ end
144
+ end
138
145
  end # module Recls
139
146
 
140
- # ############################## end of file ############################# #
141
147
 
148
+ # ############################## end of file ############################# #
142
149
 
data/lib/recls/obsolete.rb CHANGED
@@ -1,13 +1,14 @@
1
- # ######################################################################### #
2
- # File: recls/obsolete.rb
1
+ # ######################################################################## #
2
+ # File: recls/obsolete.rb
3
3
  #
4
- # Purpose: Obsolete elements
4
+ # Purpose: Obsolete elements
5
5
  #
6
- # Created: 19th July 2012
7
- # Updated: 14th April 2019
6
+ # Created: 19th July 2012
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) 2012-2019, Matthew Wilson and Synesis Software
12
13
  # All rights reserved.
13
14
  #
@@ -33,87 +34,92 @@
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
 
40
- # ######################################################################### #
41
+ # ######################################################################## #
41
42
  # Obsolete symbols
42
43
 
43
44
  if not defined? RECLS_NO_OBSOLETE
44
45
 
45
- module Recls # :nodoc: all
46
-
47
- # @!visibility private
48
- def self.pathNameSeparator
49
-
50
- PATH_NAME_SEPARATOR
51
- end
52
-
53
- # @!visibility private
54
- def self.pathSeparator
55
-
56
- PATH_SEPARATOR
57
- end
58
-
59
- # @!visibility private
60
- def self.wildcardsAll
61
-
62
- WILDCARDS_ALL
63
- end
64
-
65
- class FileSearch # :nodoc:
66
-
67
- # @!visibility private
68
- alias_method :searchRoot, :search_root
69
- # @!visibility private
70
- alias_method :pattern, :patterns
71
- end
72
-
73
- class Entry # :nodoc:
74
-
75
- # @!visibility private
76
- alias_method :uncDrive, :drive
77
- # @!visibility private
78
- alias_method :directoryPath, :directory_path
79
- # @!visibility private
80
- alias_method :directoryParts, :directory_parts
81
- # @!visibility private
82
- alias_method :file, :file_full_name
83
- # @!visibility private
84
- alias_method :shortFile, :file_short_name
85
- # @!visibility private
86
- alias_method :fileBaseName, :file_name_only
87
- # @!visibility private
88
- alias_method :fileName, :file_name_only
89
- # @!visibility private
90
- alias_method :fileExt, :file_extension
91
- # @!visibility private
92
- alias_method :searchDirectory, :search_directory
93
- # @!visibility private
94
- alias_method :searchRelativePath, :search_relative_path
95
-
96
- # @!visibility private
97
- alias_method :isDirectory, :directory?
98
- # @!visibility private
99
- alias_method :isFile, :file?
100
- #alias_method :isLink, :link?
101
- # @!visibility private
102
- alias_method :isReadOnly, :readonly?
103
- # @!visibility private
104
- def isUNC
105
-
106
- d = drive
107
-
108
- d and d.size > 2
109
- end
110
-
111
- # @!visibility private
112
- alias_method :creationTime, :modification_time
113
- end
114
- end # module Recls
46
+ # :stopdoc:
47
+
48
+ # @!visibility private
49
+ module Recls # :nodoc: all
50
+
51
+ # @!visibility private
52
+ def self.pathNameSeparator
53
+
54
+ PATH_NAME_SEPARATOR
55
+ end
56
+
57
+ # @!visibility private
58
+ def self.pathSeparator
59
+
60
+ PATH_SEPARATOR
61
+ end
62
+
63
+ # @!visibility private
64
+ def self.wildcardsAll
65
+
66
+ WILDCARDS_ALL
67
+ end
68
+
69
+ class FileSearch # :nodoc:
70
+
71
+ # @!visibility private
72
+ alias_method :searchRoot, :search_root
73
+ # @!visibility private
74
+ alias_method :pattern, :patterns
75
+ end
76
+
77
+ class Entry # :nodoc:
78
+
79
+ # @!visibility private
80
+ alias_method :uncDrive, :drive
81
+ # @!visibility private
82
+ alias_method :directoryPath, :directory_path
83
+ # @!visibility private
84
+ alias_method :directoryParts, :directory_parts
85
+ # @!visibility private
86
+ alias_method :file, :file_full_name
87
+ # @!visibility private
88
+ alias_method :shortFile, :file_short_name
89
+ # @!visibility private
90
+ alias_method :fileBaseName, :file_name_only
91
+ # @!visibility private
92
+ alias_method :fileName, :file_name_only
93
+ # @!visibility private
94
+ alias_method :fileExt, :file_extension
95
+ # @!visibility private
96
+ alias_method :searchDirectory, :search_directory
97
+ # @!visibility private
98
+ alias_method :searchRelativePath, :search_relative_path
99
+
100
+ # @!visibility private
101
+ alias_method :isDirectory, :directory?
102
+ # @!visibility private
103
+ alias_method :isFile, :file?
104
+ #alias_method :isLink, :link?
105
+ # @!visibility private
106
+ alias_method :isReadOnly, :readonly?
107
+ # @!visibility private
108
+ def isUNC
109
+
110
+ d = drive
111
+
112
+ d and d.size > 2
113
+ end
114
+
115
+ # @!visibility private
116
+ alias_method :creationTime, :modification_time
117
+ end
118
+ end # module Recls
119
+
120
+ # :startdoc:
115
121
  end
116
122
 
117
- # ############################## end of file ############################# #
118
123
 
124
+ # ############################## end of file ############################# #
119
125
 
data/lib/recls/recls.rb CHANGED
@@ -1,14 +1,14 @@
1
- # ######################################################################### #
2
- # File: recls/recls.rb
1
+ # ######################################################################## #
2
+ # File: recls/recls.rb
3
3
  #
4
- # Purpose: Main source file for recls library
4
+ # Purpose: Main source file for recls library
5
5
  #
6
- # Created: 19th July 2012
7
- # Updated: 6th April 2021
6
+ # Created: 19th July 2012
7
+ # Updated: 20th April 2024
8
8
  #
9
- # Author: Matthew Wilson
9
+ # Author: Matthew Wilson
10
10
  #
11
- # Copyright (c) 2019-2021, Matthew Wilson and Synesis Information Systems
11
+ # Copyright (c) 2019-2024, Matthew Wilson and Synesis Information Systems
12
12
  # Copyright (c) 2012-2019, Matthew Wilson and Synesis Software
13
13
  # All rights reserved.
14
14
  #
@@ -34,7 +34,7 @@
34
34
  # ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
35
35
  # POSSIBILITY OF SUCH DAMAGE.
36
36
  #
37
- # ######################################################################### #
37
+ # ######################################################################## #
38
38
 
39
39
 
40
40
  require 'recls/version'
@@ -64,29 +64,24 @@ require 'recls/ximpl/os'
64
64
  # - Recls::stat
65
65
  module Recls
66
66
 
67
- end # module Recls
68
-
69
- module Recls
67
+ # The string sequence used to separate names in paths, e.g. "/" on UNIX
68
+ PATH_NAME_SEPARATOR = Recls::Ximpl::OS::PATH_NAME_SEPARATOR
70
69
 
71
- # Represents the "all" wildcards string for the ambient operating
72
- # system
73
- WILDCARDS_ALL = Recls::Ximpl::OS::WILDCARDS_ALL
70
+ # The string sequence used to separate paths, e.g. ";" on Windows
71
+ PATH_SEPARATOR = Recls::Ximpl::OS::PATH_SEPARATOR
74
72
 
75
- # The string sequence used to separate names in paths, e.g. "/" on UNIX
76
- PATH_NAME_SEPARATOR = Recls::Ximpl::OS::PATH_NAME_SEPARATOR
73
+ # Represents the "all" wildcards string for the ambient operating system
74
+ WILDCARDS_ALL = Recls::Ximpl::OS::WILDCARDS_ALL
77
75
 
78
- # The string sequence used to separate paths, e.g. ":" on UNIX
79
- PATH_SEPARATOR = Recls::Ximpl::OS::PATH_SEPARATOR
76
+ # Indicates whether the operating system is a variant of Windows
77
+ def self.windows?
80
78
 
81
- # Indicates whether the operating system is a variant of Windows
82
- def self.windows?
83
-
84
- Recls::Ximpl::OS::OS_IS_WINDOWS
85
- end
79
+ Recls::Ximpl::OS::OS_IS_WINDOWS
80
+ end
86
81
  end # module Recls
87
82
 
88
83
  require 'recls/obsolete'
89
84
 
90
- # ############################## end of file ############################# #
91
85
 
86
+ # ############################## end of file ############################# #
92
87