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.
data/lib/recls/stat.rb CHANGED
@@ -4,7 +4,7 @@
4
4
  # Purpose: Defines the Recls.stat() method for the recls.Ruby library.
5
5
  #
6
6
  # Created: 24th July 2012
7
- # Updated: 21st March 2019
7
+ # Updated: 14th March 2019
8
8
  #
9
9
  # Author: Matthew Wilson
10
10
  #
@@ -39,10 +39,27 @@
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
- # Performs a +stat()+ but returns +nil+ if an obtained entry is not a
45
- # directory
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
46
63
  def self.directory?(path, *args)
47
64
 
48
65
  fe = self.stat(path, *args)
@@ -55,8 +72,20 @@ module Recls
55
72
  fe
56
73
  end
57
74
 
58
- # Performs a +stat()+ but returns +nil+ if an obtained entry is not a
59
- # file
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
60
89
  def self.file?(path, *args)
61
90
 
62
91
  fe = self.stat(path, *args)
@@ -69,13 +98,31 @@ module Recls
69
98
  fe
70
99
  end
71
100
 
72
- # USAGE:
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
106
+ #
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
73
113
  #
74
- # - stat(path)
75
- # - stat(path, flags)
76
- # - stat(path, search_root)
77
- # - stat(path, search_root, flags)
78
- # - stat(path, flags, search_root)
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
79
126
  def self.stat(path, *args)
80
127
 
81
128
  flags = 0
@@ -86,50 +133,46 @@ module Recls
86
133
 
87
134
  case args.size
88
135
  when 0
136
+
89
137
  ;
90
138
  when 1
139
+
91
140
  case args[0]
92
141
  when ::Integer
142
+
93
143
  flags = args[0]
94
144
  when ::String
145
+
95
146
  search_root = args[0]
96
147
  else
148
+
97
149
  message = "argument '#{args[0]}' (#{args[0].class}) not valid"
98
150
  end
99
151
  when 2
152
+
100
153
  if false
101
154
  elsif ::Integer === args[0] && ::String === args[1]
155
+
102
156
  flags = args[0]
103
157
  search_root = args[1]
104
158
  elsif ::String === args[0] && ::Integer === args[1]
159
+
105
160
  search_root = args[0]
106
161
  flags = args[1]
107
162
  else
163
+
108
164
  message = "invalid combination of arguments"
109
165
  end
110
166
  else
167
+
111
168
  message = "too many arguments"
112
169
  end
113
170
 
114
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
115
172
 
116
- begin
117
-
118
- Recls::Entry.new(path, Recls::Ximpl::FileStat.stat(path), search_root, flags)
119
- rescue Errno::ENOENT => x
120
-
121
- x = x # suppress warning
122
-
123
- if 0 != (flags & Recls::DETAILS_LATER)
124
-
125
- Recls::Entry.new(path, nil, search_root, flags)
126
- else
127
-
128
- nil
129
- end
130
- end
131
- end
132
- end
173
+ Recls::Ximpl.stat_prep(path, search_root, flags)
174
+ end
175
+ end # module Recls
133
176
 
134
177
  # ############################## end of file ############################# #
135
178
 
data/lib/recls/util.rb CHANGED
@@ -4,7 +4,7 @@
4
4
  # Purpose: Utility module functions for recls library
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
  #
@@ -36,33 +36,64 @@
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
61
  return path.path if 'Recls::Entry' === path.class.to_s
48
62
 
49
- return Recls::Ximpl.absolute_path path
63
+ Recls::Ximpl.absolute_path path
50
64
  end
51
65
 
52
66
  # Canonicalises the given path, by removing dots ('.' and '..')
53
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
54
76
  def self.canonicalise_path(path)
55
77
 
56
78
  path = path.path if 'Recls::Entry' === path.class.to_s
57
79
 
58
- return Recls::Ximpl.canonicalise_path path
80
+ Recls::Ximpl.canonicalise_path path
59
81
  end
60
82
 
61
83
  # Derives a given path relative to an origin, unless the path is
62
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
63
94
  def self.derive_relative_path(origin, path)
64
95
 
65
- return Recls::Ximpl.derive_relative_path origin, path
96
+ Recls::Ximpl.derive_relative_path origin, path
66
97
  end
