Class: CraftBook::NBT::TagBuilder

Inherits:
Object
  • Object
show all
Defined in:
lib/craftbook/nbt/tag_builder.rb

Overview

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.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(name) ⇒ TagBuilder

Creates a new instance of the CraftBook::NBT::TagBuilder class.

Parameters:

  • name (String, NilClass) —

    the name of the implicit top-level CompoundTag being created.



17
18
19
20
 
# File 'lib/craftbook/nbt/tag_builder.rb', line 17

def initialize(name)
  @root = CompoundTag.new(name)
  @stack = []
end

Instance Attribute Details

#root ⇒ CompoundTag (readonly)

Returns the implicit top-level CompoundTag that the CraftBook::NBT::TagBuilder is creating.

Returns:



12
13
14
 
# File 'lib/craftbook/nbt/tag_builder.rb', line 12

def root
  @root
end

Class Method Details

.create(name) {|builder| ... } ⇒ CompoundTag

Creates a new CraftBook::NBT::TagBuilder instance within a block, returning the completed CompoundTag when the block closes.

Parameters:

Yields:

  • (builder)

Returns:

Raises:

  • (LocalJumpError) —

    when called without a block.



29
30
31
32
33
34
 
# File 'lib/craftbook/nbt/tag_builder.rb', line 29

def self.create(name)
  raise(LocalJumpError, 'block required') unless block_given?
  builder = new(name)
  yield builder
  builder.result
end

.from(compound_tag) ⇒ TagBuilder

Creates a new CraftBook::NBT::TagBuilder instance from an existing CompoundTag.

Parameters:

Returns:

Raises:

  • (TypeError) —

    when compound_tag is not a CompoundTag.



41
42
43
44
45
46
47
48
 
# File 'lib/craftbook/nbt/tag_builder.rb', line 41

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

Instance Method Details

#add(tag) {|builder| ... } ⇒ self Also known as: <<, push

Adds an existing CraftBook::NBT::Tag instance as a child to the current node.

Parameters:

Yield Parameters:

Returns:

  • (self)

Raises:



57
58
59
60
61
62
63
64
65
66
67
68
69
 
# File 'lib/craftbook/nbt/tag_builder.rb', line 57

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

#byte(name, value) ⇒ self

Creates a ByteTag from the specified value, and adds it to the current node.

Parameters:

  • value (Integer) —

    The value of the tag.

  • name (String, NilClass) —

    The name of the tag, or nil when adding to a ListTag node.

Returns:

  • (self) 


79
80
81
 
# File 'lib/craftbook/nbt/tag_builder.rb', line 79

def byte(name, value)
  add(ByteTag.new(name, Integer(value)))
end

#byte_array(name, *values) ⇒ self

Creates a ByteArrayTag from the specified values, and adds it to the current node.

Parameters:

  • values (Array<Integer>, Enumerable) —

    The child values of the tag.

  • name (String, NilClass) —

    The name of the tag, or nil when adding to a ListTag node.

Returns:

  • (self) 


142
143
144
 
# File 'lib/craftbook/nbt/tag_builder.rb', line 142

def byte_array(name, *values)
  add(ByteArrayTag.new(name, *values))
end

#compound(name = nil, children = nil) { ... } ⇒ self #compound(name = nil, children = nil) ⇒ self

Creates a CompoundTag from the specified value, and adds it to the current node.

Overloads:

  • #compound(name = nil, children = nil) { ... } ⇒ self

    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.

    Yields:

    • Yields nothing to the block.

  • #compound(name = nil, children = nil) ⇒ self

    When called without a block, all values to be included must be present in the children argument.

Parameters:

  • name (String, NilClass) —

    The name of the tag, or nil when adding to a ListTag node.

  • children (Array<Tag>, Enumerable) —

    The child values of the tag.

Returns:

  • (self) 


207
208
209
210
211
212
213
214
215
216
217
 
# File 'lib/craftbook/nbt/tag_builder.rb', line 207

def compound(name, *children)
  compound = CompoundTag.new(name, *children)
  
  if block_given?
    @stack.push(compound)
    yield self
    @stack.pop
  end

  add(compound)
end

#double(name, value) ⇒ self

Creates a DoubleTag from the specified value, and adds it to the current node.

Parameters:

  • name (String, NilClass) —

    The name of the tag, or nil when adding to a ListTag node.

  • value (Float) —

    The value of the tag.

