Class: Minitar::Writer

Inherits:
Object
  • Object
show all
Defined in:
lib/minitar/writer.rb

Overview

The class that writes a tar format archive to a data stream.

Constant Summary collapse

WriteBoundaryOverflow =

The exception raised when the user attempts to write more data to a BoundedWriteStream than has been allocated.

Class.new(StandardError)

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(io) ⇒ Writer

Creates and returns a new Writer object.



97
98
99
100
 
# File 'lib/minitar/writer.rb', line 97

def initialize(io)
  @io = io
  @closed = false
end

Class Method Details

.const_missing(c) ⇒ Object 



59
60
61
62
63
64
65
66
67
 
# File 'lib/minitar/writer.rb', line 59

def self.const_missing(c)
  case c
  when :BoundedStream
    warn "BoundedStream has been renamed to BoundedWriteStream"
    const_set(:BoundedStream, BoundedWriteStream)
  else
    super
  end
end

.open(io) ⇒ Object

With no associated block, Writer::open is a synonym for Writer::new. If the optional code block is given, it will be passed the new writer as an argument and the Writer object will automatically be closed when the block terminates. In this instance, Writer::open returns the value of the block.

call-seq:

w = Minitar::Writer.open(STDOUT)
w.add_file_simple('foo.txt', :size => 3)
w.close

Minitar::Writer.open(STDOUT) do |w|
  w.add_file_simple('foo.txt', :size => 3)
end



83
84
85
86
87
88
89
90
91
92
93
94
 
# File 'lib/minitar/writer.rb', line 83

def self.open(io) # :yields Writer:
  writer = new(io)
  return writer unless block_given?

  # This exception context must remain, otherwise the stream closes on open
  # even if a block is not given.
  begin
    yield writer
  ensure
    writer.close
  end
end

Instance Method Details

#add_file(name, opts = {}) {|WriteOnlyStream.new(@io), opts| ... } ⇒ Object

Adds a file to the archive as name. The data can be provided in the opts[:data] or provided to a yielded WriteOnlyStream. The size of the file will be determined from the amount of data written to the stream.

Valid parameters to opts are:

:mode

The Unix file permissions mode value. If not provided, defaults to 0644.

:uid

The Unix file owner user ID number.

:gid

The Unix file owner group ID number.

:mtime

File modification time, interpreted as an integer.

:data

Optional. The data to write to the archive.

If opts[:data] is provided, this acts the same as #add_file_simple. Otherwise, the file’s size will be determined from the amount of data written to the stream.

For #add_file to be used without opts[:data], the Writer must be wrapping a stream object that is seekable. Otherwise, #add_file_simple must be used.

opts may be modified during the writing of the file to the stream.

Yields:

  • (WriteOnlyStream.new(@io), opts)

Raises:



200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
 
# File 'lib/minitar/writer.rb', line 200

def add_file(name, opts = {}, &) # :yields WriteOnlyStream, +opts+:
  raise ClosedStream if @closed

  return add_file_simple(name, opts, &) if opts[:data]

  unless Minitar.seekable?(@io)
    raise Minitar::NonSeekableStream
  end

  short_name, prefix, needs_long_name = split_name(name)

  data_offset = needs_long_name ? 3 * 512 : 512
  init_pos = @io.pos
  @io.write("\0" * data_offset) # placeholder for the header

  yield WriteOnlyStream.new(@io), opts

  size = @io.pos - (init_pos + data_offset)
  remainder = (512 - (size % 512)) % 512
  @io.write("\0" * remainder)

  final_pos, @io.pos = @io.pos, init_pos

  header = {
    mode: opts[:mode],
    mtime: opts[:mtime],
    size: size,
    gid: opts[:gid],
    uid: opts[:uid]
  }

  write_header(header, name, short_name, prefix, needs_long_name)

  @io.pos = final_pos
end

#add_file_simple(name, opts = {}) ⇒ Object

Adds a file to the archive as name. The data can be provided in the opts[:data] or provided to a BoundedWriteStream that is yielded to the provided block.