67
98
  end # module Recls
68
99
 
@@ -74,6 +105,44 @@ else
74
105
  require 'recls/combine_paths_1'
75
106
  end
76
107
 
108
+ module Recls
109
+
110
+ # Indicates whether the given path exists, obtaining a Recls::Entry
111
+ # instance if so
112
+ #
113
+ # === Signature
114
+ #
115
+ # * *Parameters:*
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
130
+ #
131
+ # * *Parameters:*
132
+ # - +path+ (String, Recls::Entry) The path
133
+ #
134
+ # === Return
135
+ # (boolean) +true+ if +path+ is absolute; +false+ otherwise
136
+ def self.absolute_path?(path)
137
+
138
+ return nil if path.nil?
139
+
140
+ return true if 'Recls::Entry' === path.class.to_s
141
+
142
+ Recls::Ximpl.absolute_path? path
143
+ end
144
+ end # module Recls
145
+
77
146
  # ############################## end of file ############################# #
78
147
 
79
148
 
data/lib/recls/version.rb CHANGED
@@ -4,10 +4,11 @@
4
4
  # Purpose: Version for recls library
5
5
  #
6
6
  # Created: 14th February 2014
7
- # Updated: 21st March 2019
7
+ # Updated: 6th April 2021
8
8
  #
9
9
  # Author: Matthew Wilson
10
10
  #
11
+ # Copyright (c) 2019-2020, Matthew Wilson and Synesis Information Systems
11
12
  # Copyright (c) 2012-2019, Matthew Wilson and Synesis Software
12
13
  # All rights reserved.
13
14
  #
@@ -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.9.0'
48
+ VERSION = '2.12.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,16 @@
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: 6th April 2021
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) 2019-2021, Matthew Wilson and Synesis Information Systems
13
+ # Copyright (c) 2012-2019, Matthew Wilson and Synesis Software
13
14
  # All rights reserved.
14
15
  #
15
16
  # Redistribution and use in source and binary forms, with or without
@@ -37,21 +38,31 @@
37
38
  # ######################################################################### #
38
39
 
39
40
 
40
- module Recls
41
+ =begin
42
+ =end
41
43
 
42
- module Ximpl
44
+ module Recls # :nodoc:
43
45
 
44
- module OS
46
+ # :stopdoc:
45
47
 
46
- OS_IS_WINDOWS = (RUBY_PLATFORM =~ /(mswin|mingw|bccwin|wince)/i) ? true : false
48
+ module Ximpl # :nodoc: all
47
49
 
50
+ module OS # :nodoc: all
51
+
52
+ # @!visibility private
53
+ OS_IS_WINDOWS = (RUBY_PLATFORM =~ /(bccwin|cygwin|mingw|mswin|wince)/i) ? true : false
54
+
55
+ # @!visibility private
48
56
  PATH_NAME_SEPARATOR = OS_IS_WINDOWS ? '\\' : '/'
49
57
 
58
+ # @!visibility private
50
59
  PATH_SEPARATOR = OS_IS_WINDOWS ? ';' : ':'
51
60
 
61
+ # @!visibility private
52
62
  WILDCARDS_ALL = OS_IS_WINDOWS ? '*' : '*'
53
63
 
54
- def OS.get_number_of_dots_dir_(p)
64
+ # @!visibility private
65
+ def OS.get_number_of_dots_dir_(p) # :nodoc:
55
66
 
56
67
  if p
57
68
  if ?. == p[0]
@@ -69,7 +80,8 @@ module Recls
69
80
  return 0
70
81
  end
71
82
 
72
- def OS.is_root_dir_(p)
83
+ # @!visibility private
84
+ def OS.is_root_dir_(p) # :nodoc:
73
85
 
74
86
  return nil if not p
75
87
  return true if '/' == p
@@ -77,9 +89,12 @@ module Recls
77
89
 
78
90
  return false
79
91
  end
80
- end
81
- end
82
- end
92
+ end # module OS
93
+ end # module Ximpl
94
+
95
+ # :startdoc:
96
+
97
+ end # module Recls
83
98
 
84
99
  # ############################## end of file ############################# #
85
100
 
@@ -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