craftbook-nbt 1.0.0

data/Rakefile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+task(:lexer) do
+  `rex lib/craftbook/nbt/snbt/snbt.rex -o lib/craftbook/nbt/snbt/lexer.rb`
+end

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "craftbook/nbt"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/craftbook-nbt.gemspec

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative 'lib/craftbook/nbt/version'
+
+#noinspection RubyResolve
+Gem::Specification.new do |spec|
+  spec.name          = 'craftbook-nbt'
+  spec.version       = CraftBook::NBT::VERSION
+  spec.authors       = ['ForeverZer0']
+  spec.email         = ['efreed09@gmail.com']
+
+  spec.summary       = 'A feature-rich and complete Ruby implementation of the Named Binary Tag (NBT) format and SNBT parser.'
+  spec.description   = 'A feature-rich and complete Ruby implementation of the Named Binary Tag (NBT) format. While it is an integral part of the broader CraftBook API, it is an independent module with no dependencies, and can be used for any purpose where reading/writing/converting the NBT format is required.'
+  spec.homepage      = 'https://github.com/ForeverZer0/craftbook-nbt'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 2.4.0'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/ForeverZer0/craftbook-nbt'
+  spec.metadata['changelog_uri'] = 'https://github.com/ForeverZer0/craftbook-nbt/CHANGELOG.md'
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency('rake',     '~> 13.0')
+  spec.add_development_dependency('rexical',  '~> 1.0')
+
+end

data/lib/craftbook/nbt/byte_array_tag.rb

@@ -0,0 +1,37 @@
+
+module CraftBook
+
+  module NBT
+    ##
+    # Represents a contiguous collection of signed 8-bit integers in the range of `-128` to `127` inclusive.
+    class ByteArrayTag < EnumerableTag
+
+      ##
+      # Creates a new instance of the {ByteArrayTag} class.
+      #
+      # @param name [String,NilClass] The name of the tag, or `nil` when unnamed.
+      # @param values [Array<Numeric>] Zero or more values to add during initialization.
+      def initialize(name, *values)
+        super(TYPE_BYTE_ARRAY, name, values)
+      end
+
+      ##
+      # @return [Hash{Symbol => Object}] the hash-representation of this object.
+      def to_h
+        { name: @name, type: @type, values: @values }
+      end
+
+      ##
+      # @return [String] the NBT tag as a formatted and human-readable string.
+      def to_s
+        "TAG_Byte_Array(#{@name ? "\"#{@name}\"" : 'None'}): #{size} #{size == 1 ? 'item' : 'items'}"
+      end
+
+      ##
+      # @return [String] the NBT tag as an SNBT string.
+      def stringify
+        "#{snbt_prefix}[B;#{to_a.join(',')}]"
+      end
+    end
+  end
+end

data/lib/craftbook/nbt/byte_tag.rb

@@ -0,0 +1,61 @@
+
+module CraftBook
+
+  module NBT
+
+    ##
+    # A tag type representing an 8-bit signed integer in the range of `-128` and `127` inclusive.
+    class ByteTag < ValueTag
+
+      ##
+      # The minimum permissible value for this type.
+      MIN = -0x80
+
+      ##
+      # The maximum permissible value for this type.
+      MAX =  0x7F
+
+      ##
+      # @!attribute [rw] value
+      #   The value of the tag. Values of `true` and `false` will be converted to `1` and `0` respectfully.
+      #   @return [Numeric,Boolean] the value of the tag.
+
+      ##
+      # Creates a new instance of the {DoubleTag} class.
+      #
+      # @param name [String,NilClass] The name of the tag, or `nil` when unnamed.
+      # @param value [Numeric,Boolean] The value of the tag.
+      #
+      # @note Values of `true` and `false` will be converted to `1` and `0` respectfully.
+      def initialize(name, value = 0)
+        super(TYPE_BYTE, name, value)
+      end
+
+      def value=(value)
+        @value = case value
+        when TrueClass then 1
+        when FalseClass then 0
+        else validate(value, MIN, MAX)
+        end
+      end
+
+      ##
+      # @return [Boolean] the value of the tag as boolean.
+      def bool
+        @value != 0
+      end
+
+      ##
+      # @return [String] the NBT tag as a formatted and human-readable string.
+      def to_s
+        "TAG_Byte(#{@name ? "\"#{@name}\"" : 'None'}): #{@value}"
+      end
+
+      ##
+      # @return [String] the NBT tag as an SNBT string.
+      def stringify
+        "#{snbt_prefix}#{@value}B"
+      end
+    end
+  end
+end

