bit-struct 0.13.1

data/examples/bignum.rb

@@ -0,0 +1,18 @@
+require 'bit-struct'
+
+class C < BitStruct
+  unsigned    :x, 80, :endian => :big, :fixed => 1_000_000_000
+  unsigned    :y, 24, :endian => :native, :format => "0x%x"
+  unsigned    :z, 64, :format => "0x%x" # big-endian by default
+  signed      :w, 48
+end
+
+c = C.new
+
+c.x = 1.000_000_001
+c.y = 0xa00002
+c.z = 0x1234abcd5678efef
+c.w = -1
+
+p c
+#puts c.unpack("H*")

data/examples/bits.rb

@@ -0,0 +1,19 @@
+require 'bit-struct' # http://redshift.sourceforge.net/bit-struct
+
+class Bits < BitStruct
+  unsigned    :bit0,     1,     "Foo bit"
+  unsigned    :bit1,     1,     "Bar bit"
+  unsigned    :bit2,     1
+  unsigned    :bit3,     1
+  unsigned    :bit4,     1
+  unsigned    :bit5,     1
+  unsigned    :bit6,     1
+  unsigned    :bit7,     1
+end
+
+b = Bits.new
+
+b.bit3 = 1
+p b.bit3 # ==> 1
+p b.bit4 # ==> 0
+

data/examples/byte-bdy.rb

@@ -0,0 +1,30 @@
+# an example where a field may crosse one or two byte boundaries
+#
+# try with arguments like 4, 12, and 13 to see the difference
+#
+# based on test case from Jon Hart
+
+require 'bit-struct'
+class Foo < BitStruct
+  unsigned :a, 4
+  unsigned :b, 8
+  unsigned :c, (ARGV[0] || (raise "USAGE: #{$0} bits")).to_i
+end
+
+puts Foo.describe
+
+foo = Foo.new
+p foo
+p foo.unpack("B*").first.scan(/\d{8,8}/)
+puts
+
+foo.c = 3123
+p foo
+p foo.unpack("B*").first.scan(/\d{8,8}/)
+puts
+
+foo.c = (2**(ARGV[0].to_i)-1)
+p foo
+p foo.unpack("B*").first.scan(/\d{8,8}/)
+puts
+

data/examples/field-ripper.rb

@@ -0,0 +1,22 @@
+# Example to show how to programmatically "cut and paste" some of the fields
+# from one BitStruct class into another.
+
+require 'bit-struct'
+
+class BS1 < BitStruct
+  unsigned      :f1,     8
+  unsigned      :f2,     8
+  unsigned      :f3,     8
+  unsigned      :f4,     8
+  unsigned      :f5,     8
+end
+
+class BS2 < BitStruct
+  fields_to_add = BS1.fields.select {|f| f.name.to_s =~ /[234]/}
+  
+  fields_to_add.each do |field|
+    add_field(field.name, field.length, field.options)
+  end
+end
+
+puts BS2.describe

data/examples/fixed-point.rb

@@ -0,0 +1,17 @@
+require 'bit-struct'
+
+class C < BitStruct
+  unsigned    :f1,  3,  :fixed => 100
+  unsigned    :f2,  5,  :fixed => 1000
+  unsigned    :f3,  8,  :fixed => 10000
+  unsigned    :f4, 32,  :fixed => 100000
+end
+
+c = C.new
+
+c.f1 =      0.03
+c.f2 =      0.005
+c.f3 =      0.0144
+c.f4 =    456.78912
+
+p c  # ==> #<C f1=0.03, f2=0.005, f3=0.0144, f4=456.78912>

data/examples/ip.rb

