recls-ruby 2.9.0 → 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.
@@ -0,0 +1,19 @@
1
+ #! /usr/bin/env ruby
2
+
3
+ $:.unshift File.join(File.dirname(__FILE__), '..', 'lib')
4
+
5
+ require 'recls'
6
+
7
+ puts "files under current directory:"
8
+ Recls.file_rsearch(nil, nil, Recls::FILES).each { |fe| puts "\t#{fe.search_relative_path}" }
9
+ puts
10
+
11
+ puts "directories under current directory:"
12
+ Recls.file_rsearch(nil, nil, Recls::DIRECTORIES | Recls::MARK_DIRECTORIES).each { |fe| puts "\t#{fe.search_relative_path}" }
13
+ puts
14
+
15
+ puts "files and directories under current directory:"
16
+ Recls.file_rsearch(nil, nil, Recls::DIRECTORIES | Recls::FILES | Recls::MARK_DIRECTORIES).each { |fe| puts "\t#{fe.search_relative_path}" }
17
+ puts
18
+
19
+
@@ -0,0 +1,39 @@
1
+ # recls.Ruby Example - **show_hidden_files**
2
+
3
+ ## Summary
4
+
5
+ TBC
6
+
7
+ ## Source
8
+
9
+ ```ruby
10
+ #! /usr/bin/env ruby
11
+
12
+ $:.unshift File.join(File.dirname(__FILE__), '..', 'lib')
13
+
14
+ require 'recls'
15
+
16
+ # To find only hidden files, need to:
17
+ #
18
+ # 1. Ensure that they are returned in search, by including Recls::SHOW_HIDDEN
19
+ # 2. Filter returned entries by hidden? attribute
20
+ Recls.file_rsearch('.', Recls::WILDCARDS_ALL, Recls::FILES | Recls::SHOW_HIDDEN).each do |fe|
21
+
22
+ puts fe.path if fe.hidden?
23
+ end
24
+ ```
25
+
26
+ ## Discussion
27
+
28
+ TBC
29
+
30
+ ## Example results
31
+
32
+ ```
33
+ /Users/matthewwilson/dev/freelibs/recls/100/recls.Ruby/trunk/.gitignore
34
+ /Users/matthewwilson/dev/freelibs/recls/100/recls.Ruby/trunk/.ruby-version
35
+ /Users/matthewwilson/dev/freelibs/recls/100/recls.Ruby/trunk/.ruby-version-exclusions
36
+ /Users/matthewwilson/dev/freelibs/recls/100/recls.Ruby/trunk/test/fixtures/hidden/.file-1
37
+ /Users/matthewwilson/dev/freelibs/recls/100/recls.Ruby/trunk/test/fixtures/hidden/.file-2
38
+ ```
39
+
@@ -1,3 +1,4 @@
1
+ #! /usr/bin/env ruby
1
2
 
2
3
  $:.unshift File.join(File.dirname(__FILE__), '..', 'lib')
3
4
 
@@ -7,9 +8,8 @@ require 'recls'
7
8
  #
8
9
  # 1. Ensure that they are returned in search, by including Recls::SHOW_HIDDEN
9
10
  # 2. Filter returned entries by hidden? attribute
10
- Recls::FileSearch.new('.', Recls::WILDCARDS_ALL, Recls::FILES | Recls::RECURSIVE | Recls::SHOW_HIDDEN).each do |fe|
11
+ Recls.file_rsearch('.', Recls::WILDCARDS_ALL, Recls::FILES | Recls::SHOW_HIDDEN).each do |fe|
11
12
 
12
13
  puts fe.path if fe.hidden?
13
-
14
14
  end
15
15
 
