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,276 +1,288 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- class Minitar
4
- # The class that reads a tar format archive from a data stream. The data stream may be
5
- # sequential or random access, but certain features only work with random access data
6
- # streams.
7
- class Reader
8
- include Enumerable
3
+ # The class that reads a tar format archive from a data stream. The data stream may be
4
+ # sequential or random access, but certain features only work with random access data
5
+ # streams.
6
+ class Minitar::Reader
7
+ include Enumerable
9
8
 
10
- # This marks the EntryStream closed for reading without closing the actual data
11
- # stream.
12
- module InvalidEntryStream
13
- def read(*) = raise ClosedStream # :nodoc:
9
+ # This marks the EntryStream closed for reading without closing the actual data
10
+ # stream.
11
+ module InvalidEntryStream
12
+ def read(*) = raise Minitar::ClosedStream # :nodoc:
14
13
 
15
- def getc = raise ClosedStream # :nodoc:
14
+ def getc = raise Minitar::ClosedStream # :nodoc:
16
15
 
17
- def rewind = raise ClosedStream # :nodoc:
16
+ def rewind = raise Minitar::ClosedStream # :nodoc:
18
17
 
19
- def closed? = true # :nodoc:
18
+ def closed? = true # :nodoc:
19
+ end
20
+
21
+ # EntryStreams are pseudo-streams on top of the main data stream.
22
+ class EntryStream
23
+ Minitar::PosixHeader::FIELDS.each do |field|
24
+ attr_reader field.to_sym
20
25
  end
21
26
 
22
- # EntryStreams are pseudo-streams on top of the main data stream.
23
- class EntryStream
24
- Minitar::PosixHeader::FIELDS.each do |field|
25
- attr_reader field.to_sym
26
- end
27
+ def initialize(header, io)
28
+ @io = io
29
+ @name = header.name
30
+ @mode = header.mode
31
+ @uid = header.uid
32
+ @gid = header.gid
33
+ @size = header.size
34
+ @mtime = header.mtime
35
+ @checksum = header.checksum
36
+ @typeflag = header.typeflag
37
+ @linkname = header.linkname
38
+ @magic = header.magic
39
+ @version = header.version
40
+ @uname = header.uname
41
+ @gname = header.gname
42
+ @devmajor = header.devmajor
43
+ @devminor = header.devminor
44
+ @prefix = header.prefix
45
+ @read = 0
46
+ @orig_pos =
47
+ if Minitar.seekable?(@io)
48
+ @io.pos
49
+ else
50
+ 0
51
+ end
52
+ end
27
53
 
28
- def initialize(header, io)
29
- @io = io
30
- @name = header.name
31
- @mode = header.mode
32
- @uid = header.uid
33
- @gid = header.gid
34
- @size = header.size
35
- @mtime = header.mtime
36
- @checksum = header.checksum
37
- @typeflag = header.typeflag
38
- @linkname = header.linkname
39
- @magic = header.magic
40
- @version = header.version
41
- @uname = header.uname
42
- @gname = header.gname
43
- @devmajor = header.devmajor
44
- @devminor = header.devminor
45
- @prefix = header.prefix
46
- @read = 0
47
- @orig_pos =
48
- if Minitar.seekable?(@io)
49
- @io.pos
50
- else
51
- 0
54
+ # Reads `len` bytes (or all remaining data) from the entry. If `out_string`
55
+ # is provided, the read data is stored there instead of allocating a new
56
+ # string. Returns `nil` if there is no more data to read.
57
+ def read(len = nil, out_string = nil)
58
+ return nil if @read >= @size
59
+ len ||= @size - @read
60
+ max_read = [len, @size - @read].min
61
+
62
+ ret =
63
+ if out_string
64
+ begin
65
+ @io.read(max_read, out_string)
66
+ rescue ArgumentError # If `@io` does not support `out_string`
67
+ out_string.replace(@io.read(max_read))
52
68
  end
53
- end
69
+ else
70
+ @io.read(max_read)
71
+ end
54
72
 
55
- # Reads +len+ bytes (or all remaining data) from the entry. Returns +nil+ if there
56
- # is no more data to read.
57
- def read(len = nil)
58
- return nil if @read >= @size
59
- len ||= @size - @read
60
- max_read = [len, @size - @read].min
61
- ret = @io.read(max_read)
62
- @read += ret.bytesize
63
- ret
64
- end
73
+ @read += ret.bytesize
74
+ ret
75
+ end
65
76
 
