minitar 0.12.1 → 1.0.0

data/lib/{archive/tar/minitar → minitar}/output.rb

@@ -1,9 +1,7 @@
-# coding: utf-8
+require "minitar/writer"
 
-require "archive/tar/minitar/writer"
-
-module Archive::Tar::Minitar
-  # Wraps a Archive::Tar::Minitar::Writer with convenience methods and wrapped
+class Minitar
+  # Wraps a Minitar::Writer with convenience methods and wrapped
   # stream management. If the stream provided to Output does not support random
   # access, only Writer#add_file_simple and Writer#mkdir are guaranteed to
   # work.
@@ -15,8 +13,8 @@ module Archive::Tar::Minitar
     # instance, +Output.open+ returns the value of the block.
     #
     # call-seq:
-    #    Archive::Tar::Minitar::Output.open(io) -> output
-    #    Archive::Tar::Minitar::Output.open(io) { |output| block } -> obj
+    #    Minitar::Output.open(io) -> output
+    #    Minitar::Output.open(io) { |output| block } -> obj
     def self.open(output)
       stream = new(output)
       return stream unless block_given?
@@ -35,8 +33,8 @@ module Archive::Tar::Minitar
     # will be created with the same behaviour.
     #
     # call-seq:
-    #    Archive::Tar::Minitar::Output.tar(io) -> enumerator
-    #    Archive::Tar::Minitar::Output.tar(io) { |tar| block } -> obj
+    #    Minitar::Output.tar(io) -> enumerator
+    #    Minitar::Output.tar(io) { |tar| block } -> obj
     def self.tar(output)
       return to_enum(__method__, output) unless block_given?
 
@@ -51,15 +49,15 @@ module Archive::Tar::Minitar
     # object wrapped will be closed.
     #
     # call-seq:
-    #    Archive::Tar::Minitar::Output.new(io) -> output
-    #    Archive::Tar::Minitar::Output.new(path) -> output
+    #    Minitar::Output.new(io) -> output
+    #    Minitar::Output.new(path) -> output
     def initialize(output)
       @io = if output.respond_to?(:write)
         output
       else
         ::Kernel.open(output, "wb")
       end
-      @tar = Archive::Tar::Minitar::Writer.new(@io)
+      @tar = Minitar::Writer.new(@io)
     end
 
     # Returns the Writer object for direct access.

data/lib/minitar/posix_header.rb