If opts[:data] is provided, all other values to opts are optional. If the data is provided to the yielded BoundedWriteStream, opts[:size] must be provided.

Valid parameters to opts are:

:data

Optional. The data to write to the archive.

:mode

The Unix file permissions mode value. If not provided, defaults to 0644.

:size

The size, in bytes. If :data is provided, this parameter may be ignored (if it is less than the size of the data provided) or used to add padding (if it is greater than the size of the data provided).

:uid

The Unix file owner user ID number.

:gid

The Unix file owner group ID number.

:mtime

File modification time, interpreted as an integer.

An exception will be raised if the Writer is already closed, or if more data is written to the BoundedWriteStream than expected.

call-seq:

writer.add_file_simple('foo.txt', :data => "bar")
writer.add_file_simple('foo.txt', :size => 3) do |w|
  w.write("bar")
end

Raises:



132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
 
# File 'lib/minitar/writer.rb', line 132

def add_file_simple(name, opts = {}) # :yields BoundedWriteStream:
  raise ClosedStream if @closed

  header = {
    mode: opts.fetch(:mode, 0o644),
    mtime: opts.fetch(:mtime, nil),
    gid: opts.fetch(:gid, nil),
    uid: opts.fetch(:uid, nil)
  }

  data = opts.fetch(:data, nil)
  size = opts.fetch(:size, nil)

  if block_given?
    if data
      raise ArgumentError,
        "Too much data (opts[:data] and block_given?)."
    end

    raise ArgumentError, "No size provided" unless size
  else
    raise ArgumentError, "No data provided" unless data

    bytes = data.bytesize
    size = bytes if size.nil? || size < bytes
  end

  header[:size] = size

  short_name, prefix, needs_long_name = split_name(name)
  write_header(header, name, short_name, prefix, needs_long_name)

  os = BoundedWriteStream.new(@io, size)
  if block_given?
    yield os
  else
    os.write(data)
  end

  min_padding = size - os.written
  @io.write("\0" * min_padding)
  remainder = (512 - (size % 512)) % 512
  @io.write("\0" * remainder)
end

#close ⇒ Object

Closes the Writer. This does not close the underlying wrapped output stream.



291
292
293
294
295
 
# File 'lib/minitar/writer.rb', line 291

def close
  return if @closed
  @io.write("\0" * 1024)
  @closed = true
end

#closed? ⇒ Boolean

Returns false if the writer is open.

Returns:

  • (Boolean) 


285
286
287
 
# File 'lib/minitar/writer.rb', line 285

def closed?
  @closed
end

#flush ⇒ Object

Passes the #flush method to the wrapped stream, used for buffered streams.

Raises:



279
280
281
282
 
# File 'lib/minitar/writer.rb', line 279

def flush
  raise ClosedStream if @closed
  @io.flush if @io.respond_to?(:flush)
end

#mkdir(name, opts = {}) ⇒ Object

Creates a directory entry in the tar.

Raises:



237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
 
# File 'lib/minitar/writer.rb', line 237

def mkdir(name, opts = {})
  raise ClosedStream if @closed

  header = {
    mode: opts[:mode],
    typeflag: "5",
    size: 0,
    gid: opts[:gid],
    uid: opts[:uid],
    mtime: opts[:mtime]
  }

  short_name, prefix, needs_long_name = split_name(name)
  write_header(header, name, short_name, prefix, needs_long_name)

  nil
end

#symlink(name, link_target, opts = {}) ⇒ Object

Creates a symbolic link entry in the tar.

Raises:



256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
 
# File 'lib/minitar/writer.rb', line 256

def symlink(name, link_target, opts = {})
  raise ClosedStream if @closed

  raise FileNameTooLong if link_target.size > 100

  name, prefix = split_name(name)
  header = {
    name: name,
    mode: opts[:mode],
    typeflag: "2",
    size: 0,
    linkname: link_target,
    gid: opts[:gid],
    uid: opts[:uid],
    mtime: opts[:mtime],
    prefix: prefix
  }
  @io.write(PosixHeader.new(header))
  nil
end