craftbook-nbt 1.0.0

data/lib/craftbook/nbt/snbt/snbt.rb

@@ -0,0 +1,121 @@
+
+require_relative 'lexer'
+
+module CraftBook
+
+  module NBT
+
+    ##
+    # Parses a stringified NBT string and creates a {CompoundTag} from it.
+    #
+    # @param string_nbt [String] The stringified NBT code to parse.
+    #
+    # @raise [SyntaxError] When the source `string_nbt` is not valid S-NBT.
+    # @raise [ParseError] When a an incorrect value is specified for the type of tag it represents.
+    # @raise [ArgumentError] When `string_nbt` is `nil`
+    #
+    # @return [CompoundTag] The parsed {CompoundTag} instance.
+    #
+    # @note This method is not safe to call in parallel from multiple threads.
+    # @see https://minecraft.fandom.com/wiki/NBT_format#SNBT_format
+    def self.parse_snbt(string_nbt)
+      raise(ArgumentError, "input string cannot be nil or empty") if string_nbt.nil? || string_nbt.empty?
+      @pos = 0
+      @depth = 0
+      lexer = Tokenizer.new
+      @tokens = lexer.tokenize(string_nbt)
+      parse_object(@tokens.first)
+    end
+
+    private
+
+    def self.assert_type(expected, actual)
+      raise(SyntaxError, "expected #{expected} token, got #{actual}") unless expected == actual
+    end
+
+    def self.parse_name(token)
+      assert_type(:IDENTIFIER, token.type)
+      assert_type(:SEPARATOR, move_next.type)
+      # move_next
+      token.value
+    end
+
+    def self.parse_array(name, klass)
+      values = []
+      loop do
+        token = move_next
+        case token.type
+        when :END_ARRAY then break
+        when :COMMA then next
+        else values.push(token.value)
+        end
+      end
+
+      klass.new(name, *values)
+    end
+
+    def self.move_next
+      @pos += 1
+      token = @tokens[@pos] || raise(SyntaxError, 'unexpected end of input')
+      [:WHITESPACE, :COMMA].include?(token.type) ? move_next : token
+    end
+
+    def self.parse_list(name)
+      values = []
+      types = []
+      loop do
+        token = move_next
+        case token.type
+        when :COMMA then next
+        when :END_ARRAY then break
+        else
+          types.push(token.type)
+          values.push(parse_object(token))
+        end
+      end
+
+      return ListTag.new(name, Tag::TYPE_END) if types.empty?
+      raise(ParseError, "lists must contain only the same child type") unless types.uniq.size <= 1
+      ListTag.new(name, values.first.type, *values)
+    end
+
+    def self.parse_object(token)
+
+      name = nil
+      if token.type == :IDENTIFIER
+        name = parse_name(token)
+        token = move_next
+      end
+
+      case token.type
+      when :STRING then StringTag.new(name, token.value)
+      when :INT then IntTag.new(name, token.value)
+      when :DOUBLE then DoubleTag.new(name, token.value)
+      when :FLOAT then FloatTag.new(name, token.value)
+      when :BYTE then ByteTag.new(name, token.value)
+      when :SHORT then ShortTag.new(name, token.value)
+      when :LONG then LongTag.new(name, token.value)
+      when :BYTE_ARRAY then parse_array(name, ByteArrayTag)
+      when :INT_ARRAY then parse_array(name, IntArrayTag)
+      when :LONG_ARRAY then parse_array(name, LongArrayTag)
+      when :LIST_ARRAY then parse_list(name)
+      when :COMPOUND_BEGIN then parse_compound(token, name)
+      else raise(ParseError, "invalid token, expected object type, got :#{token.type}")
+      end
+    end
+
+    def self.parse_compound(token, name)
+      assert_type(:COMPOUND_BEGIN, token.type)
+      compound = CompoundTag.new(name)
+
+      loop do
+        token = move_next
+        break if token.type == :COMPOUND_END
+        next if token.type == :COMMA
+        compound.add(parse_object(token))
+      end
+
+      compound
+    end
+  end
+end

data/lib/craftbook/nbt/snbt/snbt.rex