@@ -0,0 +1,35 @@
1
+ # recls.Ruby Example - **show_hidden_files**
2
+
3
+ ## Summary
4
+
5
+ TBC
6
+
7
+ ## Source
8
+
9
+ ```ruby
10
+ #! /usr/bin/env ruby
11
+
12
+ $:.unshift File.join(File.dirname(__FILE__), '..', 'lib')
13
+
14
+ require 'recls'
15
+
16
+ # To find only readonly files, need to:
17
+ #
18
+ # 1. Filter returned entries by readonly? attribute
19
+ Recls.file_rsearch('.', Recls::WILDCARDS_ALL, Recls::FILES).each do |fe|
20
+
21
+ puts fe.path if fe.readonly?
22
+ end
23
+ ```
24
+
25
+ ## Discussion
26
+
27
+ TBC
28
+
29
+ ## Example results
30
+
31
+ ```
32
+ /Users/matthewwilson/dev/freelibs/recls/100/recls.Ruby/trunk/test/fixtures/readonly/file-1
33
+ /Users/matthewwilson/dev/freelibs/recls/100/recls.Ruby/trunk/test/fixtures/readonly/file-2
34
+ ```
35
+
@@ -1,3 +1,4 @@
1
+ #! /usr/bin/env ruby
1
2
 
2
3
  $:.unshift File.join(File.dirname(__FILE__), '..', 'lib')
3
4
 
@@ -6,9 +7,8 @@ require 'recls'
6
7
  # To find only readonly files, need to:
7
8
  #
8
9
  # 1. Filter returned entries by readonly? attribute
9
- Recls::FileSearch.new('.', Recls::WILDCARDS_ALL, Recls::FILES | Recls::RECURSIVE).each do |fe|
10
+ Recls.file_rsearch('.', Recls::WILDCARDS_ALL, Recls::FILES).each do |fe|
10
11
 
11
12
  puts fe.path if fe.readonly?
12
-
13
13
  end
14
14
 
data/lib/recls/api.rb CHANGED
@@ -4,7 +4,7 @@
4
4
  # Purpose: Defines Recls module search functions
5
5
  #
6
6
  # Created: 9th June 2016
7
- # Updated: 21st March 2019
7
+ # Updated: 14th April 2019
8
8
  #
9
9
  # Author: Matthew Wilson
10
10
  #
@@ -39,11 +39,14 @@
39
39
  require 'recls/file_search'
40
40
  require 'recls/flags'
41
41
 
42
+ =begin
43
+ =end
44
+
45
+ class Object; end # :nodoc:
46
+
42
47
  module Recls
43
48
 
44
- # [DEPRECATED] Use +Recls.file_search()+
45
- #
46
- # @deprecated
49
+ # [DEPRECATED] Use Recls::file_search()
47
50
  def self.FileSearch(search_root, patterns, options = {})
48
51
 
49
52
  Recls::FileSearch.new(search_root, patterns, options)
@@ -55,26 +58,16 @@ module Recls
55
58
  # === Signature
56
59
  #
57
60
  # * *Parameters:*
58
- # - +search_root+:: (String, Recls::Entry) The root directory of
59
- # the search. May be +nil+, in which case the current directory
60
- # is assumed
61
- # - +patterns+:: (String, Array) The pattern(s) for which to
62
- # search. May be +nil+, in which case +Recls::WILDCARDS_ALL+ is
63
- # assumed
64
- # - +options+:: (Hash, Integer) Combination of flags (with
65
- # behaviour as described below for the +flags+ option), or an
66
- # options hash
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
67
64
  #
68
65
  # * *Options:*
69
- # - +flags+:: (Integer) Combination of flags - FILES,
70
- # DIRECTORIES, etc. If the value modulo TYPEMASK is 0,
71
- # then FILES is assumed. The value RECURSIVE is added by the
72
- # function, and so need not be added by the caller; it cannot be
73
- # removed
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
74
67
  #
75
68
  # === Return
76
- # An instance of +::Recls::FileSearch+
77
- #
69
+ # An instance of a class implementing ::Enumerable whose value type is
70
+ # Recls::Entry
78
71
  def self.file_rsearch(search_root, patterns, options = {})
