bit-struct 0.13.1

data/lib/bit-struct/char-field.rb

@@ -0,0 +1,48 @@
+class BitStruct
+  # Class for fixed length binary strings of characters.
+  # Declared with BitStruct.char.
+  class CharField < Field
+    #def self.default
+    #  don't define this, since it must specify N nulls and we don't know N
+    #end
+    
+    # Used in describe.
+    def self.class_name
+      @class_name ||= "char"
+    end
+
+    def add_accessors_to(cl, attr = name) # :nodoc:
+      unless offset % 8 == 0
+        raise ArgumentError,
+          "Bad offset, #{offset}, for #{self.class} #{name}." +
+          " Must be multiple of 8."
+      end
+      
+      unless length % 8 == 0
+        raise ArgumentError,
+          "Bad length, #{length}, for #{self.class} #{name}." +
+          " Must be multiple of 8."
+      end
+      
+      offset_byte = offset / 8
+      length_byte = length / 8
+      last_byte = offset_byte + length_byte - 1
+      byte_range = offset_byte..last_byte
+      val_byte_range = 0..length_byte-1
+
+      cl.class_eval do
+        define_method attr do ||
+          self[byte_range].to_s
+        end
+
+        define_method "#{attr}=" do |val|
+          val = val.to_s
+          if val.length < length_byte
+            val += "\0" * (length_byte - val.length)
+          end
+          self[byte_range] = val[val_byte_range]
+        end
+      end
+    end
+  end
+end

data/lib/bit-struct/fields.rb

