recls-ruby 2.8.2 → 2.11.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 (41) hide show
  1. checksums.yaml +4 -4
  2. data/README.md +57 -10
  3. data/examples/find_files_and_directories.md +77 -0
  4. data/examples/find_files_and_directories.rb +19 -0
  5. data/examples/find_files_and_directories.recursive.md +304 -0
  6. data/examples/find_files_and_directories.recursive.rb +19 -0
  7. data/examples/show_hidden_files.md +39 -0
  8. data/examples/show_hidden_files.rb +2 -2
  9. data/examples/show_readonly_files.md +35 -0
  10. data/examples/show_readonly_files.rb +2 -2
  11. data/lib/recls.rb +2 -0
  12. data/lib/recls/api.rb +70 -3
  13. data/lib/recls/combine_paths_1.rb +70 -0
  14. data/lib/recls/combine_paths_2plus.rb +76 -0
  15. data/lib/recls/entry.rb +40 -4
  16. data/lib/recls/file_search.rb +48 -14
  17. data/lib/recls/flags.rb +21 -4
  18. data/lib/recls/foreach.rb +45 -6
  19. data/lib/recls/obsolete.rb +119 -0
  20. data/lib/recls/recls.rb +27 -56
  21. data/lib/recls/stat.rb +96 -24
  22. data/lib/recls/util.rb +74 -23
  23. data/lib/recls/version.rb +10 -4
  24. data/lib/recls/ximpl/os.rb +29 -15
  25. data/lib/recls/ximpl/unix.rb +29 -16
  26. data/lib/recls/ximpl/util.rb +141 -39
  27. data/lib/recls/ximpl/windows.rb +56 -25
  28. data/test/fixtures/readonly/file-1 +0 -0
  29. data/test/fixtures/readonly/file-2 +0 -0
  30. data/test/scratch/test_display_parts.rb +9 -9
  31. data/test/scratch/test_entry.rb +11 -9
  32. data/test/scratch/test_files_and_directories.rb +17 -14
  33. data/test/scratch/test_foreach.rb +0 -3
  34. data/test/scratch/test_module_function.rb +10 -10
  35. data/test/scratch/test_pattern_arrays.rb +32 -0
  36. data/test/scratch/test_show_dev_and_ino.rb +1 -1
  37. data/test/scratch/test_show_hidden.rb +3 -3
  38. data/test/unit/tc_recls_util.rb +6 -0
  39. data/test/unit/tc_recls_ximpl_util.rb +156 -101
  40. data/test/unit/ts_all.rb +11 -9
  41. metadata +36 -11
@@ -4,11 +4,11 @@
4
4
  # Purpose: Defines the Recls.stat() method for the recls.Ruby library.
5
5
  #
6
6
  # Created: 24th July 2012
7
- # Updated: 22nd June 2017
7
+ # Updated: 14th March 2019
8
8
  #
9
9
  # Author: Matthew Wilson
10
10
  #
11
- # Copyright (c) 2012-2017, Matthew Wilson and Synesis Software
11
+ # Copyright (c) 2012-2019, Matthew Wilson and Synesis Software
12
12
  # All rights reserved.
13
13
  #
14
14
  # Redistribution and use in source and binary forms, with or without