79
72
 
80
73
  case options
@@ -104,29 +97,21 @@ module Recls
104
97
  # === Signature
105
98
  #
106
99
  # * *Parameters:*
107
- # - +search_root+:: (String, Recls::Entry) The root directory of
108
- # the search. May be +nil+, in which case the current directory
109
- # is assumed
110
- # - +patterns+:: (String, Array) The pattern(s) for which to
111
- # search. May be +nil+, in which case +Recls::WILDCARDS_ALL+ is
112
- # assumed
113
- # - +options+:: (Hash, Integer) Combination of flags (with
114
- # behaviour as described below for the +flags+ option), or an
115
- # options hash
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
116
103
  #
117
104
  # * *Options:*
118
- # - +flags+:: (Integer) Combination of flags - FILES,
119
- # DIRECTORIES, RECURSIVE, etc. If the value modulo TYPEMASK is 0,
120
- # then FILES is assumed
105
+ # - +flags+ (Integer) Combination of flags - FILES, DIRECTORIES, RECURSIVE, etc. If the value modulo TYPEMASK is 0, then FILES is assumed
121
106
  #
122
107
  # === Return
123
- # An instance of +::Recls::FileSearch+
124
- #
108
+ # An instance of a class implementing ::Enumerable whose value type is
109
+ # Recls::Entry
125
110
  def self.file_search(search_root, patterns, options = {})
126
111
 
127
112
  Recls::FileSearch.new(search_root, patterns, options)
128
113
  end
129
- end
114
+ end # module Recls
130
115
 
131
116
  # ############################## end of file ############################# #
132
117
 
@@ -4,7 +4,7 @@
4
4
  # Purpose: Definition of Recls::compare_paths() for Ruby 1.x
5
5
  #
6
6
  # Created: 17th February 2014
7
- # Updated: 21st March 2019
7
+ # Updated: 14th April 2019
8
8
  #
9
9
  # Author: Matthew Wilson
10
10
  #
@@ -38,6 +38,11 @@
38
38
 
39
39
  require 'recls/ximpl/util'
40
40
 
41
+ =begin
42
+ =end
43
+
44
+ class Object; end # :nodoc:
45
+
41
46
  module Recls
42
47
 
43
48
  # Combines paths
@@ -45,11 +50,10 @@ module Recls
45
50
  # === Signature
46
51
  #
47
52
  # * *Parameters:*
48
- # - +paths+:: ([ (::String, ::Recls::Entry( ]) Array of 1 or more path
49
- # elements to be combined
53
+ # - +paths+ ([ (::String, ::Recls::Entry) ]) Array of 1 or more path elements to be combined
50
54
  #
51
55
  # === Return
52
- # The combined path
56
+ # (String) The combined path
53
57
  def self.combine_paths(*paths)
54
58
 
55
59
  paths = paths.reject { |p| p.nil? }
@@ -4,7 +4,7 @@
4
4
  # Purpose: Definition of Recls::compare_paths() for Ruby 2+
5
5
  #
6
6
  # Created: 17th February 2014
7
- # Updated: 21st March 2019
7
+ # Updated: 14th April 2019
8
8
  #
9
9
  # Author: Matthew Wilson
10
10
  #
@@ -38,6 +38,11 @@
38
38
 
39
39
  require 'recls/ximpl/util'
40
40
 
41
+ =begin
42
+ =end
43
+
44
+ class Object; end # :nodoc:
45
+
41
46
  module Recls
42
47
 
43
48
  # Combines paths, optionally canonicalising them
@@ -45,22 +50,16 @@ module Recls
45
50
  # === Signature
46
51
  #
47
52
  # * *Parameters:*
48
- # - +paths+:: ([ (::String, ::Recls::Entry( ]) Array of 1 or more path
49
- # elements to be combined
50
- # - +options+:: (::Hash) Options that moderate the combination
53
+ # - +paths+ ([ (::String, ::Recls::Entry) ]) Array of 1 or more path elements to be combined
54
+ # - +options+ (::Hash) Options that moderate the combination
51
55
  #
