ctypes 0.2.0

data/lib/ctypes/bitfield.rb

@@ -0,0 +1,278 @@
+# encoding: ASCII-8BIT
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Cisco
+# SPDX-License-Identifier: MIT
+
+module CTypes
+  # define a bit-field type for use in structures
+  # @example 8-bit integer split into three multibit values
+  #   class MyBits < CTypes::Bitfield
+  #     # declare bit layout in right-to-left order
+  #     layout do
+  #       unsigned :bit             # single bit for a
+  #       skip 1                    # skip one bit
+  #       unsigned :two, 2          # two bits for this field
+  #       signed :nibble, 4         # four bit nibble as a signed int
+  #     end
+  #   end
+  #
+  #   # size is the number of bytes required by the layout, but can be larger
+  #   # when requested in #layout
+  #   MyBits.size                   # => 1
+  #
+  #   # The bits are packed right-to-left
+  #   MyBits.pack({bit: 1})         # => "\x01" (0b00000001)
+  #   MyBits.pack({two: 3})         # => "\x0c" (0b00001100)
+  #   MyBits.pack({nibble: -1})     # => "\xf0" (0b11110000)
+  #
+  #   # unpack a value and access individual fields
+  #   value = MyBits.unpack("\xf1") # => #<Bitfield bit: 1, two: 0, nibble: -1>
+  #   value.bit                     # => 1
+  #   value.two                     # => 0
+  #   value.nibble                  # => -1
+  #
+  #   # update the value and repack
+  #   value.two = 1
+  #   value.nibble = 0
+  #   value.to_binstr               # => "\x05" (0b00000101)
+  class Bitfield
+    extend Type
+    using PrettyPrintHelpers
+
+    # describe the layout of the bitfield
+    #
+    # @example right-to-left bit layout
+    #   layout do
+    #     unsigned :bit             # single bit for a
+    #     skip 1                    # skip one bit
+    #     unsigned :two, 2          # two bits for this field
+    #     signed :nibble, 4         # four bit nibble as a signed int
+    #   end
+    #
+    # @example explicit bit layout
+    #   layout do
+    #     field :bit, offset: 0, bits: 1
+    #     field :two, offset: 2, bits: 2
+    #     field :nibble, offset: 4, bits: 4
+    #   end
+    #
+    # @example create a two-byte bitfield, but only one bit declared
+    #   layout do
+    #     size 2                    # bitfield will take two bytes
+    #     field :bit, offset: 9, bits: 1
+    #   end
+    #
+    def self.layout(&block)
+      raise Error, "no block given" unless block
+      builder = Builder.new(&block)
+      builder.instance_eval(&block)
+      apply_layout(builder)
+    end
+
+    # @api private
+    def self.builder
+      Builder.new
+    end
+
+    # @api private
+    def self.apply_layout(builder)
+      @type, @bits, @dry_type, @endian, @layout = builder.result
+
+      # clear all existing field accessors
+      @fields ||= {}
+      @fields.each { |_, methods| remove_method(*methods) }
+      @fields.clear
+
+      @bits.each do |name, _|
+        @fields[name] = attr_accessor(name)
+      end
+
+      self
+    end
+    private_class_method :apply_layout
+
+    # get the size of the bitfield in bytes
+    def self.size
+      @type.size
+    end
+
+    # check if bitfield is a fixed size
+    def self.fixed_size?
+      true
+    end
+
+    # check if bitfield is greedy
+    def self.greedy?
+      false
+    end
+
+    # pack a ruby hash containing bitfield values into a binary string
+    # @param value [Hash] value to be encoded
+    # @param endian [Symbol] optional endian override
+    # @param validate [Boolean] set to false to disable value validation
+    # @return [::String] binary encoding for value
+    def self.pack(value, endian: default_endian, validate: true)
+      value = value.to_hash.freeze
+      value = @dry_type[value] unless validate == false
+      out = 0
+      @bits.each do |(name, offset, mask, _)|
+        out |= (value[name] & mask) << offset
+      end
+      @type.pack(out, endian:, validate:)
+    end
+
+    # convert a String containing the binary represention of a c type into the
+    # equivalent ruby type
+    #
+    # @param buf [::String] bytes that make up the type
+    # @param endian [Symbol] endian of data within buf
+    # @return [Bitfield] unpacked bitfield
+    def self.unpack_one(buf, endian: default_endian)
+      value, rest = @type.unpack_one(buf, endian:)
+      out = _new
+      @bits.each do |(name, offset, mask, signed, var)|
+        v = (value >> offset) & mask
+        v |= (-1 << signed) | v if signed && v[signed - 1] == 1
+        out.instance_variable_set(var, v)
+      end
+
+      [out, rest]
+    end
+
+    # get the list of fields defined in this bitfield
+    def self.fields
+      @fields.keys
+    end
+
+    # check if the bitfield declared a specific field
+    def self.has_field?(name)
+      @fields.has_key?(name)
+    end
+
+    def self.pretty_print(q)
+      q.ctype("bitfield", @endian) do
+        q.seplist(@layout, -> { q.breakable(";") }) do |cmd|
+          q.text(cmd)
+        end
+      end
+    end
+    class << self
+      alias_method :inspect, :pretty_inspect # :nodoc:
+    end
+
+    # generate ruby code needed to create this type
+    def self.export_type(q)
+      q << "bitfield {"
+      q.break
+      q.nest(2) do
+        @layout.each do |cmd|
+          q << cmd
+          q.break
+        end
+      end
+      q << "}"
+      q << ".with_endian(%p)" % [@endian] if @endian
+    end
+
+    class << self
+      # @method _new
+      # allocate an uninitialized instance of the bitfield
+      # @return [Bitfield] uninitialized bitfield instance
+      # @api private
+      alias_method :_new, :new
+      private :_new
+    end
+
+    # allocate an instance of the Bitfield and initialize default values
+    # @param fields [Hash] values to set
+    # @return [Bitfield]
+    def self.new(fields = nil)
+      buf = fields.nil? ? ("\0" * size) : pack(fields)
+      unpack(buf)
+    end
+
+    def self.==(other)
+      return true if super
+      return false unless other.is_a?(Class) && other < Bitfield
+      other.field_layout == @bits &&
+        other.default_endian == default_endian &&
+        other.size == size
+    end
+
+    # @api private
+    def self.field_layout # :nodoc:
+      @bits
+    end
+
+    # set a bitfield value
+    # @param k [Symbol] field name
+    # @param v value
+    def []=(k, v)
+      has_field!(k)
+      instance_variable_set(:"@#{k}", v)
+    end
+
+    # get an bitfield value
+    # @param k [Symbol] field name
+    # @return value
+    def [](k)
+      has_field!(k)
+      instance_variable_get(:"@#{k}")
+    end
+
+    def has_key?(name)
+      self.class.has_field?(name)
+    end
+
+    def has_field!(name) # :nodoc:
+      raise UnknownFieldError, "unknown field: %p" % name unless
+        self.class.has_field?(name)
+    end
+    private :has_field!
+
+    def to_h(shallow: false)
+      out = {}
+      self.class.field_layout.each do |name, _, _, _, var|
+        out[name] = instance_variable_get(var)
+      end
+      out
+    end
+    alias_method :to_hash, :to_h
+
+    def pretty_print(q) # :nodoc:
+      q.group(4, "bitfield {", "}") do
+        q.seplist(self.class.field_layout, -> { q.breakable("") }) do |name, _|
+          q.text(".#{name} = ")
+          q.pp(instance_variable_get(:"@#{name}"))
+          q.text(", ")
+        end
+      end
+    end
+    alias_method :inspect, :pretty_inspect # :nodoc:
+
+    # return the binary representation of this Bitfield instance
+    # @return [::String] binary representation of struct
+    def to_binstr(endian: self.class.default_endian)
+      self.class.pack(to_h, endian:)
+    end
+
+    # determine if this instance of the bitfield is equal to another instance
+    #
+    # @note this implementation also supports Hash equality through {to_h}
+    def ==(other)
+      case other
+      when self.class
+        self.class.field_layout.all? do |name, _, _, _, var|
+          instance_variable_get(var) == other[name]
+        end
+      when Hash
+        other == to_h
+      else
+        super
+      end
+    end
+  end
+end
+
+require_relative "bitfield/builder"

