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.
Files changed (42) hide show
  1. checksums.yaml +7 -0
  2. data/CHANGELOG.md +3 -0
  3. data/LICENSE +289 -0
  4. data/README.md +128 -0
  5. data/lib/fs/atomic_write.rb +121 -0
  6. data/lib/fs/concerns/argument_validation.rb +140 -0
  7. data/lib/fs/concerns/file_dsl_methods.rb +471 -0
  8. data/lib/fs/concerns/required_arguments.rb +141 -0
  9. data/lib/fs/directory/accessibility_check.rb +89 -0
  10. data/lib/fs/directory.rb +497 -0
  11. data/lib/fs/errors.rb +491 -0
  12. data/lib/fs/file.rb +1524 -0
  13. data/lib/fs/file_variant_builder.rb +269 -0
  14. data/lib/fs/file_variant_proxy.rb +253 -0
  15. data/lib/fs/files/csv.rb +26 -0
  16. data/lib/fs/files/gif.rb +10 -0
  17. data/lib/fs/files/image.rb +390 -0
  18. data/lib/fs/files/jpg.rb +36 -0
  19. data/lib/fs/files/json.rb +24 -0
  20. data/lib/fs/files/pdf.rb +231 -0
  21. data/lib/fs/files/pdf_collection.rb +64 -0
  22. data/lib/fs/files/png.rb +10 -0
  23. data/lib/fs/files/text.rb +13 -0
  24. data/lib/fs/files/tiff.rb +24 -0
  25. data/lib/fs/files/zip.rb +123 -0
  26. data/lib/fs/lockfile_sweeper.rb +70 -0
  27. data/lib/fs/tempfile_sweeper.rb +79 -0
  28. data/lib/fs/testing/mock/fs/configurator.rb +223 -0
  29. data/lib/fs/testing/mock/fs/dirs/directory.rb +41 -0
  30. data/lib/fs/testing/mock/fs/dsl.rb +81 -0
  31. data/lib/fs/testing/mock/fs/file.rb +60 -0
  32. data/lib/fs/testing/mock/fs/file_klass_mock.rb +350 -0
  33. data/lib/fs/testing/mock/fs/files/jpg.rb +14 -0
  34. data/lib/fs/testing/mock/fs/files/pdf.rb +19 -0
  35. data/lib/fs/testing/mock/fs/files/png.rb +12 -0
  36. data/lib/fs/testing/mock/fs/files/tiff.rb +12 -0
  37. data/lib/fs/testing/mock/fs/files/zip.rb +23 -0
  38. data/lib/fs/testing.rb +17 -0
  39. data/lib/fs/version.rb +3 -0
  40. data/lib/fs.rb +26 -0
  41. data/lib/gubbins/fs.rb +4 -0
  42. metadata +124 -0
