snow-data 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 40d3b634a2fe9ad1783ff57bd03dbdb9e01d28a4
-  data.tar.gz: 0087c9dd8a0f26fbc239b518d66243ee4b391f48
+  metadata.gz: 4070dd82808151a7dcdd5e41c49fcd14e2dc7f14
+  data.tar.gz: dfaee4ffae49a3c3752f052a3089c6c0010afea2
 SHA512:
-  metadata.gz: 7e8e6ec2a0160b4ba35170e73d4db301bb99a6af90a769f72ee75e8e1aef4d6ccb0708f4f84546330721ae134487261e8c8ac4dd2897cf9b56f8f229ed257c53
-  data.tar.gz: a46085a0735417717a5af9a952027e1e711b292b0b76406dd2522e038ca21473bcd38e15562503747ae4c3f09430d5a418d7ea286c839bcf00e91af41dd7c6f3
+  metadata.gz: 264998e906e61221c5f4ad786a32bcf647b895b02d2af123f244da4a488ced5c2fba8f145b55c877963fca7ff10c14a7022763e9b0a33ecc2a84dbaa6be4696d
+  data.tar.gz: 4b64d995bb9c8ad6c4f187cb919ed3e673b478bdb8d5fb95b93354a6887e2488e16488c3daca301a79545df4003b7e324bcda0599e4181c2fcdd18e162b16796

data/lib/snow-data/c_struct.rb

@@ -79,7 +79,7 @@ class CStruct
   #     CStruct.member_encoding(:foo, :float, 32, nil) # => "foo:float[32]:4"
   #
   def self.member_encoding(name, type, length: 1, alignment: nil)
-    type = type.intern
+    type = type.to_sym
     alignment = alignment || ALIGNMENTS[type] || ALIGNMENTS[:*]
     raise ArgumentError, "Invalid length: #{length}. Must be > 0." if length < 1
     raise ArgumentError, "Invalid alignment: #{alignment}. Must be a power of two." if ! power_of_two?(alignment)
@@ -111,6 +111,9 @@ class CStruct
       (?<type_alignment_decl> \s* \: \s*            # 4
         (?<type_alignment> \d+ )                    # 5
         )?
+      (?<offset_decl> \s* @ \s*                     # 6
+        (?<offset> \d+ )                            # 7
+      )?
     \s* (?: ; | $ | \n) # terminator
   }mx
 
@@ -280,7 +283,7 @@ class CStruct
       define_method(setter) do |offset, data|
         raise "Invalid value type, must be Data, but got #{data.class}" if ! data.kind_of?(Data)
         local_addr = self.address + offset
-        if !data.respond_to?(:address) || local_addr != data.address
+        if ! data.respond_to?(:address) || local_addr != data.address
           copy!(data, offset, 0, klass::SIZE)
         end
 
@@ -332,11 +335,12 @@ class CStruct
   # Encodings are how you define C structs using Snow::CStruct. It's a fairly
   # simple string format, defined as such:
   #
+  #     offset        ::=   '@' integer
   #     length        ::=   '[' integer ']'
   #     alignment     ::=   ':' integer
   #     typename      ::=   ':' Name
   #     member_name   ::=   Name
-  #     member_decl   ::=   member_name typename [ length ] [ alignment ]
+  #     member_decl   ::=   member_name typename [ length ] [ alignment ] [ offset ]
   #
   # So, for example, the encoding string "foo: float[4]:8" defines a C struct
   # with a single member, `foo`, which is an array of 4 32-bit floats with an
@@ -344,6 +348,12 @@ class CStruct
   # size (e.g., "foo: float" would be algiend to 4 bytes) and all members have a
   # length of 1 unless specified otherwise.
   #
+  # Offsets should only be specified if you absolutely know what you're doing,
+  # otherwise you may break certain things (for example, native sizing on ints).
+  # In addition, an offset can be provided to simulate union-like behavior for
+  # some members, though you are better off using the Builder methods to define
+  # a union than you are via an encoding string.
+  #
   # A list of all types follows, including their short and long names, and their
   # corresponding types in C. Short names are only provided for convenience and
   # are generally not too useful except for reducing string length. They're