52
56
  # * *Options:*
53
- # - +:canonicalise+:: (boolean) Causes the evaluated path to be
54
- # canonicalised - with +Recls.canonicalise_path+ - before it is
55
- # returned
56
- # - +:clean+:: (boolean) Causes the evaluated path to be cleaned
57
- # (i.e. sent to +cleanpath+) before it is returned. Ignored if
58
- # +:canonicalise+ is specified
59
- # - +:clean_path+:: (boolean) Equivalent to +:clean+, but deprecated
60
- # and may be removed in a future version
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
61
60
  #
62
61
  # === Return
63
- # The combined path
62
+ # (String) The combined path
64
63
  def self.combine_paths(*paths, **options)
65
64
 
66
65
  paths = paths.reject { |p| p.nil? }
data/lib/recls/entry.rb CHANGED
@@ -4,11 +4,12 @@
4
4
  # Purpose: Defines the Recls::Entry class for the recls.Ruby library.
5
5
  #
6
6
  # Created: 24th July 2012
7
- # Updated: 11th July 2016
7
+ # Updated: 25th May 2020
8
8
  #
9
9
  # Author: Matthew Wilson
10
10
  #
11
- # Copyright (c) 2012-2016, Matthew Wilson and Synesis Software
11
+ # Copyright (c) 2019-2020, Matthew Wilson and Synesis Information Systems
12
+ # Copyright (c) 2012-2019, Matthew Wilson and Synesis Software
12
13
  # All rights reserved.
13
14
  #
14
15
  # Redistribution and use in source and binary forms, with or without
@@ -41,11 +42,18 @@ require 'recls/ximpl/' + (Recls::Ximpl::OS::OS_IS_WINDOWS ? 'windows' : 'unix')
41
42
  require 'recls/ximpl/util'
42
43
  require 'recls/flags'
43
44
 
45
+ =begin
46
+ =end
47
+
48
+ class Object; end # :nodoc:
49
+
44
50
  module Recls
45
51
 
52
+ # A file-system entry
46
53
  class Entry
47
54
 
48
55
  private
56
+ # @!visibility private
49
57
  def self.get_compare_path_(path)
50
58
  return path.upcase if Recls::Ximpl::OS::OS_IS_WINDOWS
51
59
  path
@@ -90,6 +98,7 @@ module Recls
90
98
  @nlink = @file_stat.nlink if @file_stat
91
99
 
92
100
  if Recls::Ximpl::OS::OS_IS_WINDOWS && @file_stat
101
+
93
102
  @dev = @file_stat.by_handle_information.volume_id
94
103
  @ino = @file_stat.by_handle_information.file_index
95
104
  @nlink = @file_stat.by_handle_information.num_links
@@ -102,26 +111,43 @@ module Recls
102
111
  # ##########################
103
112
  # Name-related attributes
104
113
 
114
+ # (String) A normalised form of #path that can be used in comparisons
105
115
  attr_reader :compare_path
106
116
 
117
+ # (String) The full-path of the instance
107
118
  attr_reader :path
119
+ # (String) The (Windows) short-form of #path, or +nil+ if not on Windows
108
120
  attr_reader :short_path
121
+ # (String) The (Windows) drive. +nil+ if does not exist
109
122
  attr_reader :drive
123
+ # (String) The full path of the entry's directory (taking into account the
124
+ # #drive if on Windows)
110
125
  attr_reader :directory_path
111
126
  alias_method :dirname, :directory_path
127
+ # (String) The entry's directory (excluding the #drive if on Windows)
112
128
  attr_reader :directory
129
+ # ([String]) An array of directory parts, where each part ends in Recls::PATH_NAME_SEPARATOR
113
130
  attr_reader :directory_parts