@@ -0,0 +1,74 @@
+module CraftBook
+module NBT
+class Tokenizer
+
+macro
+  nl          \n|\r\n|\r|\f
+  w           [\s]*
+  num         -?([0-9]+|[0-9]*\.[0-9]+)
+  l_bracket   \[
+  r_bracket   \]
+  l_brace     \{
+  r_brace     \}
+
+  integer     -?([0-9]+)
+  decimal     -?[0-9]*\.[0-9]+
+  escape    {unicode}|\\[^\n\r\f0-9A-Fa-f]
+  id [A-Za-z0-9-_]
+rule
+    \{{w}                { [:COMPOUND_BEGIN] }
+    {w}\}                { [:COMPOUND_END] }
+
+    ".+?"(?=:)      { [:IDENTIFIER, text.gsub!(/\A"|"\Z/, '') ] }
+    '.+?'(?=:)      { [:IDENTIFIER, text.gsub!(/\A'|'\Z/, '') ] }
+    [A-Za-z0-9_-]+?(?=:)        { [:IDENTIFIER, text] }
+    ".*?"        { [:STRING, text.gsub!(/\A"|"\Z/, '') ] }
+    '.*?'        { [:STRING, text.gsub!(/\A'|'\Z/, '') ] }
+
+    # Control Characters
+    {w}:{w}                { [:SEPARATOR, text] }
+    {w},{w}                { [:COMMA, text] }
+
+    # Collection Types
+
+    {l_bracket}B;{w}?    { [:BYTE_ARRAY, text] }
+    {l_bracket}I;{w}?    { [:INT_ARRAY, text]  }
+    {l_bracket}L;{w}?    { [:LONG_ARRAY, text] }
+    \[{w}?               { [:LIST_ARRAY, text] }
+    {w}\]                { [:END_ARRAY, text]  }
+
+    # Numeric Types
+    {decimal}[Ff]    { [:FLOAT,  text.chop.to_f         ] }
+    {decimal}[Dd]?   { [:DOUBLE, text.tr('Dd', '').to_f ] }
+    {integer}[Bb]    { [:BYTE,   text.chop.to_i         ] }
+    {integer}[Ss]    { [:SHORT,  text.chop.to_i         ] }
+    {integer}[Ll]    { [:LONG,   text.chop.to_i         ] }
+    {integer}        { [:INT,    text.to_i              ] }
+
+    [\s]+            { [:WHITESPACE, text] }
+    [\S]+            { [:STRING, text] }
+    .                { [:CHAR, text] }
+
+inner
+
+  Token = Struct.new(:type, :value)
+
+  def tokenize(code)
+    scan_setup(code)
+    if block_given?
+      while token = next_token
+        yield Token.new(*token)
+      end
+      return self
+    end
+    tokens = []
+    while token = next_token
+      tokens << Token.new(*token)
+    end
+    tokens
+  end
+end
+
+end
+end
+end

data/lib/craftbook/nbt/snbt.rb

@@ -0,0 +1,2 @@
+require_relative 'snbt/lexer'
+require_relative 'snbt/snbt'

data/lib/craftbook/nbt/string_tag.rb

@@ -0,0 +1,40 @@
+
+module CraftBook
+
+  module NBT
+
+    ##
+    # Represents a UTF-8 encoded string.
+    class StringTag < ValueTag
+
+      ##
+      # @!attribute [rw] value
+      #   @return [String] the value of the tag.
+
+      ##
+      # Creates a new instance of the {StringTag} class.
+      #
+      # @param name [String,NilClass] The name of the tag, or `nil` when unnamed.
+      # @param value [String,NilClass] The value of the tag.
+      def initialize(name, value = '')
+        super(TYPE_STRING, name, value)
+      end
+
+      def value=(value)
+        @value = String(value)
+      end
+
+      ##
+      # @return [String] the NBT tag as a formatted and human-readable string.
+      def to_s
+        "TAG_String(#{@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/tag.rb