@@ -0,0 +1,267 @@
+class Minitar
+  # Implements the POSIX tar header as a Ruby class. The structure of
+  # the POSIX tar header is:
+  #
+  #   struct tarfile_entry_posix
+  #   {                      //                               pack/unpack
+  #      char name[100];     // ASCII (+ Z unless filled)     a100/Z100
+  #      char mode[8];       // 0 padded, octal, null         a8  /A8
+  #      char uid[8];        // 0 padded, octal, null         a8  /A8
+  #      char gid[8];        // 0 padded, octal, null         a8  /A8
+  #      char size[12];      // 0 padded, octal, null         a12 /A12
+  #      char mtime[12];     // 0 padded, octal, null         a12 /A12
+  #      char checksum[8];   // 0 padded, octal, null, space  a8  /A8
+  #      char typeflag[1];   // see below                     a   /a
+  #      char linkname[100]; // ASCII + (Z unless filled)     a100/Z100
+  #      char magic[6];      // "ustar\0"                     a6  /A6
+  #      char version[2];    // "00"                          a2  /A2
+  #      char uname[32];     // ASCIIZ                        a32 /Z32
+  #      char gname[32];     // ASCIIZ                        a32 /Z32
+  #      char devmajor[8];   // 0 padded, octal, null         a8  /A8
+  #      char devminor[8];   // 0 padded, octal, null         a8  /A8
+  #      char prefix[155];   // ASCII (+ Z unless filled)     a155/Z155
+  #   };
+  #
+  # The #typeflag is one of several known values.
+  #
+  # POSIX indicates that "A POSIX-compliant implementation must treat any
+  # unrecognized typeflag value as a regular file."
+  class PosixHeader
+    BLOCK_SIZE = 512
+    MAGIC_BYTES = "ustar".freeze
+
+    GNU_EXT_LONG_LINK = "././@LongLink"
+
+    # Fields that must be set in a POSIX tar(1) header.
+    REQUIRED_FIELDS = [:name, :size, :prefix, :mode].freeze
+    # Fields that may be set in a POSIX tar(1) header.
+    OPTIONAL_FIELDS = [
+      :uid, :gid, :mtime, :checksum, :typeflag, :linkname, :magic, :version,
+      :uname, :gname, :devmajor, :devminor
+    ].freeze
+
+    # All fields available in a POSIX tar(1) header.
+    FIELDS = (REQUIRED_FIELDS + OPTIONAL_FIELDS).freeze
+
+    FIELDS.each do |f|
+      attr_reader f.to_sym unless f.to_sym == :name
+    end
+
+    # The name of the file. By default, limited to 100 bytes. Required. May be
+    # longer (up to BLOCK_SIZE bytes) if using the GNU long name tar extension.
+    attr_accessor :name
+
+    # The pack format passed to Array#pack for encoding a header.
+    HEADER_PACK_FORMAT = "a100a8a8a8a12a12a7aaa100a6a2a32a32a8a8a155".freeze
+    # The unpack format passed to String#unpack for decoding a header.
+    HEADER_UNPACK_FORMAT = "Z100A8A8A8A12A12A8aZ100A6A2Z32Z32A8A8Z155".freeze
+
+    class << self
+      # Creates a new PosixHeader from a data stream.
+      def from_stream(stream)
+        from_data(stream.read(BLOCK_SIZE))
+      end
+
+      # Creates a new PosixHeader from a data stream. Deprecated; use
+      # PosixHeader.from_stream instead.
+      def new_from_stream(stream)
+        warn "#{__method__} has been deprecated; use from_stream instead."
+        from_stream(stream)
+      end
+
+      # Creates a new PosixHeader from a BLOCK_SIZE-byte data buffer.
+      def from_data(data)
+        fields = data.unpack(HEADER_UNPACK_FORMAT)
+        name = fields.shift
+        mode = fields.shift.oct
+        uid = fields.shift.oct
+        gid = fields.shift.oct
+        size = strict_oct(fields.shift)
+        mtime = fields.shift.oct
+        checksum = fields.shift.oct
+        typeflag = fields.shift
+        linkname = fields.shift
+        magic = fields.shift
+        version = fields.shift.oct
+        uname = fields.shift
+        gname = fields.shift
+        devmajor = fields.shift.oct
+        devminor = fields.shift.oct
+        prefix = fields.shift
+
+        empty = !data.each_byte.any?(&:nonzero?)
+
+        new(
+          name: name,
+          mode: mode,
+          uid: uid,
+          gid: gid,
+          size: size,
+          mtime: mtime,
+          checksum: checksum,
+          typeflag: typeflag,
+          magic: magic,
+          version: version,
+          uname: uname,
+          gname: gname,
+          devmajor: devmajor,
+          devminor: devminor,
+          prefix: prefix,
+          empty: empty,
+          linkname: linkname
+        )
+      end
+
+      private
+
+      def strict_oct(string)
+        return string.oct if /\A[0-7 ]*\z/.match?(string)
+        raise ArgumentError, "#{string.inspect} is not a valid octal string"
+      end
+    end
+
+    # Creates a new PosixHeader. A PosixHeader cannot be created unless
+    # +name+, +size+, +prefix+, and +mode+ are provided.
+    def initialize(v)
+      REQUIRED_FIELDS.each do |f|
+        raise ArgumentError, "Field #{f} is required." unless v.key?(f)
+      end
+
+      v[:mtime] = v[:mtime].to_i
+      v[:checksum] ||= ""
+      v[:typeflag] ||= "0"
+      v[:magic] ||= MAGIC_BYTES
+      v[:version] ||= "00"
+
+      FIELDS.each do |f|
+        instance_variable_set(:"@#{f}", v[f])
+      end
+
+      @empty = v[:empty]
+    end
+
+    # Indicates if the header was an empty header.
+    def empty?
+      @empty
+    end
+
+    # Indicates if the header has a valid magic value.
+    def valid?
+      empty? || @magic == MAGIC_BYTES
+    end
+
+    # Returns +true+ if the header is a long name special header which indicates
+    # that the next block of data is the filename.
+    def long_name?
+      typeflag == "L" && name == GNU_EXT_LONG_LINK
+    end
+
+    # A string representation of the header.
+    def to_s
+      update_checksum
+      header(@checksum)
+    end
+    alias_method :to_str, :to_s
+
+    # Update the checksum field.
+    def update_checksum
+      hh = header(" " * 8)
+      @checksum = oct(calculate_checksum(hh), 6)
+    end
+
+    private
+
+    def oct(num, len)
+      if num.nil?
+        "\0" * (len + 1)
+      else
+        "%0#{len}o" % num
+      end
+    end
+
+    def calculate_checksum(hdr)
+      hdr.unpack("C*").inject { |a, e| a + e }
+    end
+
+    def header(chksum)
+      arr = [name, oct(mode, 7), oct(uid, 7), oct(gid, 7), oct(size, 11),
+        oct(mtime, 11), chksum, " ", typeflag, linkname, magic, version,
+        uname, gname, oct(devmajor, 7), oct(devminor, 7), prefix]
+      str = arr.pack(HEADER_PACK_FORMAT)
+      str + "\0" * ((BLOCK_SIZE - str.bytesize) % BLOCK_SIZE)
+    end
+
+    ##
+    # :attr_reader: size
+    # The size of the file. Required.
+
+    ##
+    # :attr_reader: prefix
+    # The prefix of the file; the path before #name. Limited to 155 bytes.
+    # Required.
+
+    ##
+    # :attr_reader: mode
+    # The Unix file mode of the file. Stored as an octal integer. Required.
+
+    ##
+    # :attr_reader: uid
+    # The Unix owner user ID of the file. Stored as an octal integer.
+
+    ##
+    # :attr_reader: uname
+    # The user name of the Unix owner of the file.
+
+    ##
+    # :attr_reader: gid
+    # The Unix owner group ID of the file. Stored as an octal integer.
+
+    ##
+    # :attr_reader: gname
+    # The group name of the Unix owner of the file.
+
+    ##
+    # :attr_reader: mtime
+    # The modification time of the file in epoch seconds. Stored as an
+    # octal integer.
+
+    ##
+    # :attr_reader: checksum
+    # The checksum of the file. Stored as an octal integer. Calculated
+    # before encoding the header as a string.
+
+    ##
+    # :attr_reader: typeflag
+    # The type of record in the file.
+    #
+    # +0+::  Regular file. NULL should be treated as a synonym, for compatibility
+    #        purposes.
+    # +1+::  Hard link.
+    # +2+::  Symbolic link.
+    # +3+::  Character device node.
+    # +4+::  Block device node.
+    # +5+::  Directory.
+    # +6+::  FIFO node.
+    # +7+::  Reserved.
+
+    ##
+    # :attr_reader: linkname
+    # The name of the link stored. Not currently used.
+
+    ##
+    # :attr_reader: magic
+    # Always "ustar\0".
+
+    ##
+    # :attr_reader: version
+    # Always "00"
+
+    ##
+    # :attr_reader: devmajor
+    # The major device ID. Not currently used.
+
+    ##
+    # :attr_reader: devminor
+    # The minor device ID. Not currently used.
+  end
+end

