minitar 1.1.0 → 1.2.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.
@@ -1,302 +1,287 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- class Minitar
4
- # The class that writes a tar format archive to a data stream.
5
- class Writer
6
- # The exception raised when the user attempts to write more data to
7
- # a BoundedWriteStream than has been allocated.
8
- WriteBoundaryOverflow = Class.new(StandardError)
9
-
10
- # A stream wrapper that can only be written to. Any attempt to read from this
11
- # restricted stream will result in a NameError being thrown.
12
- class WriteOnlyStream
13
- def initialize(io)
14
- @io = io
15
- end
16
-
17
- def write(data) = @io.write(data)
3
+ # The class that writes a tar format archive to a data stream.
4
+ class Minitar::Writer
5
+ # The exception raised when the user attempts to write more data to a BoundedWriteStream
6
+ # than has been allocated.
7
+ WriteBoundaryOverflow = Class.new(Minitar::Error)
8
+
9
+ # A stream wrapper that can only be written to. Any attempt to read from this restricted
10
+ # stream will result in a NameError being thrown.
11
+ class WriteOnlyStream
12
+ def initialize(io)
13
+ @io = io
18
14
  end
19
15
 
20
- private_constant :WriteOnlyStream
16
+ def write(data) = @io.write(data)
17
+ end
21
18
 
22
- # A WriteOnlyStream that also has a size limit.
23
- class BoundedWriteStream < WriteOnlyStream
24
- # The maximum number of bytes that may be written to this data stream.
25
- attr_reader :limit
26
- # The current total number of bytes written to this data stream.
27
- attr_reader :written
19
+ private_constant :WriteOnlyStream
28
20
 
29
- def initialize(io, limit)
30
- @io = io
31
- @limit = limit
32
- @written = 0
33
- end
21
+ # A WriteOnlyStream that also has a size limit.
22
+ class BoundedWriteStream < WriteOnlyStream
23
+ # The maximum number of bytes that may be written to this data stream.
24
+ attr_reader :limit
25
+ # The current total number of bytes written to this data stream.
26
+ attr_reader :written
34
27
 
35
- def write(data)
36
- size = data.bytesize
37
- raise WriteBoundaryOverflow if (size + @written) > @limit
38
- @io.write(data)
39
- @written += size
40
- size
41
- end
28
+ def initialize(io, limit)
29
+ @io = io
30
+ @limit = limit
31
+ @written = 0
42
32
  end
43
33
 
44
- private_constant :BoundedWriteStream
45
-
46
- # With no associated block, +Writer::open+ is a synonym for +Writer::new+. If the
47
- # optional code block is given, it will be passed the new _writer_ as an argument and
48
- # the Writer object will automatically be closed when the block terminates. In this
49
- # instance, +Writer::open+ returns the value of the block.
50
- #
51
- # :call-seq:
52
- # w = Minitar::Writer.open(STDOUT)
53
- # w.add_file_simple('foo.txt', :size => 3)
54
- # w.close
55
- #
56
- # Minitar::Writer.open(STDOUT) do |w|
57
- # w.add_file_simple('foo.txt', :size => 3)
58
- # end
59
- def self.open(io) # :yields: Writer
60
- writer = new(io)
61
- return writer unless block_given?
62
-
63
- # This exception context must remain, otherwise the stream closes on open even if
64
- # a block is not given.
65
- begin
66
- yield writer
67
- ensure
68
- writer.close
69
- end
34
+ def write(data)
35
+ size = data.bytesize
36
+ raise WriteBoundaryOverflow if (size + @written) > @limit
37
+ @io.write(data)
38
+ @written += size
39
+ size
70
40
  end
41
+ end
71
42
 
72
- # Creates and returns a new Writer object.
73
- def initialize(io)
74
- @io = io
75
- @closed = false
43
+ private_constant :BoundedWriteStream
44
+
45
+ # With no associated block, Writer::open is a synonym for Writer::new. If the optional
46
+ # code block is given, it will be passed the new _writer_ as an argument and the Writer
47
+ # object will automatically be closed when the block terminates. In this instance,
48
+ # Writer::open returns the value of the block.
49
+ #
50
+ # :call-seq:
51
+ # Minitar::Writer.open(io) -> writer
52
+ # Minitar::Writer.open(io) { |writer| block } -> obj
53
+ def self.open(io) # :yields: Writer
54
+ writer = new(io)
55
+ return writer unless block_given?
56
+
57
+ # This exception context must remain, otherwise the stream closes on open even if
58
+ # a block is not given.
59
+ begin
60
+ yield writer
61
+ ensure
62
+ writer.close
76
63
  end