@@ -0,0 +1,197 @@
+
+module CraftBook
+  module NBT
+
+    ##
+    # @abstract
+    # Abstract base class for all tag types.
+    class Tag
+
+      ##
+      # Not a concrete tag, implies the end of a Compound tag during serialization.
+      TYPE_END        = 0x00
+
+      ##
+      # A signed 8-bit integer in the range of `-128` to `127` inclusive.
+      TYPE_BYTE       = 0x01
+
+      ##
+      # A signed 16-bit integer in the range of `-32768` to `32767` inclusive.
+      TYPE_SHORT      = 0x02
+
+      ##
+      # A signed 32-bit integer in the range of `-2147483648` to `2147483647` inclusive.
+      TYPE_INT        = 0x03
+
+      ##
+      # A signed 64-bit integer in the range of `-9223372036854775808` and `9223372036854775807` inclusive.
+      TYPE_LONG       = 0x04
+
+      ##
+      # An IEEE-754 single-precision floating point number (NaN possible).
+      TYPE_FLOAT      = 0x05
+
+      ##
+      # An IEEE-754 double-precision floating point number (NaN possible).
+      TYPE_DOUBLE     = 0x06
+
+      ##
+      # A contiguous collection of signed 8-bit integers in the range of `-128` to `127` inclusive.
+      TYPE_BYTE_ARRAY = 0x07
+
+      ##
+      # A UTF-8 encoded string.
+      TYPE_STRING     = 0x08
+
+      ##
+      # A collection of **unnamed** tags of the same type.
+      TYPE_LIST       = 0x09
+
+      ##
+      # A collection of **named** tags, order not guaranteed.
+      TYPE_COMPOUND   = 0x0A
+
+      ##
+      # A contiguous collection of signed 32-bit integers in the range of `-2147483648` to `2147483647` inclusive.
+      TYPE_INT_ARRAY  = 0x0B
+
+      ##
+      # A contiguous collection of signed 64-bit integers in the range of `-9223372036854775808`
+      # and `9223372036854775807` inclusive.
+      TYPE_LONG_ARRAY = 0x0C
+
+      ##
+      # @return [Integer] one of the `TYPE_*` constants to describe the primitive NBT type.
+      attr_reader :type
+
+      ##
+      # @return [String?] the name of the tag, or `nil` if unnamed.
+      attr_reader :name
+
+      ##
+      # Creates a new instance of the {Tag} 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.
+      def initialize(type, name)
+        @type = type || raise(TypeError, 'type cannot be nil')
+        @name = name
+      end
+
+      ##
+      # Sets the name of the tag.
+      # @param value [String] The value to set the tag name as.
+      # @return [String?] The name of the tag.
+      def name=(value)
+        @name = value.nil? ? nil : String(value)
+      end
+
+      ##
+      # @abstract
+      # @return [Hash{Symbol => Object}] the hash-representation of this object.
+      def to_h
+        { name: @name, type: @type }
+      end
+
+      ##
+      # Retrieves the NBT tag in JavaScript Object Notation (JSON) format.
+      #
+      # @param pretty [Boolean] Flag indicating if output should be formatted in a more human-readable structure.
+      # @param opts [{Symbol=>String}] Options for how the output is formatted when using `pretty` flag.
+      # @option opts [String] indent: ('  ') The string used for indenting.
+      # @option opts [String] space: (' ') The string used for spaces.
+      # @option opts [String] array_nl: ("\n") The string used for newlines between array elements.
+      # @option opts [String] object_nl: ("\n") The string used for newlines between objects.
+      #
+      # @return [String] the JSON representation of this object.
+      def to_json(pretty = false, **opts)
+        pretty ? JSON.pretty_generate(to_h.compact, **opts) : to_h.compact.to_json
+      end
+
+      ##
+      # Parses a {Tag} object from a JSON string.
+      #
+      # @param json [String] A string in JSON format.
+      # @return [Tag] The deserialized {Tag} instance.
+      def self.parse(json)
+        hash = JSON.parse(json, symbolize_names: true )
+        raise(ParseError, 'invalid format, expected object') unless hash.is_a?(Hash)
+        from_hash(hash)
+      end
+
+      ##
+      # @abstract
+      # @raise [NotImplementedError] Method must be overridden in derived classes.
+      # @return [String] the NBT tag as an SNBT string.
+      def stringify
+        raise(NotImplementedError, "#{__method__} must be implemented in derived classes")
+      end
+
+      alias_method :snbt, :stringify
+      alias_method :to_hash, :to_h
+      alias_method :to_str, :to_s
+
+      ##
+      # Retrieves the NBT tag as a formatted and tree-structured string.
+      #
+      # @param indent [String] The string inserted for each level of indent.
+      #
+      # @see pretty_print
+      # @return [String] The NBT string as a formatted string.
+      def pretty(indent = '    ')
+        io = StringIO.new
+        pretty_print(io, 0, indent)
+        io.string
+      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.
+      #
+      # @see pretty
+      # @return [void]
+      def pretty_print(io = STDOUT, level = 0, indent = '    ')
+        io.puts(indent * level + self.to_s)
+      end
+
+      protected
+
+      def snbt_prefix
+        @name ? "#{@name}:" : ''
+      end
+
+      def self.class_from_type(type)
+        case type
+        when Tag::TYPE_BYTE then ByteTag
+        when Tag::TYPE_SHORT then ShortTag
+        when Tag::TYPE_INT then IntTag
+        when Tag::TYPE_LONG then LongTag
+        when Tag::TYPE_FLOAT then FloatTag
+        when Tag::TYPE_DOUBLE then DoubleTag
+        when Tag::TYPE_BYTE_ARRAY then ByteArrayTag
+        when Tag::TYPE_STRING then StringTag
+        when Tag::TYPE_LIST then ListTag
+        when Tag::TYPE_COMPOUND then CompoundTag
+        when Tag::TYPE_INT_ARRAY then IntArrayTag
+        when Tag::TYPE_LONG_ARRAY then LongArrayTag
+        else raise(ParseError, "invalid tag type")
+        end
+      end
+
+      def self.from_hash(hash)
+
+        name = hash[:name]
+        type = hash[:type]
+        raise(ParseError, "invalid type") unless !type.nil? & type.between?(TYPE_END, TYPE_LONG_ARRAY)
+
+        tag = class_from_type(type).allocate
+        tag.instance_variable_set(:@name, name)
+        tag.instance_variable_set(:@type, type)
+        tag.send(:parse_hash, hash)
+        tag
+      end
+    end
+  end
+end