data/lib/{archive/tar/minitar → minitar}/reader.rb

@@ -1,12 +1,9 @@
-# coding: utf-8
-
-module Archive::Tar::Minitar
+class Minitar
   # The class that reads a tar format archive from a data stream. The data
   # stream may be sequential or random access, but certain features only work
   # with random access data streams.
   class Reader
     include Enumerable
-    include Archive::Tar::Minitar::ByteSize
 
     # This marks the EntryStream closed for reading without closing the
     # actual data stream.
@@ -30,9 +27,7 @@ module Archive::Tar::Minitar
 
     # EntryStreams are pseudo-streams on top of the main data stream.
     class EntryStream
-      include Archive::Tar::Minitar::ByteSize
-
-      Archive::Tar::Minitar::PosixHeader::FIELDS.each do |field|
+      Minitar::PosixHeader::FIELDS.each do |field|
         attr_reader field.to_sym
       end
 
@@ -56,7 +51,7 @@ module Archive::Tar::Minitar
         @prefix = header.prefix
         @read = 0
         @orig_pos =
-          if Archive::Tar::Minitar.seekable?(@io)
+          if Minitar.seekable?(@io)
             @io.pos
           else
             0
@@ -70,7 +65,7 @@ module Archive::Tar::Minitar
         len ||= @size - @read
         max_read = [len, @size - @read].min
         ret = @io.read(max_read)
-        @read += bytesize(ret)
+        @read += ret.bytesize
         ret
       end
 
@@ -119,8 +114,8 @@ module Archive::Tar::Minitar
 
       # Sets the current read pointer to the beginning of the EntryStream.
       def rewind
-        unless Archive::Tar::Minitar.seekable?(@io, :pos=)
-          raise Archive::Tar::Minitar::NonSeekableStream
+        unless Minitar.seekable?(@io, :pos=)
+          raise Minitar::NonSeekableStream
         end
         @io.pos = @orig_pos
         @read = 0