@@ -0,0 +1,273 @@
+class BitStruct
+  class << self
+    # Define a char string field in the current subclass of BitStruct,
+    # with the given _name_ and _length_ (in bits). Trailing nulls _are_
+    # considered part of the string.
+    #
+    # If a class is provided, use it for the Field class.
+    # If a string is provided, use it for the display_name.
+    # If a hash is provided, use it for options.
+    #
+    # Note that the accessors have COPY semantics, not reference.
+    #
+    def char(name, length, *rest)
+      opts = parse_options(rest, name, CharField)
+      add_field(name, length, opts)
+    end
+    alias string char
+    autoload :CharField, "bit-struct/char-field"
+
+    # Define a floating point field in the current subclass of BitStruct,
+    # with the given _name_ and _length_ (in bits).
+    #
+    # If a class is provided, use it for the Field class.
+    # If a string is provided, use it for the display_name.
+    # If a hash is provided, use it for options.
+    #
+    # The <tt>:endian => :native</tt> option overrides the default of
+    # <tt>:network</tt> byte ordering, in favor of native byte ordering. Also
+    # permitted are <tt>:big</tt> (same as <tt>:network</tt>) and
+    # <tt>:little</tt>.
+    #
+    def float name, length, *rest
+      opts = parse_options(rest, name, FloatField)
+      add_field(name, length, opts)
+    end
+    autoload :FloatField, "bit-struct/float-field"
+
+    # Define an octet string field in the current subclass of BitStruct,
+    # with the given _name_ and _length_ (in bits). Trailing nulls are
+    # not considered part of the string. The field is accessed using
+    # period-separated hex digits.
+    #
+    # If a class is provided, use it for the Field class.
+    # If a string is provided, use it for the display_name.
+    # If a hash is provided, use it for options.
+    #
+    def hex_octets(name, length, *rest)
+      opts = parse_options(rest, name, HexOctetField)
+      add_field(name, length, opts)
+    end
+    autoload :HexOctetField, "bit-struct/hex-octet-field"
+
+    # Define a nested field in the current subclass of BitStruct,
+    # with the given _name_ and _nested_class_. Length is determined from
+    # _nested_class_.
+    #
+    # In _rest_:
+    #
+    # If a class is provided, use it for the Field class (i.e. <=NestedField).
+    # If a string is provided, use it for the display_name.
+    # If a hash is provided, use it for options.
+    #
+    # WARNING: the accessors have COPY semantics, not reference. When you call a
+    # reader method to get the nested structure, you get a *copy* of that data.
+    #
+    # For example:
+    #
+    #   class Sub < BitStruct
+    #     unsigned :x,    8
+    #   end
+    #
+    #   class A < BitStruct
+    #     nest    :n,  Sub
+    #   end
+    #
+    #   a = A.new
+    #
+    #   p a  # ==> #<A n=#<Sub x=0>>
+    #
+    #   # This fails to set x in a.
+    #   a.n.x = 3
+    #   p a  # ==> #<A n=#<Sub x=0>>
+    #
+    #   # This works
+    #   n = a.n
+    #   n.x = 3
+    #   a.n = n
+    #   p a  # ==> #<A n=#<Sub x=3>>
+    # 
+    def nest(name, nested_class, *rest)
+      opts = parse_options(rest, name, NestedField)
+      opts[:default] ||= nested_class.initial_value.dup
+      opts[:nested_class] = nested_class
+      field = add_field(name, nested_class.bit_length, opts)
+      field
+    end
+    alias struct nest
+    autoload :NestedField, "bit-struct/nested-field"
+
+    # Define an octet string field in the current subclass of BitStruct,
+    # with the given _name_ and _length_ (in bits). Trailing nulls are
+    # not considered part of the string. The field is accessed using
+    # period-separated decimal digits.
+    #
+    # If a class is provided, use it for the Field class.
+    # If a string is provided, use it for the display_name.
+    # If a hash is provided, use it for options.
+    #
+    def octets(name, length, *rest)
+      opts = parse_options(rest, name, OctetField)
+      add_field(name, length, opts)
+    end
+    autoload :OctetField, "bit-struct/octet-field"
+
+    # Define a padding field in the current subclass of BitStruct,
+    # with the given _name_ and _length_ (in bits).
+    #
+    # If a class is provided, use it for the Field class.
+    # If a string is provided, use it for the display_name.
+    # If a hash is provided, use it for options.
+    #
+    def pad(name, length, *rest)
+      opts = parse_options(rest, name, PadField)
+      add_field(name, length, opts)
+    end
+    alias padding pad
+    autoload :PadField, "bit-struct/pad-field"
+
+    # Define a signed integer field in the current subclass of BitStruct,
+    # with the given _name_ and _length_ (in bits).
+    #
+    # If a class is provided, use it for the Field class.
+    # If a string is provided, use it for the display_name.
+    # If a hash is provided, use it for options.
+    #
+    # SignedField adds the <tt>:fixed => divisor</tt> option, which specifies
+    # that the internally stored value is interpreted as a fixed point real
+    # number with the specified +divisor+.
+    #
+    # The <tt>:endian => :native</tt> option overrides the default of
+    # <tt>:network</tt> byte ordering, in favor of native byte ordering. Also
+    # permitted are <tt>:big</tt> (same as <tt>:network</tt>) and
+    # <tt>:little</tt>.
+    #
+    def signed name, length, *rest
+      opts = parse_options(rest, name, SignedField)
+      add_field(name, length, opts)
+    end
+    autoload :SignedField, "bit-struct/signed-field"
+
+    # Define a printable text string field in the current subclass of BitStruct,
+    # with the given _name_ and _length_ (in bits). Trailing nulls are
+    # _not_ considered part of the string.
+    #
+    # If a class is provided, use it for the Field class.
+    # If a string is provided, use it for the display_name.
+    # If a hash is provided, use it for options.
+    #
+    # Note that the accessors have COPY semantics, not reference.
+    #
+    def text(name, length, *rest)
+      opts = parse_options(rest, name, TextField)
+      add_field(name, length, opts)
+    end
+    autoload :TextField, "bit-struct/text-field"
+
+    # Define a unsigned integer field in the current subclass of BitStruct,
+    # with the given _name_ and _length_ (in bits).
+    #
+    # If a class is provided, use it for the Field class.
+    # If a string is provided, use it for the display_name.
+    # If a hash is provided, use it for options.
+    #
+    # UnsignedField adds the <tt>:fixed => divisor</tt> option, which specifies
+    # that the internally stored value is interpreted as a fixed point real
+    # number with the specified +divisor+.
+    #
+    # The <tt>:endian => :native</tt> option overrides the default of
+    # <tt>:network</tt> byte ordering, in favor of native byte ordering. Also
+    # permitted are <tt>:big</tt> (same as <tt>:network</tt>) and
+    # <tt>:little</tt>.
+    #
+    def unsigned name, length, *rest
+      opts = parse_options(rest, name, UnsignedField)
+      add_field(name, length, opts)
+    end
+    autoload :UnsignedField, "bit-struct/unsigned-field"
+
+    # Define a vector field in the current subclass of BitStruct,
+    # with the given _name_.
+    #
+    # If a class is provided, use it for the Vector class, otherwise
+    # the block must define the entry fields. The two forms looks like
+    # this:
+    #
+    #   class Vec < BitStruct::Vector
+    #     # these declarations apply to *each* entry in the vector:
+    #     unsigned :x,  16
+    #     signed   :y,  32
+    #   end
+    #
+    #   class Packet < BitStruct
+    #     # Using the Vec class defined above
+    #     vector  :v, Vec, "a vector", :length => 5
+    #
+    #     # equivalently, using an anonymous subclass of BitStruct::Vector
+    #     vector :v2, "a vector", :length => 5 do
+    #       unsigned :x,  16
+    #       signed   :y,  32
+    #     end
+    #   end
+    #
+    # If a string is provided, use it for the display_name.
+    # If a hash is provided, use it for options.
+    #
+    # WARNING: the accessors have COPY semantics, not reference. When you call a
+    # reader method to get the vector structure, you get a *copy* of that data.
+    #
+    # For example, to modify the numeric fields in a Packet as defined above:
+    #
+    #   pkt = Packet.new
+    #     vec = pkt.v
+    #       entry = vec[2]
+    #         entry.x = 123
+    #         entry.y = -456
+    #       vec[2] = entry
+    #     pkt.v = vec
+    # 
+    def vector(name, *rest, &block)
+      opts = parse_options(rest, name, nil)
+      cl = opts[:field_class]
+      opts[:field_class] = VectorField
+      
+      unless (block and not cl) or (cl and not block)
+        raise ArgumentError,
+          "vector must have either a class or a block, but not both"
+      end
+      
+      case
+      when cl == nil
+        vector_class = Class.new(BitStruct::Vector)
+        vector_class.class_eval(&block)
+
+      when cl < BitStruct
+        vector_class = Class.new(BitStruct::Vector)
+        vector_class.struct_class cl
+
+      when cl < BitStruct::Vector
+        vector_class = cl
+      
+      else raise ArgumentError, "Bad vector class: #{cl.inspect}"
+      end
+      
+      vector_class.default_options default_options
+      
+      length = opts[:length] ## what about :length => :lenfield
+      unless length
+        raise ArgumentError, "Must provide length as :length => N"
+      end
+
+      opts[:default] ||= vector_class.new(length) ## nil if variable length
+      opts[:vector_class] = vector_class
+      
+      bit_length = vector_class.struct_class.round_byte_length * 8 * length
+      
+      field = add_field(name, bit_length, opts)
+      field
+    end
+    autoload :VectorField, "bit-struct/vector-field"
+  end
+  
+  autoload :Vector, "bit-struct/vector"
+end