data/lib/craftbook/nbt/compound_tag.rb

@@ -0,0 +1,32 @@
+
+module CraftBook
+
+  module NBT
+
+    ##
+    # Represents a collection of **named** tags, order not guaranteed.
+    class CompoundTag < ContainerTag
+
+      ##
+      # Creates a new instance of the {CompoundTag} class.
+      #
+      # @param name [String,NilClass] The name of the tag, or `nil` when unnamed.
+      # @param values [Array<Tag>] Zero or more values to add during initialization.
+      def initialize(name, *values)
+        super(TYPE_COMPOUND, name, *values)
+      end
+
+      ##
+      # @return [String] the NBT tag as a formatted and human-readable string.
+      def to_s
+        "TAG_Compound(#{@name ? "\"#{@name}\"" : 'None'}): #{size} #{size == 1 ? 'child' : 'children'}"
+      end
+
+      ##
+      # @return [String] the NBT tag as an SNBT string.
+      def stringify
+        "{#{snbt_prefix}{#{map(&:stringify).join(',')}}"
+      end
+    end
+  end
+end

data/lib/craftbook/nbt/container_tag.rb

@@ -0,0 +1,55 @@
+
+module CraftBook
+  module NBT
+
+    ##
+    # @abstract
+    # Abstract base class for tag types that can contain other {Tag} objects as children.
+    class ContainerTag < EnumerableTag
+
+      ##
+      # Creates a new instance of the {EnumerableTag} class.
+      #
+      # @param name [String,NilClass] The name of the tag, or `nil` when unnamed.
+      # @param values [Array<Tag>] Zero or more values to add during initialization.
+      def initialize(type, name, *values)
+        super(type, name, *values)
+      end
+
+      ##
+      # @return [Hash{Symbol => Object}] the hash-representation of this object.
+      def to_h
+        a = @values.map { |child| child.to_h }
+        { name: @name, type: @type, values: a }
+      end
+
+      ##
+      # Outputs the NBT tag as a formatted and tree-structured string.
+      #
+      # @param io [IO,#puts] An IO-like object that responds to #puts.
+      # @param level [Integer] The indentation level.
+      # @param indent [String] The string inserted for each level of indent.
+      #
+      # @return [void]
+      def pretty_print(io = STDOUT, level = 0, indent = '    ')
+        space = indent * level
+        io.puts(space + to_s)
+        io.puts(space + '{')
+        each { |child| child.pretty_print(io, level + 1, indent) }
+        io.puts(space + '}')
+      end
+
+      protected
+
+      def parse_hash(hash)
+        @values = []
+        values = hash[:values]
+        raise(ParseError, "invalid array") unless values.is_a?(Array)
+        values.each do |value|
+          raise(ParseError, "expected JSON object") unless value.is_a?(Hash)
+          push(Tag.from_hash(value))
+        end
+      end
+    end
+  end
+end

data/lib/craftbook/nbt/double_tag.rb

@@ -0,0 +1,40 @@
+
+module CraftBook
+
+  module NBT
+
+    ##
+    # Represents a IEEE-754 double-precision floating point number (NaN possible).
+    class DoubleTag < ValueTag
+
+      ##
+      # @!attribute [rw] value
+      #   @return [Float] the value of the tag.
+
+      ##
+      # Creates a new instance of the {DoubleTag} class.
+      #
+      # @param name [String,NilClass] The name of the tag, or `nil` when unnamed.
+      # @param value [Float] The value of the tag.
+      def initialize(name, value = 0.0)
+        super(TYPE_DOUBLE, name, value)
+      end
+
+      def value=(value)
+        @value = Float(value)
+      end
+
+      ##
+      # @return [String] the NBT tag as a formatted and human-readable string.
+      def to_s
+        "TAG_Double(#{@name ? "\"#{@name}\"" : 'None'}): #{@value}"
+      end
+
+      ##
+      # @return [String] the NBT tag as an SNBT string.
+      def stringify
+        "#{snbt_prefix}#{@value}"
+      end
+    end
+  end
+end