66
- # Reads one byte from the entry. Returns +nil+ if there is no more data to read.
67
- def getc
68
- return nil if @read >= @size
69
- ret = @io.getc
70
- @read += 1 if ret
71
- ret
72
- end
77
+ # Reads one byte from the entry. Returns `nil` if there is no more data to read.
78
+ def getc
79
+ return nil if @read >= @size
80
+ ret = @io.getc
81
+ @read += 1 if ret
82
+ ret
83
+ end
73
84
 
74
- # Returns +true+ if the entry represents a directory.
75
- def directory?
76
- case @typeflag
77
- when "5"
78
- true
79
- when "0", "\0"
80
- # If the name ends with a slash, treat it as a directory. This is what other
81
- # major tar implementations do for interoperability and compatibility with older
82
- # tar variants and some new ones.
83
- @name.end_with?("/")
84
- else
85
- false
86
- end
85
+ # Returns `true` if the entry represents a directory.
86
+ #
87
+ # This is primarily controlled by #typeflag `5`, but if the #typeflag is `0` or `\0`,
88
+ # filenames that end with a forward slash (`/`) will be treated as directories for
89
+ # compatibility purposes.
90
+ def directory?
91
+ case @typeflag
92
+ when "5"
93
+ true
94
+ when "0", "\0"
95
+ @name.end_with?("/")
96
+ else
97
+ false
87
98
  end
88
- alias_method :directory, :directory?
99
+ end
100
+ alias_method :directory, :directory?
89
101
 
90
- # Returns +true+ if the entry represents a plain file.
91
- def file?
92
- (@typeflag == "0" || @typeflag == "\0") && !@name.end_with?("/")
93
- end
94
- alias_method :file, :file?
102
+ # Returns `true` if the entry represents a plain file.
103
+ def file?
104
+ (@typeflag == "0" || @typeflag == "\0") && !@name.end_with?("/")
105
+ end
106
+ alias_method :file, :file?
95
107
 
96
- # Returns +true+ if the current read pointer is at the end of the EntryStream data.
97
- def eof? = @read >= @size
108
+ # Returns `true` if the current read pointer is at the end of the EntryStream data.
109
+ def eof? = @read >= @size
98
110
 
99
- # Returns the current read pointer in the EntryStream.
100
- def pos = @read
111
+ # Returns the current read pointer in the EntryStream.
112
+ def pos = @read
101
113
 
102
- alias_method :bytes_read, :pos
114
+ alias_method :bytes_read, :pos
103
115
 
104
- # Sets the current read pointer to the beginning of the EntryStream.
105
- def rewind
106
- unless Minitar.seekable?(@io, :pos=)
107
- raise Minitar::NonSeekableStream
108
- end
109
- @io.pos = @orig_pos
110
- @read = 0
116
+ # Sets the current read pointer to the beginning of the EntryStream.
117
+ def rewind
118
+ unless Minitar.seekable?(@io, :pos=)
119
+ raise Minitar::NonSeekableStream
111
120
  end
121
+ @io.pos = @orig_pos
122
+ @read = 0
123
+ end
112
124
 
113
- # Returns the full and proper name of the entry.
114
- def full_name
115
- if @prefix != ""
116
- File.join(@prefix, @name)
117
- else
118
- @name
119
- end
125
+ # Returns the full and proper name of the entry.
126
+ def full_name
127
+ if @prefix != ""
128
+ File.join(@prefix, @name)
129
+ else
130
+ @name
120
131
  end
132
+ end
121
133
 
122
- # Returns false if the entry stream is valid.
123
- def closed? = false
134
+ # Returns false if the entry stream is valid.
135
+ def closed? = false
124
136
 
125
- # Closes the entry.
126
- def close = invalidate
137
+ # Closes the entry.
138
+ def close = invalidate
127
139
 
128
- private
140
+ private
129
141
 
130
- def invalidate
131
- extend InvalidEntryStream
132
- end
142
+ def invalidate
143
+ extend InvalidEntryStream
133
144
  end
145
+ end
134
146
 
