gubbins-fs 0.1.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.
- checksums.yaml +7 -0
- data/CHANGELOG.md +3 -0
- data/LICENSE +289 -0
- data/README.md +128 -0
- data/lib/fs/atomic_write.rb +121 -0
- data/lib/fs/concerns/argument_validation.rb +140 -0
- data/lib/fs/concerns/file_dsl_methods.rb +471 -0
- data/lib/fs/concerns/required_arguments.rb +141 -0
- data/lib/fs/directory/accessibility_check.rb +89 -0
- data/lib/fs/directory.rb +497 -0
- data/lib/fs/errors.rb +491 -0
- data/lib/fs/file.rb +1524 -0
- data/lib/fs/file_variant_builder.rb +269 -0
- data/lib/fs/file_variant_proxy.rb +253 -0
- data/lib/fs/files/csv.rb +26 -0
- data/lib/fs/files/gif.rb +10 -0
- data/lib/fs/files/image.rb +390 -0
- data/lib/fs/files/jpg.rb +36 -0
- data/lib/fs/files/json.rb +24 -0
- data/lib/fs/files/pdf.rb +231 -0
- data/lib/fs/files/pdf_collection.rb +64 -0
- data/lib/fs/files/png.rb +10 -0
- data/lib/fs/files/text.rb +13 -0
- data/lib/fs/files/tiff.rb +24 -0
- data/lib/fs/files/zip.rb +123 -0
- data/lib/fs/lockfile_sweeper.rb +70 -0
- data/lib/fs/tempfile_sweeper.rb +79 -0
- data/lib/fs/testing/mock/fs/configurator.rb +223 -0
- data/lib/fs/testing/mock/fs/dirs/directory.rb +41 -0
- data/lib/fs/testing/mock/fs/dsl.rb +81 -0
- data/lib/fs/testing/mock/fs/file.rb +60 -0
- data/lib/fs/testing/mock/fs/file_klass_mock.rb +350 -0
- data/lib/fs/testing/mock/fs/files/jpg.rb +14 -0
- data/lib/fs/testing/mock/fs/files/pdf.rb +19 -0
- data/lib/fs/testing/mock/fs/files/png.rb +12 -0
- data/lib/fs/testing/mock/fs/files/tiff.rb +12 -0
- data/lib/fs/testing/mock/fs/files/zip.rb +23 -0
- data/lib/fs/testing.rb +17 -0
- data/lib/fs/version.rb +3 -0
- data/lib/fs.rb +26 -0
- data/lib/gubbins/fs.rb +4 -0
- metadata +124 -0
data/lib/fs/directory.rb
ADDED
|
@@ -0,0 +1,497 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require "pathname"
|
|
4
|
+
require "fileutils"
|
|
5
|
+
require "active_support/concern"
|
|
6
|
+
require "active_support/core_ext/class/attribute"
|
|
7
|
+
require "active_support/core_ext/module/delegation"
|
|
8
|
+
require "active_support/core_ext/object/blank"
|
|
9
|
+
require "shell/zip"
|
|
10
|
+
require_relative "errors"
|
|
11
|
+
require_relative "concerns/argument_validation"
|
|
12
|
+
require_relative "concerns/required_arguments"
|
|
13
|
+
require_relative "directory/accessibility_check"
|
|
14
|
+
|
|
15
|
+
module Fs
|
|
16
|
+
class Directory
|
|
17
|
+
include Fs::Concerns::RequiredArguments
|
|
18
|
+
include Fs::Concerns::ArgumentValidation
|
|
19
|
+
|
|
20
|
+
WHEN_MISSING_MODES = %i[create raise ignore].freeze
|
|
21
|
+
|
|
22
|
+
attr_reader :parent
|
|
23
|
+
attr_reader :dynamic_base_path
|
|
24
|
+
|
|
25
|
+
delegate :exist?, :directory?, :glob, :symlink?, :children, :rmdir, :rmtree, :join,
|
|
26
|
+
to: :path
|
|
27
|
+
|
|
28
|
+
class << self
|
|
29
|
+
# @return [Class] the class of the parent {Directory}, if given
|
|
30
|
+
attr_reader :parent_klass
|
|
31
|
+
# @return [Proc] a Proc responsible for assembling the arguments
|
|
32
|
+
# to the parent {Directory}, if there is one and if it requires
|
|
33
|
+
# arguments. Is executed in the instance scope of the current
|
|
34
|
+
# {Directory}.
|
|
35
|
+
attr_reader :parent_klass_argument_proc
|
|
36
|
+
# @return [Symbol] setting for how to handle missing base paths
|
|
37
|
+
attr_reader :on_base_path_missing
|
|
38
|
+
# @return [Symbol] setting for how to handle missing instance paths
|
|
39
|
+
attr_reader :on_instance_path_missing
|
|
40
|
+
# @return [Class, nil] an anonymous subclass of `self` used to
|
|
41
|
+
# locate this directory at a legacy location, if configured
|
|
42
|
+
attr_reader :legacy_klass
|
|
43
|
+
# @return [Boolean] whether instantiating this Directory should
|
|
44
|
+
# itself relocate content found via `legacy_klass` - see {.legacy}
|
|
45
|
+
attr_reader :legacy_migrate
|
|
46
|
+
|
|
47
|
+
# This is a hook Ruby calls whenever a subclass is created. We use
|
|
48
|
+
# the opportunity to copy our class instance variables over to the
|
|
49
|
+
# new class, mirroring `Fs::Concerns::FileDslMethods#inherited`.
|
|
50
|
+
#
|
|
51
|
+
# Without this, a concrete subclass's `base_path`/`requires_arguments`/
|
|
52
|
+
# etc. would not be visible on a further subclass of it - which
|
|
53
|
+
# `legacy` (below) relies on: its block builds an anonymous
|
|
54
|
+
# subclass of the current, already-configured class.
|
|
55
|
+
#
|
|
56
|
+
# @return [void]
|
|
57
|
+
def inherited(subclass)
|
|
58
|
+
subclass.instance_variable_set(:@raw_base_path, @raw_base_path)
|
|
59
|
+
subclass.instance_variable_set(:@parent_klass, @parent_klass)
|
|
60
|
+
subclass.instance_variable_set(:@parent_klass_argument_proc, @parent_klass_argument_proc)
|
|
61
|
+
subclass.instance_variable_set(:@on_base_path_missing, @on_base_path_missing)
|
|
62
|
+
subclass.instance_variable_set(:@on_instance_path_missing, @on_instance_path_missing)
|
|
63
|
+
subclass.instance_variable_set(:@required_arguments, required_arguments)
|
|
64
|
+
|
|
65
|
+
# `root_path` is deliberately not copied: it is a `class_attribute`, looked up
|
|
66
|
+
# through the superclass chain on every read. A copy made here would freeze the
|
|
67
|
+
# value at class-definition time, ie. before an initializer had a chance to set it.
|
|
68
|
+
end
|
|
69
|
+
|
|
70
|
+
# Declare where this directory used to live before some past
|
|
71
|
+
# reorganization (eg. before a Teams::Merger reassigned a
|
|
72
|
+
# Member to a different Team).
|
|
73
|
+
#
|
|
74
|
+
# The block is used to build an anonymous subclass of the current
|
|
75
|
+
# class (same pattern as `Fs::File`'s `variant`'s `define`) -
|
|
76
|
+
# override `#path` using plain Ruby and the class's own inherited
|
|
77
|
+
# `base_path`/`requires_arguments`.
|
|
78
|
+
#
|
|
79
|
+
# Careful with `super` inside that `#path` override: the legacy
|
|
80
|
+
# klass's superclass is *this* class, not `Fs::Directory` - if this
|
|
81
|
+
# class itself already overrides `#path` (the usual case), `super`
|
|
82
|
+
# calls that override rather than `Fs::Directory#path`, applying
|
|
83
|
+
# its logic a second time. Build the full path from `base_path`
|
|
84
|
+
# directly instead.
|
|
85
|
+
#
|
|
86
|
+
# By default, declaring `legacy` here does *not* make instantiating
|
|
87
|
+
# this Directory relocate anything - it only makes `legacy_klass`
|
|
88
|
+
# available, typically so a {Fs::File} stored in this Directory can
|
|
89
|
+
# point its own `legacy` block at it (see {Fs::File.legacy}) and
|
|
90
|
+
# migrate exactly the one file being accessed. Migrating a whole
|
|
91
|
+
# Directory is wrong whenever its legacy location was shared by
|
|
92
|
+
# several records that must move independently (eg. one directory
|
|
93
|
+
# per Member used to hold every one of that Member's files, each
|
|
94
|
+
# now belonging in its own, per-record Directory) - File-level
|
|
95
|
+
# migration handles that correctly, Directory-level does not.
|
|
96
|
+
#
|
|
97
|
+
# Pass `migrate: true` to opt into Directory-level self-healing
|
|
98
|
+
# anyway - appropriate when the legacy and current locations are
|
|
99
|
+
# genuinely both directory-shaped 1:1 (eg. a directory that only
|
|
100
|
+
# changed its base path, not what it groups together), where
|
|
101
|
+
# relocating the whole thing at once is a worthwhile perf win over
|
|
102
|
+
# migrating file-by-file.
|
|
103
|
+
#
|
|
104
|
+
# @param migrate [Boolean] automatically relocate the whole
|
|
105
|
+
# directory to its current location on first instantiation
|
|
106
|
+
# @yield class-eval'd to build the anonymous subclass
|
|
107
|
+
# @return [void]
|
|
108
|
+
def legacy(migrate: false, &block)
|
|
109
|
+
@legacy_klass = Class.new(self, &block)
|
|
110
|
+
@legacy_migrate = migrate
|
|
111
|
+
end
|
|
112
|
+
|
|
113
|
+
# Combined getter/setter for an optional parent {Directory}
|
|
114
|
+
#
|
|
115
|
+
# @param klass [Class] Fs::Directory-subclass of the parent {Directory}
|
|
116
|
+
def below(klass = nil)
|
|
117
|
+
if klass
|
|
118
|
+
if klass.required_arguments
|
|
119
|
+
raise ArgumentError, "You cannot nest a Directory below another that takes arguments"
|
|
120
|
+
end
|
|
121
|
+
|
|
122
|
+
@parent_klass = klass
|
|
123
|
+
else
|
|
124
|
+
@parent_klass
|
|
125
|
+
end
|
|
126
|
+
end
|
|
127
|
+
|
|
128
|
+
# Combined getter/setter
|
|
129
|
+
#
|
|
130
|
+
# Resolved on every read, so that {Fs::Directory.root_path} may be
|
|
131
|
+
# configured after the subclasses have been defined.
|
|
132
|
+
def base_path(value = nil)
|
|
133
|
+
if value
|
|
134
|
+
@raw_base_path = value
|
|
135
|
+
# `to_s`: for a Pathname, `present?` asks the file system unless ActiveSupport 7.1's
|
|
136
|
+
# `pathname/blank` is loaded, and a path to an empty directory or file counts as "blank"
|
|
137
|
+
elsif @raw_base_path.to_s.present?
|
|
138
|
+
parent_klass.present? ? parent_klass.base_path + @raw_base_path : Pathname(root_path).join(@raw_base_path)
|
|
139
|
+
end
|
|
140
|
+
end
|
|
141
|
+
|
|
142
|
+
# @param value [Symbol] `:create`, `:raise` or `:ignore`
|
|
143
|
+
def on_base_path_missing(value = nil)
|
|
144
|
+
if value
|
|
145
|
+
ensure_value_is_one_of value => WHEN_MISSING_MODES
|
|
146
|
+
@on_base_path_missing = value
|
|
147
|
+
else
|
|
148
|
+
@on_base_path_missing || :create
|
|
149
|
+
end
|
|
150
|
+
end
|
|
151
|
+
|
|
152
|
+
# @param value [Symbol] `:create`, `:raise` or `:ignore`
|
|
153
|
+
def on_instance_path_missing(value = nil)
|
|
154
|
+
if value
|
|
155
|
+
ensure_value_is_one_of value => WHEN_MISSING_MODES
|
|
156
|
+
@on_instance_path_missing = value
|
|
157
|
+
else
|
|
158
|
+
@on_instance_path_missing || :create
|
|
159
|
+
end
|
|
160
|
+
end
|
|
161
|
+
end
|
|
162
|
+
|
|
163
|
+
# The directory relative `base_path`s are anchored at; absolute ones
|
|
164
|
+
# ignore it. Defaults to the file system root, so that relative paths
|
|
165
|
+
# are never silently tied to a particular application layout.
|
|
166
|
+
#
|
|
167
|
+
# Inherited by subclasses unless they set their own, which then applies
|
|
168
|
+
# to that subclass and its descendants only. Set it on `Fs::Directory`
|
|
169
|
+
# itself to configure it globally.
|
|
170
|
+
#
|
|
171
|
+
# @!scope class
|
|
172
|
+
# @return [Pathname, String]
|
|
173
|
+
class_attribute :root_path, instance_accessor: false, instance_predicate: false,
|
|
174
|
+
default: Pathname.new("/")
|
|
175
|
+
|
|
176
|
+
def self.to_s
|
|
177
|
+
base_path.to_s
|
|
178
|
+
end
|
|
179
|
+
|
|
180
|
+
# Does the base path exist?
|
|
181
|
+
#
|
|
182
|
+
# `on_base_path_missing` settings do not apply
|
|
183
|
+
#
|
|
184
|
+
# @return [Boolean]
|
|
185
|
+
def self.exist?
|
|
186
|
+
base_path.exist?
|
|
187
|
+
end
|
|
188
|
+
|
|
189
|
+
# Remove all contents from base_path
|
|
190
|
+
#
|
|
191
|
+
# @return [void]
|
|
192
|
+
def self.empty!
|
|
193
|
+
return unless exist?
|
|
194
|
+
|
|
195
|
+
Dir.each_child(base_path) do |entry|
|
|
196
|
+
FileUtils.rm_rf(::File.join(base_path, entry))
|
|
197
|
+
end
|
|
198
|
+
end
|
|
199
|
+
|
|
200
|
+
# Does the instance path exist?
|
|
201
|
+
#
|
|
202
|
+
# `on_base_path_missing` and `on_instance_path_missing` settings
|
|
203
|
+
# do not apply
|
|
204
|
+
#
|
|
205
|
+
# @return [Boolean]
|
|
206
|
+
def self.instance_path_exist?(**kargs)
|
|
207
|
+
new(when_missing: :ignore, **kargs).exist?
|
|
208
|
+
end
|
|
209
|
+
|
|
210
|
+
# Takes a block and creates a directory instance for the duration
|
|
211
|
+
# of that block
|
|
212
|
+
#
|
|
213
|
+
# When the given block returns, the directory and its contents
|
|
214
|
+
# are removed.
|
|
215
|
+
#
|
|
216
|
+
# If configured, the base_path is ignored and replaced by a
|
|
217
|
+
# temporary base directory managed by `Dir.mktmpdir`.
|
|
218
|
+
#
|
|
219
|
+
# @param kargs which arguments are required dependeds on the
|
|
220
|
+
# `Fs::Directory` subclass configuration
|
|
221
|
+
# @return [void]
|
|
222
|
+
def self.temp_dir_for(**kargs)
|
|
223
|
+
if block_given?
|
|
224
|
+
Dir.mktmpdir do |tmp_base_path|
|
|
225
|
+
dir = new(base_path: tmp_base_path, **kargs)
|
|
226
|
+
yield dir
|
|
227
|
+
end
|
|
228
|
+
else
|
|
229
|
+
new(base_path: Dir.mktmpdir, **kargs)
|
|
230
|
+
end
|
|
231
|
+
end
|
|
232
|
+
|
|
233
|
+
# @param when_missing [Symbol] when base or instance path do not
|
|
234
|
+
# exist, `:create`, `:raise` or `:ignore`. Overrides class settings
|
|
235
|
+
# for `on_base_path_missing` and `on_instance_path_missing`
|
|
236
|
+
# @param base_path [String, #to_s] a dynamic base_path; useful for
|
|
237
|
+
# one-off wrappings of directory paths in a generic Fs::Directory
|
|
238
|
+
# @option **kargs which arguments are required dependeds on the
|
|
239
|
+
# `Fs::Directory` subclass configuration
|
|
240
|
+
def initialize(when_missing: nil, base_path: nil, **kargs)
|
|
241
|
+
@parent = self.class.parent_klass.new if self.class.parent_klass
|
|
242
|
+
@dynamic_base_path = base_path ? Pathname.new(base_path.to_s) : nil
|
|
243
|
+
|
|
244
|
+
process_required_arguments(**kargs)
|
|
245
|
+
|
|
246
|
+
# A directory wrapped via `base_path:` is not one of our configured base directories
|
|
247
|
+
ensure_accessibility_of(self.base_path,
|
|
248
|
+
when_missing: when_missing || self.class.on_base_path_missing,
|
|
249
|
+
base: dynamic_base_path.nil?)
|
|
250
|
+
|
|
251
|
+
instance_path_when_missing = when_missing || self.class.on_instance_path_missing
|
|
252
|
+
|
|
253
|
+
if self.class.legacy_klass && self.class.legacy_migrate && instance_path_when_missing != :ignore
|
|
254
|
+
migrate_from_legacy_location!
|
|
255
|
+
end
|
|
256
|
+
|
|
257
|
+
ensure_accessibility_of(path, when_missing: instance_path_when_missing)
|
|
258
|
+
end
|
|
259
|
+
|
|
260
|
+
# @return [Pathname]
|
|
261
|
+
def base_path
|
|
262
|
+
@dynamic_base_path || self.class.base_path
|
|
263
|
+
end
|
|
264
|
+
|
|
265
|
+
# Remove all contents from this directory
|
|
266
|
+
#
|
|
267
|
+
# @return [void]
|
|
268
|
+
def empty!
|
|
269
|
+
return unless exist?
|
|
270
|
+
|
|
271
|
+
Dir.each_child(path) do |entry|
|
|
272
|
+
FileUtils.rm_rf(::File.join(path, entry))
|
|
273
|
+
end
|
|
274
|
+
end
|
|
275
|
+
|
|
276
|
+
# Creates a subdirectory
|
|
277
|
+
#
|
|
278
|
+
# @param dirpath [String]
|
|
279
|
+
# @return [Fs::Directory]
|
|
280
|
+
def mkdir(dirpath)
|
|
281
|
+
path.join(dirpath).mkdir
|
|
282
|
+
|
|
283
|
+
Fs::Directory.new(base_path: path.join(dirpath))
|
|
284
|
+
end
|
|
285
|
+
|
|
286
|
+
# Creates a subdirectory, plus any missing intermediate subdirectories
|
|
287
|
+
#
|
|
288
|
+
# @param dirpath [String]
|
|
289
|
+
# @return [Fs::Directory]
|
|
290
|
+
def mkpath(dirpath)
|
|
291
|
+
path.join(dirpath).mkpath
|
|
292
|
+
|
|
293
|
+
Fs::Directory.new(base_path: path.join(dirpath))
|
|
294
|
+
end
|
|
295
|
+
|
|
296
|
+
# @return [Pathname]
|
|
297
|
+
def parent_path
|
|
298
|
+
parent.present? ? parent.path : Pathname.new("")
|
|
299
|
+
end
|
|
300
|
+
|
|
301
|
+
# @return [Pathname]
|
|
302
|
+
def path
|
|
303
|
+
parent_path + base_path
|
|
304
|
+
end
|
|
305
|
+
|
|
306
|
+
# @return [Array<Pathname>]
|
|
307
|
+
def subdirectories
|
|
308
|
+
path.children.select(&:directory?)
|
|
309
|
+
end
|
|
310
|
+
|
|
311
|
+
# @return [Pathname]
|
|
312
|
+
def to_path
|
|
313
|
+
path
|
|
314
|
+
end
|
|
315
|
+
|
|
316
|
+
# @return [String]
|
|
317
|
+
def to_s
|
|
318
|
+
path.to_s
|
|
319
|
+
end
|
|
320
|
+
|
|
321
|
+
# Overload for adding paths and alikes
|
|
322
|
+
#
|
|
323
|
+
# Note that you will receive back a generic `Fs::Directory`
|
|
324
|
+
# instance, even when called on a specific subclass.
|
|
325
|
+
#
|
|
326
|
+
# @param other [Path, #to_path]
|
|
327
|
+
# @return [Fs::Directory]
|
|
328
|
+
def +(other)
|
|
329
|
+
other = other.to_path if other.respond_to?(:to_path)
|
|
330
|
+
|
|
331
|
+
Fs::Directory.new(base_path: path + other)
|
|
332
|
+
end
|
|
333
|
+
|
|
334
|
+
alias_method :/, :+
|
|
335
|
+
|
|
336
|
+
# Recursively copy this directory at `path` to `to`
|
|
337
|
+
#
|
|
338
|
+
# The behaviour depends on whether `to` exists. If
|
|
339
|
+
# you copy `reports` to `/foo`:
|
|
340
|
+
#
|
|
341
|
+
# * if `/foo` is an existing directory, `/foo/reports`
|
|
342
|
+
# will be created
|
|
343
|
+
# * if `/foo` does not exist, `/foo` will be created
|
|
344
|
+
#
|
|
345
|
+
# @param to [String, Pathname, #to_path]
|
|
346
|
+
def copy_to(to)
|
|
347
|
+
FileUtils.cp_r(path, get_path_from(to))
|
|
348
|
+
end
|
|
349
|
+
|
|
350
|
+
# Move this directory at `path` to `to`
|
|
351
|
+
#
|
|
352
|
+
# The behaviour depends on whether `to` exists. If
|
|
353
|
+
# you move `reports` to `/foo`:
|
|
354
|
+
#
|
|
355
|
+
# * if `/foo` is an existing directory, `/foo/reports`
|
|
356
|
+
# will be created
|
|
357
|
+
# * if `/foo` does not exist, `/foo` will be created
|
|
358
|
+
#
|
|
359
|
+
# @param to [String, Pathname, #to_path]
|
|
360
|
+
def move_to(to)
|
|
361
|
+
FileUtils.mv(path, get_path_from(to))
|
|
362
|
+
end
|
|
363
|
+
|
|
364
|
+
# Create a symlink here at our `path` that points to
|
|
365
|
+
# the existing source at `source`
|
|
366
|
+
#
|
|
367
|
+
# @param source [String, Pathname, #to_path]
|
|
368
|
+
def symlink_from(source)
|
|
369
|
+
FileUtils.ln_s(get_path_from(source), path)
|
|
370
|
+
end
|
|
371
|
+
|
|
372
|
+
# Create a symlink at `to` that points to us as the
|
|
373
|
+
# existing source.
|
|
374
|
+
#
|
|
375
|
+
# @param from [String, Pathname, #to_path]
|
|
376
|
+
def symlink_to(to)
|
|
377
|
+
FileUtils.ln_s(path, get_path_from(to))
|
|
378
|
+
end
|
|
379
|
+
|
|
380
|
+
# Creates this directory, if it does not already exist, and
|
|
381
|
+
# tests r/w permissions
|
|
382
|
+
#
|
|
383
|
+
# Useful for directories which were initialized with
|
|
384
|
+
# `on_instance_path_missing :ignore` and might not exist
|
|
385
|
+
#
|
|
386
|
+
# @raise [Errors::Fs::ReadWrite]
|
|
387
|
+
# @return [Boolean]
|
|
388
|
+
def create
|
|
389
|
+
ensure_accessibility_of(path, when_missing: :create)
|
|
390
|
+
end
|
|
391
|
+
|
|
392
|
+
# Create a zipfile at `path` from the current `Fs::Directory`
|
|
393
|
+
# contents
|
|
394
|
+
#
|
|
395
|
+
# @param path [Pathname, String, Fs::File]
|
|
396
|
+
# @param relative_to [Pathname, String, Fs::File, Symbol] store
|
|
397
|
+
# subdirectories and files relative to this path instead of the
|
|
398
|
+
# current working directory. Set to `:target` to use `directory_path`
|
|
399
|
+
# @option **kargs passed on to {Shell::Zip.from_directory}
|
|
400
|
+
# @return [Shell::Command::Result]
|
|
401
|
+
def to_zip(path, relative_to: :target, **kargs)
|
|
402
|
+
Shell::Zip.from_directory(self, to: path, relative_to: relative_to, **kargs)
|
|
403
|
+
end
|
|
404
|
+
|
|
405
|
+
# Create a temporary zipfile from the current `Fs::Directory`
|
|
406
|
+
# contents and yields it to a given block
|
|
407
|
+
#
|
|
408
|
+
# @param relative_to [Pathname, String, Fs::File, Symbol] store
|
|
409
|
+
# subdirectories and files relative to this path instead of the
|
|
410
|
+
# current working directory. Set to `:target` to use `directory_path`
|
|
411
|
+
# @option **kargs passed on to {Shell::Zip.from_directory}
|
|
412
|
+
# @yield [Fs::File]
|
|
413
|
+
# @return the return value of the given block
|
|
414
|
+
def to_temp_zip(relative_to: :target, **kargs)
|
|
415
|
+
Fs::File.create_temp do |temp_file|
|
|
416
|
+
# `zip` does not like it if a 0-byte target file already exists;
|
|
417
|
+
# it complains about an invalid target.
|
|
418
|
+
temp_file.delete
|
|
419
|
+
|
|
420
|
+
to_zip(temp_file, relative_to: relative_to, **kargs)
|
|
421
|
+
|
|
422
|
+
yield(temp_file)
|
|
423
|
+
end
|
|
424
|
+
end
|
|
425
|
+
|
|
426
|
+
# Year / month / day
|
|
427
|
+
#
|
|
428
|
+
# Helper for producing the common subdirectory pattern
|
|
429
|
+
#
|
|
430
|
+
# @param date_or_time [Date, Time]
|
|
431
|
+
# @return [String]
|
|
432
|
+
def ymd(date_or_time = Time.now)
|
|
433
|
+
"#{date_or_time.year}/#{date_or_time.month}/#{date_or_time.day}"
|
|
434
|
+
end
|
|
435
|
+
|
|
436
|
+
private
|
|
437
|
+
|
|
438
|
+
# Makes sure `path` is a directory we can read and write, creating it if told to
|
|
439
|
+
#
|
|
440
|
+
# @param path [Pathname]
|
|
441
|
+
# @param when_missing [Symbol] one of {WHEN_MISSING_MODES}: what to do if `path` does not
|
|
442
|
+
# exist. With `:ignore`, nothing is checked at all.
|
|
443
|
+
# @param base [Boolean] is `path` a configured base directory? Decides which
|
|
444
|
+
# exceptions are raised, see {AccessibilityCheck}.
|
|
445
|
+
# @return [true, nil] `nil` if `when_missing` is `:ignore`
|
|
446
|
+
# @raise [Errors::Fs::BaseDirectory, Errors::Fs::ReadWrite]
|
|
447
|
+
# @raise [ArgumentError] on an unknown `when_missing`
|
|
448
|
+
def ensure_accessibility_of(path, when_missing: :raise, base: false)
|
|
449
|
+
ensure_value_is_one_of when_missing => WHEN_MISSING_MODES
|
|
450
|
+
return nil if when_missing == :ignore
|
|
451
|
+
|
|
452
|
+
AccessibilityCheck.new(path, when_missing: when_missing, base: base).run
|
|
453
|
+
end
|
|
454
|
+
|
|
455
|
+
# @param arg [#to_path, Object]
|
|
456
|
+
# @return [String, Object] `arg.to_path` if `arg` responds to it, else `arg` unchanged
|
|
457
|
+
def get_path_from(arg)
|
|
458
|
+
arg.respond_to?(:to_path) ? arg.to_path : arg
|
|
459
|
+
end
|
|
460
|
+
|
|
461
|
+
# No-op in the overwhelming majority of cases where nothing needs
|
|
462
|
+
# migrating - runs on every instantiation of a class with a
|
|
463
|
+
# `legacy(migrate: true)` block, so it must stay cheap and silent
|
|
464
|
+
# when there's nothing to do.
|
|
465
|
+
#
|
|
466
|
+
# Checks for a non-empty `path`, not merely an existing one: this
|
|
467
|
+
# method itself always runs before `ensure_accessibility_of(path)`
|
|
468
|
+
# (below), but that guarantee only covers the current call -
|
|
469
|
+
# `ensure_accessibility_of` auto-creates a missing directory as a
|
|
470
|
+
# side effect of *any* prior instantiation of this class, migration
|
|
471
|
+
# or not (eg. simply checking whether a not-yet-attached record has
|
|
472
|
+
# a directory). Treating mere existence as "already migrated" would
|
|
473
|
+
# permanently wedge the migration behind such an empty directory.
|
|
474
|
+
#
|
|
475
|
+
# @return [void]
|
|
476
|
+
def migrate_from_legacy_location!
|
|
477
|
+
return if path.exist? && !Dir.empty?(path.to_s)
|
|
478
|
+
|
|
479
|
+
legacy_path = self.class.legacy_klass.new(when_missing: :ignore, **required_arguments_given).path
|
|
480
|
+
|
|
481
|
+
return unless legacy_path.exist? && legacy_path != path
|
|
482
|
+
|
|
483
|
+
# `path` may already exist as an empty, auto-vivified directory
|
|
484
|
+
# (see above) - if left in place, `FileUtils.mv` would move
|
|
485
|
+
# `legacy_path` *into* it (nesting) rather than renaming it, since
|
|
486
|
+
# `mv` targets an existing directory by nesting. `rmdir` only
|
|
487
|
+
# succeeds on an empty directory, matching the guard above.
|
|
488
|
+
path.rmdir if path.exist?
|
|
489
|
+
path.dirname.mkpath
|
|
490
|
+
FileUtils.mv(legacy_path.to_s, path.to_s)
|
|
491
|
+
rescue Errno::ENOENT
|
|
492
|
+
# Lost a race with another process/thread doing the same migration
|
|
493
|
+
# concurrently - fine, ensure_accessibility_of below finds `path`
|
|
494
|
+
# already present.
|
|
495
|
+
end
|
|
496
|
+
end
|
|
497
|
+
end
|