@@ -177,7 +172,7 @@ module Archive::Tar::Minitar
     # Iterates over each entry in the provided input. This wraps the common
     # pattern of:
     #
-    #     Archive::Tar::Minitar::Input.open(io) do |i|
+    #     Minitar::Input.open(io) do |i|
     #       inp.each do |entry|
     #         # ...
     #       end
@@ -187,8 +182,8 @@ module Archive::Tar::Minitar
     # behaviour.
     #
     # call-seq:
-    #    Archive::Tar::Minitar::Reader.each_entry(io) -> enumerator
-    #    Archive::Tar::Minitar::Reader.each_entry(io) { |entry| block } -> obj
+    #    Minitar::Reader.each_entry(io) -> enumerator
+    #    Minitar::Reader.each_entry(io) { |entry| block } -> obj
     def self.each_entry(io)
       return to_enum(__method__, io) unless block_given?
 
@@ -214,13 +209,13 @@ module Archive::Tar::Minitar
     # random access data streams that respond to #rewind and #pos.
     def rewind
       if @init_pos.zero?
-        unless Archive::Tar::Minitar.seekable?(@io, :rewind)
-          raise Archive::Tar::Minitar::NonSeekableStream
+        unless Minitar.seekable?(@io, :rewind)
+          raise Minitar::NonSeekableStream
         end
         @io.rewind
       else
-        unless Archive::Tar::Minitar.seekable?(@io, :pos=)
-          raise Archive::Tar::Minitar::NonSeekableStream
+        unless Minitar.seekable?(@io, :pos=)
+          raise Minitar::NonSeekableStream
         end
         @io.pos = @init_pos
       end
@@ -233,11 +228,11 @@ module Archive::Tar::Minitar
       loop do
         return if @io.eof?
 
-        header = Archive::Tar::Minitar::PosixHeader.from_stream(@io)
-        raise Archive::Tar::Minitar::InvalidTarStream unless header.valid?
+        header = Minitar::PosixHeader.from_stream(@io)
+        raise Minitar::InvalidTarStream unless header.valid?
         return if header.empty?
 
-        raise Archive::Tar::Minitar::InvalidTarStream if header.size < 0
+        raise Minitar::InvalidTarStream if header.size < 0
 
         if header.long_name?
           name_block = (header.size / 512.0).ceil * 512
@@ -256,13 +251,13 @@ module Archive::Tar::Minitar
 
         skip = (512 - (size % 512)) % 512
 
-        if Archive::Tar::Minitar.seekable?(@io, :seek)
+        if Minitar.seekable?(@io, :seek)
           # avoid reading...
           @io.seek(size - entry.bytes_read, IO::SEEK_CUR)
         else
           pending = size - entry.bytes_read
           while pending > 0
-            bread = bytesize(@io.read([pending, 4096].min))
+            bread = @io.read([pending, 4096].min).bytesize
             raise UnexpectedEOF if @io.eof?
             pending -= bread
           end

data/lib/{archive/tar/minitar → minitar}/writer.rb

@@ -1,10 +1,6 @@
-# coding: utf-8
-
-module Archive::Tar::Minitar
+class Minitar
   # The class that writes a tar format archive to a data stream.
   class Writer
-    include Archive::Tar::Minitar::ByteSize
-
     # The exception raised when the user attempts to write more data to a
     # BoundedWriteStream than has been allocated.
     WriteBoundaryOverflow = Class.new(StandardError)
@@ -25,15 +21,13 @@ module Archive::Tar::Minitar
 
     # A WriteOnlyStream that also has a size limit.
     class BoundedWriteStream < WriteOnlyStream
-      include Archive::Tar::Minitar::ByteSize
-
       def self.const_missing(c)
         case c
         when :FileOverflow
           warn "Writer::BoundedWriteStream::FileOverflow has been renamed " \
             "to Writer::WriteBoundaryOverflow"
           const_set :FileOverflow,
-            Archive::Tar::Minitar::Writer::WriteBoundaryOverflow
+            Minitar::Writer::WriteBoundaryOverflow
         else
           super
         end
@@ -52,7 +46,7 @@ module Archive::Tar::Minitar
       end
 
       def write(data)
-        size = bytesize(data)
+        size = data.bytesize
         raise WriteBoundaryOverflow if (size + @written) > @limit
         @io.write(data)
         @written += size