131
+ # (String) The entry's file name (combination of #stem + #extension)
114
132
  attr_reader :file_full_name
133
+ # (String) The (Windows) short-form of #basename, or +nil+ if not on Windows
115
134
  attr_reader :file_short_name
116
135
  alias_method :basename, :file_full_name
136
+ # (String) The entry's file stem
117
137
  attr_reader :file_name_only
118
138
  alias_method :stem, :file_name_only
139
+ # (String) The entry's file extension
119
140
  attr_reader :file_extension
120
141
  alias_method :extension, :file_extension
142
+ # (String) The search directory if specified; +nil+ otherwise
121
143
  attr_reader :search_directory
144
+ # (String) The #path relative to #search_directory; +nil+ if no search directory specified
122
145
  attr_reader :search_relative_path
146
+ # (String) The #directory relative to #search_directory; +nil+ if no search directory specified
123
147
  attr_reader :search_relative_directory
148
+ # (String) The #directory_path relative to #search_directory; +nil+ if no search directory specified
124
149
  attr_reader :search_relative_directory_path
150
+ # ([String]) The #directory_parts relative to #search_directory; +nil+ if no search directory specified
125
151
  attr_reader :search_relative_directory_parts
126
152
 
127
153
  # ##########################
@@ -157,6 +183,7 @@ module Recls
157
183
 
158
184
  if Recls::Ximpl::OS::OS_IS_WINDOWS
159
185
 
186
+ # [WINDOWS-ONLY] Indicates whether the entry has the *system* bit
160
187
  def system?
161
188
 
162
189
  return false if @file_stat.nil?
@@ -164,6 +191,7 @@ module Recls
164
191
  @file_stat.system?
165
192
  end
166
193
 
194
+ # [WINDOWS-ONLY] Indicates whether the entry has the *archive* bit
167
195
  def archive?
168
196
 
169
197
  return false if @file_stat.nil?
@@ -171,6 +199,7 @@ module Recls
171
199
  @file_stat.archive?
172
200
  end
173
201
 
202
+ # [WINDOWS-ONLY] Indicates whether the entry is a device
174
203
  def device?
175
204
 
176
205
  return false if @file_stat.nil?
@@ -178,6 +207,7 @@ module Recls
178
207
  @file_stat.device?
179
208
  end
180
209
 
210
+ # [WINDOWS-ONLY] Indicates whether the entry is *normal*
181
211
  def normal?
182
212
 
183
213
  return false if @file_stat.nil?
@@ -185,6 +215,7 @@ module Recls
185
215
  @file_stat.normal?
186
216
  end
187
217
 
218
+ # [WINDOWS-ONLY] Indicates whether the entry has the *temporary* bit
188
219
  def temporary?
189
220
 
190
221
  return false if @file_stat.nil?
@@ -192,6 +223,7 @@ module Recls
192
223
  @file_stat.temporary?
193
224
  end
194
225
 
226
+ # [WINDOWS-ONLY] Indicates whether the entry has the *compressed* bit
195
227
  def compressed?
196
228
 
197
229
  return false if @file_stat.nil?
@@ -199,6 +231,7 @@ module Recls
199
231
  @file_stat.compressed?
200
232
  end
201
233
 
234
+ # [WINDOWS-ONLY] Indicates whether the entry has the *encrypted* bit
202
235
  def encrypted?
203
236
 
204
237
  return false if @file_stat.nil?
@@ -215,6 +248,8 @@ module Recls
215
248
  @file_stat.directory?
216
249
  end
217
250
 
251
+ alias_method :dir?, :directory?
252
+
218
253
  # indicates whether the given entry represents a file
219
254
  def file?
220
255
 
@@ -355,8 +390,8 @@ module Recls
355
390
 
356
391
  path
357
392
  end
358
- end
359
- end
393
+ end # class Entry
394
+ end # module Recls
360
395
 
361
396
  # ############################## end of file ############################# #
362
397