@@ -39,15 +39,90 @@
39
39
  require 'recls/entry'
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
- # USAGE:
49
+ # Equivalent to a Recls::stat() but only returns (a non-+nil+ value) if the
50
+ # path exists _and_ represents a directory
51
+ #
52
+ # This has two advantages over +File.directory?+: it obtains a
53
+ # Recls::Entry in the case where the path represents a directory; and
54
+ # it does '~' interpretation
55
+ #
56
+ # === Signature
57
+ #
58
+ # * *Parameters:*
59
+ # - +path+ (String, Recls::Entry) The path
60
+ #
61
+ # === Return
62
+ # (Recls::Entry, nil) The entry if +path+ exists and is a directory; +nil+ otherwise
63
+ def self.directory?(path, *args)
64
+
65
+ fe = self.stat(path, *args)
66
+
67
+ if fe
68
+
69
+ return nil unless fe.directory?
70
+ end
71
+
72
+ fe
73
+ end
74
+
75
+ # Equivalent to a Recls::stat() but only returns (a non-+nil+ value) if the
76
+ # path exists _and_ represents a file
77
+ #
78
+ # This has two advantages over +File.file?+: it obtains a
79
+ # Recls::Entry in the case where the path represents a file; and
80
+ # it does '~' interpretation
81
+ #
82
+ # === Signature
83
+ #
84
+ # * *Parameters:*
85
+ # - +path+ (String, Recls::Entry) The path
86
+ #
87
+ # === Return
88
+ # (Recls::Entry, nil) The entry if +path+ exists and is a file; +nil+ otherwise
89
+ def self.file?(path, *args)
90
+
91
+ fe = self.stat(path, *args)
92
+
93
+ if fe
94
+
95
+ return nil unless fe.file?
96
+ end
97
+
98
+ fe
99
+ end
100
+
101
+ # Obtains a single Recls::Entry instance from a path, according to the
102
+ # given arguments, which can be any combination of search-root and
103
+ # flags, as discussed below
104
+ #
105
+ # === Signature
45
106
  #
46
- # - stat(path)
47
- # - stat(path, flags)
48
- # - stat(path, search_root)
49
- # - stat(path, search_root, flags)
50
- # - stat(path, flags, search_root)
107
+ # * *Parameters:*
108
+ # - +path+ (String) A path to evaluate. May not be +nil+
109
+ # - +search_root+ (String, Recls::Entry) A directory from which the returned Entry instance's search-relative attributes are evaluated
110
+ # - +flags+ (Integer) A bit-combined set of flags (such as Recls::DIRECTORIES, Recls::FILES, Recls::RECURSIVE, Recls::DETAILS_LATER, and so on)
111
+ #
112
+ # ==== Parameter Ordering
113
+ #
114
+ # The parameters may be expressed in any of the following permutations:
115
+ # - +path+
116
+ # - +path+, +flags+
117
+ # - +path+, +search_root+
118
+ # - +path+, +flags+, +search_root+
119
+ # - +path+, +search_root+, +flags+
120
+ #
121
+ # === Return
122
+ # (Recls::Entry) An entry representing the path on the file-system, or
123
+ # +nil+ if the path does not refer to an existing entity. If the
124
+ # Recls::DETAILS_LATER flag is included, then an entry is returned
125
+ # regardless of its existence
51
126
  def self.stat(path, *args)
52
127
 
53
128
  flags = 0
@@ -58,50 +133,47 @@ module Recls
58
133
 
59
134
  case args.size
60
135
  when 0
136
+
61
137
  ;
62
138
  when 1
139
+
63
140
  case args[0]
64
141
  when ::Integer
142
+
65
143
  flags = args[0]
66
144
  when ::String
145
+
67
146
  search_root = args[0]
68
147
  else
148
+
69
149
  message = "argument '#{args[0]}' (#{args[0].class}) not valid"
70
150
  end
71
151
  when 2
152
+
72
153
  if false
73
154
  elsif ::Integer === args[0] && ::String === args[1]
155
+
74
156
  flags = args[0]
75
157
  search_root = args[1]
76
158
  elsif ::String === args[0] && ::Integer === args[1]
159
+
77
160
  search_root = args[0]
78
161
  flags = args[1]
79
162
  else
163
+
80
164
  message = "invalid combination of arguments"
81
165
  end
82
166
  else
167
+
83
168
  message = "too many arguments"
84
169
  end
85
170
 
86
171
  raise ArgumentError, "#{message}: Recls.stat() takes one (path), two (path+flags or path+search_root), or three (path+search_root+flags) arguments" if message
87
172
 
88
- begin
89
-
90
- Recls::Entry.new(path, Recls::Ximpl::FileStat.stat(path), search_root, flags)
91
- rescue Errno::ENOENT => x
92
-
93
- x = x # suppress warning
94
-
95
- if 0 != (flags & Recls::DETAILS_LATER)
96
-
97
- Recls::Entry.new(path, nil, search_root, flags)
98
- else
99
-
100
- nil
101
- end
102
- end
173
+ Recls::Ximpl.stat_prep(path, search_root, flags)
103
174
  end