data/lib/ctypes/bitmap.rb

@@ -0,0 +1,154 @@
+# encoding: ASCII-8BIT
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Cisco
+# SPDX-License-Identifier: MIT
+
+module CTypes
+  # map bits in an integer to specific flags
+  #
+  # This class enables the mapping of individual bits in an integer to specific
+  # flags that each bit represents.  This class only supports single bit
+  # fields.  See `Bitfield` if you need to unpack multibit values.
+  #
+  # @example 8-bit bitmap, the long way
+  #   b = Bitmap.new(
+  #     bits: Enum.new({a: 0, b: 1, c: 7}),
+  #     type: CTypes::UInt8)
+  #
+  #   # pack some values
+  #   b.pack([])                # => "\x00"
+  #   b.pack([:a])              # => "\x01"
+  #   b.pack([:b])              # => "\x02"
+  #   b.pack([:c])              # => "\x80"
+  #   b.pack([:c, :a])          # => "\x81"
+  #   b.pack([:a, :c])          # => "\x81"
+  #
+  #   # unpack some values
+  #   b.unpack("\x00")          # => []
+  #   b.unpack("\x01")          # => [:a]
+  #   b.unpack("\x02")          # => [:b]
+  #   b.unpack("\x03")          # => [:a, :b]
+  #   b.unpack("\x80")          # => [:c]
+  #
+  # @example 8-bit bitmap, using helpers
+  #   include CTypes::Helpers   # for bitmap and uint8
+  #   b = bitmap(uint8, {a: 0, b: 1, c: 7})
+  #   b.pack([:a, :c])          # => "\x81"
+  #   b.unpack("\x03")          # => [:a, :b]
+  class Bitmap
+    extend Forwardable
+    include Type
+
+    # create a new Bitmap
+    # @param bits [Enum] mapping of bit position to name
+    # @param type [Type] ctype to encode value as; defaults to uint32
+    def initialize(bits:, type: Helpers.uint32)
+      raise Error, "bits must be an Enum instance: %p" % bits unless
+        bits.is_a?(Enum)
+
+      @type = type
+      @bits = bits
+      @bits_max = type.size * 8
+      @bits_constraint = Dry::Types["integer"]
+        .constrained(gteq: 0, lt: @bits_max)
+      @dry_type = Dry::Types["array"].of(@bits.dry_type).default([].freeze)
+    end
+    def_delegators :@type, :greedy?
+
+    def size
+      @type.size
+    end
+
+    def fixed_size?
+      @type.fixed_size?
+    end
+
+    # pack a ruby Array containing symbol names for each bit into a binary
+    # string
+    # @param value [::Array] Array of bits to be set, by name or right-to-left
+    #   index
+    # @param endian [Symbol] optional endian override
+    # @param validate [Boolean] set to false to disable value validation
+    # @return [::String] binary encoding for value
+    #
+    # @example packing with named values
+    #   b = CTypes::Helpers.bitmap(uint8, {a: 0, b: 1, c: 7})
+    #   b.pack([:a, :c])          # => "\x81"
+    #
+    # @example packing explicit bits
+    #   b = CTypes::Helpers.bitmap(uint8, {a: 0, b: 1, c: 7})
+    #   b.pack([0, 7])                    # => "\x81" (0b10000000)
+    #   b.pack([0, 6])                    # => Dry::Types::ConstraintError
+    #   b.pack([0, 6], validate: false)   # => "\x41" (0b01000001)
+    #
+    def pack(value, endian: default_endian, validate: true)
+      value = @dry_type[value] unless validate == false
+      mapping = @bits.mapping
+      bits = value.inject(0) do |out, v|
+        bit = case v
+        when Integer
+          v
+        when /\Abit_(\d+)\z/
+          $1.to_i
+        when Symbol
+          mapping[v]
+        else
+          raise Error, "unknown bitmap value: %p" % v
+        end
+        @bits_constraint[bit]
+        out |= 1 << bit
+      end
+      @type.pack(bits, endian: @type.endian || endian, validate: validate)
+    end
+
+    # convert a String containing the binary represention of a c type into the
+    # equivalent ruby type
+    #
+    # @param buf [::String] bytes that make up the type
+    # @param endian [Symbol] endian of data within buf
+    # @return [::Array] unpacked bitfield
+    #
+    # @example
+    #   b = bitmap(uint8, {a: 0, b: 1, c: 7})
+    #   b.unpack("\x00")                  # => []
+    #   b.unpack("\x01")                  # => [:a]
+    #   b.unpack("\x81")                  # => [:a, :c]
+    #
+    # @example allow unlabelled bits in the value
+    #   b = bitmap(uint8, {a: 0, b: 1, c: 7})
+    #   b.unpack("\x04")                  # => Dry::Types::ConstraintError
+    #
+    #   # create a new permissive bitmap from the initial bitmap
+    #   bp = b.permissive
+    #   bp.unpack("\x04")                 # => [:bit_2]
+    #
+    #   # known bits are still unpacked with the proper name
+    #   bp.unpack("\x05")                 # => [:a, :bit_2]
+    #
+    def unpack_one(buf, endian: default_endian)
+      value, rest = @type.unpack_one(buf, endian: @type.endian || endian)
+      bits = []
+      @bits_max.times do |bit|
+        next if value & (1 << bit) == 0
+        v = @bits.dry_type[bit]
+        v = :"bit_#{v}" if v.is_a?(Integer)
+        bits << v
+      end
+      [bits, rest]
+    end
+
+    # get a permissive version of this bitmap
+    # @return [Bitmap] permissive version of the bitmap.
+    #
+    # @example
+    #   b = CTypes::Helpers.bitmap(uint8, {a: 0})
+    #   b.unpack("\x04")                  # => Dry::Types::ConstraintError
+    #
+    #   b = CTypes::Helpers.bitmap(uint8, {a: 0}).permissive
+    #   b.unpack("\x04")                  # => [:bit_2]
+    def permissive
+      Bitmap.new(type: @type, bits: @bits.permissive)
+    end
+  end
+end