64
+ end
77
65
 
78
- # Adds a file to the archive as +name+. The data can be provided in the
79
- # <tt>opts[:data]</tt> or provided to a BoundedWriteStream that is yielded to the
80
- # provided block.
81
- #
82
- # If <tt>opts[:data]</tt> is provided, all other values to +opts+ are optional. If the
83
- # data is provided to the yielded BoundedWriteStream, <tt>opts[:size]</tt> must be
84
- # provided.
85
- #
86
- # Valid parameters to +opts+ are:
87
- #
88
- # <tt>:data</tt>:: Optional. The data to write to the archive.
89
- # <tt>:mode</tt>:: The Unix file permissions mode value. If not provided, defaults to
90
- # 0o644.
91
- # <tt>:size</tt>:: The size, in bytes. If <tt>:data</tt> is provided, this parameter
92
- # may be ignored (if it is less than the size of the data provided)
93
- # or used to add padding (if it is greater than the size of the data
94
- # provided).
95
- # <tt>:uid</tt>:: The Unix file owner user ID number.
96
- # <tt>:gid</tt>:: The Unix file owner group ID number.
97
- # <tt>:mtime</tt>:: File modification time, interpreted as an integer.
98
- #
99
- # An exception will be raised if the Writer is already closed, or if more data is
100
- # written to the BoundedWriteStream than expected.
101
- #
102
- # :call-seq:
103
- # writer.add_file_simple('foo.txt', :data => "bar")
104
- # writer.add_file_simple('foo.txt', :size => 3) do |w|
105
- # w.write("bar")
106
- # end
107
- def add_file_simple(name, opts = {}) # :yields: BoundedWriteStream
108
- raise ClosedStream if @closed
109
-
110
- header = {
111
- mode: opts.fetch(:mode, 0o644),
112
- mtime: opts.fetch(:mtime, nil),
113
- gid: opts.fetch(:gid, nil),
114
- uid: opts.fetch(:uid, nil)
115
- }
116
-
117
- data = opts.fetch(:data, nil)
118
- size = opts.fetch(:size, nil)
119
-
120
- if block_given?
121
- raise ArgumentError, "Too much data (opts[:data] and block_given?)." if data
122
- raise ArgumentError, "No size provided" unless size
123
- else
124
- raise ArgumentError, "No data provided" unless data
125
-
126
- bytes = data.bytesize
127
- size = bytes if size.nil? || size < bytes
128
- end
66
+ # Creates and returns a new Writer object.
67
+ def initialize(io)
68
+ @io = io
69
+ @closed = false
70
+ end
129
71
 
130
- header[:size] = size
72
+ # Adds a file to the archive as `name`. The data can be provided in `opts[:data]` or
73
+ # provided to a BoundedWriteStream that is yielded to the provided block.
74
+ #
75
+ # If `opts[:data]` is provided, all other values to `opts` are optional. If the data is
76
+ # provided to the yielded BoundedWriteStream, `opts[:size]` must be provided.
77
+ #
78
+ # Valid parameters to `opts` are:
79
+ #
80
+ # - `:data` (_optional_): The data to write to the archive.
81
+ # - `:mode`: The Unix file permissions mode value. If not provided, defaults to `0o644`.
82
+ # - `:size`: The size, in bytes. If `:data` is provided, this parameter may be ignored
83
+ # (if it is less than the size of the data provided) or used to add padding
84
+ # (if it is greater than the size of the data provided).
85
+ # - `:uid`: The Unix file owner user ID number.
86
+ # - `:gid`: The Unix file owner group ID number.
87
+ # - `:mtime`: File modification time, interpreted as an integer.
88
+ #
89
+ # An exception will be raised if the Writer is already closed, or if more data is
90
+ # written to the BoundedWriteStream than expected.
91
+ #
92
+ # :call-seq:
93
+ # add_file_simple('foo.txt', :data => "bar") -> writer
94
+ # add_file_simple('foo.txt', :size => 3) { |w| block }
95
+ def add_file_simple(name, opts = {}) # :yields: BoundedWriteStream
96
+ raise Minitar::ClosedStream if @closed
97
+
98
+ header = {
99
+ mode: opts.fetch(:mode, 0o644),
100
+ mtime: opts.fetch(:mtime, nil),
101
+ gid: opts.fetch(:gid, nil),
102
+ uid: opts.fetch(:uid, nil)
103
+ }
104
+
105
+ data = opts.fetch(:data, nil)
106
+ size = opts.fetch(:size, nil)
107
+
108
+ if block_given?
109
+ raise ArgumentError, "Too much data (opts[:data] and block_given?)." if data
110
+ raise ArgumentError, "No size provided" unless size
111
+ else
112
+ raise ArgumentError, "No data provided" unless data
113
+
114
+ bytes = data.bytesize
115
+ size = bytes if size.nil? || size < bytes
116
+ end
131
117
 