@@ -0,0 +1,81 @@
+require 'bit-struct'
+
+class IP < BitStruct
+  unsigned    :ip_v,     4,     "Version"
+  unsigned    :ip_hl,    4,     "Header length"
+  unsigned    :ip_tos,   8,     "TOS"
+  unsigned    :ip_len,  16,     "Length"
+  unsigned    :ip_id,   16,     "ID"
+  unsigned    :ip_off,  16,     "Frag offset"
+  unsigned    :ip_ttl,   8,     "TTL"
+  unsigned    :ip_p,     8,     "Protocol"
+  unsigned    :ip_sum,  16,     "Checksum"
+  octets      :ip_src,  32,     "Source addr"
+  octets      :ip_dst,  32,     "Dest addr"
+  rest        :body,            "Body of message"
+
+  note "     rest is application defined message body"
+  
+  initial_value.ip_v    = 4
+  initial_value.ip_hl   = 5
+end
+
+if __FILE__ == $0
+  ip1 = IP.new
+  ip1.ip_tos = 0
+  ip1.ip_len = 0
+  ip1.ip_id  = 0
+  ip1.ip_off = 0
+  ip1.ip_ttl = 255
+  ip1.ip_p   = 255
+  ip1.ip_sum = 0
+  ip1.ip_src = "192.168.1.4"
+  ip1.ip_dst = "192.168.1.255"
+  ip1.body   = "This is the payload text."
+  ip1.ip_len = ip1.length
+  
+  ip2 = IP.new do |ip|
+    ip.ip_tos = 0
+    ip.ip_len = 0
+    ip.ip_id  = 0
+    ip.ip_off = 0
+    ip.ip_ttl = 255
+    ip.ip_p   = 255
+    ip.ip_sum = 0
+    ip.ip_src = "192.168.1.4"
+    ip.ip_dst = "192.168.1.255"
+    ip.body   = "This is the payload text."
+    ip.ip_len = ip.length
+  end
+  
+  ip3 = IP.new(
+    :ip_tos => 0,
+    :ip_len => 0,
+    :ip_id  => 0,
+    :ip_off => 0,
+    :ip_ttl => 255,
+    :ip_p   => 255,
+    :ip_sum => 0,
+    :ip_src => "192.168.1.4",
+    :ip_dst => "192.168.1.255",
+    :body   => "This is the payload text."
+  ) do |ip|
+    ip.ip_len = ip.length
+  end
+  
+  ip4 = IP.new(ip1) # Construct from a BitStruct (or String)
+  
+  raise unless ip1 == ip2
+  raise unless ip1 == ip3
+  raise unless ip1 == ip4
+
+  ip = ip1
+  
+  puts ip.inspect
+  puts "-"*50
+  puts ip.inspect_detailed
+  puts "-"*50
+  puts
+  puts "Description of IP Packet:"
+  puts IP.describe
+end

data/examples/longlong.rb

@@ -0,0 +1,30 @@
+require 'bit-struct'
+
+class MyPacket < BitStruct
+  unsigned :x, 8*8, "The x field", :endian => :network
+    # :network is the default, and it's the same as :big
+  unsigned :y, 8*8, "The y field", :endian => :little
+end
+
+pkt = MyPacket.new
+pkt.x = 59843759843759843
+pkt.y = 59843759843759843
+
+p pkt.x  # 59843759843759843           
+p pkt.y  # 59843759843759843           
+
+p pkt
+# #<MyPacket x=59843759843759843, y=59843759843759843>
+p pkt.to_s
+# "\000\324\233\225\037\202\326\343\343\326\202\037\225\233\324\000"
+
+puts pkt.inspect_detailed
+# MyPacket:
+#                    The x field = 59843759843759843
+#                    The y field = 59843759843759843
+
+puts MyPacket.describe
+#     byte: type         name          [size] description
+# ----------------------------------------------------------------------
+#       @0: unsigned     x             [  8B] The x field
+#       @8: unsigned     y             [  8B] The y field

data/examples/md.rb

@@ -0,0 +1,23 @@
+require 'bit-struct'
+
+class MD < BitStruct
+  vector :row, :length => 3 do
+    vector :col, :length => 10 do
+      float :x, 32
+    end
+  end
+end
+
+md = MD.new
+  rows = md.row
+    row = rows[2]
+      cols = row.col
+        col = cols[7]
+          col.x = 1.23
+        cols[7] = col
+      row.col = cols
+    rows[2] = row
+  md.row = rows
+  
+p md
+p md.row[2].col[7].x

data/examples/modular-def.rb

@@ -0,0 +1,38 @@
+# This example shows how to refactor a BitStruct class defininition
+# using modules.
+
+module ModuleMethodSaver
+  def method_missing(meth, *args, &block)
+    @saved ||= []
+    @saved << [meth, args, block]
+  end
+  
+  def included(m)
+    if @saved
+      @saved.each do |meth, args, block|
+        m.send(meth, *args, &block)
+      end
+    end
+  end
+end
+
+
+require 'bit-struct'
+
+module M
+  extend ModuleMethodSaver
+  
+  unsigned  :x, 13
+  signed    :y, 7
+end
+
+class BS < BitStruct
+  include M
+end
+
+
+bs = BS.new
+bs.x = 123
+bs.y = -63
+
+p bs  # ==> #<BS x=123, y=-63>

data/examples/native.rb

@@ -0,0 +1,31 @@
+require 'bit-struct'
+
+class NativeNumbers < BitStruct
+
+  unsigned   :x0,    1,   :endian => :native
+  unsigned   :x1,    13,  :endian => :native
+  unsigned   :x2,    2,   :endian => :native
+  unsigned   :x3,    32,  :endian => :native
+  
+  float      :f1,    32,  :endian => :native
+  float      :f2,    64,  :endian => :native
+  float      :f3,    32
+  float      :f4,    64
+  
+  default_options :endian => :native
+    # affects fields defined after this and in subclasses
+  
+  unsigned    :y1,   32
+
+end
+
+n = NativeNumbers.new
+p n
+n.x1 = 5
+n.f1 = n.f3 = 1234.567
+n.f2 = n.f4 = 6543.321
+n.y1 = 1
+
+p n
+p n.unpack("C*")
+

