nbt_utils 0.0.1

data/.gitignore

@@ -0,0 +1,2 @@
+.bundle/
+.idea/

data/Gemfile

@@ -0,0 +1,3 @@
+source 'http://rubygems.org'
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,18 @@
+PATH
+  remote: .
+  specs:
+    nbt_utils (0.0.1)
+      bindata (~> 1.2)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    bindata (1.2.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bindata (~> 1.2)
+  bundler (>= 1.0.0)
+  nbt_utils!

data/README.md

@@ -0,0 +1,28 @@
+nbt_utils
+=========
+
+Some classes for handling Minecraft .nbt files.
+
+See http://www.minecraft.net/docs/NBT.txt for specification info, also mirred in the doc directory.
+
+Installation
+============
+
+Requires ruby 1.9 minimum. Tested with 1.9.2.
+
+    gem install nbt_utils
+
+Use
+===
+
+    require 'nbt_utils'
+
+    @tag = NBTUtils::File.new.read('some_nbt_file.nbt')
+    puts @tag.to_s
+
+Copyright
+=========
+
+Copyright (c) 2010 Michael Dungan, mpd@jesters-court.net, released under the MIT license.
+
+The files `NBT.txt`, `test.nbt`, and `bigtest.nbt` in the `doc` directory are mirred from the Minecraft website.

data/Rakefile

@@ -0,0 +1,2 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks

data/doc/NBT.txt

@@ -0,0 +1,149 @@
+Named Binary Tag specification
+
+NBT (Named Binary Tag) is a tag based binary format designed to carry large amounts of binary data with smaller amounts of additional data.
+An NBT file consists of a single GZIPped Named Tag of type TAG_Compound.
+
+A Named Tag has the following format:
+
+    byte tagType
+    TAG_String name
+    [payload]
+    
+The tagType is a single byte defining the contents of the payload of the tag.
+
+The name is a descriptive name, and can be anything (eg "cat", "banana", "Hello World!"). It has nothing to do with the tagType.
+The purpose for this name is to name tags so parsing is easier and can be made to only look for certain recognized tag names.
+Exception: If tagType is TAG_End, the name is skipped and assumed to be "".
+
+The [payload] varies by tagType.
+
+Note that ONLY Named Tags carry the name and tagType data. Explicitly identified Tags (such as TAG_String above) only contains the payload. 
+
+
+The tag types and respective payloads are:
+
+    TYPE: 0  NAME: TAG_End
+    Payload: None.
+    Note:    This tag is used to mark the end of a list.
+             Cannot be named! If type 0 appears where a Named Tag is expected, the name is assumed to be "".
+             (In other words, this Tag is always just a single 0 byte when named, and nothing in all other cases)
+    
+    TYPE: 1  NAME: TAG_Byte
+    Payload: A single signed byte (8 bits)
+
+    TYPE: 2  NAME: TAG_Short
+    Payload: A signed short (16 bits, big endian)
+
+    TYPE: 3  NAME: TAG_Int
+    Payload: A signed short (32 bits, big endian)
+
+    TYPE: 4  NAME: TAG_Long
+    Payload: A signed long (64 bits, big endian)
+
+    TYPE: 5  NAME: TAG_Float
+    Payload: A floating point value (32 bits, big endian, IEEE 754-2008, binary32)
+
+    TYPE: 6  NAME: TAG_Double
+    Payload: A floating point value (64 bits, big endian, IEEE 754-2008, binary64)
+    
+    TYPE: 7  NAME: TAG_Byte_Array
+    Payload: TAG_Int length 
+             An array of bytes of unspecified format. The length of this array is <length> bytes
+
+    TYPE: 8  NAME: TAG_String
+    Payload: TAG_Short length 
+             An array of bytes defining a string in UTF-8 format. The length of this array is <length> bytes
+
+    TYPE: 9  NAME: TAG_List
+    Payload: TAG_Byte tagId
+             TAG_Int length
+             A sequential list of Tags (not Named Tags), of type <typeId>. The length of this array is <length> Tags
+    Notes:   All tags share the same type.
+             
+    TYPE: 10 NAME: TAG_Compound
+    Payload: A sequential list of Named Tags. This array keeps going until a TAG_End is found.
+             TAG_End end
+    Notes:   If there's a nested TAG_Compound within this tag, that one will also have a TAG_End, so simply reading until the next TAG_End will not work.
+             The names of the named tags have to be unique within each TAG_Compound
+             The order of the tags is not guaranteed.
+             
+             
+
+
+
+Decoding example:
+(Use http://www.minecraft.net/docs/test.nbt to test your implementation)
+
+
+First we start by reading a Named Tag.
+After unzipping the stream, the first byte is a 10. That means the tag is a TAG_Compound (as expected by the specification).
+
+The next two bytes are 0 and 11, meaning the name string consists of 11 UTF-8 characters. In this case, they happen to be "hello world".
+That means our root tag is named "hello world". We can now move on to the payload.
+
+From the specification, we see that TAG_Compound consists of a series of Named Tags, so we read another byte to find the tagType.
+It happens to be an 8. The name is 4 letters long, and happens to be "name". Type 8 is TAG_String, meaning we read another two bytes to get the length,
+then read that many bytes to get the contents. In this case, it's "Bananrama".
+
+So now we know the TAG_Compound contains a TAG_String named "name" with the content "Bananrama"
+
+We move on to reading the next Named Tag, and get a 0. This is TAG_End, which always has an implied name of "". That means that the list of entries
+in the TAG_Compound is over, and indeed all of the NBT file.
+
+So we ended up with this:
+
+	TAG_Compound("hello world"): 1 entries
+	{
+	   TAG_String("name"): Bananrama
+	}
+
+
+
+For a slightly longer test, download http://www.minecraft.net/docs/bigtest.nbt
+You should end up with this:
+
+	TAG_Compound("Level"): 11 entries
+	{
+	   TAG_Short("shortTest"): 32767
+	   TAG_Long("longTest"): 9223372036854775807
+	   TAG_Float("floatTest"): 0.49823147
+	   TAG_String("stringTest"): HELLO WORLD THIS IS A TEST STRING ���!
+	   TAG_Int("intTest"): 2147483647
+	   TAG_Compound("nested compound test"): 2 entries
+	   {
+	      TAG_Compound("ham"): 2 entries
+	      {
+	         TAG_String("name"): Hampus
+	         TAG_Float("value"): 0.75
+	      }
+	      TAG_Compound("egg"): 2 entries
+	      {
+	         TAG_String("name"): Eggbert
+	         TAG_Float("value"): 0.5
+	      }
+	   }
+	   TAG_List("listTest (long)"): 5 entries of type TAG_Long
+	   {
+	      TAG_Long: 11
+	      TAG_Long: 12
+	      TAG_Long: 13
+	      TAG_Long: 14
+	      TAG_Long: 15
+	   }
+	   TAG_Byte("byteTest"): 127
+	   TAG_List("listTest (compound)"): 2 entries of type TAG_Compound
+	   {
+	      TAG_Compound: 2 entries
+	      {
+	         TAG_String("name"): Compound tag #0
+	         TAG_Long("created-on"): 1264099775885
+	      }
+	      TAG_Compound: 2 entries
+	      {
+	         TAG_String("name"): Compound tag #1
+	         TAG_Long("created-on"): 1264099775885
+	      }
+	   }
+	   TAG_Byte_Array("byteArrayTest (the first 1000 values of (n*n*255+n*7)%100, starting with n=0 (0, 62, 34, 16, 8, ...))"): [1000 bytes]
+	   TAG_Double("doubleTest"): 0.4931287132182315
+	}

data/lib/nbt_utils.rb

@@ -0,0 +1,19 @@
+require 'zlib'
+require 'bindata'
+
+require File.expand_path('nbt_utils/tag/exceptions', File.dirname(__FILE__))
+
+require File.expand_path('nbt_utils/file', File.dirname(__FILE__))
+require File.expand_path('nbt_utils/tag_name', File.dirname(__FILE__))
+require File.expand_path('nbt_utils/tag', File.dirname(__FILE__))
+require File.expand_path('nbt_utils/tag/end', File.dirname(__FILE__))
+require File.expand_path('nbt_utils/tag/byte', File.dirname(__FILE__))
+require File.expand_path('nbt_utils/tag/short', File.dirname(__FILE__))
+require File.expand_path('nbt_utils/tag/int', File.dirname(__FILE__))
+require File.expand_path('nbt_utils/tag/long', File.dirname(__FILE__))
+require File.expand_path('nbt_utils/tag/float', File.dirname(__FILE__))
+require File.expand_path('nbt_utils/tag/double', File.dirname(__FILE__))
+require File.expand_path('nbt_utils/tag/byte_array', File.dirname(__FILE__))
+require File.expand_path('nbt_utils/tag/string', File.dirname(__FILE__))
+require File.expand_path('nbt_utils/tag/list', File.dirname(__FILE__))
+require File.expand_path('nbt_utils/tag/compound', File.dirname(__FILE__))

data/lib/nbt_utils/file.rb

@@ -0,0 +1,25 @@
+module NBTUtils
+  class File
+    def initialize(path = nil)
+      @path = path
+    end
+
+    def read(path = @path)
+      Zlib::GzipReader.open(path) do |f|
+        # ostensibly this will always be a single TAG_Compound, per the spec
+        last_byte = f.read(1).bytes.first
+        klass = NBTUtils::Tag.tag_type_to_class(last_byte)
+
+        @tag = klass.new(f, true)
+      end
+
+      @tag
+    end
+
+    def write(path = @path, tag = @tag)
+      Zlib::GzipWriter.open(path) do |gz|
+        gz.write tag.to_nbt_string
+      end
+    end
+  end
+end

data/lib/nbt_utils/tag.rb

@@ -0,0 +1,77 @@
+module NBTUtils
+  module Tag
+    attr_reader :name
+    attr_reader :payload
+
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+    def initialize(io, named = true)
+      read_name(io) if named
+      @payload = self.class.payload_class.new.read(io)
+    end
+    
+    def type_id
+      self.class.type_id
+    end
+
+    def binary_type_id
+      # I hope i'm doing this wrong.
+      byte = ::BinData::Int8be.new
+      byte.value = type_id
+      byte.to_binary_s
+    end
+
+    def to_s(indent = 0)
+      klass = self.class.to_s.split('::').last
+      (' ' * indent) + "TAG_#{klass}#{@name ? "(\"#{@name}\")" : ''}: #{@payload.value}"
+    end
+
+    def to_nbt_string(named = true)
+      result = named ? binary_type_id + name_to_nbt_string : ''
+      result + @payload.to_binary_s
+    end
+
+    def read_name(io)
+      @name = NBTUtils::TagName.new.read(io).data
+    end
+
+    def name_to_nbt_string
+      nm = NBTUtils::TagName.new
+      nm.data = @name
+      nm.to_binary_s
+    end
+
+    def tag_type_to_class(tag_type)
+      NBTUtils::Tag.tag_type_to_class(tag_type)
+    end
+
+    module ClassMethods
+      def type_id(new_id = nil)
+        if new_id
+          @type_id = new_id
+          NBTUtils::Tag.add_tag_type(new_id, self)
+        end
+
+        @type_id
+      end
+
+      def payload_class(new_klass = nil)
+        @payload_class = new_klass if new_klass
+        @payload_class
+      end
+    end
+
+    def self.tag_type_to_class(tag_type)
+      @tag_types[tag_type.to_i]
+    end
+
+    protected
+
+    def self.add_tag_type(index, tag_type)
+      @tag_types ||= []
+      @tag_types[index] = tag_type
+    end
+  end
+end

data/lib/nbt_utils/tag/byte.rb

@@ -0,0 +1,10 @@
+module NBTUtils
+  module Tag
+    class Byte # signed, per spec
+      include NBTUtils::Tag
+
+      type_id 1
+      payload_class ::BinData::Int8be
+    end
+  end
+end

data/lib/nbt_utils/tag/byte_array.rb

@@ -0,0 +1,29 @@
+module NBTUtils
+  module Tag
+    class ByteArray
+      include NBTUtils::Tag
+
+      type_id 7
+
+      def initialize(io, named = true)
+        read_name(io) if named
+
+        len = ::BinData::Int32be.new.read(io).value
+        # signedness of the bytes in the array is not defined in the spec.
+        @payload = ::BinData::Array.new(:type => :uint8, :initial_length => len).read(io)
+      end
+
+      def to_s(indent = 0)
+        (' ' * indent) + "TAG_Byte_Array#{@name ? "(\"#{@name}\")" : ''}: [#{@payload.length} bytes]"
+      end
+
+      def to_nbt_string(named = true)
+        result = named ? binary_type_id + name_to_nbt_string : ''
+        len = ::BinData::Int32be.new
+        len.value = @payload.length
+        result += len.to_binary_s
+        result + @payload.to_binary_s
+      end
+    end
+  end
+end

data/lib/nbt_utils/tag/compound.rb

@@ -0,0 +1,56 @@
+module NBTUtils
+  module Tag
+    class Compound
+      include NBTUtils::Tag
+
+      type_id 10
+
+      def initialize(io, named = true)
+        @payload = []
+        @tag_names = []
+        read_name(io) if named
+
+        until (last_byte = io.read(1).bytes.first) == NBTUtils::Tag::End.type_id
+          klass = tag_type_to_class(last_byte)
+          add_tag klass.new(io, true)
+        end
+      end
+
+      def to_s(indent = 0)
+        ret = (' ' * indent) + "TAG_Compound#{@name ? "(\"#{@name}\")" : ''}: #{@payload.length} entries\n"
+        ret += (' ' * indent) + "{\n"
+        @payload.each do |load|
+          ret += "#{load.to_s(indent + 2)}\n"
+        end
+        ret += (' ' * indent) + "}"
+
+        ret
+      end
+
+      def to_nbt_string(named = true)
+        result = named ? binary_type_id + name_to_nbt_string : ''
+
+        result = @payload.inject(result) do |r, load|
+          r + load.to_nbt_string(true)
+        end
+
+        result + NBTUtils::Tag::End.new(nil).to_nbt_string
+      end
+
+      def find_tag(name)
+        @payload.detect { |tag| tag.name =~ /#{name}/ }
+      end
+
+      def find_tags(name)
+        @payload.select { |tag| tag.name =~ /#{name}/ }
+      end
+
+      def add_tag(tag)
+        raise MissingCompoundPayloadTagNameError if tag.name.nil?
+        raise DuplicateCompoundPayloadTagNameError if @tag_names.include?(tag.name)
+        @tag_names << tag.name
+        @payload << tag
+      end
+    end
+  end
+end

data/lib/nbt_utils/tag/double.rb

@@ -0,0 +1,10 @@
+module NBTUtils
+  module Tag
+    class Double # signed, per spec
+      include NBTUtils::Tag
+
+      type_id 6
+      payload_class ::BinData::DoubleBe
+    end
+  end
+end

data/lib/nbt_utils/tag/end.rb

@@ -0,0 +1,21 @@
+module NBTUtils
+  module Tag
+    class End
+      include NBTUtils::Tag
+
+      type_id 0
+
+      def initialize(input, named = false)
+        @name = ''
+      end
+
+      def to_s(indent = 0)
+        ''
+      end
+
+      def to_nbt_string(named = false)
+        binary_type_id
+      end
+    end
+  end
+end

data/lib/nbt_utils/tag/exceptions.rb

@@ -0,0 +1,2 @@
+class DuplicateCompoundPayloadTagNameError < StandardError; end
+class MissingCompoundPayloadTagNameError < StandardError; end

data/lib/nbt_utils/tag/float.rb

@@ -0,0 +1,10 @@
+module NBTUtils
+  module Tag
+    class Float # signed, per spec
+      include NBTUtils::Tag
+
+      type_id 5
+      payload_class ::BinData::FloatBe
+    end
+  end
+end

data/lib/nbt_utils/tag/int.rb

@@ -0,0 +1,10 @@
+module NBTUtils
+  module Tag
+    class Int # signed, per spec
+      include NBTUtils::Tag
+
+      type_id 3
+      payload_class ::BinData::Int32be
+    end
+  end
+end

data/lib/nbt_utils/tag/list.rb

@@ -0,0 +1,44 @@
+module NBTUtils
+  module Tag
+    class List
+      include NBTUtils::Tag
+
+      type_id 9
+
+      def initialize(io, named = true)
+        @payload = []
+        read_name(io) if named
+
+        tag_id = io.read(1).bytes.first.to_i
+        @tag_type = NBTUtils::Tag.tag_type_to_class(tag_id)
+        len = ::BinData::Int32be.new.read(io).value
+        len.times do
+          @payload << @tag_type.new(io, false)
+        end
+      end
+
+      def to_s(indent = 0)
+        ret = (' ' * indent) + "TAG_List#{@name ? "(\"#{@name}\")" : ''}: #{@payload.length} entries of type TAG_#{@tag_type.to_s.split('::').last}\n"
+        ret += (' ' * indent) + "{\n"
+        @payload.each do |load|
+          ret += "#{load.to_s(indent + 2)}\n"
+        end
+        ret += (' ' * indent) + "}"
+        ret
+      end
+
+      def to_nbt_string(named = true)
+        result = named ? binary_type_id + name_to_nbt_string : ''
+        type =::BinData::Int8be.new
+        type.value = @tag_type.type_id
+        result += type.to_binary_s
+        len = ::BinData::Int32be.new
+        len.value = @payload.length
+        result += len.to_binary_s
+        @payload.inject(result) do |r, load|
+          r + load.to_nbt_string(false)
+        end
+      end
+    end
+  end
+end

data/lib/nbt_utils/tag/long.rb

@@ -0,0 +1,10 @@
+module NBTUtils
+  module Tag
+    class Long # signed, per spec
+      include NBTUtils::Tag
+
+      type_id 4
+      payload_class ::BinData::Int64be
+    end
+  end
+end

data/lib/nbt_utils/tag/short.rb

@@ -0,0 +1,10 @@
+module NBTUtils
+  module Tag
+    class Short # signed, per spec
+      include NBTUtils::Tag
+
+      type_id 2
+      payload_class ::BinData::Int16be
+    end
+  end
+end

data/lib/nbt_utils/tag/string.rb

@@ -0,0 +1,10 @@
+module NBTUtils
+  module Tag
+    class String
+      include NBTUtils::Tag
+
+      type_id 8
+      payload_class NBTUtils::TagName
+    end
+  end
+end

data/lib/nbt_utils/tag_name.rb

@@ -0,0 +1,13 @@
+module NBTUtils
+  class TagName < ::BinData::Record
+    # Spec says this is a TAG_Short, which is signed. Staying strict
+    # though this may really be unsigned in practice.
+    int16be :len, :value => Proc.new { data.length }
+    string :data, :read_length => :len
+
+    # things break for some reason if you just call the string :value
+    def value
+      data
+    end
+  end
+end

data/lib/nbt_utils/version.rb

@@ -0,0 +1,3 @@
+module NBTUtils
+  VERSION = "0.0.1"
+end

data/nbt_utils.gemspec

@@ -0,0 +1,24 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path("../lib/nbt_utils/version", __FILE__)
+
+Gem::Specification.new do |s|
+  s.name        = "nbt_utils"
+  s.version     = NBTUtils::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ['Michael Dungan']
+  s.email       = ['mpd@jesters-court.net']
+  s.homepage    = "http://rubygems.org/gems/nbt_utils"
+  s.summary     = "Set of classes to read and write Minecraft .nbt files"
+  s.description = "Some classes to read and write Minecraft .nbt files. See http://www.minecraft.net/docs/NBT.txt for format description."
+
+  s.required_rubygems_version = ">= 1.3.6"
+
+  s.add_dependency "bindata", "~> 1.2"
+  s.add_development_dependency "bundler", ">= 1.0.0"
+
+  s.required_ruby_version = "~> 1.9"
+
+  s.files        = `git ls-files`.split("\n")
+  s.executables  = `git ls-files`.split("\n").map{|f| f =~ /^bin\/(.*)/ ? $1 : nil}.compact
+  s.require_path = 'lib'
+end

data/script.rb

@@ -0,0 +1,31 @@
+# encoding: UTF-8
+
+require 'bundler'
+Bundler.require :default
+
+require File.expand_path('./lib/nbt_utils', File.dirname(__FILE__))
+require 'zlib'
+
+@compound = nil
+
+file = NBTUtils::File.new('doc/test.nbt')
+@compound = file.read
+
+puts @compound.to_s
+
+#puts @compound.to_nbt_string
+#Zlib::GzipWriter.open('lolwut.nbt') do |gz|
+#  gz.write @compound.to_nbt_string
+#end
+
+@compound = NBTUtils::File.new.read('doc/bigtest.nbt')
+puts @compound.to_s
+
+#puts @compound.to_nbt_string
+#Zlib::GzipWriter.open('biglolwut.nbt') do |gz|
+#  gz.write @compound.to_nbt_string
+#end
+
+puts @compound.find_tag('Test')
+#puts @compound.find_tags(/(?:byte|int)Test/)
+#puts @compound.find_tags 'intasdf'

metadata

@@ -0,0 +1,122 @@
+--- !ruby/object:Gem::Specification 
+name: nbt_utils
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- Michael Dungan
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-09-23 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: bindata
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 2
+        version: "1.2"
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: bundler
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 0
+        - 0
+        version: 1.0.0
+  type: :development
+  version_requirements: *id002
+description: Some classes to read and write Minecraft .nbt files. See http://www.minecraft.net/docs/NBT.txt for format description.
+email: 
+- mpd@jesters-court.net
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- Gemfile
+- Gemfile.lock
+- README.md
+- Rakefile
+- doc/NBT.txt
+- doc/bigtest.nbt
+- doc/test.nbt
+- lib/nbt_utils.rb
+- lib/nbt_utils/file.rb
+- lib/nbt_utils/tag.rb
+- lib/nbt_utils/tag/byte.rb
+- lib/nbt_utils/tag/byte_array.rb
+- lib/nbt_utils/tag/compound.rb
+- lib/nbt_utils/tag/double.rb
+- lib/nbt_utils/tag/end.rb
+- lib/nbt_utils/tag/exceptions.rb
+- lib/nbt_utils/tag/float.rb
+- lib/nbt_utils/tag/int.rb
+- lib/nbt_utils/tag/list.rb
+- lib/nbt_utils/tag/long.rb
+- lib/nbt_utils/tag/short.rb
+- lib/nbt_utils/tag/string.rb
+- lib/nbt_utils/tag_name.rb
+- lib/nbt_utils/version.rb
+- nbt_utils.gemspec
+- script.rb
+has_rdoc: true
+homepage: http://rubygems.org/gems/nbt_utils
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ~>
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 1
+      - 9
+      version: "1.9"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 1
+      - 3
+      - 6
+      version: 1.3.6
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Set of classes to read and write Minecraft .nbt files
+test_files: []
+