104
- end
175
+ end # module Recls
105
176
 
106
177
  # ############################## end of file ############################# #
107
178
 
179
+
@@ -4,11 +4,11 @@
4
4
  # Purpose: Utility module functions for recls library
5
5
  #
6
6
  # Created: 17th February 2014
7
- # Updated: 25th January 2018
7
+ # Updated: 14th April 2019
8
8
  #
9
9
  # Author: Matthew Wilson
10
10
  #
11
- # Copyright (c) 2012-2018, Matthew Wilson and Synesis Software
11
+ # Copyright (c) 2012-2019, Matthew Wilson and Synesis Software
12
12
  # All rights reserved.
13
13
  #
14
14
  # Redistribution and use in source and binary forms, with or without
@@ -36,61 +36,112 @@
36
36
  # ######################################################################### #
37
37
 
38
38
 
39
+ require 'recls/stat'
39
40
  require 'recls/ximpl/util'
40
41
  require 'recls/ximpl/os'
41
42
 
43
+ =begin
44
+ =end
45
+
46
+ class Object; end # :nodoc:
47
+
42
48
  module Recls
43
49
 
44
50
  # Obtains the absolute form of the given path
51
+ #
52
+ # === Signature
53
+ #
54
+ # * *Parameters:*
55
+ # - +path+ (String, Recls::Entry) The path
56
+ #
57
+ # === Return
58
+ # (String) The absolute form of the path
45
59
  def self.absolute_path(path)
46
60
 
47
- return Recls::Ximpl.absolute_path path
61
+ return path.path if 'Recls::Entry' === path.class.to_s
62
+
63
+ Recls::Ximpl.absolute_path path
48
64
  end
49
65
 
50
66
  # Canonicalises the given path, by removing dots ('.' and '..')
51
67
  # directories
68
+ #
69
+ # === Signature
70
+ #
71
+ # * *Parameters:*
72
+ # - +path+ (String, Recls::Entry) The path
73
+ #
74
+ # === Return
75
+ # (String) The canonical form of the path
52
76
  def self.canonicalise_path(path)
53
77
 
54
- return Recls::Ximpl.canonicalise_path path
78
+ path = path.path if 'Recls::Entry' === path.class.to_s
79
+
80
+ Recls::Ximpl.canonicalise_path path
55
81
  end
56
82
 
57
83
  # Derives a given path relative to an origin, unless the path is
58
84
  # absolute
85
+ #
86
+ # === Signature
87
+ #
88
+ # * *Parameters:*
89
+ # - +origin+ (String, Recls::Entry) The path against which +path+ will be evaluated
90
+ # - +path+ (String, Recls::Entry) The path to evaluate
91
+ #
92
+ # === Return
93
+ # (String) The relative form of the path
59
94
  def self.derive_relative_path(origin, path)
60
95
 
61
- return Recls::Ximpl.derive_relative_path origin, path
96
+ Recls::Ximpl.derive_relative_path origin, path
62
97
  end
98
+ end # module Recls
99
+
100
+ if RUBY_VERSION >= '2'
101
+
102
+ require 'recls/combine_paths_2plus'
103
+ else
104
+
105
+ require 'recls/combine_paths_1'
106
+ end
107
+
108
+ module Recls
63
109
 
64
- # Combines paths, optionally canonicalising them
110
+ # Indicates whether the given path exists, obtaining a Recls::Entry
111
+ # instance if so
65
112
  #
66
113
  # === Signature
67
114
  #
68
115
  # * *Parameters:*
69
- # - +paths+:: [ [ ::String, ::Recls::Entry ] ] Array of 1 or more path
70
- # elements to be combined
71
- # - +options+:: [::Hash] Options that moderate the combination
116
+ # - +path+ (String, Recls::Entry) The path
117
+ #
118
+ # === Return
119
+ # (Recls::Entry, nil) The entry if +path+ exists; +nil+ otherwise
120
+ def self.exist?(path)
121
+
122
+ return nil if path.nil?
123
+
124
+ Recls.stat(path)
125
+ end
126
+
127
+ # Indicates whether the given path is absolute
128
+ #
129
+ # === Signature
72
130
  #