@@ -79,11 +73,11 @@ module Archive::Tar::Minitar
     # of the block.
     #
     # call-seq:
-    #    w = Archive::Tar::Minitar::Writer.open(STDOUT)
+    #    w = Minitar::Writer.open(STDOUT)
     #    w.add_file_simple('foo.txt', :size => 3)
     #    w.close
     #
-    #    Archive::Tar::Minitar::Writer.open(STDOUT) do |w|
+    #    Minitar::Writer.open(STDOUT) do |w|
     #      w.add_file_simple('foo.txt', :size => 3)
     #    end
     def self.open(io) # :yields Writer:
@@ -139,10 +133,10 @@ module Archive::Tar::Minitar
       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)
+        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)
@@ -158,7 +152,7 @@ module Archive::Tar::Minitar
       else
         raise ArgumentError, "No data provided" unless data
 
-        bytes = bytesize(data)
+        bytes = data.bytesize
         size = bytes if size.nil? || size < bytes
       end
 
@@ -203,13 +197,13 @@ module Archive::Tar::Minitar
     # #add_file_simple must be used.
     #
     # +opts+ may be modified during the writing of the file to the stream.
-    def add_file(name, opts = {}, &block) # :yields WriteOnlyStream, +opts+:
+    def add_file(name, opts = {}, &) # :yields WriteOnlyStream, +opts+:
       raise ClosedStream if @closed
 
-      return add_file_simple(name, opts, &block) if opts[:data]
+      return add_file_simple(name, opts, &) if opts[:data]
 
-      unless Archive::Tar::Minitar.seekable?(@io)
-        raise Archive::Tar::Minitar::NonSeekableStream
+      unless Minitar.seekable?(@io)
+        raise Minitar::NonSeekableStream
       end
 
       short_name, prefix, needs_long_name = split_name(name)
@@ -227,11 +221,11 @@ module Archive::Tar::Minitar
       final_pos, @io.pos = @io.pos, init_pos
 
       header = {
-        :mode => opts[:mode],
-        :mtime => opts[:mtime],
-        :size => size,
-        :gid => opts[:gid],
-        :uid => opts[:uid]
+        mode: opts[:mode],
+        mtime: opts[:mtime],
+        size: size,
+        gid: opts[:gid],
+        uid: opts[:uid]
       }
 
       write_header(header, name, short_name, prefix, needs_long_name)
@@ -244,12 +238,12 @@ module Archive::Tar::Minitar
       raise ClosedStream if @closed
 
       header = {
-        :mode => opts[:mode],
-        :typeflag => "5",
-        :size => 0,
-        :gid => opts[:gid],
-        :uid => opts[:uid],
-        :mtime => opts[:mtime]
+        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)
@@ -266,15 +260,15 @@ module Archive::Tar::Minitar
 
       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
+        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
@@ -305,23 +299,23 @@ module Archive::Tar::Minitar
     def write_header(header, long_name, short_name, prefix, needs_long_name)
       if needs_long_name
         long_name_header = {
-          :prefix => "",
-          :name => PosixHeader::GNU_EXT_LONG_LINK,
-          :typeflag => "L",
-          :size => long_name.length + 1,
-          :mode => 0
+          prefix: "",
+          name: PosixHeader::GNU_EXT_LONG_LINK,
+          typeflag: "L",
+          size: long_name.length + 1,
+          mode: 0
         }
         @io.write(PosixHeader.new(long_name_header))
         @io.write(long_name)
         @io.write("\0" * (512 - (long_name.length % 512)))
       end
 
-      new_header = header.merge({:name => short_name, :prefix => prefix})
+      new_header = header.merge({name: short_name, prefix: prefix})
       @io.write(PosixHeader.new(new_header))
     end
 
     def split_name(name)
-      if bytesize(name) <= 100
+      if name.bytesize <= 100
         prefix = ""
       else
         parts = name.split("/")
@@ -331,7 +325,7 @@ module Archive::Tar::Minitar
 
         loop do
           nxt = parts.pop || ""
-          break if bytesize(newname) + 1 + bytesize(nxt) >= 100
+          break if newname.bytesize + 1 + nxt.bytesize >= 100
           newname = "#{nxt}/#{newname}"
         end
 
@@ -340,7 +334,7 @@ module Archive::Tar::Minitar
         name = newname
       end
 
-      [name, prefix, bytesize(name) > 100 || bytesize(prefix) > 155]
+      [name, prefix, name.bytesize > 100 || prefix.bytesize > 155]
     end
   end
 end