135
- # With no associated block, +Reader::open+ is a synonym for +Reader::new+. If the
136
- # optional code block is given, it will be passed the new _writer_ as an argument and
137
- # the Reader object will automatically be closed when the block terminates. In this
138
- # instance, +Reader::open+ returns the value of the block.
139
- def self.open(io)
140
- reader = new(io)
141
- return reader unless block_given?
142
-
143
- # This exception context must remain, otherwise the stream closes on open even if
144
- # a block is not given.
145
- begin
146
- yield reader
147
- ensure
148
- reader.close
149
- end
147
+ # With no associated block, Reader::open is a synonym for Reader::new. If the optional
148
+ # code block is given, it will be passed the new _reader_ as an argument and the Reader
149
+ # object will automatically be closed when the block terminates. In this
150
+ # instance, Reader::open returns the value of the block.
151
+ def self.open(io)
152
+ reader = new(io)
153
+ return reader unless block_given?
154
+
155
+ # This exception context must remain, otherwise the stream closes on open even if
156
+ # a block is not given.
157
+ begin
158
+ yield reader
159
+ ensure
160
+ reader.close
150
161
  end
162
+ end
151
163
 
152
- # Iterates over each entry in the provided input. This wraps the common pattern of:
153
- #
154
- # Minitar::Input.open(io) do |i|
155
- # inp.each do |entry|
156
- # # ...
157
- # end
158
- # end
159
- #
160
- # If a block is not provided, an enumerator will be created with the same behaviour.
161
- #
162
- # :call-seq:
163
- # Minitar::Reader.each_entry(io) -> enumerator
164
- # Minitar::Reader.each_entry(io) { |entry| block } -> obj
165
- def self.each_entry(io)
166
- return to_enum(__method__, io) unless block_given?
167
-
168
- Input.open(io) do |reader|
169
- reader.each_entry do |entry|
170
- yield entry
171
- end
164
+ # Iterates over each entry in the provided input. This wraps the common pattern of:
165
+ #
166
+ # ```ruby
167
+ # Minitar::Input.open(io) do |i|
168
+ # inp.each do |entry|
169
+ # # ...
170
+ # end
171
+ # end
172
+ # ```
173
+ #
174
+ # If a block is not provided, an enumerator will be created with the same behaviour.
175
+ #
176
+ # :call-seq:
177
+ # Minitar::Reader.each_entry(io) -> enumerator
178
+ # Minitar::Reader.each_entry(io) { |entry| block } -> obj
179
+ def self.each_entry(io)
180
+ return to_enum(__method__, io) unless block_given?
181
+
182
+ Input.open(io) do |reader|
183
+ reader.each_entry do |entry|
184
+ yield entry
172
185
  end
173
186
  end
187
+ end
174
188
 
175
- # Creates and returns a new Reader object.
176
- def initialize(io)
177
- @io = io
178
- @init_pos = begin
179
- io.pos
180
- rescue
181
- nil
182
- end
189
+ # Creates and returns a new Reader object.
190
+ def initialize(io)
191
+ @io = io
192
+ @init_pos = begin
193
+ io.pos
194
+ rescue
195
+ nil
183
196
  end
197
+ end
184
198
 
185
- # Resets the read pointer to the beginning of data stream. Do not call this during
186
- # a #each or #each_entry iteration. This only works with random access data streams
187
- # that respond to #rewind and #pos.
188
- def rewind
189
- if @init_pos.zero?
190
- raise Minitar::NonSeekableStream unless Minitar.seekable?(@io, :rewind)
191
- @io.rewind
192
- else
193
- raise Minitar::NonSeekableStream unless Minitar.seekable?(@io, :pos=)
194
- @io.pos = @init_pos
195
- end
199
+ # Resets the read pointer to the beginning of data stream. Do not call this during
200
+ # a #each or #each_entry iteration. This only works with random access data streams that
201
+ # respond to #rewind and #pos.
202
+ def rewind
203
+ if @init_pos.zero?
204
+ raise Minitar::NonSeekableStream unless Minitar.seekable?(@io, :rewind)
205
+ @io.rewind
206
+ else
207
+ raise Minitar::NonSeekableStream unless Minitar.seekable?(@io, :pos=)
208
+ @io.pos = @init_pos
196
209
  end
210
+ end
197
211
 
198
- # Iterates through each entry in the data stream.
199
- def each_entry
200
- return to_enum unless block_given?
212
+ # Iterates through each entry in the data stream.
213
+ def each_entry
214
+ return to_enum unless block_given?
201
215
 
202
- loop do
203
- return if @io.eof?
216
+ loop do
217
+ return if @io.eof?
204
218
 
205
- header = Minitar::PosixHeader.from_stream(@io)
206
- raise Minitar::InvalidTarStream unless header.valid?
207
- return if header.empty?
219
+ header = Minitar::PosixHeader.from_stream(@io)
220
+ raise Minitar::InvalidTarStream unless header.valid?
221
+ return if header.empty?
208
222
 