132
- short_name, prefix, needs_long_name = split_name(name)
133
- write_header(header, name, short_name, prefix, needs_long_name)
118
+ header[:size] = size
134
119
 
135
- os = BoundedWriteStream.new(@io, size)
136
- if block_given?
137
- yield os
138
- else
139
- os.write(data)
140
- end
120
+ short_name, prefix, needs_long_name = split_name(name)
121
+ write_header(header, name, short_name, prefix, needs_long_name)
141
122
 
142
- min_padding = size - os.written
143
- @io.write("\0" * min_padding)
144
- remainder = (512 - (size % 512)) % 512
145
- @io.write("\0" * remainder)
123
+ os = BoundedWriteStream.new(@io, size)
124
+ if block_given?
125
+ yield os
126
+ else
127
+ os.write(data)
146
128
  end
147
129
 
148
- # Adds a file to the archive as +name+. The data can be provided in the
149
- # <tt>opts[:data]</tt> or provided to a yielded +WriteOnlyStream+. The size of the
150
- # file will be determined from the amount of data written to the stream.
151
- #
152
- # Valid parameters to +opts+ are:
153
- #
154
- # <tt>:mode</tt>:: The Unix file permissions mode value. If not provided, defaults to
155
- # 0o644.
156
- # <tt>:uid</tt>:: The Unix file owner user ID number.
157
- # <tt>:gid</tt>:: The Unix file owner group ID number.
158
- # <tt>:mtime</tt>:: File modification time, interpreted as an integer.
159
- # <tt>:data</tt>:: Optional. The data to write to the archive.
160
- #
161
- # If <tt>opts[:data]</tt> is provided, this acts the same as #add_file_simple.
162
- # Otherwise, the file's size will be determined from the amount of data written to the
163
- # stream.
164
- #
165
- # For #add_file to be used without <tt>opts[:data]</tt>, the Writer must be wrapping
166
- # a stream object that is seekable. Otherwise, #add_file_simple must be used.
167
- #
168
- # +opts+ may be modified during the writing of the file to the stream.
169
- def add_file(name, opts = {}, &) # :yields: WriteOnlyStream, +opts+
170
- raise ClosedStream if @closed
171
-
172
- return add_file_simple(name, opts, &) if opts[:data]
173
-
174
- raise Minitar::NonSeekableStream unless Minitar.seekable?(@io)
175
-
176
- short_name, prefix, needs_long_name = split_name(name)
177
-
178
- data_offset = needs_long_name ? 3 * 512 : 512
179
- init_pos = @io.pos
180
- @io.write("\0" * data_offset) # placeholder for the header
181
-
182
- yield WriteOnlyStream.new(@io), opts
183
-
184
- size = @io.pos - (init_pos + data_offset)
185
- remainder = (512 - (size % 512)) % 512
186
- @io.write("\0" * remainder)
187
-
188
- final_pos, @io.pos = @io.pos, init_pos
189
-
190
- header = {
191
- mode: opts[:mode],
192
- mtime: opts[:mtime],
193
- size: size,
194
- gid: opts[:gid],
195
- uid: opts[:uid]
196
- }
130
+ min_padding = size - os.written
131
+ @io.write("\0" * min_padding)
132
+ remainder = (512 - (size % 512)) % 512
133
+ @io.write("\0" * remainder)
134
+ end
197
135
 