data/examples/nested.rb

@@ -0,0 +1,33 @@
+require 'bit-struct'
+
+class NestedPart < BitStruct
+  unsigned :x,    5
+  unsigned :y,    3
+  char     :s,  5*8
+end
+
+class Container < BitStruct
+  nest    :n1,  NestedPart, "Nest 1"
+  nest    :n2,  NestedPart, "Nest 2"
+end
+
+cont = Container.new
+
+n = NestedPart.new(:x=>1, :y=>2, :s=>"abc")
+
+p n
+
+cont.n1 = n
+
+n.x = 5
+n.y = 0
+n.s = " xyz "
+
+cont.n2 = n # note copy semantics here!
+
+puts
+p cont
+puts
+puts cont.inspect_detailed
+
+puts "-"*80

data/examples/pad.rb

@@ -0,0 +1,14 @@
+require 'bit-struct'
+
+class PadTest < BitStruct
+  unsigned :x,    3
+  pad      :p1,   2
+  unsigned :y,    3
+end
+
+pt = PadTest.new
+pt.x = 1
+pt.y = 2
+
+p pt
+y pt

data/examples/ping-recv.rb

@@ -0,0 +1,25 @@
+require "socket"
+require "./ip"
+
+# Example of using the IP class to receive ping (ICMP) messages.
+
+begin
+  rsock = Socket.open(Socket::PF_INET, Socket::SOCK_RAW, Socket::IPPROTO_ICMP)
+rescue Errno::EPERM
+  $stderr.puts "Must run #{$0} as root."
+  exit!
+end
+
+Thread.new do
+  loop do
+    data, sender = rsock.recvfrom(8192)
+    port, host = Socket.unpack_sockaddr_in(sender)
+    puts "-"*80,
+         "packet received from #{host}:#{port}:",
+         IP.new(data).inspect_detailed,
+         "-"*80
+    $stdout.flush
+  end
+end
+
+system "ping 127.0.0.1"

data/examples/ping.rb

@@ -0,0 +1,73 @@
+require "socket"
+require "./ip"
+
+### example is broken
+
+# A more substantial example of sending and receiving ICMP packets.
+
+class ICMP < IP
+  unsigned    :icmp_type,   8,    "Message type"
+  unsigned    :icmp_code,   8,    "Message code"
+  unsigned    :icmp_cksum,  16,   "ICMP checksum"
+  unsigned    :icmp_id,     16
+  unsigned    :icmp_seq,    16
+  rest        :body,              "Body of ICMP message"
+end
+
+# Example of using the IP class to receive ping (ICMP) messages.
+
+begin
+  rsock = Socket.open(Socket::PF_INET, Socket::SOCK_RAW, Socket::IPPROTO_ICMP)
+rescue Errno::EPERM
+  $stderr.puts "Must run #{$0} as root."
+  exit!
+end
+
+begin
+  ssock = Socket.open(Socket::PF_INET, Socket::SOCK_RAW, Socket::IPPROTO_ICMP)
+  ssock.setsockopt(Socket::SOL_IP, Socket::IP_HDRINCL, true)
+    # IP_HDRINCL isn't necessary to send ICMP, but we are inheriting
+    # ICMP from IP, so the header is included in this example.
+rescue Errno::EPERM
+  $stderr.puts "Must run #{$0} as root."
+  exit!
+end
+
+Thread.new do
+  loop do
+    data, sender = rsock.recvfrom(8192)
+    port, host = Socket.unpack_sockaddr_in(sender)
+    out = "-"*80,
+          "packet received from #{host}:#{port}:",
+          ICMP.new(data).inspect_detailed,
+          "-"*80
+    puts out
+    $stdout.flush
+  end
+end
+
+addr = Socket.pack_sockaddr_in(1024, "localhost")
+5.times do |i|
+  icmp = ICMP.new do |b|
+    # ip_v and ip_hl are set for us by IP class
+    b.ip_tos  = 0
+    b.ip_id   = i
+    b.ip_off  = 0 ## ?
+    b.ip_ttl  = 64
+    b.ip_p    = Socket::IPPROTO_ICMP
+    b.ip_src  = "127.0.0.1"
+    b.ip_dst  = "127.0.0.1"
+    b.body    = "" ## ?
+    b.ip_len  = b.length
+    b.ip_sum  = 0 ## ?
+  end
+  
+  out = "-"*80,
+        "packet sent:",
+        icmp.inspect_detailed,
+        "-"*80
+  puts out
+  $stdout.flush
+  ssock.send(icmp, 0, addr)
+  sleep 1
+end