Returns:

  • (self) 


124
125
126
 
# File 'lib/craftbook/nbt/tag_builder.rb', line 124

def double(name, value)
  add(DoubleTag.new(name, Float(value)))
end

#float(name, value) ⇒ self

Creates a FloatTag from the specified value, and adds it to the current node.

Parameters:

  • name (String, NilClass) —

    The name of the tag, or nil when adding to a ListTag node.

  • value (Float) —

    The value of the tag.

Returns:

  • (self) 


115
116
117
 
# File 'lib/craftbook/nbt/tag_builder.rb', line 115

def float(name, value)
  add(FloatTag.new(name, Float(value)))
end

#int(name, value) ⇒ self

Creates a IntTag from the specified value, and adds it to the current node.

Parameters:

  • value (Integer) —

    The value of the tag.

  • name (String, NilClass) —

    The name of the tag, or nil when adding to a ListTag node.

Returns:

  • (self) 


97
98
99
 
# File 'lib/craftbook/nbt/tag_builder.rb', line 97

def int(name, value)
  add(IntTag.new(name, Integer(value)))
end

#int_array(name, *values) ⇒ self

Creates a IntArrayTag from the specified values, and adds it to the current node.

Parameters:

  • values (Array<Integer>, Enumerable) —

    The child values of the tag.

  • name (String, NilClass) —

    The name of the tag, or nil when adding to a ListTag node.

Returns:

  • (self) 


151
152
153
 
# File 'lib/craftbook/nbt/tag_builder.rb', line 151

def int_array(name, *values)
  add(IntArrayTag.new(name, *values))
end

#list(child_type, name = nil, children = nil) { ... } ⇒ self #list(child_type, name = nil, children = nil) ⇒ self

Creates a ListTag from the specified value, and adds it to the current node.

Overloads:

  • #list(child_type, name = nil, children = nil) { ... } ⇒ self

    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.

    Yields:

    • Yields nothing to the block.

  • #list(child_type, name = nil, children = nil) ⇒ self

    When called without a block, all values to be included must be present in the children argument.

Parameters:

  • child_type (Integer) —

    One of the Tag::TYPE_* constants indicating the type of children in this tag.

  • name (String, NilClass) —

    The name of the tag, or nil when adding to a ListTag node.

  • children (Array<Tag>, Enumerable) —

    The child values of the tag.

Returns:

  • (self) 


180
181
182
183
184
185
186
187
188
189
190
 
# File 'lib/craftbook/nbt/tag_builder.rb', line 180

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

#long(name, value) ⇒ self

Creates a LongTag from the specified value, and adds it to the current node.

Parameters:

  • value (Integer) —

    The value of the tag.

  • name (String, NilClass) —

    The name of the tag, or nil when adding to a ListTag node.

Returns:

  • (self) 


106
107
108
 
# File 'lib/craftbook/nbt/tag_builder.rb', line 106

def long(name, value)
  add(LongTag.new(name, Integer(value)))
end

#long_array(name, *values) ⇒ self

Creates a LongArrayTag from the specified values, and adds it to the current node.

Parameters:

  • values (Array<Integer>, Enumerable) —

    The child values of the tag.

  • name (String, NilClass) —

    The name of the tag, or nil when adding to a ListTag node.

Returns:

  • (self) 


160
161
162
 
# File 'lib/craftbook/nbt/tag_builder.rb', line 160

def long_array(name, *values)
  add(LongArrayTag.new(name, *values))
end

#short(name, value) ⇒ self

Creates a ShortTag from the specified value, and adds it to the current node.

Parameters:

  • value (Integer) —

    The value of the tag.

  • name (String, NilClass) —

    The name of the tag, or nil when adding to a ListTag node.

Returns:

  • (self) 


88
89
90
 
# File 'lib/craftbook/nbt/tag_builder.rb', line 88

def short(name, value)
  add(ShortTag.new(name, Integer(value)))
end

#string(name, value) ⇒ self

Creates a StringTag from the specified value, and adds it to the current node.

Parameters:

  • value (String, Object) —

    The value of the tag.

  • name (String, NilClass) —

    The name of the tag, or nil when adding to a ListTag node.

Returns:

  • (self) 


133
134
135
 
# File 'lib/craftbook/nbt/tag_builder.rb', line 133

def string(name, value)
  add(StringTag.new(name, String(value)))
end