data/lib/bit-struct/float-field.rb

@@ -0,0 +1,61 @@
+class BitStruct
+  # Class for floats (single and double precision) in network order.
+  # Declared with BitStruct.float.
+  class FloatField < Field
+    # Used in describe.
+    def self.class_name
+      @class_name ||= "float"
+    end
+    
+    def add_accessors_to(cl, attr = name) # :nodoc:
+      unless offset % 8 == 0
+        raise ArgumentError,
+          "Bad offset, #{offset}, for #{self.class} #{name}." +
+          " Must be multiple of 8."
+      end
+      
+      unless length == 32 or length == 64
+        raise ArgumentError,
+          "Bad length, #{length}, for #{self.class} #{name}." +
+          " Must be 32 or 64."
+      end
+      
+      offset_byte = offset / 8
+      length_byte = length / 8
+      last_byte = offset_byte + length_byte - 1
+      byte_range = offset_byte..last_byte
+
+      endian = (options[:endian] || options["endian"]).to_s
+      case endian
+      when "native"
+        ctl = case length
+          when 32; "f"
+          when 64; "d"
+        end
+      when "little"
+        ctl = case length
+          when 32; "e"
+          when 64; "E"
+        end
+      when "network", "big", ""
+        ctl = case length
+          when 32; "g"
+          when 64; "G"
+        end
+      else
+        raise ArgumentError,
+          "Unrecognized endian option: #{endian.inspect}"
+      end
+      
+      cl.class_eval do
+        define_method attr do ||
+          self[byte_range].unpack(ctl).first
+        end
+
+        define_method "#{attr}=" do |val|
+          self[byte_range] = [val].pack(ctl)
+        end
+      end
+    end
+  end
+end