data/lib/ctypes/enum/builder.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Cisco
+# SPDX-License-Identifier: MIT
+
+module CTypes
+  # {Enum} layout builder
+  #
+  # This class is used to define the name/value pairs for {Enum} types.  The
+  # builder supports dynamic numbering similar to that used in C.  The
+  # {Builder} is used internally by {Enum}, and should not be used directly.
+  #
+  # @example Supported syntax and dynamic numbering
+  #   CTypes::Enum.new do |builder|
+  #     # automatic numbering
+  #     builder << :a       # :a will have value 0
+  #     builder << :b       # :b will have value 1
+  #     builder << {c: 10}  # :c will have value 10
+  #     builder << :d       # :d will have value 11
+  #
+  #     # bulk assignment
+  #     builder << %i[e f g]  # :e == 12, :f == 11, :g == 12
+  #
+  #     # bulk assignment with values
+  #     builder << {z: 25, y: 24, x: 23}
+  #     builder << :max       # :max == 26
+  #   end
+  class Enum::Builder
+    def initialize(&block)
+      @map = {}
+      @next = 0
+      @default = nil
+      block.call(self)
+    end
+    attr_reader :map
+    attr_accessor :default
+
+    # append new key/value pairs to the {Enum}
+    # @param value name or name/value pairs
+    #
+    # @example
+    #   CTypes::Enum.new do |builder|
+    #     # automatic numbering
+    #     builder << :a       # :a will have value 0
+    #     builder << :b       # :b will have value 1
+    #     builder << {c: 10}  # :c will have value 10
+    #     builder << :d       # :d will have value 11
+    #
+    #     # bulk assignment
+    #     builder << %i[e f g]  # :e == 12, :f == 11, :g == 12
+    #
+    #     # bulk assignment with values
+    #     builder << {z: 25, y: 24, x: 23}
+    #     builder << :max       # :max == 26
+    #   end
+    def <<(value)
+      case value
+      when Hash
+        value.each_pair { |k, v| set(k, v) }
+      when ::Array
+        value.each { |v| set(v, @next) }
+      else
+        set(value, @next)
+      end
+      self
+    end
+
+    def push(*values)
+      values.each { |v| self << v }
+    end
+
+    private
+
+    def set(key, value)
+      key = key.to_sym
+      raise Error, "duplicate key %p" % key if
+          @map.has_key?(key)
+      raise Error, "value must be Integer: %p" unless
+          value.is_a?(Integer)
+      @map[key] = value
+      @next = value + 1 if value >= @next
+      @default ||= key
+    end
+  end
+end

