nwn-lib 0.3.6 → 0.4.0

data/lib/nwn/gff/api.rb

@@ -0,0 +1,88 @@
+
+module NWN::Gff::Field
+#:stopdoc:
+  # Used by NWN::Gff::Struct#by_flat_path
+  def each_by_flat_path &block
+    case field_type
+      when :cexolocstr
+        yield("", self)
+        field_value.sort.each {|lid, str|
+          yield("/" + lid.to_s, str)
+        }
+
+      when :struct
+        yield("", self)
+        field_value.each_by_flat_path {|v, x|
+          yield(v, x)
+        }
+
+      when :list
+        yield("", self)
+        field_value.each_with_index {|item, index|
+          yield("[" + index.to_s + "]", item)
+          item.each_by_flat_path("/") {|v, x|
+            yield("[" + index.to_s + "]" + v, x)
+          }
+        }
+
+      else
+        yield("", self)
+    end
+  end
+#:startdoc:
+end
+
+module NWN::Gff::Struct
+
+  # Iterates this struct, yielding flat, absolute
+  # pathes and the Gff::Field for each element found.
+
+  # Example:
+  # "/AddCost" => {"type"=>:dword, ..}
+  def each_by_flat_path prefix = "/", &block
+    sort.each {|label, field|
+      field.each_by_flat_path do |ll, lv|
+        yield(prefix + label + ll, lv)
+      end
+    }
+  end
+
+  # Retrieve an object from within the given tree.
+  # Path is a slash-separated destination, given as
+  # a string
+  #
+  # Prefixed/postfixed slashes are optional.
+  #
+  # Examples:
+  # /
+  # /AddCost
+  # /PropertiesList/
+  # /PropertiesList[0]/CostValue
+  def by_path path
+    struct = self
+    current_path = ""
+    path = path.split('/').map {|v| v.strip }.reject {|v| v.empty?}.join('/')
+
+    path.split('/').each {|v|
+      if v =~ /^(.+?)\[(\d+)\]$/
+        v, index = $1, $2
+      end
+
+      struct = struct[v]
+      if index
+        struct.field_type == :list or raise NWN::Gff::GffPathInvalidError,
+          "Specified a list offset for a non-list item: #{v}[#{index}]."
+
+        struct = struct.field_value[index.to_i]
+      end
+
+      raise NWN::Gff::GffPathInvalidError,
+        "Cannot find a path to /#{path} (at: /#{current_path})." unless struct
+
+      current_path += v
+    }
+
+    struct
+  end
+
+end

data/lib/nwn/gff/cexolocstr.rb

@@ -0,0 +1,28 @@
+module NWN::Gff::Field
+  def has_str_ref?
+    false
+  end
+end
+
+module NWN::Gff::Cexolocstr
+  DEFAULT_STR_REF = 0xffffffff
+
+  def str_ref
+    self['str_ref'] || DEFAULT_STR_REF
+  end
+  def str_ref= s
+    self['str_ref'] = s.to_i
+  end
+  def has_str_ref?
+    str_ref != DEFAULT_STR_REF
+  end
+end
+
+module NWN::Gff::CexolocstrValue
+  # Removes all nil and empty strings.
+  def compact!
+    self.each {|lid,str|
+      self.delete(lid) if str.nil? || str.empty?
+    }
+  end
+end

data/lib/nwn/gff/field.rb

@@ -0,0 +1,105 @@
+# A Field wraps a GFF label->value pair, providing:
+# * +.field_type+ describing the field type (e.g. :int)
+# * +.field_value+ holding the value of this Field
+
+# and, if loaded by Gff::Reader or through YAML:
+# * +.field_label+ holding the label
+# * +.parent+ holding the struct this Field is child of.
+#
+# Note that it is ADVISED to use the provided accessors,
+# since they do some structure-keeping in the background.
+# If you do NOT want it to do that, use hash-notation for access:
+#
+#  field['value'], field['type'], field['str_ref'], field['label']
+module NWN::Gff::Field
+  # The parent struct.
+  # This is set internally by Gff::Reader on load.
+  attr_accessor :parent
+
+  def field_type
+    self['type']
+  end
+  alias :t :field_type
+
+  def field_type= t
+    self['type'] = t
+  end
+  alias :t= :field_type=
+
+  def field_value
+    self['value']
+  end
+  alias :v :field_value
+
+  def field_value= v
+    Field.valid_for?(v, field_type) or raise ArgumentError,
+      "Given field_value is not valid for type #{field_type.inspect}."
+
+    self['value'] = v
+  end
+  alias :v= :field_value=
+
+  def field_label
+    self['label']
+  end
+  alias :l :field_label
+
+  def field_label= l
+    self['label']= l
+  end
+  alias :l= :field_label=
+
+  # Returns the path to this field, including all parents structs.
+  # For example: UTI/PropertiesList/CostTable
+  def path
+    raise NWN::Gff::GffError, "field not bound to a parent" unless @parent
+    parent_path = @parent.path
+    parent_path + "/" + field_label
+  end
+
+  # This extends this field object and its' value with the
+  # appropriate meta classes, depending on field_type.
+  def extend_meta_classes
+    return if field_type == :struct
+
+    field_klass_name = field_type.to_s.capitalize
+    field_klass = NWN::Gff.const_defined?(field_klass_name) ?
+      NWN::Gff.const_get(field_klass_name) : nil
+    field_value_klass = NWN::Gff.const_defined?(field_klass_name + 'Value') ?
+      NWN::Gff.const_get(field_klass_name + 'Value') : nil
+
+    self.extend(field_klass) unless field_klass.nil? ||
+      self.is_a?(field_klass)
+
+    field_value.extend(field_value_klass) unless field_value_klass.nil? ||
+      field_value.is_a?(field_value_klass)
+  end
+
+  # Validate if +value+ is within bounds of +type+.
+  def self.valid_for? value, type
+    case type
+      when :char, :byte
+        value.is_a?(Fixnum)
+      when :short, :word
+        value.is_a?(Fixnum)
+      when :int, :dword
+        value.is_a?(Fixnum)
+      when :int64, :dword64
+        value.is_a?(Fixnum)
+      when :float, :double
+        value.is_a?(Float)
+      when :resref
+        value.is_a?(String) && (1..16).member?(value.size)
+      when :cexostr
+        value.is_a?(String)
+      when :cexolocstr
+        value.is_a?(Array)
+      when :struct, :list
+        value.is_a?(Array)
+      when :void
+        true
+      else
+        false
+    end
+  end
+end