data/lib/craftbook/nbt/enumerable_tag.rb

@@ -0,0 +1,106 @@
+
+module CraftBook
+
+  module NBT
+    ##
+    # @abstract
+    # Abstract base class for tags that can be enumerated.
+    class EnumerableTag < Tag
+
+      include Enumerable
+
+      ##
+      # Creates a new instance of the {EnumerableTag} class.
+      #
+      # @param type [Integer] One of the `TAG_*` constants indicating the primitive tag type.
+      # @param name [String,NilClass] The name of the tag, or `nil` when unnamed.
+      # @param values [Array<Object>] Zero or more values to add during initialization.
+      def initialize(type, name, *values)
+        super(type, name)
+        @values = Array.new
+        values.each { |value| push(value) }
+      end
+
+      ##
+      # Appends a value as a child of this instance.
+      #
+      # @param child [Object] The value to add.
+      #
+      # @raise [TypeError] When `child` is `nil`.
+      # @return [Object] the value that was added.
+      def push(child)
+        @values.push(validate(child))
+      end
+
+      ##
+      # @overload each(&block)
+      #   When called with a block, yields each child element to the block before returning `self`.
+      #   @yieldparam child [Object] Yields a child element to the block.
+      #   @return [self]
+      #
+      # @overload each
+      #   When called without a block, returns an Enumerator object for this instance.
+      #   @return [Enumerable]
+      def each
+        return enum_for(__method__) unless block_given?
+        @values.compact.each { |child| yield child }
+        self
+      end
+
+      ##
+      # @return [Hash{Symbol => Object}] the hash-representation of this object.
+      def to_h
+        { name: @name, type: @type, values: @values }
+      end
+
+      ##
+      # @return [Integer] the number of child elements.
+      def size
+        @values.compact.size
+      end
+
+      ##
+      # Retrieves the child at the given `index`, or `nil` if index is out of bounds.
+      #
+      # @param index [Integer] The zero-based index of the child element to retrieve.
+      # @return [Object] The element, or `nil` if index was out of bounds.
+      def [](index)
+        @values[index]
+      end
+
+      ##
+      # Sets the child element at the given `index`.
+      #
+      # @param index [Integer] The zero-based index of the child element to set.
+      # @param value [Object] The value to set.
+      #
+      # @return [Object] the value that was passed in.
+      #
+      # @raise [TypeError] When `value` is `nil`.
+      # @note Unlike normal Array object, when index is beyond the bounds of the collection, it will not insert `nil`
+      #   elements to fill the space, the new item is simply appended to the end of the collection.
+      def []=(index, value)
+        validate(value)
+        @values[index] = value
+      end
+
+      alias_method :<<, :push
+      alias_method :add, :push
+      alias_method :length, :size
+
+      protected
+
+      def validate(child)
+        raise(TypeError, 'enumerable tag cannot contain nil') unless child
+        child
+      end
+
+      def parse_hash(hash)
+        @values = []
+        values = hash[:values]
+        raise(ParseError, "invalid array") unless values.is_a?(Array)
+        values.each { |value| push(value) }
+      end
+    end
+  end
+end

data/lib/craftbook/nbt/float_tag.rb

@@ -0,0 +1,35 @@
+
+module CraftBook
+
+  module NBT
+
+    ##
+    # Represents a IEEE-754 single-precision floating point number (NaN possible).
+    class FloatTag < ValueTag
+
+      ##
+      # @!attribute [rw] value
+      #   @return [Numeric] the value of the tag.
+
+      def initialize(name, value = 0.0)
+        super(TYPE_FLOAT, name, value)
+      end
+
+      def value=(value)
+        @value = Float(value)
+      end
+
+      ##
+      # @return [String] the NBT tag as a formatted and human-readable string.
+      def to_s
+        "TAG_Float(#{@name ? "\"#{@name}\"" : 'None'}): #{@value}"
+      end
+
+      ##
+      # @return [String] the NBT tag as an SNBT string.
+      def stringify
+        "#{snbt_prefix}#{@value}F"
+      end
+    end
+  end
+end