@@ -423,23 +433,98 @@ class CStruct
       raise ArgumentError, "wrong number of arguments (#{args.length} for 0..2)"
     end
 
-    klass_name = klass_name.intern if klass_name
-
     members = if block_given?
       Builder.new(&block).member_info
     else
       decode_member_info(encoding)
     end
 
-    raise "No valid members found in encoding" if members.empty?
+    __define_struct__(klass_name, build_struct_type(members))
+  end
 
-    klass = build_struct_type(members)
 
-    if klass_name
-      const_set(klass_name, klass)
-      add_type(klass_name, klass)
-    end
+  #
+  # :nodoc:
+  #
+  # Passes a block through to a Builder and provides a flag for whether the root
+  # level of the builder is a struct or union.
+  #
+  def self.__build_struct__(name, is_union, &block)
+    members = Builder.new(is_union: is_union, &block).member_info
+    __define_struct__(name, build_struct_type(members))
+  end
+
+
+  #
+  # call-seq:
+  #   union { ... } => Class
+  #   union(name) { ... } => Class
+  #
+  # Defines a union with a block for declaring the members of the union using
+  # Builder methods. Unions are basically structs whose root members occupy the
+  # same or adjacent locations in memory. You may use Builder#struct to define
+  # multiple internal unnamed structs inside a union.
+  #
+  # If a name is provided, the resulting class will be added as a constant under
+  # CStruct and it will be added as a type recognized in other CStruct-defined
+  # structs and unions.
+  #
+  # ### Example
+  #
+  #     CStruct.union {
+  #       # size, name, and some_value all share the same memory in the union
+  #       # so set_name will modify size and some_value, and any transposition
+  #       # of those names is also true.
+  #       size_t    :size
+  #       uint32_t  :name
+  #       double    :some_value
+  #     }
+  #
+  def self.union(name = nil, &block)
+    __build_struct__(name, true, &block)
+  end
+
 
+  #
+  # call-seq:
+  #   struct { ... } => Class
+  #   struct(name) { ... } => Class
+  #
+  # Defines a struct with a block for declaring the members of the struct using
+  # Builder methods. Members of structs do not share space, unlike unions.
+  #
+  # If a name is provided, the resulting class will be added as a constant under
+  # CStruct and it will be added as a type recognized in other CStruct-defined
+  # structs and unions.
+  #
+  # ### Example
+  #
+  #     CStruct.struct {
+  #       # size, red, green, and blue all get their own memory in the struct,
+  #       # one after the other. Modifying one value will not modify another.
+  #       size_t    :size
+  #       uint16_t  :red[256]
+  #       uint16_t  :green[256]
+  #       uint16_t  :blue[256]
+  #     }
+  #
+  def self.struct(name = nil, &block)
+    __build_struct__(name, false, &block)
+  end
+
+
+  #
+  # :nodoc:
+  #
+  # Used by ::__build_struct__ and ::new to handle defining a struct class's
+  # constant and adding its type to those recognized by CStruct.
+  #
+  def self.__define_struct__(name, klass)
+    if name
+      name = name.to_sym
+      const_set(name, klass)
+      add_type(name, klass)
+    end
     klass
   end
 
@@ -455,12 +540,13 @@ class CStruct
     total_size = 0
     encoding.scan(ENCODING_REGEX).map do
       |match|
-      name        = match[0].intern
-      type        = real_type_of(match[1].intern)
+      name        = match[0].to_sym
+      type        = real_type_of(match[1].to_sym)
       length      = (match[3] || 1).to_i
       align       = (match[5] || ALIGNMENTS[type] || 1).to_i
       size        = SIZES[type] * length
-      offset      = Memory.align_size(total_size, align)
+      offset      = (match[7] || 0).to_i
+      offset += Memory.align_size(total_size, align) if ! match[7]
       total_size  = offset + size
 
       StructMemberInfo[name, type, size, length, align, offset]
@@ -476,7 +562,7 @@ class CStruct
   #
   def self.encode_member_info(members)
     members.map { |member|
-      "#{member.name}:#{member.type}[#{member.length}]:#{member.alignment}"
+      "#{member.name}:#{member.type}[#{member.length}]:#{member.alignment}@#{member.offset}"
     }.join(?;)
   end
 