data/lib/craftbook/nbt/tag_builder.rb

@@ -0,0 +1,220 @@
+
+module CraftBook
+  module NBT
+
+    ##
+    # Provides an intuitive and simplified way of building a complete NBT document from scratch, using only basic
+    # values without the need of creating intermediate {Tag} objects.
+    class TagBuilder
+
+      ##
+      # @return [CompoundTag] the implicit top-level {CompoundTag} that the {TagBuilder} is creating.
+      attr_reader :root
+
+      ##
+      # Creates a new instance of the {TagBuilder} class.
+      # @param name [String,NilClass] the name of the implicit top-level {CompoundTag} being created.
+      def initialize(name)
+        @root = CompoundTag.new(name)
+        @stack = []
+      end
+
+      ##
+      # Creates a new {TagBuilder} instance within a block, returning the completed {CompoundTag} when the block
+      # closes.
+      #
+      # @param name [String,NilClass] the name of the implicit top-level {CompoundTag} that the {TagBuilder} is creating.
+      # @return [CompoundTag] The resulting {CompoundTag} that was created.
+      # @raise [LocalJumpError] when called without a block.
+      def self.create(name)
+        raise(LocalJumpError, 'block required') unless block_given?
+        builder = new(name)
+        yield builder
+        builder.result
+      end
+
+      ##
+      # Creates a new {TagBuilder} instance from an existing {CompoundTag}.
+      # @param compound_tag [CompoundTag] An existing {CompoundTag} instance.
+      # @return [TagBuilder] A newly created {TagBuilder}.
+      # @raise [TypeError] when `compound_tag` is not a {CompoundTag}.
+      def self.from(compound_tag)
+        raise(TypeError, "#{compound_tag} is not a #{CompoundTag}") unless compound_tag.is_a?(CompoundTag)
+
+        builder = allocate
+        builder.instance_variable_set(:@root, compound_tag)
+        builder.instance_variable_set(:@stack, Array.new)
+        builder
+      end
+
+      ##
+      # Adds an existing {Tag} instance as a child to the current node.
+      # @param tag [Tag] The {Tag} object to add.
+      #
+      # @yieldparam builder [TagBuilder] Yields the {TagBuilder} instance to the block.
+      # @return [self]
+      # @raise [TypeError] when `tag` is not a {Tag} instance or `nil`.
+      def add(tag)
+        raise(TypeError, "tag cannot be nil") unless tag.is_a?(Tag)
+
+        root = @stack.empty? ? @root : @stack.last
+
+        if root.is_a?(CompoundTag) && tag.name.nil?
+          warn("direct children of Compound tags must be named")
+        elsif root.is_a?(ListTag) && tag.name
+          tag.name = nil
+        end
+        root.push(tag)
+        self
+      end
+
+      alias_method :<<, :add
+      alias_method :push, :add
+
+      ##
+      # Creates a {ByteTag} from the specified value, and adds it to the current node.
+      # @param value [Integer] The value of the tag.
+      # @param name [String,NilClass] The name of the tag, or `nil` when adding to a {ListTag} node.
+      # @return [self]
+      def byte(name, value)
+        add(ByteTag.new(name, Integer(value)))
+      end
+
+      ##
+      # Creates a {ShortTag} from the specified value, and adds it to the current node.
+      # @param value [Integer] The value of the tag.
+      # @param name [String,NilClass] The name of the tag, or `nil` when adding to a {ListTag} node.
+      # @return [self]
+      def short(name, value)
+        add(ShortTag.new(name, Integer(value)))
+      end
+
+      ##
+      # Creates a {IntTag} from the specified value, and adds it to the current node.
+      # @param value [Integer] The value of the tag.
+      # @param name [String,NilClass] The name of the tag, or `nil` when adding to a {ListTag} node.
+      # @return [self]
+      def int(name, value)
+        add(IntTag.new(name, Integer(value)))
+      end
+
+      ##
+      # Creates a {LongTag} from the specified value, and adds it to the current node.
+      # @param value [Integer] The value of the tag.
+      # @param name [String,NilClass] The name of the tag, or `nil` when adding to a {ListTag} node.
+      # @return [self]
+      def long(name, value)
+        add(LongTag.new(name, Integer(value)))
+      end
+
+      ##
+      # Creates a {FloatTag} from the specified value, and adds it to the current node.
+      # @param name [String,NilClass] The name of the tag, or `nil` when adding to a {ListTag} node.
+      # @param value [Float] The value of the tag.
+      # @return [self]
+      def float(name, value)
+        add(FloatTag.new(name, Float(value)))
+      end
+
+      ##
+      # Creates a {DoubleTag} from the specified value, and adds it to the current node.
+      # @param name [String,NilClass] The name of the tag, or `nil` when adding to a {ListTag} node.
+      # @param value [Float] The value of the tag.
+      # @return [self]
+      def double(name, value)
+        add(DoubleTag.new(name, Float(value)))
+      end
+
+      ##
+      # Creates a {StringTag} from the specified value, and adds it to the current node.
+      # @param value [String,Object] The value of the tag.
+      # @param name [String,NilClass] The name of the tag, or `nil` when adding to a {ListTag} node.
+      # @return [self]
+      def string(name, value)
+        add(StringTag.new(name, String(value)))
+      end
+
+      ##
+      # Creates a {ByteArrayTag} from the specified values, and adds it to the current node.
+      # @param values [Array<Integer>,Enumerable] The child values of the tag.
+      # @param name [String,NilClass] The name of the tag, or `nil` when adding to a {ListTag} node.
+      # @return [self]
+      def byte_array(name, *values)
+        add(ByteArrayTag.new(name, *values))
+      end
+
+      ##
+      # Creates a {IntArrayTag} from the specified values, and adds it to the current node.
+      # @param values [Array<Integer>,Enumerable] The child values of the tag.
+      # @param name [String,NilClass] The name of the tag, or `nil` when adding to a {ListTag} node.
+      # @return [self]
+      def int_array(name, *values)
+        add(IntArrayTag.new(name, *values))
+      end
+
+      ##
+      # Creates a {LongArrayTag} from the specified values, and adds it to the current node.
+      # @param values [Array<Integer>,Enumerable] The child values of the tag.
+      # @param name [String,NilClass] The name of the tag, or `nil` when adding to a {ListTag} node.
+      # @return [self]
+      def long_array(name, *values)
+        add(LongArrayTag.new(name, *values))
+      end
+
+      ##
+      # Creates a {ListTag} from the specified value, and adds it to the current node.
+      #
+      # @param child_type [Integer] One of the `Tag::TYPE_*` constants indicating the type of children in this tag.
+      # @param name [String,NilClass] The name of the tag, or `nil` when adding to a {ListTag} node.
+      # @param children [Array<Tag>,Enumerable] The child values of the tag.
+      #
+      # @overload list(child_type, name = nil, children =nil, &block)
+      #   When called with a block, creates a new node that is pushed onto the stack. All tags created within the
+      #   block will be added to this new scope. The node is closed when the block exits.
+      #   @yield Yields nothing to the block.
+      #
+      # @overload list(child_type, name = nil, children =nil)
+      #   When called without a block, all values to be included must be present in the `children` argument.
+      #
+      # @return [self]
+      def list(name, child_type, *children)
+        list = ListTag.new(name, child_type, *children)
+
+        if block_given?
+          @stack.push(list)
+          yield
+          @stack.pop
+        end
+
+        add(list)
+      end
+
+      ##
+      # Creates a {CompoundTag} from the specified value, and adds it to the current node.
+      #
+      # @param name [String,NilClass] The name of the tag, or `nil` when adding to a {ListTag} node.
+      # @param children [Array<Tag>,Enumerable] The child values of the tag.
+      #
+      # @overload compound(name = nil, children =nil, &block)
+      #   When called with a block, creates a new node that is pushed onto the stack. All tags created within the
+      #   block will be added to this new scope. The node is closed when the block exits.
+      #   @yield Yields nothing to the block.
+      #
+      # @overload compound(name = nil, children =nil)
+      #   When called without a block, all values to be included must be present in the `children` argument.
+      #
+      # @return [self]
+      def compound(name, *children)
+        compound = CompoundTag.new(name, *children)
+        
+        if block_given?
+          @stack.push(compound)
+          yield self
+          @stack.pop
+        end
+
+        add(compound)
+      end
+    end
+  end
+end