@@ -0,0 +1,269 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "active_support"
4
+ require "active_support/core_ext/string/inflections"
5
+
6
+ module Fs
7
+ # When you define file variants in a `variant do` block, the block scope
8
+ # is an instance of this class. Its instance methods are the available DSL
9
+ # methods.
10
+ class FileVariantBuilder
11
+ # @return [Class, String] the variants anonymous class or class name
12
+ attr_writer :klass
13
+ # @return [Boolean, nil] is this variant declared to be a standard
14
+ # variant?
15
+ attr_reader :standard
16
+
17
+ # @param name [Symbol]
18
+ def initialize(name)
19
+ @name = name
20
+ end
21
+
22
+ # `define {}` blocks allow you to open up the anonymous variant
23
+ # class and configure it to your liking.
24
+ #
25
+ # @example
26
+ # ```ruby
27
+ # variant(:loud_text, Fs::TextFile) do
28
+ # define do
29
+ # extension :loud_text
30
+ #
31
+ # def is_this_loud?
32
+ # "YEAH!"
33
+ # end
34
+ # end
35
+ # end
36
+ # ```
37
+ #
38
+ # @param subklass_of [Class] which class this variant should inherit from
39
+ # @yield your block is executed in the scope of the class body
40
+ def define(subklass_of: klass, &block)
41
+ @klass = Class.new(subklass_of, &block)
42
+ end
43
+
44
+ # `create_with {}` blocks allow you to define a block handler that creates
45
+ # a new variant. The block is executed in the scope of the variants parent
46
+ # `File` instance.
47
+ #
48
+ # @example
49
+ # ```ruby
50
+ # create_with do |klass:|
51
+ # new_content = content.upcase
52
+ # new_path = path.dirname / "loud_#{basename}.#{klass.extension}"
53
+ #
54
+ # klass.create(path: new_path, content: new_content)
55
+ # end
56
+ # ```
57
+ #
58
+ # @yieldparam klass [Class] your block receives the variant class
59
+ # @yieldparam kargs your block receives all other parameters passed
60
+ # into `variant(name).create`
61
+ # @yieldreturn [Fs::File] your block is expected to return a fully
62
+ # functional instance of the variant class
63
+ def create_with(&block)
64
+ @create_proc = block
65
+ end
66
+
67
+ # `create_with_content_from {}` blocks allow you to define a block handler that
68
+ # returns the content that will be written to a new file on `#create`. The block
69
+ # is executed in the scope of the variants parent `File` instance and receives
70
+ # all parameters passed into `#create`.
71
+ #
72
+ # @example
73
+ # ```ruby
74
+ # create_with_content_from do
75
+ # content.upcase
76
+ # end
77
+ # ```
78
+ #
79
+ # @yieldparam kargs your block receives all parameters passed into
80
+ # `variant(name).load` or `variant(name).create`
81
+ # @yieldreturn [Pathname, String] your block is expected to return a the files content
82
+ def create_with_content_from(&block)
83
+ @content_proc = block
84
+ end
85
+
86
+ # `load_with {}` blocks allow you to define a block handler that loads
87
+ # an existing variant. The block is executed in the scope of the variants parent
88
+ # `File` instance.
89
+ #
90
+ # @example
91
+ # ```ruby
92
+ # load_with do |klass:|
93
+ # new_path = path.dirname / "loud_#{basename}.#{klass.extension}"
94
+ #
95
+ # klass.load(path: new_path, content: new_content)
96
+ # end
97
+ # ```
98
+ #
99
+ # @yieldparam klass [Class] your block receives the variant class
100
+ # @yieldparam kargs your block receives all other parameters passed
101
+ # into `variant(name).load`
102
+ # @yieldreturn [Fs::File] your block is expected to return a fully
103
+ # functional instance of the variant class
104
+ def load_with(&block)
105
+ @load_proc = block
106
+ end
107
+
108
+ # `get_path_from {}` blocks allow you to define a block handler that
109
+ # returns the path for instances of this variant. The block is executed in
110
+ # the scope of the variants parent `File` instance.
111
+ #
112
+ # @example
113
+ # ```ruby
114
+ # get_path_from do
115
+ # "report_#{project.id}"
116
+ # end
117
+ # ```
118
+ #
119
+ # @yieldparam klass [Class] your block receives the variant class
120
+ # @yieldparam kargs your block receives all other parameters passed
121
+ # into `variant(name).load` or `variant(name).create`
122
+ # @yieldreturn [Pathname, String] your block is expected to return a path
123
+ def get_path_from(&block)
124
+ @path_proc = block
125
+ end
126
+
127
+ # Configure whether creating this variant is serialized, so that concurrent creators of the
128
+ # same file wait for one another instead of each doing the work (see
129
+ # {Fs::File.with_creation_lock}). Optional, defaults to the setting of the variants class.
130
+ #
131
+ # Atomic writes already keep anybody from reading a half-written file. Locks are only for
132
+ # variants which are too expensive to be created twice.
133
+ #
134
+ # @example
135
+ # ```ruby
136
+ # variant(:png, Fs::Files::PNG) do
137
+ # use_locks true
138
+ # end
139
+ # ```
140
+ #
141
+ # @param value [Boolean, nil]
142
+ # @return [Boolean, nil]
143
+ def use_locks(value = nil)
144
+ if value.nil?
145
+ @use_locks
146
+ else
147
+ @use_locks = value
148
+ end
149
+ end
150
+
151
+ # Configure whether this variant is written through a temporary file, which is moved into
152
+ # place once complete (see {Fs::AtomicWrite}). Optional, defaults to the setting of the
153
+ # variants class.
154
+ #
155
+ # Your `create_with` block is handed the temporary path as `path:`.
156
+ #
157
+ # @param value [Boolean, nil]
158
+ # @return [Boolean, nil]
159
+ def use_atomic_writes(value = nil)
160
+ if value.nil?
161
+ @use_atomic_writes
162
+ else
163
+ @use_atomic_writes = value
164
+ end
165
+ end
166
+
167
+ # Marks this variant as a standard variant.
168
+ #
169
+ # Standard variants can be created in one swoop by calling
170
+ # `#prepare_standard_variants` on the parent file - useful for ensuring the
171
+ # existence of variants in advance that will definitely be used in the future.
172
+ #
173
+ # @return [void]
174
+ def include_in_standard_set
175
+ @standard = true
176
+ end
177
+
178
+ # @private
179
+ # @param parent [Fs::File] the variants parent instance
180
+ # @return [Fs::FileVariantProxy]
181
+ def to_proxy(parent:)
182
+ Fs::FileVariantProxy.new(
183
+ parent: parent,
184
+ variant_klass: klass,
185
+ create_proc: create_proc || default_create_proc,
186
+ content_proc: content_proc,
187
+ load_proc: load_proc || default_load_proc,
188
+ path_proc: path_proc,
189
+ use_locks: @use_locks,
190
+ use_atomic_writes: @use_atomic_writes
191
+ )
192
+ end
193
+
194
+ private
195
+
196
+ # @return [Symbol] the variants name
197
+ attr_reader :name
198
+ # @return [Proc, nil] a handler proc for creating
199
+ # new instances of this variant
200
+ attr_reader :create_proc
201
+ attr_reader :content_proc
202
+ # @return [Proc, nil] a handler proc for loading
203
+ # existing instances of this variant
204
+ attr_reader :load_proc
205
+ # @return [Proc, nil] a handler proc that returns a path
206
+ # for a variant instance
207
+ attr_reader :path_proc
208
+
209
+ # @return [Class] the variants anonymous class
210
+ def klass
211
+ case @klass
212
+ when Class
213
+ @klass
214
+ when String
215
+ @klass.constantize
216
+ else
217
+ Class.new(Fs::File)
218
+ end
219
+ end
220
+
221
+ # The default creation logic used when a variant does not specify a
222
+ # `create_with {}` block
223
+ #
224
+ # @return [Proc]
225
+ def default_create_proc
226
+ ->(klass:, content: nil, create_block: nil, path: nil, **kargs) {
227
+ path = path
228
+
229
+ if path.nil?
230
+ # We'll just take the parent files filename and change the extension to the one of the
231
+ # variant
232
+ unless klass.extension
233
+ raise "Cannot create variant because the variants filename is not known. See comment where this is raised."
234
+ end
235
+
236
+ path = self.path.sub_ext("." + klass.extensions.first)
237
+ end
238
+
239
+ if create_block
240
+ klass.create(path: path, **kargs, &create_block)
241
+ else
242
+ klass.create(path: path, content: content, **kargs)
243
+ end
244
+ }
245
+ end
246
+
247
+ # The default loading logic used when a variant does not specify a
248
+ # `load_with {}` block
249
+ #
250
+ # @return [Proc]
251
+ def default_load_proc
252
+ ->(klass:, klass_method: :load, path: nil, **kargs) {
253
+ path = path
254
+
255
+ if path.nil?
256
+ # We'll just take the parent files filename and change the extension to the one of the
257
+ # variant
258
+ unless klass.extension
259
+ raise "Cannot load variant because the variants filename is not known. See comment where this is raised."
260
+ end
261
+
262
+ path = self.path.sub_ext("." + klass.extensions.first)
263
+ end
264
+
265
+ klass.send(klass_method, path: path, **kargs)
266
+ }
267
+ end
268
+ end
269
+ end
@@ -0,0 +1,253 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "active_support"
4
+ require "active_support/core_ext/string/inflections"
5
+
6
+ module Fs
7
+ # When you access a variant through `some_file.variant(name)`, you'll receive back
8
+ # an instance of this class.
9
+ class FileVariantProxy
10
+ # @param parent [Fs::File] this variants parent instance
11
+ # @param variant_klass [Class] this variants class
12
+ # @param create_proc [Proc] the handler responsible for creating a new
13
+ # instance
14
+ # @param load_proc [Proc] the handler responsible for loading an existing
15
+ # instance
16
+ # @param path_proc [Proc, nil] an optional handler responsible for determining
17
+ # the variants path
18
+ # @param content_proc [Proc, nil] an optional handler responsible for fetching the content
19
+ # that will be written to the file on #create
20
+ # @param use_locks [Boolean, nil] serialize concurrent creators; nil leaves it to
21
+ # the variants class
22
+ # @param use_atomic_writes [Boolean, nil] write through a temporary file; nil leaves it
23
+ # to the variants class
24
+ def initialize(parent:, variant_klass:, create_proc:, load_proc:, path_proc:, content_proc:,
25
+ use_locks: nil, use_atomic_writes: nil)
26
+ @parent_file = parent
27
+ @variant_klass = variant_klass
28
+ @create_proc = create_proc
29
+ @content_proc = content_proc
30
+ @load_proc = load_proc
31
+ @path_proc = path_proc
32
+ @use_locks = use_locks
33
+ @use_atomic_writes = use_atomic_writes
34
+ end
35
+
36
+ # Load an instance of this variant
37
+ #
38
+ # The exact arguments depend on the variants `load_with`
39
+ # handler.
40
+ #
41
+ # @param path [String, Pathname, nil] usually optional and predetermined
42
+ # by the variants configuration. Can be overridden here.
43
+ # @return [Fs::File] an instance of this variants class
44
+ def load(path: nil, **kargs)
45
+ parent_file.instance_exec(
46
+ klass: variant_klass,
47
+ path: resolve_path(path, **kargs),
48
+ **kargs,
49
+ &load_proc
50
+ )
51
+ end
52
+
53
+ # Test whether this variant exists on disk and is usable.
54
+ #
55
+ # @see {#load}
56
+ def exists?(**kargs)
57
+ # TODO make rescue more discriminating - this hides bugs
58
+ # occurring during load
59
+ !!(load(**kargs) rescue nil)
60
+ end
61
+
62
+ # Create an instance of this variant
63
+ #
64
+ # The exact arguments depend on the variants `create_with`
65
+ # handler.
66
+ #
67
+ # Unless the variant opts out, the handler writes to a temporary path, which is moved
68
+ # to the variants own once the handler returns.
69
+ #
70
+ # @param path [String, Pathname, nil] usually optional and predetermined
71
+ # by the variants configuration. Can be overridden here.
72
+ # @param content [#to_s] usually optional and predetermined by the variants
73
+ # configuration. Can be overridden here.
74
+ # @param lock [Boolean] see {Fs::File.create}
75
+ # @param lock_timeout [Numeric] see {Fs::File.with_creation_lock}
76
+ # @yield [IO] optionally yields an IO object, similar to `File.open`
77
+ # @return [Fs::File] an instance of this variants class
78
+ def create(path: nil, content: nil, lock: locking?, lock_timeout: Fs::File::CREATION_LOCK_TIMEOUT, **kargs, &block)
79
+ path = resolve_path(path, **kargs)
80
+
81
+ serialized(path, lock: lock, lock_timeout: lock_timeout) do
82
+ create_without_lock(path: path, content: content, **kargs, &block)
83
+ end
84
+ end
85
+
86
+ # Load an instance of this variant from disk if it exists, or create
87
+ # it otherwise.
88
+ #
89
+ # The exact arguments depend on the variants `create_with`
90
+ # handler.
91
+ #
92
+ # If the variant writes atomically, an existing file is loaded without taking any lock:
93
+ # it is either complete, or not there.
94
+ #
95
+ # @see {#create}
96
+ # @return [Fs::File] an instance of this variants class
97
+ def load_or_create(path: nil, content: nil, lock: locking?, lock_timeout: Fs::File::CREATION_LOCK_TIMEOUT, **kargs, &block)
98
+ path = resolve_path(path, **kargs)
99
+ existing = load_if_present(path: path, **kargs) if atomic?
100
+
101
+ return existing if existing
102
+
103
+ serialized(path, lock: lock, lock_timeout: lock_timeout) do
104
+ # Somebody else may have created it while we were waiting for the lock
105
+ load_if_present(path: path, **kargs) || create_without_lock(path: path, content: content, **kargs, &block)
106
+ end
107
+ end
108
+
109
+ # Delete an `Fs::File` object from disk
110
+ #
111
+ # @param quiet [Boolean] ignore if the file already
112
+ # does not exist
113
+ # @return [Boolean]
114
+ def delete(quiet: true, **kargs)
115
+ instance = load(**kargs) rescue nil
116
+
117
+ return false if quiet && !instance&.exists?
118
+
119
+ instance.delete
120
+
121
+ true
122
+ end
123
+
124
+ # Create a temporary instance of this variant
125
+ #
126
+ # The instance will be yielded to a provided block and automatically
127
+ # removed after the block has returned.
128
+ #
129
+ # It is not recommended to retain a reference to the instance outside
130
+ # of the block, because the underlying file will be gone.
131
+ #
132
+ # @param content [#to_s] optional: content to be written to the file
133
+ # @yield [Fs::File] yields an instance of this variants class
134
+ # @return the return value of the given block
135
+ def create_temp(content: nil, **kargs)
136
+ unless block_given?
137
+ raise ArgumentError, "create_temp requires a block to yield the temporary Fs::File object to"
138
+ end
139
+
140
+ tempfile =
141
+ Tempfile.new([parent_file.class.name.parameterize, "." + variant_klass.extensions.first.to_s],
142
+ Fs::File.resolve_temp_directory(variant_klass.temp_directory).to_s)
143
+
144
+ instance =
145
+ parent_file.instance_exec(
146
+ klass: variant_klass,
147
+ path: tempfile.path,
148
+ content: get_content(content),
149
+ **kargs,
150
+ &create_proc
151
+ )
152
+
153
+ yield instance
154
+ ensure
155
+ tempfile.close
156
+ tempfile.unlink
157
+ end
158
+
159
+ private
160
+
161
+ # @return [Class] this variants class
162
+ attr_reader :variant_klass
163
+ # @return [Fs::File] this variants parent Fs::File instance
164
+ attr_reader :parent_file
165
+ # @return [Proc] the handler responsible for creating a new
166
+ # instance
167
+ attr_reader :create_proc
168
+ # @return [Proc, nil]
169
+ attr_reader :content_proc
170
+ # @return [Proc] the handler responsible for loading an existing
171
+ # instance
172
+ attr_reader :load_proc
173
+ # @return [Proc, nil] an optional handler responsible for determining
174
+ # the variants path
175
+ attr_reader :path_proc
176
+
177
+ # @return [Boolean] does creating this variant serialize concurrent creators?
178
+ def locking?
179
+ @use_locks.nil? ? variant_klass.use_locks : @use_locks
180
+ end
181
+
182
+ # @return [Boolean] is this variant written through a temporary file?
183
+ def atomic?
184
+ @use_atomic_writes.nil? ? variant_klass.use_atomic_writes : @use_atomic_writes
185
+ end
186
+
187
+ # @param path [Pathname, String, nil] nil if the variant determines its path
188
+ # itself, in which case there is nothing for us to lock
189
+ # @see Fs::File.with_creation_lock
190
+ def serialized(path, lock:, lock_timeout:, &block)
191
+ return yield unless path
192
+
193
+ Fs::File.with_creation_lock(path, lock: lock, timeout: lock_timeout, &block)
194
+ end
195
+
196
+ # @return [Fs::File, nil]
197
+ def load_if_present(**kargs)
198
+ # TODO make rescue more discriminating - this hides bugs
199
+ # occurring during load
200
+ load(**kargs) rescue nil
201
+ end
202
+
203
+ # @param path [Pathname, String, nil] the already resolved path
204
+ # @return [Fs::File] an instance of this variants class
205
+ def create_without_lock(path:, content:, **kargs, &block)
206
+ return run_create_proc(path: path, content: content, **kargs, &block) unless atomic? && path
207
+
208
+ Fs::AtomicWrite.perform(path, directory: variant_klass.atomic_write_directory) do |temp_path|
209
+ run_create_proc(path: temp_path, content: content, **kargs, &block)
210
+ end
211
+
212
+ # What the handler returned lives at the temporary path
213
+ load(path: path, **kargs)
214
+ end
215
+
216
+ # @return [Fs::File] an instance of this variants class
217
+ def run_create_proc(path:, content:, **kargs, &block)
218
+ parent_file.instance_exec(
219
+ klass: variant_klass,
220
+ path: path,
221
+ content: get_content(content, **kargs),
222
+ create_block: block,
223
+ **kargs,
224
+ &create_proc
225
+ )
226
+ end
227
+
228
+ # Returns the explicitely given path, a path from the path handler
229
+ # or nil
230
+ #
231
+ # @param path [String, Pathname, nil]
232
+ # @param kargs all other parameters given to `#load` or `#create`
233
+ # @return [String, Pathname, nil]
234
+ def resolve_path(path, **kargs)
235
+ return path if path
236
+ return parent_file.instance_exec(klass: variant_klass, **kargs, &path_proc) if path_proc
237
+
238
+ nil
239
+ end
240
+
241
+ # Returns the explicitely given content, content returned from a
242
+ # content proc or nil
243
+ #
244
+ # @param kargs all other parameters given to `#load` or `#create`
245
+ # @param content
246
+ def get_content(content, **kargs)
247
+ return content if content
248
+ return parent_file.instance_eval(**kargs, &content_proc) if content_proc
249
+
250
+ nil
251
+ end
252
+ end
253
+ end
@@ -0,0 +1,26 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "csv"
4
+
5
+ module Fs
6
+ module Files
7
+ class CSV < Fs::File
8
+ extension :csv
9
+ mime_type "application/csv", /^text\//
10
+ encoding "utf-8", "us-ascii", "iso-8859-1", "iso-8859-15", "cp1252", "unknown-8bit"
11
+
12
+ # @return [String]
13
+ def raw_content
14
+ @raw_content ||=
15
+ ::File.read(path)
16
+ .then do |string|
17
+ string.encode(Encoding::UTF_8)
18
+ end
19
+ end
20
+
21
+ def content(**parser_options)
22
+ ::CSV.read(path, **parser_options)
23
+ end
24
+ end
25
+ end
26
+ end
@@ -0,0 +1,10 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Fs
4
+ module Files
5
+ class GIF < Image
6
+ extension :gif
7
+ mime_type "image/gif"
8
+ end
9
+ end
10
+ end