73
131
  # * *Parameters:*
74
- # - +:canonicalise+:: [boolean] Causes the evaluated path to be
75
- # canonicalised - with +Recls.canonicalise_path+ - before it is
76
- # returned
77
- # - +:clean+:: [boolean] Causes the evaluated path to be cleaned
78
- # (i.e. sent to +cleanpath+) before it is returned. Ignored if
79
- # +:canonicalise+ is specified
80
- # - +:clean_path+:: [boolean] Equivalent to +:clean+, but deprecated
81
- # and may be removed in a future version
132
+ # - +path+ (String, Recls::Entry) The path
82
133
  #
83
134
  # === Return
84
- # The combined path
85
- def self.combine_paths(*paths, **options)
135
+ # (boolean) +true+ if +path+ is absolute; +false+ otherwise
136
+ def self.absolute_path?(path)
86
137
 
87
- paths = paths.reject { |p| p.nil? }
138
+ return nil if path.nil?
88
139
 
89
- raise ArgumentError, 'must specify one or more path elements' if paths.empty?
140
+ return true if 'Recls::Entry' === path.class.to_s
90
141
 
91
- return Recls::Ximpl.combine_paths paths, options
142
+ Recls::Ximpl.absolute_path? path
92
143
  end
93
- end
144
+ end # module Recls
94
145
 
95
146
  # ############################## end of file ############################# #
96
147
 
@@ -4,11 +4,12 @@
4
4
  # Purpose: Version for recls library
5
5
  #
6
6
  # Created: 14th February 2014
7
- # Updated: 5th February 2018
7
+ # Updated: 25th May 2020
8
8
  #
9
9
  # Author: Matthew Wilson
10
10
  #
11
- # Copyright (c) 2012-2018, 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
@@ -36,10 +37,15 @@
36
37
  # ######################################################################### #
37
38
 
38
39
 
40
+ =begin
41
+ =end
42
+
43
+ class Object; end # :nodoc:
44
+
39
45
  module Recls
40
46
 
41
47
  # Current version of the recls.Ruby library
42
- VERSION = '2.8.2'
48
+ VERSION = '2.11.0'
43
49
 
44
50
  private
45
51
  VERSION_PARTS_ = VERSION.split(/[.]/).collect { |n| n.to_i } # :nodoc:
@@ -47,7 +53,7 @@ module Recls
47
53
  VERSION_MAJOR = VERSION_PARTS_[0] # :nodoc:
48
54
  VERSION_MINOR = VERSION_PARTS_[1] # :nodoc:
49
55
  VERSION_REVISION = VERSION_PARTS_[2] # :nodoc:
50
- end
56
+ end # module Recls
51
57
 
52
58
  # ############################## end of file ############################# #
53
59
 
@@ -1,15 +1,15 @@
1
1
  # ######################################################################### #
2
- # File: recls/ximpl/os.rb
2
+ # File: recls/ximpl/os.rb
3
3
  #
4
- # Purpose: Operating system internal implementation constructs for the
5
- # recls library.
4
+ # Purpose: Operating system internal implementation constructs for the
5
+ # recls library.
6
6
  #
7
- # Created: 16th February 2014
8
- # Updated: 27th August 2015
7
+ # Created: 16th February 2014
8
+ # Updated: 14th April 2019
9
9
  #
10
- # Author: Matthew Wilson
10
+ # Author: Matthew Wilson
11
11
  #
12
- # Copyright (c) 2012-2015, Matthew Wilson and Synesis Software
12
+ # Copyright (c) 2012-2019, Matthew Wilson and Synesis Software
13
13
  # All rights reserved.
14
14
  #
15
15
  # Redistribution and use in source and binary forms, with or without
@@ -37,21 +37,31 @@
37
37
  # ######################################################################### #
38
38
 
39
39
 
40
- module Recls
40
+ =begin
41
+ =end
41
42
 
42
- module Ximpl
43
+ module Recls # :nodoc:
43
44
 
44
- module OS
45
+ # :stopdoc:
45
46
 