data/lib/nwn/gff/list.rb

@@ -0,0 +1,2 @@
+module NWN::Gff::List
+end

data/lib/nwn/gff/reader.rb

@@ -0,0 +1,220 @@
+# A class that parses binary GFF bytes into ruby-friendly data structures.
+class NWN::Gff::Reader
+  include NWN::Gff
+
+  attr_reader :root_struct
+
+  # Create a new Reader with the given +bytes+ and immediately parse it.
+  # This is not needed usually; use Reader.read instead.
+  def initialize bytes
+    @bytes = bytes
+
+    read_all
+  end
+
+  # Reads +bytes+ as gff data and returns a NWN::Gff:Gff object.
+  def self.read bytes
+    self.new(bytes).root_struct
+  end
+
+  private
+
+  def read_all
+    type, version,
+    struct_offset, struct_count,
+    field_offset, field_count,
+    label_offset, label_count,
+    field_data_offset, field_data_count,
+    field_indices_offset, field_indices_count,
+    list_indices_offset, list_indices_count =
+      @bytes.unpack("a4a4 VV VV VV VV VV VV")
+
+    raise GffError, "Unknown version #{@version}; not a gff?" unless
+      version == "V3.2"
+
+    raise GffError, "struct offset at wrong place, not a gff?" unless
+      struct_offset == 56
+
+    struct_len = struct_count * 12
+    field_len  = field_count * 16
+    label_len  = label_count * 16
+
+    @structs = @bytes[struct_offset, struct_len].unpack("V*")
+    @fields  = @bytes[field_offset, field_len].unpack("V*")
+    @labels  = @bytes[label_offset, label_len].unpack("A16" * label_count)
+    @field_data = @bytes[field_data_offset, field_data_count]
+    @field_indices = @bytes[field_indices_offset, field_indices_count].unpack("V*")
+    @list_indices = @bytes[list_indices_offset, list_indices_count].unpack("V*")
+    @root_struct = read_struct 0, type.strip, version
+  end
+
+  # This iterates through a struct and reads all fields into a hash, which it returns.
+  def read_struct index, file_type = nil, file_version = nil
+    struct = {}.taint
+    struct.extend(NWN::Gff::Struct)
+
+    type = @structs[index * 3]
+    data_or_offset = @structs[index * 3 + 1]
+    count = @structs[index * 3 + 2]
+
+    raise GffError, "struct index #{index} outside of struct_array" if
+      index * 3 + 3 > @structs.size + 1
+
+    struct.struct_id = type
+    struct.data_type = file_type
+    struct.data_version = file_version
+
+    if count == 1
+      lbl, vl = * read_field(data_or_offset, struct)
+      struct[lbl] = vl
+    else
+      if count > 0
+        raise GffError, "struct index not divisable by 4" if
+          data_or_offset % 4 != 0
+        data_or_offset /= 4
+        for i in data_or_offset...(data_or_offset+count)
+          lbl, vl = * read_field(@field_indices[i], struct)
+          struct[lbl] = vl
+        end
+      end
+    end
+
+    struct
+  end
+
+  # Reads the field at +index+ and returns [label_name, Gff::Field]
+  def read_field index, parent_of
+    gff = {}
+
+    field = {}.taint
+    field.extend(NWN::Gff::Field)
+
+    index *= 3
+    type = @fields[index]
+    label_index = @fields[index + 1]
+    data_or_offset = @fields[index + 2]
+
+    raise GffError, "Label index #{label_index} outside of label array" if
+      label_index > @labels.size
+
+    label = @labels[label_index]
+
+    raise GffError, "Unknown field type #{type}." unless Types[type]
+    type = Types[type]
+
+    raise GffError, "Field '#{label}' (type: #{type} )data offset #{data_or_offset} outside of field data block (#{@field_data.size})" if
+      ComplexTypes.index(type) && data_or_offset > @field_data.size
+
+    field['type'] = type
+    field['label'] = label
+    field.parent = parent_of
+
+    value = case type
+      when :byte, :char
+        data_or_offset & 0xff
+
+      when :word
+        data_or_offset & 0xffff
+
+      when :short
+        [(data_or_offset & 0xffff)].pack("S").unpack("s")[0]
+
+      when :dword
+        data_or_offset
+
+      when :int
+        [data_or_offset].pack("I").unpack("i")[0]
+
+      when :float
+        [data_or_offset].pack("V").unpack("f")[0]
+
+      when :dword64
+        len = 8
+        v1, v2 = @field_data[data_or_offset, len].unpack("II")
+        v1 * (2**32) + v2
+
+      when :int64
+        len = 8
+        @field_data[data_or_offset, len].unpack("q")[0]
+
+      when :double
+        len = 8
+        @field_data[data_or_offset, len].unpack("d")[0]
+
+      when :cexostr
+        len = @field_data[data_or_offset, 4].unpack("V")[0]
+        @field_data[data_or_offset + 4, len]
+
+      when :resref
+        len = @field_data[data_or_offset, 1].unpack("C")[0]
+        @field_data[data_or_offset + 1, len]
+
+      when :cexolocstr
+        exostr = {}
+
+        total_size, str_ref, str_count =
+          @field_data[data_or_offset, 12].unpack("VVV")
+        all = @field_data[data_or_offset + 12, total_size]
+        field.extend(NWN::Gff::Cexolocstr)
+        field.str_ref = str_ref
+
+        str_count.times {
+          id, len = all.unpack("VV")
+          str = all[8, len].unpack("a*")[0]
+          all = all[(8 + len)..-1]
+          exostr[id] = str
+        }
+        len = total_size + 4
+        # Filter out empty strings.
+        exostr.reject! {|k,v| v.nil? || v.empty?} if
+          ENV['NWN_LIB_FILTER_EMPTY_EXOLOCSTR']
+        exostr.taint
+
+      when :void
+        len = @field_data[data_or_offset, 4].unpack("V")[0]
+        @field_data[data_or_offset + 4, len].unpack("H*")[0]
+
+      when :struct
+        read_struct data_or_offset, field.path, field.parent.data_version
+
+      when :list
+        list = []
+
+        raise GffError, "List index not divisable by 4" unless
+          data_or_offset % 4 == 0
+
+        data_or_offset /= 4
+
+        raise GffError, "List index outside list indices" if
+          data_or_offset > @list_indices.size
+
+        count = @list_indices[data_or_offset]
+
+        raise GffError, "List index overflow the list indices array" if
+          data_or_offset + count > @list_indices.size
+
+        data_or_offset += 1
+
+        for i in data_or_offset...(data_or_offset + count)
+          list << read_struct(@list_indices[i], field.path, field.parent.data_version)
+        end
+
+        list.taint
+
+    end
+
+    raise GffError, "Field data overflows from the field data block area\
+      offset = #{data_or_offset + len}, len = #{@field_data.size}" if
+      len && data_or_offset + len > @field_data.size
+
+    [value].compact.flatten.each {|iv|
+      iv.element = field if iv.respond_to?('element=')
+    }
+    field['value'] = value.taint
+
+    # We extend all fields and field_values with matching classes.
+    field.extend_meta_classes
+
+    [label, field]
+  end
+end

data/lib/nwn/gff/struct.rb

@@ -0,0 +1,34 @@
+# A Gff::Struct is a hash of label->Element pairs with some
+# meta-information in local variables.
+module NWN::Gff::Struct
+  DEFAULT_DATA_VERSION = "V3.2"
+
+  # The file-type this struct represents.
+  # This is usually the file extension for root structs,
+  # and nil for sub-structs.
+  attr_accessor :data_type
+
+  # The file version. Usually "V3.2" for root structs,
+  # and nil for sub-structs.
+  attr_accessor :data_version
+
+  # GFF struct type
+  attr_accessor :struct_id
+
+  # The field this struct is value of.
+  # It is most likely a Field of :list, or
+  # :nil if it is the root struct.
+  attr_accessor :element
+
+  # Returns the path to this struct (which is usually __data_type)
+  def path
+    @data_type.to_s
+  end
+
+  # Dump this struct as GFF binary data.
+  #
+  # Optionally specify data_type and data_version
+  def to_gff data_type = nil
+    NWN::Gff::Writer.dump(self, data_type)
+  end
+end