198
- write_header(header, name, short_name, prefix, needs_long_name)
136
+ # Adds a file to the archive as `name`. The data can be provided in `opts[:data]` or
137
+ # provided to a yielded WriteOnlyStream. The size of the file will be determined from
138
+ # the amount of data written to the stream.
139
+ #
140
+ # Valid parameters to `opts` are:
141
+ #
142
+ # - `:data` (_optional_): The data to write to the archive.
143
+ # - `:mode`: The Unix file permissions mode value. If not provided, defaults to `0o644`.
144
+ # - `:uid`: The Unix file owner user ID number.
145
+ # - `:gid`: The Unix file owner group ID number.
146
+ # - `:mtime`: File modification time, interpreted as an integer.
147
+ #
148
+ # If `opts[:data]` is provided, this acts the same as #add_file_simple. Otherwise, the
149
+ # file's size will be determined from the amount of data written to the stream.
150
+ #
151
+ # For #add_file to be used without `opts[:data]`, the Writer must be wrapping a stream
152
+ # object that is seekable. Otherwise, #add_file_simple must be used.
153
+ #
154
+ # `opts` may be modified during the writing of the file to the stream.
155
+ def add_file(name, opts = {}, &) # :yields: WriteOnlyStream, `opts`
156
+ raise Minitar::ClosedStream if @closed
157
+
158
+ return add_file_simple(name, opts, &) if opts[:data]
159
+
160
+ raise Minitar::NonSeekableStream unless Minitar.seekable?(@io)
161
+
162
+ short_name, prefix, needs_long_name = split_name(name)
163
+
164
+ data_offset = needs_long_name ? 3 * 512 : 512
165
+ init_pos = @io.pos
166
+ @io.write("\0" * data_offset) # placeholder for the header
167
+
168
+ yield WriteOnlyStream.new(@io), opts
169
+
170
+ size = @io.pos - (init_pos + data_offset)
171
+ remainder = (512 - (size % 512)) % 512
172
+ @io.write("\0" * remainder)
173
+
174
+ final_pos, @io.pos = @io.pos, init_pos
175
+
176
+ header = {
177
+ mode: opts[:mode],
178
+ mtime: opts[:mtime],
179
+ size: size,
180
+ gid: opts[:gid],
181
+ uid: opts[:uid]
182
+ }
183
+
184
+ write_header(header, name, short_name, prefix, needs_long_name)
185
+
186
+ @io.pos = final_pos
187
+ end
199
188
 
200
- @io.pos = final_pos
201
- end
189
+ # Creates a directory entry in the tar.
190
+ def mkdir(name, opts = {})
191
+ raise Minitar::ClosedStream if @closed
202
192
 
203
- # Creates a directory entry in the tar.
204
- def mkdir(name, opts = {})
205
- raise ClosedStream if @closed
206
-
207
- header = {
208
- mode: opts[:mode],
209
- typeflag: "5",
210
- size: 0,
211
- gid: opts[:gid],
212
- uid: opts[:uid],
213
- mtime: opts[:mtime]
214
- }
193
+ header = {
194
+ mode: opts[:mode],
195
+ typeflag: "5",
196
+ size: 0,
197
+ gid: opts[:gid],
198
+ uid: opts[:uid],
199
+ mtime: opts[:mtime]
200
+ }
215
201
 
216
- short_name, prefix, needs_long_name = split_name(name)
217
- write_header(header, name, short_name, prefix, needs_long_name)
202
+ short_name, prefix, needs_long_name = split_name(name)
203
+ write_header(header, name, short_name, prefix, needs_long_name)
218
204
 
219
- nil
220
- end
205
+ nil
206
+ end
221
207
 
222
- # Creates a symbolic link entry in the tar.
223
- def symlink(name, link_target, opts = {})
224
- raise ClosedStream if @closed
225
- raise FileNameTooLong if link_target.size > 100
226
-
227
- name, prefix = split_name(name)
228
- header = {
229
- name: name,
230
- mode: opts[:mode],
231
- typeflag: "2",
232
- size: 0,
233
- linkname: link_target,
234
- gid: opts[:gid],
235
- uid: opts[:uid],
236
- mtime: opts[:mtime],
237
- prefix: prefix
238
- }
239
- @io.write(PosixHeader.new(header).to_s)
240
- nil
241
- end
208
+ # Creates a symbolic link entry in the tar.
209
+ def symlink(name, link_target, opts = {})
210
+ raise Minitar::ClosedStream if @closed
211
+ raise Minitar::FileNameTooLong if link_target.size > 100
212
+
213
+ name, prefix = split_name(name)
214
+ header = {
215
+ name: name,
216
+ mode: opts[:mode],
217
+ typeflag: "2",
218
+ size: 0,
219
+ linkname: link_target,
220
+ gid: opts[:gid],
221
+ uid: opts[:uid],
222
+ mtime: opts[:mtime],
223
+ prefix: prefix
224
+ }
225
+ @io.write(Minitar::PosixHeader.new(header).to_s)
226
+ nil
227
+ end
242
228
 
