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/file.rb
ADDED
|
@@ -0,0 +1,1524 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require "fileutils"
|
|
4
|
+
require "tempfile"
|
|
5
|
+
require "active_support"
|
|
6
|
+
require "active_support/core_ext/module/delegation"
|
|
7
|
+
require "active_support/core_ext/object/blank"
|
|
8
|
+
require "active_support/core_ext/string/inflections"
|
|
9
|
+
require "shell/base_64"
|
|
10
|
+
require "shell/clam_av"
|
|
11
|
+
require "shell/file"
|
|
12
|
+
require "shell/open_ssl"
|
|
13
|
+
require_relative "file_variant_builder"
|
|
14
|
+
require_relative "file_variant_proxy"
|
|
15
|
+
require_relative "concerns/file_dsl_methods"
|
|
16
|
+
require_relative "concerns/required_arguments"
|
|
17
|
+
|
|
18
|
+
module Fs
|
|
19
|
+
# `Fs::File` represents a file on disk and provides methods to operate on it.
|
|
20
|
+
#
|
|
21
|
+
# Create subclasses for specific file types such as `Fs::Files::Text`, `Fs::Files::JPG`
|
|
22
|
+
# or `Fs::Files::PDF` to provide capabilities for these file types, such as thumbnailing
|
|
23
|
+
# for images or text extraction for PDFs.
|
|
24
|
+
#
|
|
25
|
+
# You can then subclass these file types into context-specific files, such as a
|
|
26
|
+
# `Fs::Files::ProjectPdf` that inherits from `Fs::Files::PDF`, to encode their
|
|
27
|
+
# directory locations, naming schemes and so on.
|
|
28
|
+
#
|
|
29
|
+
# Basic interface
|
|
30
|
+
# ---------------
|
|
31
|
+
#
|
|
32
|
+
# The basic interface is the same for all `Fs::File` classes:
|
|
33
|
+
#
|
|
34
|
+
# ```ruby
|
|
35
|
+
# # Initialize a new object for a file that does or does not yet exist on disk
|
|
36
|
+
# file = Fs::File.new(path: "/path/to/file")
|
|
37
|
+
#
|
|
38
|
+
# # Use #load for a file that should already exist
|
|
39
|
+
# file = Fs::File.load(path: "/path/to/file")
|
|
40
|
+
#
|
|
41
|
+
# # Use #create for a file that does not yet exist
|
|
42
|
+
# content = "lorem ipsum dolor"
|
|
43
|
+
# file =
|
|
44
|
+
# Fs::File.create(path: "/path/to/file") do |f|
|
|
45
|
+
# f << content
|
|
46
|
+
# end
|
|
47
|
+
#
|
|
48
|
+
# # or alternatively:
|
|
49
|
+
# file = Fs::File.create(path: "/path/to/file", content: content)
|
|
50
|
+
# ```
|
|
51
|
+
#
|
|
52
|
+
# Creating basic subclasses with the DSL
|
|
53
|
+
# --------------------------------------
|
|
54
|
+
#
|
|
55
|
+
# Let's assume our application creates a report CSV file for every {Project} and
|
|
56
|
+
# stores it in `#{Fs::Directory.root_path}/project_reports/<project id>/report_<project id>.csv`.
|
|
57
|
+
#
|
|
58
|
+
# In this example we will create three classes:
|
|
59
|
+
#
|
|
60
|
+
# 1. a `Fs::CsvFile` class to represent CSV files in general
|
|
61
|
+
# 2. `Fs::Dirs::ProjectReports` to represent the directory our reports are stored in
|
|
62
|
+
# 3. `Fs::Files::ProjectReportCsv` to represent our report files specifically
|
|
63
|
+
#
|
|
64
|
+
# We begin by subclassing `Fs::File` for our general CSV class:
|
|
65
|
+
#
|
|
66
|
+
# ```ruby
|
|
67
|
+
# require 'csv'
|
|
68
|
+
#
|
|
69
|
+
# module Fs
|
|
70
|
+
# module Files
|
|
71
|
+
# class Csv < Fs::File
|
|
72
|
+
# extension :csv
|
|
73
|
+
# end
|
|
74
|
+
# end
|
|
75
|
+
# end
|
|
76
|
+
# ```
|
|
77
|
+
#
|
|
78
|
+
# Our class now knows its expected file type:
|
|
79
|
+
#
|
|
80
|
+
# ```ruby
|
|
81
|
+
# Fs::Files::Csv.load(path: "/some/test.csv")
|
|
82
|
+
# # => Fs::Files::Csv
|
|
83
|
+
#
|
|
84
|
+
# Fs::Files::Csv.load(path: "/some/image.jpg")
|
|
85
|
+
# # => Errors::Fs::Validation::UnsupportedExtension
|
|
86
|
+
# ```
|
|
87
|
+
#
|
|
88
|
+
# By the way, you can pass multiple extensions to `extension`. When validating existing
|
|
89
|
+
# files, all of them will be accepted; when creating a new file, the first extension will
|
|
90
|
+
# be used. You can also skip `extension` completely.
|
|
91
|
+
#
|
|
92
|
+
# Additional options for validating files are `mime_type` and `encoding`:
|
|
93
|
+
#
|
|
94
|
+
# ```ruby
|
|
95
|
+
# require 'csv'
|
|
96
|
+
#
|
|
97
|
+
# module Fs
|
|
98
|
+
# module Files
|
|
99
|
+
# class CsvFile < Fs::File
|
|
100
|
+
# extension :csv
|
|
101
|
+
# mime_type "application/csv", /^text\//
|
|
102
|
+
# encoding "utf-8", /ascii/
|
|
103
|
+
# end
|
|
104
|
+
# end
|
|
105
|
+
# end
|
|
106
|
+
# ```
|
|
107
|
+
#
|
|
108
|
+
# Both settings accept strings as well as regular expressions.
|
|
109
|
+
#
|
|
110
|
+
# Lets give it a method for parsing the CSV. We have access to {Fs::File#path}, which is
|
|
111
|
+
# all we really need:
|
|
112
|
+
#
|
|
113
|
+
# ```ruby
|
|
114
|
+
# require 'csv'
|
|
115
|
+
#
|
|
116
|
+
# module Fs
|
|
117
|
+
# module Files
|
|
118
|
+
# class CsvFile < Fs::File
|
|
119
|
+
# extension :csv
|
|
120
|
+
#
|
|
121
|
+
# def content(**parser_options)
|
|
122
|
+
# CSV.read(path, **parser_options)
|
|
123
|
+
# end
|
|
124
|
+
# end
|
|
125
|
+
# end
|
|
126
|
+
# end
|
|
127
|
+
# ```
|
|
128
|
+
#
|
|
129
|
+
# Now we have something that reads CSV files; we ignore writing for the moment.
|
|
130
|
+
#
|
|
131
|
+
# ```ruby
|
|
132
|
+
# Fs::Files::Csv.load(path: "/some/test.csv").content
|
|
133
|
+
# # => Array
|
|
134
|
+
# ```
|
|
135
|
+
#
|
|
136
|
+
# Step 2 is our `Fs::Directory` subclass to represent the storage location at `project_reports/`.
|
|
137
|
+
#
|
|
138
|
+
# ```ruby
|
|
139
|
+
# module Fs
|
|
140
|
+
# module Dirs
|
|
141
|
+
# class ProjectReports < Fs::Directory
|
|
142
|
+
# base_path "project_reports"
|
|
143
|
+
# end
|
|
144
|
+
# end
|
|
145
|
+
# end
|
|
146
|
+
# ```
|
|
147
|
+
#
|
|
148
|
+
# Note that relative paths are anchored at `Fs::Directory.root_path` (default `/`); absolute ones,
|
|
149
|
+
# ie. `base_path "/project_reports"`, ignore it.
|
|
150
|
+
#
|
|
151
|
+
# This gives us a class that knows where project reports are stored in general:
|
|
152
|
+
#
|
|
153
|
+
# ```ruby
|
|
154
|
+
# Fs::Dirs::ProjectReports.base_path
|
|
155
|
+
# # => #<Pathname:/app/storage/project_reports>
|
|
156
|
+
#
|
|
157
|
+
# # We can also instantiate our directory class, but the path remains the same so far:
|
|
158
|
+
# Fs::Dirs::ProjectReports.new.path
|
|
159
|
+
# # => #<Pathname:/app/storage/project_reports>
|
|
160
|
+
# ```
|
|
161
|
+
#
|
|
162
|
+
# But what about the directory for a _specific_ report, ie. `project_reports/15/`?
|
|
163
|
+
# That's easily done - someone just needs to pass in the {Project} so that we can
|
|
164
|
+
# get the ID:
|
|
165
|
+
#
|
|
166
|
+
# ```ruby
|
|
167
|
+
# module Fs
|
|
168
|
+
# module Dirs
|
|
169
|
+
# class ProjectReports < Fs::Directory
|
|
170
|
+
# base_path "project_reports"
|
|
171
|
+
# requires_arguments project: "Project"
|
|
172
|
+
#
|
|
173
|
+
# def path
|
|
174
|
+
# super/project.id.to_s
|
|
175
|
+
# end
|
|
176
|
+
# end
|
|
177
|
+
# end
|
|
178
|
+
# end
|
|
179
|
+
# ```
|
|
180
|
+
#
|
|
181
|
+
# We configured it to require a `:project` parameter of type `Project`. We then
|
|
182
|
+
# use that passed-in project to overload the default `path`. Now `base_path` and our
|
|
183
|
+
# instances `#path` differ:
|
|
184
|
+
#
|
|
185
|
+
# ```ruby
|
|
186
|
+
# Fs::Dirs::ProjectReports.base_path
|
|
187
|
+
# # => #<Pathname:/app/storage/project_reports>
|
|
188
|
+
#
|
|
189
|
+
# Fs::Dirs::ProjectReports.new(project: Project.last).path
|
|
190
|
+
# # => #<Pathname:/app/storage/project_reports/15>
|
|
191
|
+
# ```
|
|
192
|
+
#
|
|
193
|
+
# We are now ready to create our `ProjectReportCsv` and configure it with our new directory:
|
|
194
|
+
#
|
|
195
|
+
# ```ruby
|
|
196
|
+
# module Fs
|
|
197
|
+
# module Files
|
|
198
|
+
# class ProjectReportCsv < Fs::Files::Csv
|
|
199
|
+
# directory Fs::Dirs::ProjectReports
|
|
200
|
+
# end
|
|
201
|
+
# end
|
|
202
|
+
# end
|
|
203
|
+
# ```
|
|
204
|
+
#
|
|
205
|
+
# Something is missing: the directory requires the `:project` parameter for `#new`, so our file
|
|
206
|
+
# needs it as well:
|
|
207
|
+
#
|
|
208
|
+
# ```ruby
|
|
209
|
+
# module Fs
|
|
210
|
+
# module Files
|
|
211
|
+
# class ProjectReportCsv < Fs::Files::Csv
|
|
212
|
+
# directory Fs::Dirs::ProjectReports
|
|
213
|
+
# requires_arguments project: "Project"
|
|
214
|
+
# end
|
|
215
|
+
# end
|
|
216
|
+
# end
|
|
217
|
+
# ```
|
|
218
|
+
#
|
|
219
|
+
# The `:project` parameter is passed along automatically. Our class now knows the path from the
|
|
220
|
+
# directory, and the file extension from its parent class `Fs::CsvFile` - all that is missing is the
|
|
221
|
+
# basename (filename without extension):
|
|
222
|
+
#
|
|
223
|
+
# ```ruby
|
|
224
|
+
# project = Project.last
|
|
225
|
+
# Fs::Files::ProjectReportCsv.load(project: project,
|
|
226
|
+
# basename: "report_#{project.id}")
|
|
227
|
+
# ```
|
|
228
|
+
#
|
|
229
|
+
# But since we already have everything to determine the basename ourselves, lets provide a `get_path_from`
|
|
230
|
+
# block to do so:
|
|
231
|
+
#
|
|
232
|
+
# ```ruby
|
|
233
|
+
# module Fs
|
|
234
|
+
# module Files
|
|
235
|
+
# class ProjectReportCsv < Fs::CsvFile
|
|
236
|
+
# directory Fs::Dirs::ProjectReports
|
|
237
|
+
# requires_arguments project: "Project"
|
|
238
|
+
#
|
|
239
|
+
# get_path_from do
|
|
240
|
+
# directory_path/"report_#{project.id}"
|
|
241
|
+
# end
|
|
242
|
+
# end
|
|
243
|
+
# end
|
|
244
|
+
# end
|
|
245
|
+
# ```
|
|
246
|
+
#
|
|
247
|
+
# We now have a class that represents a specific kind of CSV, where it is located, how it
|
|
248
|
+
# should be named and provides a method for reading it:
|
|
249
|
+
#
|
|
250
|
+
# ```ruby
|
|
251
|
+
# file = Fs::Files::ProjectReportCsv.load(project: Project.last)
|
|
252
|
+
#
|
|
253
|
+
# file.path
|
|
254
|
+
# # => #<Pathname:/app/storage/project_reports/15/report_15.csv>
|
|
255
|
+
# file.content
|
|
256
|
+
# # => Array
|
|
257
|
+
# ```
|
|
258
|
+
#
|
|
259
|
+
# `.copy_from` and `.move_from`
|
|
260
|
+
# -----------------------------
|
|
261
|
+
#
|
|
262
|
+
# If the file you want to create already exists elsewhere in your filesystem, you can use
|
|
263
|
+
# `.copy_from` or `.move_from` to create it.
|
|
264
|
+
#
|
|
265
|
+
# Imagine the project report CSV for `Project.last` was created by some external process
|
|
266
|
+
# at the location `/var/tmp/reports/last_report.csv`, and you now wish to import it into your
|
|
267
|
+
# well-defined directory structure.
|
|
268
|
+
#
|
|
269
|
+
# ```ruby
|
|
270
|
+
# Fs::Files::ProjectReportCsv.exists?(project: Project.last)
|
|
271
|
+
# # => false
|
|
272
|
+
#
|
|
273
|
+
# file =
|
|
274
|
+
# Fs::Files::ProjectReportCsv.copy_from("/var/tmp/reports/last_report.csv", project: Project.last)
|
|
275
|
+
#
|
|
276
|
+
# file.path
|
|
277
|
+
# # => #<Pathname:/app/storage/project_reports/15/report_15.csv>
|
|
278
|
+
# ```
|
|
279
|
+
#
|
|
280
|
+
# Advanced subclasses: file conversions with variants
|
|
281
|
+
# ---------------------------------------------------
|
|
282
|
+
#
|
|
283
|
+
# We regularly need file contents in different forms or formats — PNGs as JPEGs, JPEGS as thumbnails,
|
|
284
|
+
# PDFs as text files. To that end, we can provide _variants_.
|
|
285
|
+
#
|
|
286
|
+
# Lets take an unspecific text file class called `SomeTextFile` as an example. Each variant you define
|
|
287
|
+
# must have at minimum a name:
|
|
288
|
+
#
|
|
289
|
+
# ```ruby
|
|
290
|
+
# module Fs
|
|
291
|
+
# module Files
|
|
292
|
+
# class SomeTextFile < Fs::Files::Text
|
|
293
|
+
# variant :loud_text do
|
|
294
|
+
# end
|
|
295
|
+
# end
|
|
296
|
+
# end
|
|
297
|
+
# end
|
|
298
|
+
# ```
|
|
299
|
+
#
|
|
300
|
+
# For any `SomeTextFile` instance, we can now create and load this `:loud_text` variant:
|
|
301
|
+
#
|
|
302
|
+
# ```ruby
|
|
303
|
+
# some_text_file =
|
|
304
|
+
# Fs::Files::SomeTextFile.create(path: "/some/path/text.txt", content: "lorem ipsum")
|
|
305
|
+
# # => Fs::Files::SomeTextFile
|
|
306
|
+
#
|
|
307
|
+
# some_text_file.variant(:loud_text)
|
|
308
|
+
# .create(path: "/some/path/loud_text.txt", content: "Loud file content")
|
|
309
|
+
# # => Fs::File
|
|
310
|
+
#
|
|
311
|
+
# some_text_file.variant(:loud_text)
|
|
312
|
+
# .load(path: "/some/path/loud_text.txt")
|
|
313
|
+
# # => Fs::File
|
|
314
|
+
# ```
|
|
315
|
+
#
|
|
316
|
+
# So far this didn't do anything useful - we had to provide everything from the file path to the
|
|
317
|
+
# content for the new variant ourselves. What's interesting to note is that the type of the variant
|
|
318
|
+
# is `Fs::File`, the base class:
|
|
319
|
+
#
|
|
320
|
+
# ```ruby
|
|
321
|
+
# some_text_file.content
|
|
322
|
+
# # => "lorem ipsum"
|
|
323
|
+
#
|
|
324
|
+
# some_text_file.variant(:loud_text)
|
|
325
|
+
# .load(path: "/some/path/loud_text.txt")
|
|
326
|
+
# .content
|
|
327
|
+
# # => NoMethodError: undefined method `content` for Fs::File:Class
|
|
328
|
+
# ```
|
|
329
|
+
#
|
|
330
|
+
# Let's change that:
|
|
331
|
+
#
|
|
332
|
+
# ```ruby
|
|
333
|
+
# module Fs
|
|
334
|
+
# module Files
|
|
335
|
+
# class SomeTextFile < Fs::Files::Text
|
|
336
|
+
# variant(:loud_text, Fs::Files::Text) do
|
|
337
|
+
# end
|
|
338
|
+
# end
|
|
339
|
+
# end
|
|
340
|
+
# end
|
|
341
|
+
#
|
|
342
|
+
# some_text_file.variant(:loud_text)
|
|
343
|
+
# .load(path: "/some/path/loud_text.txt")
|
|
344
|
+
# .content
|
|
345
|
+
# # => "Loud file content"
|
|
346
|
+
# ```
|
|
347
|
+
#
|
|
348
|
+
# Great. Now lets provide the path to the file and the file content automatically; we do this
|
|
349
|
+
# with `get_path_from {}` and `create_with_content_from {}`. Both blocks are executed in the
|
|
350
|
+
# scope of the variants parent - in the above example, that's `some_text_file`. So we have
|
|
351
|
+
# access to all its methods:
|
|
352
|
+
#
|
|
353
|
+
# ```ruby
|
|
354
|
+
# module Fs
|
|
355
|
+
# module Files
|
|
356
|
+
# class SomeTextFile < Fs::Files::Text
|
|
357
|
+
# variant(:loud_text, Fs::Files::Text) do
|
|
358
|
+
# get_path_from do |klass:|
|
|
359
|
+
# # `path.dirname` = `some_text_file.dirname` from the example above
|
|
360
|
+
# path.dirname / "loud_#{basename}.#{klass.extension}"
|
|
361
|
+
# end
|
|
362
|
+
#
|
|
363
|
+
# create_with_content_from do
|
|
364
|
+
# # `content` = `some_text_file.content` from the example above
|
|
365
|
+
# content.upcase
|
|
366
|
+
# end
|
|
367
|
+
# end
|
|
368
|
+
# end
|
|
369
|
+
# end
|
|
370
|
+
# end
|
|
371
|
+
#
|
|
372
|
+
# some_text_file.variant(:loud_text)
|
|
373
|
+
# .create
|
|
374
|
+
# .content
|
|
375
|
+
# # => "LOREM IPSUM"
|
|
376
|
+
# ```
|
|
377
|
+
#
|
|
378
|
+
# `get_path_from` receives the variant class, plus all parameters passed into
|
|
379
|
+
# `#load` or `#create` as arguments. `create_with_content_from` receives all parameters
|
|
380
|
+
# passed into `#create` as arguments.
|
|
381
|
+
#
|
|
382
|
+
# These two hooks are not always sufficient, for example if you create the content by shelling
|
|
383
|
+
# out to a command like `gs` or `convert` in order to create your variant. For those cases,
|
|
384
|
+
# provide `create_with {}` and `load_with {}` hooks instead:
|
|
385
|
+
#
|
|
386
|
+
# ```ruby
|
|
387
|
+
# module Fs
|
|
388
|
+
# module Files
|
|
389
|
+
# class SomeTextFile < Fs::Files::Text
|
|
390
|
+
# variant(:loud_text, Fs::Files::Text) do
|
|
391
|
+
# get_path_from do |klass:|
|
|
392
|
+
# path.dirname / "loud_#{basename}.#{klass.extension}"
|
|
393
|
+
# end
|
|
394
|
+
#
|
|
395
|
+
# create_with do |klass:, path:|
|
|
396
|
+
# # the path passed in here automatically is the return value from `get_path_from`
|
|
397
|
+
#
|
|
398
|
+
# # we take our parents content. `self` here is our instance of `SomeTextFile`
|
|
399
|
+
# new_content = content.upcase
|
|
400
|
+
#
|
|
401
|
+
# # The `:klass` argument our block received as an argument is the anonymous
|
|
402
|
+
# # class for the loud_text variant, subclassed from `Fs::Files::Text`
|
|
403
|
+
# klass.create(path: path, content: new_content)
|
|
404
|
+
# end
|
|
405
|
+
#
|
|
406
|
+
# load_with do |klass:, path:|
|
|
407
|
+
# klass.load(path: path)
|
|
408
|
+
# end
|
|
409
|
+
# end
|
|
410
|
+
# end
|
|
411
|
+
# end
|
|
412
|
+
# end
|
|
413
|
+
# ```
|
|
414
|
+
#
|
|
415
|
+
# Note that if we had created the file by shelling out to a command like `gs`, we would have
|
|
416
|
+
# ended with `klass.load` instead of `klass.create`, since our Fs::File class did not have to
|
|
417
|
+
# create a file anymore.
|
|
418
|
+
#
|
|
419
|
+
# You have one other extremely powerful capability at your disposal: the ability to dynamically
|
|
420
|
+
# configure the variants class with `define`. Inside a `define {}` block you can do everything
|
|
421
|
+
# you can do in a regular class body and have the full DSL available - if for example you want
|
|
422
|
+
# to change the variants file extension, you can just do so:
|
|
423
|
+
#
|
|
424
|
+
# ```ruby
|
|
425
|
+
# module Fs
|
|
426
|
+
# module Files
|
|
427
|
+
# class SomeTextFile < Fs::Files::Text
|
|
428
|
+
# variant(:loud_text, Fs::Files::Text) do
|
|
429
|
+
# define do
|
|
430
|
+
# extension :loud_text
|
|
431
|
+
#
|
|
432
|
+
# def is_this_loud?
|
|
433
|
+
# "YEAH!"
|
|
434
|
+
# end
|
|
435
|
+
# end
|
|
436
|
+
#
|
|
437
|
+
# get_path_from do |klass:|
|
|
438
|
+
# path.dirname / "loud_#{basename}.#{klass.extension}"
|
|
439
|
+
# end
|
|
440
|
+
#
|
|
441
|
+
# create_with_content_from do
|
|
442
|
+
# content.upcase
|
|
443
|
+
# end
|
|
444
|
+
# end
|
|
445
|
+
# end
|
|
446
|
+
# end
|
|
447
|
+
# end
|
|
448
|
+
#
|
|
449
|
+
# variant = some_text_file.variant(:loud_text)
|
|
450
|
+
# .load
|
|
451
|
+
# variant.path
|
|
452
|
+
# # => #<Pathname:/some/path/loud_text.loud_txt>
|
|
453
|
+
# variant.is_this_loud?
|
|
454
|
+
# # => "YEAH!"
|
|
455
|
+
# ```
|
|
456
|
+
class File
|
|
457
|
+
include Fs::Concerns::RequiredArguments
|
|
458
|
+
include Fs::Concerns::FileDslMethods
|
|
459
|
+
|
|
460
|
+
# The default number of seconds {.with_creation_lock} will wait to
|
|
461
|
+
# acquire a path's creation lock before giving up.
|
|
462
|
+
#
|
|
463
|
+
# Long enough to comfortably cover a real {.create} (eg. an image
|
|
464
|
+
# conversion plus a Tesseract rotation detection call), short enough to
|
|
465
|
+
# fail well before an NFSv4 lease expiry (90s on our mounts) would, so a
|
|
466
|
+
# stuck lock doesn't tie up a whole request/job for that long.
|
|
467
|
+
CREATION_LOCK_TIMEOUT = 20
|
|
468
|
+
|
|
469
|
+
# How often to retry acquiring the lock while waiting
|
|
470
|
+
CREATION_LOCK_POLL_INTERVAL = 0.1
|
|
471
|
+
|
|
472
|
+
# The extension given to a path's creation lockfile. Shared with
|
|
473
|
+
# {Fs::LockfileSweeper}, which needs to find the same files this class
|
|
474
|
+
# creates.
|
|
475
|
+
CREATION_LOCK_EXTENSION = "lock"
|
|
476
|
+
|
|
477
|
+
# The settings of {.atomic_write_directory} which are not an {Fs::Directory}
|
|
478
|
+
ATOMIC_WRITE_DIRECTORY_MODES = %i(alongside system).freeze
|
|
479
|
+
|
|
480
|
+
# The settings of {.temp_directory} which are not an {Fs::Directory}
|
|
481
|
+
TEMP_DIRECTORY_MODES = %i(system).freeze
|
|
482
|
+
|
|
483
|
+
# @return [Fs::Directory, nil] an instance of the `Fs::Directory` configured
|
|
484
|
+
# for this File, if any
|
|
485
|
+
attr_reader :directory
|
|
486
|
+
# @return [Pathname] the full path for this File
|
|
487
|
+
attr_reader :path
|
|
488
|
+
# For compatibility with {Pathname} objects
|
|
489
|
+
alias_method :to_path, :path
|
|
490
|
+
|
|
491
|
+
delegate :size, :delete, :mtime,
|
|
492
|
+
to: :path
|
|
493
|
+
|
|
494
|
+
# Instantiate a new File object and validate that its path exists on disk
|
|
495
|
+
# and is usable.
|
|
496
|
+
#
|
|
497
|
+
# Use this for creating File objects for files that already exist.
|
|
498
|
+
#
|
|
499
|
+
# @see #initialize
|
|
500
|
+
# @param validate [Boolean] raise an exception if file is not valid
|
|
501
|
+
# @param skip_extension_validation [Boolean] ignored if `validate: false`
|
|
502
|
+
# @param skip_mime_type_validation [Boolean] ignored if `validate: false`
|
|
503
|
+
# @param skip_encoding_validation [Boolean] ignored if `validate: false`
|
|
504
|
+
def self.load(validate: true, skip_extension_validation: false, skip_mime_type_validation: false,
|
|
505
|
+
skip_encoding_validation: false, **kargs)
|
|
506
|
+
new(**kargs).tap do |instance|
|
|
507
|
+
instance.validate!(
|
|
508
|
+
skip_extension_validation: skip_extension_validation,
|
|
509
|
+
skip_mime_type_validation: skip_mime_type_validation,
|
|
510
|
+
skip_encoding_validation: skip_encoding_validation
|
|
511
|
+
) if validate
|
|
512
|
+
|
|
513
|
+
instance.load
|
|
514
|
+
end
|
|
515
|
+
end
|
|
516
|
+
|
|
517
|
+
# Test whether a path exists on disk and is usable.
|
|
518
|
+
#
|
|
519
|
+
# @see #initialize
|
|
520
|
+
# @param skip_extension_validation [Boolean] ignored if `validate: false`
|
|
521
|
+
# @param skip_mime_type_validation [Boolean] ignored if `validate: false`
|
|
522
|
+
# @param skip_encoding_validation [Boolean] ignored if `validate: false`
|
|
523
|
+
# @return [Boolean]
|
|
524
|
+
def self.exists?(skip_extension_validation: false, skip_mime_type_validation: false,
|
|
525
|
+
skip_encoding_validation: false, **kargs)
|
|
526
|
+
load(validate: false, **kargs).valid?(
|
|
527
|
+
skip_extension_validation: skip_extension_validation,
|
|
528
|
+
skip_mime_type_validation: skip_mime_type_validation,
|
|
529
|
+
skip_encoding_validation: skip_encoding_validation
|
|
530
|
+
)
|
|
531
|
+
end
|
|
532
|
+
|
|
533
|
+
# Test whether this file class would accept a file with MIME type
|
|
534
|
+
# `mime_type` and/or extension `extension` and/or encoding `encoding`
|
|
535
|
+
#
|
|
536
|
+
# @param mime_type [String, nil]
|
|
537
|
+
# @param extension [String, nil]
|
|
538
|
+
# @param encoding [String, nil]
|
|
539
|
+
# @return [Boolean]
|
|
540
|
+
def self.accepts?(mime_type: nil, extension: nil, encoding: nil)
|
|
541
|
+
if mime_type
|
|
542
|
+
return false unless string_matches_config?(mime_type, within: mime_types)
|
|
543
|
+
end
|
|
544
|
+
|
|
545
|
+
if extension
|
|
546
|
+
return false unless string_matches_config?(extension, within: extensions)
|
|
547
|
+
end
|
|
548
|
+
|
|
549
|
+
if encoding
|
|
550
|
+
return false unless string_matches_config?(encoding, within: encodings)
|
|
551
|
+
end
|
|
552
|
+
|
|
553
|
+
true
|
|
554
|
+
end
|
|
555
|
+
|
|
556
|
+
# Instantiate a new File object and create its file on disk.
|
|
557
|
+
#
|
|
558
|
+
# Use this for creating File objects for files that do not yet exist.
|
|
559
|
+
#
|
|
560
|
+
# @example
|
|
561
|
+
# Fs::File.create(path: "/some/path/file.txt") do |f|
|
|
562
|
+
# f << "file content"
|
|
563
|
+
# end
|
|
564
|
+
#
|
|
565
|
+
# #or alternatively:
|
|
566
|
+
# Fs::File.create(path: "/some/path/file.txt", content: "file content")
|
|
567
|
+
#
|
|
568
|
+
# @see #initialize
|
|
569
|
+
# @param overwrite [Boolean] overwrite the file if it already exists on disk
|
|
570
|
+
# @param content [#to_s] content to be written to the file
|
|
571
|
+
# @param lock [Boolean] serialize concurrent creators of the same path
|
|
572
|
+
# (see {.with_creation_lock}); defaults to this class' {.use_locks}
|
|
573
|
+
# setting, which is off unless creating the file is expensive
|
|
574
|
+
# @param lock_timeout [Numeric] see {.with_creation_lock}
|
|
575
|
+
# @yield [IO]
|
|
576
|
+
def self.create(overwrite: false, content: nil, lock: use_locks, lock_timeout: CREATION_LOCK_TIMEOUT, **kargs, &block)
|
|
577
|
+
with_creation_lock(new(**kargs).path, lock: lock, timeout: lock_timeout) do
|
|
578
|
+
create_without_lock(overwrite: overwrite, content: content, **kargs, &block)
|
|
579
|
+
end
|
|
580
|
+
end
|
|
581
|
+
|
|
582
|
+
# Instantiate and write to disk
|
|
583
|
+
#
|
|
584
|
+
# This is the lockless plumbing, not to be used externally
|
|
585
|
+
#
|
|
586
|
+
# @return [Fs::File]
|
|
587
|
+
def self.create_without_lock(overwrite:, content:, **kargs, &block)
|
|
588
|
+
new(**kargs).tap do |instance|
|
|
589
|
+
instance.create(overwrite: overwrite, content: content, &block)
|
|
590
|
+
end
|
|
591
|
+
end
|
|
592
|
+
private_class_method :create_without_lock
|
|
593
|
+
|
|
594
|
+
# Instantiate a new File object and create it as a tempfile on disk
|
|
595
|
+
#
|
|
596
|
+
# Use this to temporarily create File objects for files that do not
|
|
597
|
+
# yet exist.
|
|
598
|
+
#
|
|
599
|
+
# @see #initialize
|
|
600
|
+
# @param overwrite [Boolean] ignored
|
|
601
|
+
# @param content [#to_s] content to be written to the file
|
|
602
|
+
# @yield [Fs::File]
|
|
603
|
+
# @return the return value of the given block
|
|
604
|
+
def self.create_temp(**kargs, &block)
|
|
605
|
+
unless block_given?
|
|
606
|
+
raise ArgumentError, "create_temp requires a block to yield the temporary Fs::File object to"
|
|
607
|
+
end
|
|
608
|
+
|
|
609
|
+
Tempfile.create([name, "." + (extensions&.first || "temp")], resolve_temp_directory(temp_directory).to_s) do |tempfile|
|
|
610
|
+
yield create(path: tempfile.path, overwrite: true, **kargs)
|
|
611
|
+
end
|
|
612
|
+
end
|
|
613
|
+
|
|
614
|
+
# Instantiate a new File object and validate that its path exists on disk
|
|
615
|
+
# and is usable, otherwise create it on disk.
|
|
616
|
+
#
|
|
617
|
+
# Use this for creating File objects for files that may or may not exist.
|
|
618
|
+
#
|
|
619
|
+
# @example
|
|
620
|
+
# Fs::File.load_or_create(path: "/some/path/file.txt") do |f|
|
|
621
|
+
# f << "file content"
|
|
622
|
+
# end
|
|
623
|
+
#
|
|
624
|
+
# #or alternatively:
|
|
625
|
+
# Fs::File.load_or_create(path: "/some/path/file.txt", content: "file content")
|
|
626
|
+
#
|
|
627
|
+
# A file which is written atomically, see {.use_atomic_writes}, is either there complete or not
|
|
628
|
+
# there at all. If it is there, we load it without taking the lock, which would otherwise be
|
|
629
|
+
# taken, and a lockfile left, for every file we merely look at.
|
|
630
|
+
#
|
|
631
|
+
# @see #initialize
|
|
632
|
+
# @param overwrite [Boolean] overwrite the file if it already exists on disk
|
|
633
|
+
# @param content [#to_s] content to be written to the file
|
|
634
|
+
# @param lock [Boolean] see {.create}
|
|
635
|
+
# @param lock_timeout [Numeric] see {.with_creation_lock}
|
|
636
|
+
# @option **kargs [Boolean] validate (true) load only: raise an exception if file is not valid
|
|
637
|
+
# @option **kargs [Boolean] skip_extension_validation (false) load only: ignored if `validate: false`
|
|
638
|
+
# @option **kargs [Boolean] skip_mime_type_validation (false) load only: ignored if `validate: false`
|
|
639
|
+
# @option **kargs [Boolean] skip_encoding_validation (false) load only: ignored if `validate: false`
|
|
640
|
+
# @yield [IO]
|
|
641
|
+
def self.load_or_create(overwrite: false, content: nil, lock: use_locks, lock_timeout: CREATION_LOCK_TIMEOUT, **kargs, &block)
|
|
642
|
+
existing = load_if_present(**kargs) if use_atomic_writes
|
|
643
|
+
|
|
644
|
+
return existing if existing
|
|
645
|
+
|
|
646
|
+
with_creation_lock(new(**kargs).path, lock: lock, timeout: lock_timeout) do
|
|
647
|
+
# Somebody else may have created it while we were waiting for the lock
|
|
648
|
+
load_if_present(**kargs) || create_without_lock(overwrite: overwrite, content: content, **kargs, &block)
|
|
649
|
+
end
|
|
650
|
+
end
|
|
651
|
+
|
|
652
|
+
# @return [Fs::File, nil] nil if there is no file; an invalid one raises, as with {.load}
|
|
653
|
+
def self.load_if_present(**kargs)
|
|
654
|
+
load(**kargs)
|
|
655
|
+
|
|
656
|
+
rescue Errors::Fs::Validation::FileDoesNotExist
|
|
657
|
+
nil
|
|
658
|
+
end
|
|
659
|
+
private_class_method :load_if_present
|
|
660
|
+
|
|
661
|
+
# Serializes concurrent {.create}/{.load_or_create} calls for the same
|
|
662
|
+
# +path+
|
|
663
|
+
#
|
|
664
|
+
# Prevents a second concurrent writer to corrupt an ongoing write
|
|
665
|
+
# process, or a reader to access an unfinished ongoing write operation.
|
|
666
|
+
#
|
|
667
|
+
# Uses a separate lock file instead of locking the resource itself in
|
|
668
|
+
# order to be able to signal locking state before the file exists.
|
|
669
|
+
#
|
|
670
|
+
# Keeps the lockfile around after use in order to prevent the following
|
|
671
|
+
# scenario:
|
|
672
|
+
#
|
|
673
|
+
# * writer 1 creates the lock file (inode = 100), acquires the lock on it
|
|
674
|
+
# * writer 2 sees the existing lock, polls until it can get lock on it
|
|
675
|
+
# * writer 1 releases the lock, deletes the file
|
|
676
|
+
# * writer 2 has retained access to the deleted lock file (inode = 100),
|
|
677
|
+
# acquires the lock
|
|
678
|
+
# * writer 3 arrives, sees no lockfile, creates one and begins work
|
|
679
|
+
# immediately, colliding with the ongoing work of writer 2
|
|
680
|
+
#
|
|
681
|
+
# Does not use a double-locking approach (advisory shared "interest" lock
|
|
682
|
+
# plus exclusive write lock) instead of the above, because from what I
|
|
683
|
+
# can see that doesn't work reliably on NFS mounts, which is my current
|
|
684
|
+
# use case.
|
|
685
|
+
#
|
|
686
|
+
# Requires an NFSv4 mount, configured with `local_lock=none` so that
|
|
687
|
+
# locks are actually forwarded to the NFS server instead of being
|
|
688
|
+
# simulated locally.
|
|
689
|
+
#
|
|
690
|
+
# @param path [Pathname, Fs::File, Fs::Directory, String]
|
|
691
|
+
# @param lock [Boolean] whether to lock at all; see {.use_locks}
|
|
692
|
+
# @param timeout [Numeric] seconds to wait for the lock before raising
|
|
693
|
+
# {Errors::Fs::LockTimeout} - most likely to trigger if whoever is
|
|
694
|
+
# holding the lock crashed without releasing it and the underlying
|
|
695
|
+
# filesystem hasn't noticed yet (eg. an unexpired NFS lease)
|
|
696
|
+
# @raise [Errors::Fs::LockTimeout]
|
|
697
|
+
# @yield
|
|
698
|
+
# @return the block's return value
|
|
699
|
+
def self.with_creation_lock(path, lock:, timeout: CREATION_LOCK_TIMEOUT)
|
|
700
|
+
return yield unless lock
|
|
701
|
+
|
|
702
|
+
path = normalize_path_input(path)
|
|
703
|
+
|
|
704
|
+
::File.open("#{path}.#{CREATION_LOCK_EXTENSION}", ::File::CREAT | ::File::RDWR) do |lockfile|
|
|
705
|
+
deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
|
|
706
|
+
|
|
707
|
+
until lockfile.flock(::File::LOCK_EX | ::File::LOCK_NB)
|
|
708
|
+
if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
|
|
709
|
+
raise Errors::Fs::LockTimeout, "could not acquire creation lock for #{path} within #{timeout}s"
|
|
710
|
+
end
|
|
711
|
+
|
|
712
|
+
sleep CREATION_LOCK_POLL_INTERVAL
|
|
713
|
+
end
|
|
714
|
+
|
|
715
|
+
yield
|
|
716
|
+
end
|
|
717
|
+
end
|
|
718
|
+
|
|
719
|
+
# Create a new `Fs::File` object by copying an existing file from `source`.
|
|
720
|
+
#
|
|
721
|
+
# The source file must be valid according to the current `Fs::File` subclass.
|
|
722
|
+
#
|
|
723
|
+
# Validation of the source file can be disabled either completely through
|
|
724
|
+
# `validate_source: false`, or selectively through the three `skip_` arguments.
|
|
725
|
+
#
|
|
726
|
+
# Provide the same `**kargs` you would provide to {.load}:
|
|
727
|
+
#
|
|
728
|
+
# @example
|
|
729
|
+
# # load an existing ProjectFile
|
|
730
|
+
# Fs::Files::ProjectJPG.load(project_file: ProjectFile.last)
|
|
731
|
+
#
|
|
732
|
+
# # create a new instance by copying an existing file
|
|
733
|
+
# Fs::Files::ProjectJPG.copy_from("/some/file.jpg", project_file: ProjectFile.last)
|
|
734
|
+
#
|
|
735
|
+
# @param source [Fs::File, Pathname, String]
|
|
736
|
+
# @param overwrite [Boolean] overwrite an existing destination file
|
|
737
|
+
# @option **kargs [Boolean] validate_source perform Fs::File validations on the source file
|
|
738
|
+
# @option **kargs [Boolean] skip_extension_validation (false) source validation: ignored if `validate_source: false`
|
|
739
|
+
# @option **kargs [Boolean] skip_mime_type_validation (false) source validation: ignored if `validate_source: false`
|
|
740
|
+
# @option **kargs [Boolean] skip_encoding_validation (false) source validation: ignored if `validate_source: false`
|
|
741
|
+
# The copy is made through a temporary file, see {.use_atomic_writes}: nobody sees the new
|
|
742
|
+
# file before it is complete.
|
|
743
|
+
#
|
|
744
|
+
# @see #initialize
|
|
745
|
+
# @raise [Errors::Fs::ReadWrite]
|
|
746
|
+
# @return [Fs::File]
|
|
747
|
+
def self.copy_from(source, overwrite: false, **kargs)
|
|
748
|
+
with_existing_file(source, overwrite: overwrite, **kargs) do |source_path, instance|
|
|
749
|
+
FileUtils.cp(source_path, instance.path)
|
|
750
|
+
end
|
|
751
|
+
end
|
|
752
|
+
|
|
753
|
+
# Create a new `Fs::File` object by moving an existing file from `source`.
|
|
754
|
+
#
|
|
755
|
+
# The source file must be valid according to the current `Fs::File` subclass.
|
|
756
|
+
#
|
|
757
|
+
# Validation of the source file can be disabled either completely through
|
|
758
|
+
# `validate_source: false`, or selectively through the three `skip_` arguments.
|
|
759
|
+
#
|
|
760
|
+
# Provide the same `**kargs` you would provide to {.load}:
|
|
761
|
+
#
|
|
762
|
+
# @example
|
|
763
|
+
# # load an existing ProjectFile
|
|
764
|
+
# Fs::Files::ProjectJPG.load(project_file: ProjectFile.last)
|
|
765
|
+
#
|
|
766
|
+
# # create a new instance by moving an existing file
|
|
767
|
+
# Fs::Files::ProjectJPG.move_from("/some/file.jpg", project_file: ProjectFile.last)
|
|
768
|
+
#
|
|
769
|
+
# @param source [Fs::File, Pathname, String]
|
|
770
|
+
# @param overwrite [Boolean] overwrite an existing destination file
|
|
771
|
+
# @option **kargs [Boolean] validate_source perform Fs::File validations on the source file
|
|
772
|
+
# @option **kargs [Boolean] skip_extension_validation (false) source validation: ignored if `validate_source: false`
|
|
773
|
+
# @option **kargs [Boolean] skip_mime_type_validation (false) source validation: ignored if `validate_source: false`
|
|
774
|
+
# @option **kargs [Boolean] skip_encoding_validation (false) source validation: ignored if `validate_source: false`
|
|
775
|
+
# A move is a rename wherever the two paths are on the same file system, which nobody can
|
|
776
|
+
# see half done. Across file systems the file is copied as {.copy_from} does, and the source
|
|
777
|
+
# is only removed once the copy is complete, so that being interrupted loses nothing.
|
|
778
|
+
#
|
|
779
|
+
# @see #initialize
|
|
780
|
+
# @raise [Errors::Fs::ReadWrite]
|
|
781
|
+
# @return [Fs::File]
|
|
782
|
+
def self.move_from(source, overwrite: false, **kargs)
|
|
783
|
+
with_existing_file(source, overwrite: overwrite, atomically: false, **kargs) do |source_path, instance|
|
|
784
|
+
::File.rename(source_path, instance.path)
|
|
785
|
+
|
|
786
|
+
rescue Errno::EXDEV
|
|
787
|
+
if use_atomic_writes
|
|
788
|
+
instance.write_atomically(overwrite: true) { |staged| FileUtils.cp(source_path, staged.path) }
|
|
789
|
+
else
|
|
790
|
+
FileUtils.cp(source_path, instance.path)
|
|
791
|
+
end
|
|
792
|
+
|
|
793
|
+
::File.delete(source_path)
|
|
794
|
+
end
|
|
795
|
+
end
|
|
796
|
+
|
|
797
|
+
# Delete an `Fs::File` object from disk
|
|
798
|
+
#
|
|
799
|
+
# @param quiet [Boolean] ignore if the file already
|
|
800
|
+
# does not exist
|
|
801
|
+
# @return [Boolean]
|
|
802
|
+
def self.delete(quiet: true, **kargs)
|
|
803
|
+
instance = new(**kargs)
|
|
804
|
+
|
|
805
|
+
return false if quiet && !instance.exists?
|
|
806
|
+
|
|
807
|
+
instance.delete
|
|
808
|
+
|
|
809
|
+
true
|
|
810
|
+
end
|
|
811
|
+
|
|
812
|
+
# Create a new `Fs::File` object by copying or moving an existing file from `source`.
|
|
813
|
+
#
|
|
814
|
+
# Tests the source file for validity according to this `Fs::File` instances validation
|
|
815
|
+
# rules, calls the given block with the source path and an instance of the target file to
|
|
816
|
+
# put it into, and afterwards `.load`s and returns a fresh target instance after the block
|
|
817
|
+
# returns.
|
|
818
|
+
#
|
|
819
|
+
# If the class writes atomically, the target instance is at a temporary path, and replaces
|
|
820
|
+
# the real file once the block returns. If not, it is at the real path, and the block writes
|
|
821
|
+
# to it in place.
|
|
822
|
+
#
|
|
823
|
+
# Validation of the source file can be disabled either completely through
|
|
824
|
+
# `validate_source: false`, or selectively through the three `skip_` arguments.
|
|
825
|
+
#
|
|
826
|
+
# @param source [Fs::File, Pathname, String]
|
|
827
|
+
# @param validate_source [Boolean] perform Fs::File validations on the source file
|
|
828
|
+
# @param overwrite [Boolean] overwrite an existing destination file
|
|
829
|
+
# @param atomically [Boolean] hand the block a temporary target, which replaces the real
|
|
830
|
+
# file once the block returns; for blocks which put the file in place by themselves
|
|
831
|
+
# @option **kargs [Boolean] skip_extension_validation (false) source validation: ignored if `validate_source: false`
|
|
832
|
+
# @option **kargs [Boolean] skip_mime_type_validation (false) source validation: ignored if `validate_source: false`
|
|
833
|
+
# @option **kargs [Boolean] skip_encoding_validation (false) source validation: ignored if `validate_source: false`
|
|
834
|
+
# @see #initialize
|
|
835
|
+
# @yieldparam source_path [Pathname] the path to the source file
|
|
836
|
+
# @yieldparam instance [Fs::File] where the block is to put the file; it does not exist yet
|
|
837
|
+
# (and is not the one returned to the caller!)
|
|
838
|
+
# @raise [Errors::Fs::ReadWrite]
|
|
839
|
+
# @return [Fs::File]
|
|
840
|
+
def self.with_existing_file(source, validate_source: true, overwrite: false, atomically: use_atomic_writes, **kargs)
|
|
841
|
+
source_path = normalize_path_input(source)
|
|
842
|
+
|
|
843
|
+
# We load and discard the source file just to validate it by the target
|
|
844
|
+
# classes' rules. No reason to start copying if it's the wrong type or
|
|
845
|
+
# otherwise broken.
|
|
846
|
+
begin
|
|
847
|
+
load(path: source_path, validate: validate_source, **kargs)
|
|
848
|
+
rescue Errors::Fs::ReadWrite
|
|
849
|
+
raise Errors::Fs::ReadWrite, "unsuitable source: #{source_path}"
|
|
850
|
+
end
|
|
851
|
+
|
|
852
|
+
instance = new(**kargs)
|
|
853
|
+
|
|
854
|
+
# We're not using Fs::File.exists?, because here we
|
|
855
|
+
# are only interested if something physically exists
|
|
856
|
+
# in the filesystem location we are about to write to,
|
|
857
|
+
# not whether anything existing there is otherwise valid.
|
|
858
|
+
if !overwrite && instance.exists?
|
|
859
|
+
raise Errors::Fs::ReadWrite, "#{instance.path} already exists"
|
|
860
|
+
end
|
|
861
|
+
|
|
862
|
+
begin
|
|
863
|
+
if atomically
|
|
864
|
+
instance.write_atomically(overwrite: true) { |staged| yield source_path, staged }
|
|
865
|
+
else
|
|
866
|
+
yield source_path, instance
|
|
867
|
+
end
|
|
868
|
+
rescue Errors::Fs::BaseDirectory
|
|
869
|
+
# Not the block's doing, and not ours to explain away: pass it on as it is
|
|
870
|
+
raise
|
|
871
|
+
rescue StandardError
|
|
872
|
+
raise Errors::Fs::ReadWrite
|
|
873
|
+
end
|
|
874
|
+
|
|
875
|
+
load(**kargs)
|
|
876
|
+
end
|
|
877
|
+
private_class_method :with_existing_file
|
|
878
|
+
|
|
879
|
+
# Determines a match between a String and a list of Strings
|
|
880
|
+
# or regular expressions
|
|
881
|
+
#
|
|
882
|
+
# @example
|
|
883
|
+
# string_config_match?("yes", within: ["no", "maybe", /yes/])
|
|
884
|
+
# # => true
|
|
885
|
+
#
|
|
886
|
+
# Returns default `true` when the `within` config is `nil`.
|
|
887
|
+
#
|
|
888
|
+
# Consider this method to be private; it cannot be made
|
|
889
|
+
# explicitely so, because we need to reuse it in instance
|
|
890
|
+
# context, and at least I for one have no idea how to do so
|
|
891
|
+
# without resorting to idiotic contortions.
|
|
892
|
+
#
|
|
893
|
+
# @private
|
|
894
|
+
# @param value [String, Symbol, #to_s]
|
|
895
|
+
# @param within [Array<String,Symbol,#to_s,Regexp>, nil]
|
|
896
|
+
# @return [Boolean]
|
|
897
|
+
def self.string_matches_config?(value, within:)
|
|
898
|
+
return true unless within
|
|
899
|
+
|
|
900
|
+
within.find do |match|
|
|
901
|
+
case match
|
|
902
|
+
when String
|
|
903
|
+
value.to_s == match
|
|
904
|
+
when Symbol
|
|
905
|
+
value.to_s == match.to_s
|
|
906
|
+
when Regexp
|
|
907
|
+
value.to_s
|
|
908
|
+
.match?(match)
|
|
909
|
+
end
|
|
910
|
+
end || false
|
|
911
|
+
end
|
|
912
|
+
|
|
913
|
+
# Converts a variety of inputs to a {Pathname}, such as
|
|
914
|
+
# {Fs::File}, {Fs::Directory} or {String}
|
|
915
|
+
#
|
|
916
|
+
# @private
|
|
917
|
+
# @param input [Pathname, Fs::File, Fs::Directory, String]
|
|
918
|
+
# @return [Pathname, nil]
|
|
919
|
+
def self.normalize_path_input(input)
|
|
920
|
+
return input if input.is_a?(Pathname)
|
|
921
|
+
return input.path if input.respond_to?(:path)
|
|
922
|
+
return input.to_path if input.respond_to?(:to_path)
|
|
923
|
+
return Pathname.new(input) if input.is_a?(String)
|
|
924
|
+
end
|
|
925
|
+
|
|
926
|
+
# The directory a {.temp_directory} or {.atomic_write_directory} setting stands for
|
|
927
|
+
#
|
|
928
|
+
# @private
|
|
929
|
+
# @param setting [Symbol, Class, String] `:system`, `:alongside`, an {Fs::Directory}
|
|
930
|
+
# subclass or its name
|
|
931
|
+
# @param alongside [Pathname, nil] what `:alongside` stands for, if anything
|
|
932
|
+
# @raise [ArgumentError] if the setting is not one of the above
|
|
933
|
+
# @return [Pathname]
|
|
934
|
+
def self.resolve_temp_directory(setting, alongside: nil)
|
|
935
|
+
case setting
|
|
936
|
+
when :alongside then alongside || raise(ArgumentError, "there is nothing to be alongside of")
|
|
937
|
+
when :system then Pathname.new(Dir.tmpdir)
|
|
938
|
+
when String then setting.constantize.new.path
|
|
939
|
+
when Class then setting.new.path
|
|
940
|
+
else
|
|
941
|
+
raise ArgumentError, "expected :system, :alongside, an Fs::Directory subclass or its name, not #{setting.inspect}"
|
|
942
|
+
end
|
|
943
|
+
end
|
|
944
|
+
|
|
945
|
+
# You need to pass in either a full path, or all parameters required
|
|
946
|
+
# for the class to build the path itself. Which parameters those are
|
|
947
|
+
# depends on the specific subclass:
|
|
948
|
+
#
|
|
949
|
+
# * a full `:path` always works: `new(path: "/some/file.txt")`
|
|
950
|
+
# * for subclasses that have a `directory` configured, just the
|
|
951
|
+
# `:filename` is sufficient: `new(filename: "file.txt")`
|
|
952
|
+
# * for subclasses that have a `directory` and an `extension` configured,
|
|
953
|
+
# just the `basename` is sufficient: `new(basename: "file")`
|
|
954
|
+
# * for subclasses that take care of basename and extension, just pass
|
|
955
|
+
# in a `directory`: `new(directory: "/foo")`
|
|
956
|
+
# * some subclasses handle naming themselves and require you to only pass
|
|
957
|
+
# in a related object instead: `new(project: Project.last)`
|
|
958
|
+
#
|
|
959
|
+
# @param path [String, Pathname, Fs::File] the full path to the file on disk
|
|
960
|
+
# @param filename [String, Pathname] the full filename with file extension
|
|
961
|
+
# @param basename [String] the filename without file extension
|
|
962
|
+
# @param directory [String, Pathname] the directory path in which the file will
|
|
963
|
+
# be stored
|
|
964
|
+
# @param kargs any other parameters as required by the File subclass
|
|
965
|
+
def initialize(path: nil, filename: nil, basename: nil, directory: nil, **kargs)
|
|
966
|
+
process_required_arguments(**kargs)
|
|
967
|
+
|
|
968
|
+
if directory
|
|
969
|
+
@directory = Fs::Directory.new(base_path: directory)
|
|
970
|
+
|
|
971
|
+
elsif self.class.directory
|
|
972
|
+
directory_kargs =
|
|
973
|
+
self.class.directory_args_proc ? instance_exec(&self.class.directory_args_proc) : kargs
|
|
974
|
+
|
|
975
|
+
@directory =
|
|
976
|
+
self.class
|
|
977
|
+
.directory
|
|
978
|
+
.new(**directory_kargs)
|
|
979
|
+
end
|
|
980
|
+
|
|
981
|
+
basename = basename || self.basename
|
|
982
|
+
|
|
983
|
+
@path =
|
|
984
|
+
case
|
|
985
|
+
when path && normalize_path_input(path)
|
|
986
|
+
normalize_path_input(path)
|
|
987
|
+
|
|
988
|
+
when directory_path && self.class.extensions && basename
|
|
989
|
+
directory_path / "#{basename}.#{self.class.extensions.first}"
|
|
990
|
+
|
|
991
|
+
when directory_path && filename
|
|
992
|
+
directory_path / filename
|
|
993
|
+
|
|
994
|
+
when self.class.get_path_proc
|
|
995
|
+
Pathname.new(
|
|
996
|
+
instance_eval(&self.class.get_path_proc)
|
|
997
|
+
)
|
|
998
|
+
|
|
999
|
+
else
|
|
1000
|
+
raise ArgumentError, "provide either a :path, a `get_path_from` block, "\
|
|
1001
|
+
"or set `directory` and `extension` and provide a basename"
|
|
1002
|
+
end
|
|
1003
|
+
end
|
|
1004
|
+
|
|
1005
|
+
# The directory path as configured by the `Fs::Directory` instance
|
|
1006
|
+
# associated to this `File` instance, if any
|
|
1007
|
+
#
|
|
1008
|
+
# @return [Pathname, nil]
|
|
1009
|
+
def directory_path
|
|
1010
|
+
return nil unless directory.present?
|
|
1011
|
+
|
|
1012
|
+
if self.class.directory_subdir
|
|
1013
|
+
directory.path / self.class.directory_subdir
|
|
1014
|
+
else
|
|
1015
|
+
directory.path
|
|
1016
|
+
end
|
|
1017
|
+
end
|
|
1018
|
+
|
|
1019
|
+
# The directory containing the file
|
|
1020
|
+
#
|
|
1021
|
+
# @example
|
|
1022
|
+
# Fs::File.new(path: "/home/example.txt").dirname
|
|
1023
|
+
# # => #<Pathname:/home>
|
|
1024
|
+
#
|
|
1025
|
+
# @return [Pathname]
|
|
1026
|
+
def dirname
|
|
1027
|
+
path&.dirname
|
|
1028
|
+
end
|
|
1029
|
+
|
|
1030
|
+
# The full filename including file extension
|
|
1031
|
+
#
|
|
1032
|
+
# @example
|
|
1033
|
+
# Fs::File.new(path: "/home/example.txt").filename
|
|
1034
|
+
# # => #<Pathname:example.txt>
|
|
1035
|
+
#
|
|
1036
|
+
# @return [Pathname]
|
|
1037
|
+
def filename
|
|
1038
|
+
path&.basename
|
|
1039
|
+
end
|
|
1040
|
+
|
|
1041
|
+
# The filename excluding file extension
|
|
1042
|
+
#
|
|
1043
|
+
# @example
|
|
1044
|
+
# Fs::File.new(path: "/home/example.txt").basename
|
|
1045
|
+
# # => #<Pathname:example>
|
|
1046
|
+
#
|
|
1047
|
+
# @return [Pathname]
|
|
1048
|
+
def basename
|
|
1049
|
+
path&.basename(".*")
|
|
1050
|
+
end
|
|
1051
|
+
|
|
1052
|
+
# The file extension
|
|
1053
|
+
#
|
|
1054
|
+
# @example
|
|
1055
|
+
# Fs::File.new(path: "/home/example.txt").extension
|
|
1056
|
+
# # => "txt"
|
|
1057
|
+
#
|
|
1058
|
+
# @return [String]
|
|
1059
|
+
def extension
|
|
1060
|
+
path&.extname[1..-1]
|
|
1061
|
+
end
|
|
1062
|
+
|
|
1063
|
+
def exists?
|
|
1064
|
+
path.exist?
|
|
1065
|
+
end
|
|
1066
|
+
alias_method :exist?, :exists?
|
|
1067
|
+
|
|
1068
|
+
# Copies this file to `destination`; returns a new Fs::File instance
|
|
1069
|
+
#
|
|
1070
|
+
# If the destination is a directory, the copied file will
|
|
1071
|
+
# retain its current filename.
|
|
1072
|
+
#
|
|
1073
|
+
# Please note that you'll receive a generic `Fs::File`
|
|
1074
|
+
# object back, even if `self` is some other subclass.
|
|
1075
|
+
#
|
|
1076
|
+
# This is due to the fact that `target_path` might not
|
|
1077
|
+
# be compatible with the configuration and expectations
|
|
1078
|
+
# of `self`.
|
|
1079
|
+
#
|
|
1080
|
+
# @param destination [Pathname, Fs::File, Fs::Directory, String]
|
|
1081
|
+
# @return [Fs::File]
|
|
1082
|
+
def copy_to(destination)
|
|
1083
|
+
destination =
|
|
1084
|
+
normalize_path_input(destination)
|
|
1085
|
+
|
|
1086
|
+
if destination.directory?
|
|
1087
|
+
destination = destination/filename
|
|
1088
|
+
end
|
|
1089
|
+
|
|
1090
|
+
FileUtils.cp(path, destination)
|
|
1091
|
+
|
|
1092
|
+
File.new(path: destination)
|
|
1093
|
+
end
|
|
1094
|
+
|
|
1095
|
+
# Moves this file to `destination`; returns a new Fs::File instance
|
|
1096
|
+
#
|
|
1097
|
+
# If the destination is a directory, the copied file will
|
|
1098
|
+
# retain its current filename.
|
|
1099
|
+
#
|
|
1100
|
+
# @param destination [Pathname, Fs::File, Fs::Directory, String]
|
|
1101
|
+
# @return [Fs::File]
|
|
1102
|
+
def move_to(destination)
|
|
1103
|
+
destination =
|
|
1104
|
+
normalize_path_input(destination)
|
|
1105
|
+
|
|
1106
|
+
if destination.directory?
|
|
1107
|
+
destination = destination/filename
|
|
1108
|
+
end
|
|
1109
|
+
|
|
1110
|
+
FileUtils.mv(path, destination)
|
|
1111
|
+
|
|
1112
|
+
self.class.load(path: destination, **required_arguments_given)
|
|
1113
|
+
end
|
|
1114
|
+
|
|
1115
|
+
# Ensure the file is present, readable, writable, non-zero in size and of the
|
|
1116
|
+
# expected file extension, MIME type and encoding
|
|
1117
|
+
#
|
|
1118
|
+
# @param skip_extension_validation [Boolean]
|
|
1119
|
+
# @param skip_mime_type_validation [Boolean]
|
|
1120
|
+
# @param skip_encoding_validation [Boolean]
|
|
1121
|
+
# @raise [Errors::Fs::Validation::FileDoesNotExist, Errors::Fs::Validation::FileEmpty]
|
|
1122
|
+
# @raise [Errors::Fs::Validation::FileNotReadable, Errors::Fs::Validation::FileNotWriteable]
|
|
1123
|
+
# @raise [Errors::Fs::Validation::UnsupportedExtension, Errors::Fs::Validation::UnsupportedMimeType]
|
|
1124
|
+
# @raise [Errors::Fs::Validation::UnsupportedEncoding]
|
|
1125
|
+
# @return [void]
|
|
1126
|
+
def validate!(skip_extension_validation: false, skip_mime_type_validation: false,
|
|
1127
|
+
skip_encoding_validation: false)
|
|
1128
|
+
migrate_from_legacy_location! if self.class.legacy_klass
|
|
1129
|
+
|
|
1130
|
+
# These errors reach users, so they carry no message: the path is their label, and
|
|
1131
|
+
# whoever translates them decides what to tell. For the `Unsupported*` ones the offending
|
|
1132
|
+
# value is the subject.
|
|
1133
|
+
Errors::Fs::Validation::FileDoesNotExist.raise(label: path.to_s) unless path.exist?
|
|
1134
|
+
Errors::Fs::Validation::FileEmpty.raise(label: path.to_s) unless self.class.allows_empty_files || path.size?
|
|
1135
|
+
Errors::Fs::Validation::FileNotReadable.raise(label: path.to_s) unless path.readable?
|
|
1136
|
+
Errors::Fs::Validation::FileNotWriteable.raise(label: path.to_s) unless path.writable?
|
|
1137
|
+
|
|
1138
|
+
unless skip_extension_validation
|
|
1139
|
+
unless string_matches_config?(extension, within: self.class.extensions)
|
|
1140
|
+
Errors::Fs::Validation::UnsupportedExtension.raise(label: path.to_s, subject: extension)
|
|
1141
|
+
end
|
|
1142
|
+
end
|
|
1143
|
+
|
|
1144
|
+
unless skip_mime_type_validation
|
|
1145
|
+
unless string_matches_config?(mime_type, within: self.class.mime_types)
|
|
1146
|
+
Errors::Fs::Validation::UnsupportedMimeType.raise(label: path.to_s, subject: mime_type)
|
|
1147
|
+
end
|
|
1148
|
+
end
|
|
1149
|
+
|
|
1150
|
+
unless skip_encoding_validation
|
|
1151
|
+
unless string_matches_config?(encoding, within: self.class.encodings)
|
|
1152
|
+
Errors::Fs::Validation::UnsupportedEncoding.raise(label: path.to_s, subject: encoding)
|
|
1153
|
+
end
|
|
1154
|
+
end
|
|
1155
|
+
|
|
1156
|
+
custom_validations
|
|
1157
|
+
end
|
|
1158
|
+
|
|
1159
|
+
# Is this file present, readable, writable, non-zero in size and of the
|
|
1160
|
+
# expected file extension?
|
|
1161
|
+
#
|
|
1162
|
+
# @see validate!
|
|
1163
|
+
# @return [Boolean]
|
|
1164
|
+
def valid?(**kargs)
|
|
1165
|
+
begin
|
|
1166
|
+
validate!(**kargs)
|
|
1167
|
+
true
|
|
1168
|
+
rescue Errors::Fs::ReadWrite
|
|
1169
|
+
false
|
|
1170
|
+
end
|
|
1171
|
+
end
|
|
1172
|
+
|
|
1173
|
+
# Hook to be called after {File.load} or {File.load_or_create}
|
|
1174
|
+
# has been called for a file that exists on disk
|
|
1175
|
+
#
|
|
1176
|
+
# In here, you can for example fetch the existing file's content
|
|
1177
|
+
# into instance variables.
|
|
1178
|
+
#
|
|
1179
|
+
# @return [void]
|
|
1180
|
+
def load
|
|
1181
|
+
end
|
|
1182
|
+
|
|
1183
|
+
# Create this file on disk
|
|
1184
|
+
#
|
|
1185
|
+
#
|
|
1186
|
+
# @example
|
|
1187
|
+
# file Fs::File.new(path: "/some/path/file.txt")
|
|
1188
|
+
#
|
|
1189
|
+
# file.create(path: "/some/path/file.txt") do |f|
|
|
1190
|
+
# f << "file content"
|
|
1191
|
+
# end
|
|
1192
|
+
#
|
|
1193
|
+
# #or alternatively:
|
|
1194
|
+
# file.create(path: "/some/path/file.txt", content: "file content")
|
|
1195
|
+
#
|
|
1196
|
+
# @see #initialize
|
|
1197
|
+
# @param overwrite [Boolean] overwrite the file if it already exists on disk
|
|
1198
|
+
# @param content [#to_s] content to be written to the file
|
|
1199
|
+
# @yield [IO] optionally yields an IO object, similar to `File.open`
|
|
1200
|
+
# @return [void]
|
|
1201
|
+
def create(overwrite: false, content: nil, &block)
|
|
1202
|
+
if self.class.use_atomic_writes
|
|
1203
|
+
write_atomically(overwrite: overwrite) do |temp_file|
|
|
1204
|
+
write_content_to(temp_file.path, content: content, &block)
|
|
1205
|
+
end
|
|
1206
|
+
|
|
1207
|
+
else
|
|
1208
|
+
validate_writeability(overwrite: overwrite)
|
|
1209
|
+
|
|
1210
|
+
write_content_to(path, content: content, &block)
|
|
1211
|
+
end
|
|
1212
|
+
|
|
1213
|
+
rescue IOError, EOFError, SystemCallError
|
|
1214
|
+
raise Errors::Fs::ReadWrite
|
|
1215
|
+
end
|
|
1216
|
+
|
|
1217
|
+
# Writes this file through a temporary one, so that nobody ever sees it half-written.
|
|
1218
|
+
#
|
|
1219
|
+
# Yields an instance of our class, with our arguments, at a temporary path. The block
|
|
1220
|
+
# writes to that, and once it returns, the result is moved to our path. If the block raises,
|
|
1221
|
+
# nothing is left behind and an existing file stays as it was. Use this in your own `#create`,
|
|
1222
|
+
# wherever you would otherwise write to `path`.
|
|
1223
|
+
#
|
|
1224
|
+
# The yielded instance does not exist on disk yet, and is not validated. It is meant for
|
|
1225
|
+
# whatever the block needs a file object for, such as `png.rotate` or `output: png`.
|
|
1226
|
+
#
|
|
1227
|
+
# Does not keep concurrent writers from doing the work twice, see {.with_creation_lock}.
|
|
1228
|
+
#
|
|
1229
|
+
# @example
|
|
1230
|
+
# def create(overwrite: false, **kargs)
|
|
1231
|
+
# write_atomically(overwrite: overwrite) do |temp_file|
|
|
1232
|
+
# Shell::Convert.exec(input: original, output: temp_file, **kargs).raise_failures
|
|
1233
|
+
# temp_file.rotate(degrees: 90)
|
|
1234
|
+
# end
|
|
1235
|
+
# end
|
|
1236
|
+
#
|
|
1237
|
+
# @see Fs::AtomicWrite
|
|
1238
|
+
# @see .atomic_write_directory
|
|
1239
|
+
# @param overwrite [Boolean] overwrite an existing file instead of raising an exception
|
|
1240
|
+
# @yieldparam temp_file [Fs::File] an instance of our class at the temporary path
|
|
1241
|
+
# @raise [Errors::Fs::ReadWrite]
|
|
1242
|
+
# @return [void]
|
|
1243
|
+
def write_atomically(overwrite: false)
|
|
1244
|
+
validate_writeability(overwrite: overwrite)
|
|
1245
|
+
|
|
1246
|
+
Fs::AtomicWrite.perform(path, directory: self.class.atomic_write_directory) do |temp_path|
|
|
1247
|
+
yield instance_at(temp_path)
|
|
1248
|
+
end
|
|
1249
|
+
end
|
|
1250
|
+
|
|
1251
|
+
# Opens the file, optionally yielding it to a block.
|
|
1252
|
+
#
|
|
1253
|
+
# With a block, behaves like +::File.open+: yields the open +::File+ to
|
|
1254
|
+
# the block, closes it on exit, and returns the block's value.
|
|
1255
|
+
# Without a block, returns an open +::File+; caller is responsible for
|
|
1256
|
+
# closing it.
|
|
1257
|
+
#
|
|
1258
|
+
# @param binary [Boolean] open in binary mode (+rb+ vs +r+)
|
|
1259
|
+
# @yieldparam file [::File]
|
|
1260
|
+
# @yieldreturn [Object]
|
|
1261
|
+
# @return [::File, Object] open +::File+ without a block, or block return value
|
|
1262
|
+
def open(binary: false, &block)
|
|
1263
|
+
mode = binary ? "rb" : "r"
|
|
1264
|
+
|
|
1265
|
+
::File.open(path, mode, &block)
|
|
1266
|
+
end
|
|
1267
|
+
|
|
1268
|
+
# Read the on-disk content
|
|
1269
|
+
#
|
|
1270
|
+
# @option **kargs see File.read
|
|
1271
|
+
# @return [String]
|
|
1272
|
+
def read(**kargs)
|
|
1273
|
+
::File.read(path, mode: "r", **kargs)
|
|
1274
|
+
end
|
|
1275
|
+
|
|
1276
|
+
# Read the on-disk content as binary
|
|
1277
|
+
#
|
|
1278
|
+
# @option **kargs see File.read
|
|
1279
|
+
# @return [String]
|
|
1280
|
+
def read_binary(**kargs)
|
|
1281
|
+
::File.read(path, mode: "rb", **kargs)
|
|
1282
|
+
end
|
|
1283
|
+
|
|
1284
|
+
# Returns a proxy for the `variant_name` variant
|
|
1285
|
+
#
|
|
1286
|
+
# @see FileVariantProxy
|
|
1287
|
+
#
|
|
1288
|
+
# @param variant_name [Symbol]
|
|
1289
|
+
# @return [FileVariantProxy] an instance of FileVariantProxy
|
|
1290
|
+
def variant(variant_name)
|
|
1291
|
+
return nil unless self.class.variants[variant_name]
|
|
1292
|
+
|
|
1293
|
+
self.class
|
|
1294
|
+
.variants[variant_name]
|
|
1295
|
+
.to_proxy(parent: self)
|
|
1296
|
+
end
|
|
1297
|
+
|
|
1298
|
+
# Ensure all variants marked as _standard_ exist on disk
|
|
1299
|
+
#
|
|
1300
|
+
# All variants marked as _standard_ by calling
|
|
1301
|
+
# {Fs::FileVariantBuilder#include_in_standard_set} will be created
|
|
1302
|
+
# on disk in one go.
|
|
1303
|
+
#
|
|
1304
|
+
# @return [void]
|
|
1305
|
+
def prepare_standard_variants
|
|
1306
|
+
standard_variants.each(&:load_or_create)
|
|
1307
|
+
end
|
|
1308
|
+
|
|
1309
|
+
# All variants marked as _standard_ for easy iteration
|
|
1310
|
+
#
|
|
1311
|
+
# If you call {Fs::FileVariantBuilder#include_in_standard_set} while
|
|
1312
|
+
# defining a variant, it will be included in this set. Its purpose
|
|
1313
|
+
# is to allow you to iterate over them yourself when creating
|
|
1314
|
+
# them is too resource-intensive to create them synchronously via
|
|
1315
|
+
# {#prepare_standard_variants}.
|
|
1316
|
+
#
|
|
1317
|
+
# When given a block, yields both the variant name and the variant
|
|
1318
|
+
# once for every standard variant.
|
|
1319
|
+
#
|
|
1320
|
+
# @yieldparam name [Symbol] the current standard variants name
|
|
1321
|
+
# @yieldparam variant [FileVariantProxy] an instance of the current
|
|
1322
|
+
# FileVariantProxy
|
|
1323
|
+
# @return [Array<FileVariantProxy>, void] `void` if given a block
|
|
1324
|
+
def standard_variants
|
|
1325
|
+
return [] unless self.class.standard_variants
|
|
1326
|
+
|
|
1327
|
+
if block_given?
|
|
1328
|
+
self.class
|
|
1329
|
+
.standard_variants
|
|
1330
|
+
.each { |variant_name| yield(variant_name, variant(variant_name)) }
|
|
1331
|
+
else
|
|
1332
|
+
self.class
|
|
1333
|
+
.standard_variants
|
|
1334
|
+
.map { |variant_name| variant(variant_name) }
|
|
1335
|
+
end
|
|
1336
|
+
end
|
|
1337
|
+
|
|
1338
|
+
# Create and yield a temporary instance of this file
|
|
1339
|
+
#
|
|
1340
|
+
# The instance will be yielded to a provided block and automatically
|
|
1341
|
+
# removed after the block has returned.
|
|
1342
|
+
#
|
|
1343
|
+
# It is not recommended to retain a reference to the instance outside
|
|
1344
|
+
# of the block, because the underlying file will be gone.
|
|
1345
|
+
#
|
|
1346
|
+
# @param content [#to_s] optional: content to be written to the file
|
|
1347
|
+
# @yield [Fs::File] yields an instance of this variants class
|
|
1348
|
+
# @return the return value of the given block
|
|
1349
|
+
def create_temp(content: nil, **kargs)
|
|
1350
|
+
unless exist?
|
|
1351
|
+
raise RuntimeError, "cannot create_temp for a file that does not exist"
|
|
1352
|
+
end
|
|
1353
|
+
|
|
1354
|
+
unless block_given?
|
|
1355
|
+
raise ArgumentError, "create_temp requires a block to yield the temporary Fs::File object to"
|
|
1356
|
+
end
|
|
1357
|
+
|
|
1358
|
+
Tempfile.create([basename.to_s, "." + extension], Fs::File.resolve_temp_directory(self.class.temp_directory).to_s) do |tempfile|
|
|
1359
|
+
copy_to(tempfile.path)
|
|
1360
|
+
|
|
1361
|
+
yield self.class.load(path: tempfile.path, **required_arguments_given)
|
|
1362
|
+
end
|
|
1363
|
+
end
|
|
1364
|
+
|
|
1365
|
+
# The files MIME type
|
|
1366
|
+
#
|
|
1367
|
+
# @raise [Shell::Errors::CommandUnsuccessful]
|
|
1368
|
+
# @return [String]
|
|
1369
|
+
def mime_type
|
|
1370
|
+
Shell::File.mime_type(self)
|
|
1371
|
+
.raise_failures
|
|
1372
|
+
.value
|
|
1373
|
+
end
|
|
1374
|
+
|
|
1375
|
+
# The files content in Base64
|
|
1376
|
+
#
|
|
1377
|
+
# @raise [Shell::Errors::CommandUnsuccessful]
|
|
1378
|
+
# @return [String]
|
|
1379
|
+
def base64
|
|
1380
|
+
Shell::Base64.encode(self)
|
|
1381
|
+
.raise_failures
|
|
1382
|
+
.value
|
|
1383
|
+
end
|
|
1384
|
+
|
|
1385
|
+
# The files MIME encoding
|
|
1386
|
+
#
|
|
1387
|
+
# @raise [Shell::Errors::CommandUnsuccessful]
|
|
1388
|
+
# @return [String]
|
|
1389
|
+
def encoding
|
|
1390
|
+
Shell::File.mime_encoding(self)
|
|
1391
|
+
.raise_failures
|
|
1392
|
+
.value
|
|
1393
|
+
end
|
|
1394
|
+
|
|
1395
|
+
# Do we pass a ClamAV virus scan?
|
|
1396
|
+
#
|
|
1397
|
+
# @return [Boolean]
|
|
1398
|
+
def clamav_safe?
|
|
1399
|
+
Shell::ClamAv.safe?(self)
|
|
1400
|
+
end
|
|
1401
|
+
|
|
1402
|
+
# The files SHA512 hash in hex
|
|
1403
|
+
#
|
|
1404
|
+
# @raise [Shell::Errors::CommandUnsuccessful]
|
|
1405
|
+
# @return [String]
|
|
1406
|
+
def sha512_hexdigest
|
|
1407
|
+
Shell::OpenSsl.sha512_hexdigest(self)
|
|
1408
|
+
.raise_failures
|
|
1409
|
+
.value
|
|
1410
|
+
end
|
|
1411
|
+
|
|
1412
|
+
# The file size in bytes
|
|
1413
|
+
#
|
|
1414
|
+
# @return [Integer]
|
|
1415
|
+
def size
|
|
1416
|
+
::File.size(path)
|
|
1417
|
+
end
|
|
1418
|
+
|
|
1419
|
+
# The files modification time
|
|
1420
|
+
#
|
|
1421
|
+
# @return [Time]
|
|
1422
|
+
def mtime
|
|
1423
|
+
::File.mtime(path)
|
|
1424
|
+
end
|
|
1425
|
+
|
|
1426
|
+
private
|
|
1427
|
+
|
|
1428
|
+
# @see self.string_matches_config
|
|
1429
|
+
def string_matches_config?(value, within:)
|
|
1430
|
+
self.class.string_matches_config?(value, within: within)
|
|
1431
|
+
end
|
|
1432
|
+
|
|
1433
|
+
# No-op, to be overloaded in subclasses
|
|
1434
|
+
#
|
|
1435
|
+
# Overloads are expected to raise in case of validation failures
|
|
1436
|
+
def custom_validations
|
|
1437
|
+
end
|
|
1438
|
+
|
|
1439
|
+
# No-op in the overwhelming majority of cases where nothing needs
|
|
1440
|
+
# migrating - runs on every `#validate!` call for a class with a
|
|
1441
|
+
# `legacy` block, so it must stay cheap and silent when there's
|
|
1442
|
+
# nothing to do. See {Fs::Directory#migrate_from_legacy_location!}
|
|
1443
|
+
# for the equivalent on the Directory side.
|
|
1444
|
+
#
|
|
1445
|
+
# @return [void]
|
|
1446
|
+
def migrate_from_legacy_location!
|
|
1447
|
+
return if path.exist?
|
|
1448
|
+
|
|
1449
|
+
legacy_path = self.class.legacy_klass.new(when_missing: :ignore, **required_arguments_given).path
|
|
1450
|
+
|
|
1451
|
+
return unless legacy_path.exist? && legacy_path != path
|
|
1452
|
+
|
|
1453
|
+
path.dirname.mkpath
|
|
1454
|
+
FileUtils.mv(legacy_path.to_s, path.to_s)
|
|
1455
|
+
|
|
1456
|
+
delete_legacy_directory(legacy_path.dirname) if self.class.legacy_safely_delete_directory
|
|
1457
|
+
rescue Errno::ENOENT
|
|
1458
|
+
# Lost a race with another process/thread doing the same migration
|
|
1459
|
+
# concurrently - fine, the presence checks above will find `path`
|
|
1460
|
+
# already present.
|
|
1461
|
+
end
|
|
1462
|
+
|
|
1463
|
+
# `rmdir`, not `rm_rf` - only removes `directory` if it is genuinely
|
|
1464
|
+
# empty, so an unexpected extra file left behind by something else
|
|
1465
|
+
# sharing this legacy directory is never destroyed, just kept.
|
|
1466
|
+
#
|
|
1467
|
+
# @param directory [Pathname]
|
|
1468
|
+
# @return [void]
|
|
1469
|
+
def delete_legacy_directory(directory)
|
|
1470
|
+
directory.rmdir
|
|
1471
|
+
rescue Errno::ENOTEMPTY, Errno::ENOENT
|
|
1472
|
+
end
|
|
1473
|
+
|
|
1474
|
+
# @see {Fs::File.normalize_path_input}
|
|
1475
|
+
def normalize_path_input(input)
|
|
1476
|
+
self.class.normalize_path_input(input)
|
|
1477
|
+
end
|
|
1478
|
+
|
|
1479
|
+
# @param path [Pathname]
|
|
1480
|
+
# @return [Fs::File] an instance of our class and with our arguments, at `path`
|
|
1481
|
+
def instance_at(path)
|
|
1482
|
+
self.class.new(path: path, **required_arguments_given)
|
|
1483
|
+
end
|
|
1484
|
+
|
|
1485
|
+
# Writes our content, as given or as configured, to `destination`
|
|
1486
|
+
#
|
|
1487
|
+
# @param destination [Pathname] our path, or a temporary one
|
|
1488
|
+
# @param content [#to_s, nil]
|
|
1489
|
+
# @yield [IO] optionally yields an IO object, similar to `File.open`
|
|
1490
|
+
# @return [void]
|
|
1491
|
+
def write_content_to(destination, content: nil, &block)
|
|
1492
|
+
if content
|
|
1493
|
+
::File.open(destination, "wb") { |f| f << content }
|
|
1494
|
+
|
|
1495
|
+
elsif block
|
|
1496
|
+
::File.open(destination, "wb", &block)
|
|
1497
|
+
|
|
1498
|
+
elsif self.class.content_proc
|
|
1499
|
+
content = instance_eval(&self.class.content_proc)
|
|
1500
|
+
::File.open(destination, "wb") { |f| f << content }
|
|
1501
|
+
|
|
1502
|
+
else
|
|
1503
|
+
::File.open(destination, "wb").close
|
|
1504
|
+
end
|
|
1505
|
+
end
|
|
1506
|
+
|
|
1507
|
+
# @param overwrite [Boolean] ignore the existence of an
|
|
1508
|
+
# existing file
|
|
1509
|
+
# @raise [Errors::Fs::ReadWrite] if a file exists at our path
|
|
1510
|
+
# and `overwrite` is not set
|
|
1511
|
+
# @raise [Errors::Fs::ReadWrite] if something other than a file
|
|
1512
|
+
# exists at our path, such as a directory
|
|
1513
|
+
# @raise [Errors::Fs::ReadWrite] if our path is not writeable, eg.
|
|
1514
|
+
# due to a lack of permissions
|
|
1515
|
+
def validate_writeability(overwrite: false)
|
|
1516
|
+
if path.exist?
|
|
1517
|
+
raise Errors::Fs::ReadWrite, "File #{path} already exists" if path.file? && !overwrite
|
|
1518
|
+
raise Errors::Fs::ReadWrite, "Path #{path} already exists and is of type #{path.ftype}" if !path.file?
|
|
1519
|
+
end
|
|
1520
|
+
|
|
1521
|
+
raise Errors::Fs::ReadWrite, "Cannot write to #{path.dirname}" unless path.dirname.writable?
|
|
1522
|
+
end
|
|
1523
|
+
end
|
|
1524
|
+
end
|