data/lib/bit-struct/hex-octet-field.rb

@@ -0,0 +1,20 @@
+require 'bit-struct/char-field'
+
+class BitStruct
+  # Class for char fields that can be accessed with values like
+  # "xx:xx:xx:xx", where each xx is up to 2 hex digits representing a
+  # single octet. The original string-based accessors are still available with
+  # the <tt>_chars</tt> suffix.
+  # 
+  # Declared with BitStruct.hex_octets.
+  class HexOctetField < BitStruct::OctetField
+    # Used in describe.
+    def self.class_name
+      @class_name ||= "hex_octets"
+    end
+    
+    SEPARATOR = ":"
+    FORMAT    = "%02x"
+    BASE      = 16
+  end
+end

data/lib/bit-struct/nested-field.rb

@@ -0,0 +1,76 @@
+require 'bit-struct/bit-struct'
+
+class BitStruct
+  # Class for nesting a BitStruct as a field within another BitStruct.
+  # Declared with BitStruct.nest.
+  class NestedField < Field
+    def initialize(*args)
+      super
+    end
+    
+    # Used in describe.
+    def self.class_name
+      @class_name ||= "nest"
+    end
+    
+    def class_name
+      @class_name ||= nested_class.name[/\w+$/]
+    end
+    
+    def nested_class
+      @nested_class ||= options[:nested_class] || options["nested_class"]
+    end
+
+    def describe opts
+      if opts[:expand]
+        opts = opts.dup
+        opts[:byte_offset] = offset / 8
+        opts[:omit_header] = opts[:omit_footer] = true
+        nested_class.describe(nil, opts) {|desc| yield desc}
+      else
+        super
+      end
+    end
+
+    def add_accessors_to(cl, attr = name) # :nodoc:
+      unless offset % 8 == 0
+        raise ArgumentError,
+          "Bad offset, #{offset}, for nested field #{name}." +
+          " Must be multiple of 8."
+      end
+      
+      unless length % 8 == 0
+        raise ArgumentError,
+          "Bad length, #{length}, for nested field #{name}." +
+          " Must be multiple of 8."
+      end
+      
+      offset_byte = offset / 8
+      length_byte = length / 8
+      last_byte = offset_byte + length_byte - 1
+      byte_range = offset_byte..last_byte
+
+      nc = nested_class
+      
+      cl.class_eval do
+        define_method attr do ||
+          nc.new(self[byte_range])
+        end
+
+        define_method "#{attr}=" do |val|
+          if val.length != length_byte
+            raise ArgumentError, "Size mismatch in nested struct assignment " +
+              "to #{attr} with value #{val.inspect}"
+          end
+          
+          if val.class != nc
+            warn "Type mismatch in nested struct assignment " +
+              "to #{attr} with value #{val.inspect}"
+          end
+          
+          self[byte_range] = val
+        end
+      end
+    end
+  end
+end