243
- # Passes the #flush method to the wrapped stream, used for buffered streams.
244
- def flush
245
- raise ClosedStream if @closed
246
- @io.flush if @io.respond_to?(:flush)
247
- end
229
+ # Passes the #flush method to the wrapped stream, used for buffered streams.
230
+ def flush
231
+ raise Minitar::ClosedStream if @closed
232
+ @io.flush if @io.respond_to?(:flush)
233
+ end
248
234
 
249
- # Returns false if the writer is open.
250
- def closed? = @closed
235
+ # Returns false if the writer is open.
236
+ def closed? = @closed
251
237
 
252
- # Closes the Writer. This does not close the underlying wrapped output stream.
253
- def close
254
- return if @closed
255
- @io.write("\0" * 1024)
256
- @closed = true
257
- end
238
+ # Closes the Writer. This does not close the underlying wrapped output stream.
239
+ def close
240
+ return if @closed
241
+ @io.write("\0" * 1024)
242
+ @closed = true
243
+ end
258
244
 
259
- private
260
-
261
- def write_header(header, long_name, short_name, prefix, needs_long_name)
262
- if needs_long_name
263
- long_name_header = {
264
- prefix: "",
265
- name: PosixHeader::GNU_EXT_LONG_LINK,
266
- typeflag: "L",
267
- size: long_name.length + 1,
268
- mode: 0
269
- }
270
- @io.write(PosixHeader.new(long_name_header).to_s)
271
- @io.write(long_name)
272
- @io.write("\0" * (512 - (long_name.length % 512)))
273
- end
245
+ private
274
246
 
275
- new_header = header.merge({name: short_name, prefix: prefix})
276
- @io.write(PosixHeader.new(new_header).to_s)
247
+ def write_header(header, long_name, short_name, prefix, needs_long_name)
248
+ if needs_long_name
249
+ long_name_header = {
250
+ prefix: "",
251
+ name: Minitar::PosixHeader::GNU_EXT_LONG_LINK,
252
+ typeflag: "L",
253
+ size: long_name.length + 1,
254
+ mode: 0
255
+ }
256
+ @io.write(Minitar::PosixHeader.new(long_name_header).to_s)
257
+ @io.write(long_name)
258
+ @io.write("\0" * (512 - (long_name.length % 512)))
277
259
  end
278
260
 
279
- def split_name(name)
280
- if name.bytesize <= 100
281
- prefix = ""
282
- else
283
- parts = name.split("/")
284
- newname = parts.pop
285
-
286
- nxt = ""
261
+ new_header = header.merge({name: short_name, prefix: prefix})
262
+ @io.write(Minitar::PosixHeader.new(new_header).to_s)
263
+ end
287
264
 
288
- loop do
289
- nxt = parts.pop || ""
290
- break if newname.bytesize + 1 + nxt.bytesize >= 100
291
- newname = "#{nxt}/#{newname}"
292
- end
265
+ def split_name(name)
266
+ if name.bytesize <= 100
267
+ prefix = ""
268
+ else
269
+ parts = name.split("/")
270
+ newname = parts.pop
293
271
 
294
- prefix = (parts + [nxt]).join("/")
272
+ nxt = ""
295
273
 
296
- name = newname
274
+ loop do
275
+ nxt = parts.pop || ""
276
+ break if newname.bytesize + 1 + nxt.bytesize >= 100
277
+ newname = "#{nxt}/#{newname}"
297
278
  end
298
279
 
299
- [name, prefix, name.bytesize > 100 || prefix.bytesize > 155]
280
+ prefix = (parts + [nxt]).join("/")
281
+
282
+ name = newname
300
283
  end
284
+
285
+ [name, prefix, name.bytesize > 100 || prefix.bytesize > 155]
301
286
  end
302
287
  end