47
+ module Ximpl # :nodoc: all
48
+
49
+ module OS # :nodoc: all
50
+
51
+ # @!visibility private
46
52
  OS_IS_WINDOWS = (RUBY_PLATFORM =~ /(mswin|mingw|bccwin|wince)/i) ? true : false
47
53
 
54
+ # @!visibility private
48
55
  PATH_NAME_SEPARATOR = OS_IS_WINDOWS ? '\\' : '/'
49
56
 
57
+ # @!visibility private
50
58
  PATH_SEPARATOR = OS_IS_WINDOWS ? ';' : ':'
51
59
 
60
+ # @!visibility private
52
61
  WILDCARDS_ALL = OS_IS_WINDOWS ? '*' : '*'
53
62
 
54
- def OS.get_number_of_dots_dir_(p)
63
+ # @!visibility private
64
+ def OS.get_number_of_dots_dir_(p) # :nodoc:
55
65
 
56
66
  if p
57
67
  if ?. == p[0]
@@ -69,7 +79,8 @@ module Recls
69
79
  return 0
70
80
  end
71
81
 
72
- def OS.is_root_dir_(p)
82
+ # @!visibility private
83
+ def OS.is_root_dir_(p) # :nodoc:
73
84
 
74
85
  return nil if not p
75
86
  return true if '/' == p
@@ -77,9 +88,12 @@ module Recls
77
88
 
78
89
  return false
79
90
  end
80
- end
81
- end
82
- end
91
+ end # module OS
92
+ end # module Ximpl
93
+
94
+ # :startdoc:
95
+
96
+ end # module Recls
83
97
 
84
98
  # ############################## end of file ############################# #
85
99
 
@@ -1,14 +1,14 @@
1
1
  # ######################################################################### #
2
- # File: recls/ximpl/unix.rb
2
+ # File: recls/ximpl/unix.rb
3
3
  #
4
- # Purpose: UNIX-specific constructs for the recls library.
4
+ # Purpose: UNIX-specific constructs for the recls library.
5
5
  #
6
- # Created: 19th February 2014
7
- # Updated: 27th August 2015
6
+ # Created: 19th February 2014
7
+ # Updated: 14th April 2019
8
8
  #
9
- # Author: Matthew Wilson
9
+ # Author: Matthew Wilson
10
10
  #
11
- # Copyright (c) 2012-2015, Matthew Wilson and Synesis Software
11
+ # Copyright (c) 2012-2019, Matthew Wilson and Synesis Software
12
12
  # All rights reserved.
13
13
  #
14
14
  # Redistribution and use in source and binary forms, with or without
@@ -38,14 +38,21 @@
38
38
 
39
39
  require 'recls/ximpl/util'
40
40
 
41
- module Recls
41
+ =begin
42
+ =end
42
43
 
43
- module Ximpl
44
+ module Recls # :nodoc:
44
45
 
45
- class FileStat < File::Stat
46
+ # :stopdoc:
47
+
48
+ module Ximpl # :nodoc: all
49
+
50
+ # @!visibility private
51
+ class FileStat < File::Stat # :nodoc:
46
52
 
47
53
  private
48
- def initialize(path)
54
+ # @!visibility private
55
+ def initialize(path) # :nodoc:
49
56
 
50
57
  @path = path
51
58
 
@@ -53,9 +60,11 @@ module Recls
53
60
  end
54
61
 
55
62
  public
56
- attr_reader :path
63
+ # @!visibility private
64
+ attr_reader :path # :nodoc:
57
65
 
58
- def hidden?
66
+ # @!visibility private
67
+ def hidden? # :nodoc:
59
68
 
60
69
  basename = File.basename @path
61
70
 
@@ -68,14 +77,18 @@ module Recls
68
77
  end
69
78
 
70
79
  public
71
- def FileStat.stat(path)
80
+ # @!visibility private
81
+ def FileStat.stat(path) # :nodoc:
72
82
 
73
83
  Recls::Ximpl::FileStat.new(path)
74
84
 
75
85
  end
76
- end
77
- end
78
- end
86
+ end # class FileStat
87
+ end # module Ximpl
88
+
89
+ # :startdoc:
90
+
91
+ end # module Recls
79
92
 
80
93
  # ############################## end of file ############################# #
81
94