@@ -498,8 +584,8 @@ class CStruct
     members.freeze
 
     # Get the alignment, size, aligned size, and encoding of the struct.
-    alignment    = members.map { |member| member.alignment }.max { |lhs, rhs| lhs <=> rhs }
-    type_size    = members.last.size + members.last.offset
+    alignment    = members.map(&:alignment).max
+    type_size    = members.map { |m| m.offset + m.size }.max
     aligned_size = Memory.align_size(type_size, alignment)
     # Oddly enough, it would be easier to pass the encoding string into this
     # function, but then it would ruin the nice little thing I have going where

data/lib/snow-data/c_struct/builder.rb

@@ -1,12 +1,35 @@
+# This file is part of ruby-snowdata.
+# Copyright (c) 2013 Noel Raymond Cower. All rights reserved.
+# See COPYING for license details.
+
 require 'set'
 
 module Snow ; end
 class Snow::CStruct ; end
 
+#
+# Utility classes used by CStruct to create member info structs. Exposed to the
+# user via instance_exec blocks for declaring struct/union members.
+#
+# See CStruct::new, CStruct::struct, or CStruct::union.
+#
 class Snow::CStruct::Builder
 
+  #
+  # Struct describing a level of a C struct. Contains a flag for whether the
+  # level is a union, its offset, alignment, size, and its members (which may
+  # include descendant levels).
+  #
+  MemberStackLevel = Struct.new(:is_union, :offset, :alignment, :size, :members)
+
+
+  #
+  # A Set of symbols for all types whose declaration methods have already been
+  # defined by ::flush_type_methods!.
+  #
   @@defined_types = Set.new
 
+
   #
   # call-seq:
   #     new => Builder
@@ -16,23 +39,69 @@ class Snow::CStruct::Builder
   # given, then it will be instance_exec'd, allowing you to easily call any
   # declaration methods on the builder instance.
   #
-  def initialize(&block)
-    @members = []
-    @last_offset = 0
+  def initialize(is_union: false, &block)
+    @member_names = Set.new
+    @level = MemberStackLevel[!!is_union, 0, 1, 0, []]
     instance_exec(&block) if block_given?
+    @members = []
+    self.class.adjust_level(@level)
+    @level.members.each { |member| member.freeze }
+    @members = self.class.flatten_level(@level)
+    @members.each(&:freeze)
+    @members.freeze
+  end
+
+
+  #
+  # Flattens a MemberStackLevel's members into a single array and returns an
+  # array of StructMemberInfo objects.
+  #
+  def self.flatten_level(level, info_buffer = [])
+    level.members.each { |m|
+      if m.kind_of?(MemberStackLevel)
+        flatten_level(m, info_buffer)
+      else
+        info_buffer.push(m)
+      end
+    }
+    info_buffer
+  end
+
+
+  #
+  # Iterates over a level's members, including sub-levels, and adjusts their
+  # offsets and the level's size accordingly. This is essentially the processing
+  # phase done to give members their offsets and levels their sizes.
+  #
+  def self.adjust_level(level, start_at: 0)
+    base_offset = offset = ::Snow::Memory.align_size(start_at, level.alignment)
+    level.size = 0
+    level.members.each do |m|
+      m.offset = offset = ::Snow::Memory.align_size(offset, m.alignment)
+      if m.kind_of?(MemberStackLevel)
+        adjust_level(m, start_at: offset)
+      end
+      if level.is_union
+        level.size = [level.size, (m.offset + m.size) - base_offset].max
+      else
+        level.size = (m.offset + m.size) - base_offset
+        offset += m.size
+      end
+    end
   end
 
+
   #
   # call-seq:
   #     member_info => [StructMemberInfo]
   #
-  # Returns the StructMemberInfo array for the builder. You should copy this if
-  # you need to modify it, and the same goes for its elements.
+  # Returns the StructMemberInfo array for the builder.
   #
   def member_info
     @members
   end
 
+
   #
   # call-seq:
   #     flush_type_methods! => self
@@ -55,7 +124,13 @@ class Snow::CStruct::Builder
       method_name = method_name.to_sym
 
       __send__(:define_method, method_name) do | name, lengths = 1, align: nil |