data/lib/ctypes/enum.rb

@@ -0,0 +1,201 @@
+# encoding: ASCII-8BIT
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Cisco
+# SPDX-License-Identifier: MIT
+require "forwardable"
+
+module CTypes
+  # Pack & unpack C enum values
+  #
+  # @example 32-bit contiguous enum
+  #   state = Enum.new(%i[start stop block])
+  #   state.pack(:block)                # => "\2\0\0\0"
+  #   state.unpack("\0\0\0\0")          # => :start
+  #
+  # @example 8-bit contiguous enum
+  #   state = Enum.new(UInt8, %i[start stop block])
+  #   state.pack(:block)                # => "\2"
+  #   state.unpack("\1")                # => :stop
+  #
+  # @example sparse enum
+  #   state = Enum.new do |e|
+  #     e << %i{a b c}
+  #     e << {d: 32}
+  #   end
+  #   state.pack(:d)                    # => "\x20\x00\x00\x00"
+  #   state.unpack("\x02\x00\x00\x00")  # => :c
+  #
+  class Enum
+    include Type
+    using PrettyPrintHelpers
+    extend Forwardable
+
+    # @example contiguous 32-bit enum
+    #   Enum.new([:a, :b, :c])
+    #   Enum.new(%i[a b c])
+    #
+    # @example contiguous 8-bit enum
+    #   Enum.new(:uint8, %i[a b c])
+    #
+    # @example sparse enum
+    #   Enum.new({a: 46, b: 789})
+    #
+    # @example 16-bit sparse enum
+    #   Enum.new(UInt16, {a: 46, b: 789})
+    #
+    # @example 8-bit sparse enum
+    #   Enum.new(Uint8) do |e|
+    #     e << %i{zero one two}         # define 0, 1, 2
+    #     e << {eighty: 80}             # skip 3-79 (incl), define 80
+    #     e << :eighty_one
+    #     e << {a: 100, b: 200}         # define multiple sparse values
+    #   end
+    #
+    # @example dynamically generated enum
+    #   Enum.new do |e|
+    #     # declare state_0 through state_31
+    #     32.times do |i|
+    #       e << "state_#{i}"
+    #     end
+    #   end
+    #
+    # @see Builder
+    def initialize(type = Helpers.uint32, values = nil, permissive: false,
+      &block)
+      builder = if block
+        Builder.new(&block)
+      else
+        if values.nil?
+          values = type
+          type = Helpers.uint32
+        end
+
+        Builder.new { |b| b << values }
+      end
+
+      @dry_type = Dry::Types["symbol"]
+        .default(builder.default)
+        .enum(builder.map)
+      @type = type
+      @size = @type.size
+      @dry_type = @dry_type.lax if permissive
+    end
+    attr_reader :size, :type
+    def_delegators :@type, :signed?, :greedy?
+
+    # encode a ruby type into a String containing the binary representation of
+    # the enum
+    #
+    # @param value [Symbol, Integer] value to be encoded
+    # @param endian [Symbol] endian to pack with
+    # @param validate [Boolean] set to false to disable value validation
+    # @return [::String] binary encoding for value
+    #
+    # @example
+    #   e = Enum.new(%i[stopped running blocked])
+    #   e.pack(:running)                  # => "\1\0\0\0"
+    #   e.pack(2)                         # => "\2\0\0\0"
+    def pack(value, endian: default_endian, validate: true)
+      value = @dry_type[value] if validate
+      out = @dry_type.mapping[value]
+      out ||= case value
+      when /\Aunknown_(\h+)\z/
+        out = $1.to_i(16)
+      when Integer
+        value
+      else
+        raise Error, "unknown enum value: %p" % value
+      end
+
+      @type.pack(out, endian: @type.endian || endian, validate:)
+    end
+
+    # convert a String containing the binary represention of a c enum into the
+    # ruby value
+    #
+    # @param buf [String] bytes that make up the type
+    # @param endian [Symbol] endian of data within buf
+    # @return [Array(Symbol, ::String)] decoded type, and remaining bytes
+    # @see Type#unpack
+    #
+    # @example
+    #   e = Enum.new(%i[stopped running blocked])
+    #   e.unpack("\1\0\0\0")            # => :running
+    def unpack_one(buf, endian: default_endian)
+      value, rest = @type.unpack_one(buf, endian: @type.endian || endian)
+      out = @dry_type[value]
+      out = ("unknown_%0#{@size * 2}x" % value).to_sym unless out.is_a?(Symbol)
+      [out, rest]
+    end
+
+    # @api private
+    def mapping
+      @dry_type.mapping
+    end
+
+    def pretty_print(q) # :nodoc:
+      q.group(2, "enum(", ")") do
+        if @type != Helpers.uint32
+          q.pp(@type)
+          q.comma_breakable
+        end
+        q.group(0, "{", "}") do
+          q.seplist(@dry_type.mapping) do |name, value|
+            q.text("#{name}: #{value}")
+          end
+        end
+      end
+    end
+    alias_method :inspect, :pretty_inspect # :nodoc:
+
+    def export_type(q)
+      q << "enum("
+      if @type != UInt32
+        q << @type
+        q << ", "
+      end
+      q << "{"
+      q.break
+
+      q.nest(2) do
+        @dry_type.mapping.each do |name, value|
+          q << "#{name}: #{value},"
+          q.break
+        end
+      end
+      q << "})"
+      q << ".permissive" if @dry_type.is_a?(Dry::Types::Lax)
+    end
+
+    def ==(other)
+      return false unless other.is_a?(Enum)
+      other.type == @type && other.mapping == @dry_type.mapping
+    end
+
+    def default_value
+      # with `.lax` added to dry_type for permissive enum, the standard
+      # `dry_type[]` doesn't work for a default.  Instead, we're going to try
+      # whatever key is set for 0, and failing that, just the first value
+      # defined for the enum
+      self[0] || @dry_type.mapping.first.first
+    end
+
+    def permissive
+      Enum.new(@type, @dry_type.mapping, permissive: true)
+    end
+
+    # lookup the key for a given Integer value in this Enum
+    #
+    # @example
+    #   e = Enum.new(%i[a b c])
+    #   e[1]    # => :b
+    #   e[5]    # => nil
+    def [](value)
+      @inverted_mapping ||= @dry_type.mapping.invert
+      @inverted_mapping[value]
+    end
+  end
+end
+
+require_relative "enum/builder"