209
- raise Minitar::InvalidTarStream if header.size < 0
223
+ raise Minitar::InvalidTarStream if header.size < 0
210
224
 
211
- if header.long_name?
212
- name_block = (header.size / 512.0).ceil * 512
225
+ if header.long_name?
226
+ name_block = (header.size / 512.0).ceil * 512
213
227
 
214
- long_name = @io.read(name_block).rstrip
215
- header = PosixHeader.from_stream(@io)
228
+ long_name = @io.read(name_block).rstrip
229
+ header = Minitar::PosixHeader.from_stream(@io)
216
230
 
217
- return if header.empty?
218
- header.long_name = long_name
219
- elsif header.pax_header?
220
- pax_header = PaxHeader.from_stream(@io, header)
231
+ return if header.empty?
232
+ header.long_name = long_name
233
+ elsif header.pax_header?
234
+ pax_header = Minitar::PaxHeader.from_stream(@io, header)
221
235
 
222
- header = PosixHeader.from_stream(@io)
223
- return if header.empty?
236
+ header = Minitar::PosixHeader.from_stream(@io)
237
+ return if header.empty?
224
238
 
225
- header.size = pax_header.size if pax_header.size
226
- end
239
+ header.size = pax_header.size if pax_header.size
240
+ end
227
241
 
228
- entry = EntryStream.new(header, @io)
229
- size = entry.size
242
+ entry = EntryStream.new(header, @io)
243
+ size = entry.size
230
244
 
231
- yield entry
245
+ yield entry
232
246
 
233
- skip = (512 - (size % 512)) % 512
247
+ skip = (512 - (size % 512)) % 512
234
248
 
235
- if Minitar.seekable?(@io, :seek)
236
- # avoid reading...
237
- try_seek(size - entry.bytes_read)
238
- else
239
- pending = size - entry.bytes_read
240
- while pending > 0
241
- bread = @io.read([pending, 4096].min).bytesize
242
- raise UnexpectedEOF if @io.eof?
243
- pending -= bread
244
- end
249
+ if Minitar.seekable?(@io, :seek)
250
+ # avoid reading...
251
+ try_seek(size - entry.bytes_read)
252
+ else
253
+ pending = size - entry.bytes_read
254
+ while pending > 0
255
+ bread = @io.read([pending, 4096].min).bytesize
256
+ raise Minitar::UnexpectedEOF if @io.eof?
257
+ pending -= bread
245
258
  end
246
-
247
- @io.read(skip) # discard trailing zeros
248
- # make sure nobody can use #read, #getc or #rewind anymore
249
- entry.close
250
259
  end
251
- end
252
- alias_method :each, :each_entry
253
-
254
- # Returns false if the reader is open (it never closes).
255
- def closed? = false
256
260
 
257
- def close
261
+ @io.read(skip) # discard trailing zeros
262
+ # make sure nobody can use #read, #getc or #rewind anymore
263
+ entry.close
258
264
  end
259
-
260
- private
261
-
262
- def try_seek(bytes)
263
- @io.seek(bytes, IO::SEEK_CUR)
264
- rescue RangeError
265
- # This happens when skipping the large entry and the skipping entry size exceeds
266
- # maximum allowed size (varies by platform and underlying IO object).
267
- max = RbConfig::LIMITS.fetch("INT_MAX", 2147483647)
268
- skipped = 0
269
- while skipped < bytes
270
- to_skip = [bytes - skipped, max].min
271
- @io.seek(to_skip, IO::SEEK_CUR)
272
- skipped += to_skip
273
- end
265
+ end
266
+ alias_method :each, :each_entry
267
+
268
+ # Returns `false` if the reader is open (it never closes).
269
+ def closed? = false
270
+
271
+ def close = nil
272
+
273
+ private
274
+
275
+ def try_seek(bytes)
276
+ @io.seek(bytes, IO::SEEK_CUR)
277
+ rescue RangeError
278
+ # This happens when skipping the large entry and the skipping entry size exceeds
279
+ # maximum allowed size (varies by platform and underlying IO object).
280
+ max = RbConfig::LIMITS.fetch("INT_MAX", 2147483647)
281
+ skipped = 0
282
+ while skipped < bytes
283
+ to_skip = [bytes - skipped, max].min
284
+ @io.seek(to_skip, IO::SEEK_CUR)
285
+ skipped += to_skip
274
286
  end
275
287
  end
276
288
  end
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  class Minitar
4
- VERSION = "1.1.0"
4
+ VERSION = "1.2.0"
5
5
  end