+        level = instance_variable_get(:@level)
+
+        member_names = instance_variable_get(:@member_names)
+
         name = name.to_sym
+        raise ArgumentError, "#{name} redefined in struct" if member_names.include?(name)
+        member_names.add(name)
 
         length = case lengths
                  when Integer, Fixnum then lengths
@@ -69,15 +144,21 @@ class Snow::CStruct::Builder
         align = (align || ::Snow::CStruct::ALIGNMENTS[type_name]).to_i
         raise "Nil alignment for type #{type_name}" if align.nil?
 
-        last_offset = instance_variable_get(:@last_offset)
-        offset = ::Snow::Memory.align_size(last_offset, align)
-        last_offset = offset + size
+        base_offset = level.offset
+        offset = ::Snow::Memory.align_size(base_offset, align)
+        level.offset = offset + size unless level.is_union
 
         member_info = ::Snow::CStruct::StructMemberInfo[
           name, type_name, size, length, align, offset]
 
-        instance_variable_set(:@last_offset, last_offset)
-        instance_variable_get(:@members).push(member_info.freeze)
+        level.alignment = [level.alignment, align].max
+        if level.is_union
+          level.size = [level.size, size].max
+        else
+          level.size += (offset - base_offset) + size
+        end
+
+        level.members.push(member_info)
       end # define_method(type_name)
 
       @@defined_types.add(type_name)
@@ -91,4 +172,73 @@ class Snow::CStruct::Builder
     self
   end # flush_type_methods!
 
+
+  #
+  # Creates a new member level for the builder and instance_exec-s the block,
+  # then passes its alignment onto its ancestor level.
+  #
+  def __do_level__(align: nil, is_union: false, &block)
+    parent = @level
+    next_level = MemberStackLevel[!!is_union, 0, 1, 0, []]
+    @level = next_level
+
+    self.instance_exec(&block)
+
+    next_level.alignment = align || next_level.alignment
+    parent.alignment = [parent.alignment, next_level.alignment].max
+
+    @level = parent
+    parent.members.push(next_level)
+  end
+
+
+  #
+  # call-seq:
+  #     union { ... }
+  #     union(align: nil) { ... }
+  #
+  # For the scope of the block, any members declared are considered union
+  # members, as opposed to struct members. Each member of a union occupies the
+  # same space as other members of the union, though their offsets may differ
+  # if their alignments differ as well.
+  #
+  # If no alignment is specified for the union, its base offset will be aligned
+  # to that of the member with the largest alignment. Otherwise, if an alignment
+  # is specified, members may not occupy the same offsets relative to the
+  # beginning of the union.
+  #
+  # For example, if a union with an alignment of 4 has uint32_t and uint64_t
+  # members with default alignments with a starting offset of 4, the uint32_t
+  # member will be located at offset 4, while the uint64_t member will be at
+  # offset 8. As such, it's best to leave union alignments at their default
+  # unless absolutely necessary.
+  #
+  def union(align: nil, &block)
+    __do_level__(align: align, is_union: true, &block)
+  end
+
+
+  #
+  # call-seq:
+  #     struct { ... }
+  #     struct(align: nil) { ... }
+  #
+  # For the scope of the block, any members declared are considered struct
+  # members, as opposed to union members.
+  #
+  # Each member of a struct occupies its own space inside the struct, unlike a
+  # union (where each member occupies either the same or adjacent space in the
+  # union).
+  #
+  # Unless an alignment is specified, the default alignment of a struct is that
+  # of the largest alignment of all its members. If specifying an alignment,
+  # keep in mind that the members of the struct may need to also be manually
+  # aligned, otherwise the first member may be preceeded by padding bytes
+  # regardless of the start of the struct. See #union for more information on
+  # alignment oddities.
+  #
+  def struct(align: nil, &block)
+    __do_level__(align: align, is_union: false, &block)
+  end
+
 end

data/lib/snow-data/version.rb

@@ -7,6 +7,6 @@ module Snow
   #
   # The snow-data version string.
   #
-  SNOW_DATA_VERSION = '1.2.0'.freeze
+  SNOW_DATA_VERSION = '1.3.0'.freeze
 
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: snow-data
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Noel Raymond Cower