ctypes 0.2.0

data/lib/ctypes/type.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Cisco
+# SPDX-License-Identifier: MIT
+
+module CTypes
+  # interface for all supported types
+  module Type
+    # @api private
+    # Dry::Type used for constraint checking & defaults
+    attr_reader :dry_type
+
+    # endian to use when packing/unpacking.
+    # nil means {CTypes.default_endian} will be used.
+    # @see #with_endian #with_endian to create fixed-endian types
+    attr_reader :endian
+
+    # encode a ruby type into a String containing the binary representation of
+    # the c type
+    #
+    # @param value 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
+    # @see Int#pack
+    # @see Struct#pack
+    # @see Union#pack
+    # @see Array#pack
+    # @see String#pack
+    # @see Terminated#pack
+    def pack(value, endian: default_endian, validate: true)
+      raise NotImplementedError
+    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 decoded type
+    #
+    # @see Type#unpack_one
+    # @see Int#unpack_one
+    # @see Struct#unpack_one
+    # @see Union#unpack_one
+    # @see Array#unpack_one
+    # @see String#unpack_one
+    # @see Terminated#unpack_one
+    def unpack(buf, endian: default_endian)
+      o, = unpack_one(buf, endian:)
+      o
+    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(Object, ::String)] decoded type, and remaining bytes
+    #
+    # @see Type#unpack
+    # @see Int#unpack_one
+    # @see Struct#unpack_one
+    # @see Union#unpack_one
+    # @see Array#unpack_one
+    # @see String#unpack_one
+    # @see Terminated#unpack_one
+    def unpack_one(buf, endian: default_endian)
+      raise NotImplementedError
+    end
+
+    # unpack as many instances of Type are present in the supplied string
+    #
+    # @param buf [String] bytes that make up the type
+    # @param endian [Symbol] endian of data within buf
+    # @return Array(Object) decoded types, and remaining
+    def unpack_all(buf, endian: default_endian)
+      out = []
+      until buf.empty?
+        t, buf = unpack_one(buf, endian:)
+        out << t
+      end
+      out
+    end
+
+    # read a fixed-sized type from an IO instance and unpack it
+    #
+    # @param buf [::String] bytes that make up the type
+    # @param endian [Symbol] endian of data within buf
+    # @return decoded type
+    def read(io, endian: default_endian)
+      unless fixed_size?
+        raise NotImplementedError,
+          "read() does not support variable-length types"
+      end
+
+      unpack(io.read(@size), endian: default_endian)
+    end
+
+    # read a fixed-sized type from an IO instance at a specific offset and
+    # unpack it
+    #
+    # @param buf [::String] bytes that make up the type
+    # @param pos [::Integer] seek position
+    # @param endian [Symbol] endian of data within buf
+    # @return decoded type
+    def pread(io, pos, endian: default_endian)
+      unless fixed_size?
+        raise NotImplementedError,
+          "pread() does not support variable-length types"
+      end
+
+      unpack(io.pread(@size, pos), endian: default_endian)
+    end
+
+    # get a fixed-endian instance of this type.
+    #
+    # If a type has a fixed endian, it will override the default endian set
+    # with {CTypes.default_endian=}.
+    #
+    # @param value [Symbol] endian; `:big` or `:little`
+    # @return [Type] fixed-endian {Type}
+    #
+    # @example uint32_t
+    #   t = CTypes::UInt32
+    #   t.pack(1)                 # => "\1\0\0\0"
+    #   b = t.with_endian(:big)
+    #   b.pack(1)                 # => "\0\0\0\1"
+    #   l = t.with_endian(:little)
+    #   l.pack(1)                 # => "\1\0\0\0"
+    #
+    # @example array
+    #   include Ctype::Helpers
+    #   t = array(uint32, 2)
+    #   t.pack([1,2])             # => "\1\0\0\0\2\0\0\0"
+    #   b = t.with_endian(:big)
+    #   b.pack([1,2])             # => "\0\0\0\1\0\0\0\2"
+    #   l = t.with_endian(:little)
+    #   l.pack([1,2])             # => "\1\0\0\0\2\0\0\0"
+    #
+    # @example struct with mixed endian fields
+    #   include Ctype::Helpers
+    #   t = struct do
+    #     attribute native: uint32
+    #     attribute big: uint32.with_endian(:big)
+    #     attribute little: uint32.with_endian(:little)
+    #   end
+    #   t.pack({native: 1, big: 2, little: 3}) # => "\1\0\0\0\0\0\0\2\3\0\0\0"
+    def with_endian(value)
+      return self if value == @endian
+
+      endian = Endian[value]
+      @with_endian ||= {}
+      @with_endian[endian] ||= begin
+        o = clone
+        o.instance_variable_set(:@without_endian, self) unless @endian
+        o.instance_variable_set(:@endian, endian)
+        o
+      end
+    end
+
+    def without_endian
+      @without_endian ||= begin
+        o = clone
+        o.remove_instance_variable(:@endian)
+        o
+      end
+    end
+
+    def greedy?
+      raise NotImplementedError, "Type must implement `.greedy?`: %p" % [self]
+    end
+
+    # check if this is a fixed-size type
+    def fixed_size?
+      !!@size&.is_a?(Integer)
+    end
+
+    # @api private
+    def default_value
+      dry_type[]
+    end
+
+    # @api private
+    def default_endian
+      @endian || CTypes.default_endian
+    end
+
+    private
+
+    def missing_bytes_error(input:, need:)
+      MissingBytesError.new(type: self, input:, need:)
+    end
+  end
+end

data/lib/ctypes/union/builder.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Cisco
+# SPDX-License-Identifier: MIT
+
+module CTypes
+  # {Union} layout builder
+  #
+  # This class is used to describe the memory layout of a {Union} type. There
+  # are two approaches available for defining the layout, the declaritive
+  # approach used in ruby source files, or a programmatic approach that enables
+  # the construction of {Union} types from data.
+  #
+  # @example declaritive approach using CTypes::Union
+  #   class MyUnion < CTypes::Union
+  #     layout do
+  #       # this message uses network-byte order
+  #       endian :big
+  #
+  #       # TLV message header with some fixed types
+  #       header = struct(
+  #         msg_type: enum(uint8, {invalid: 0, hello: 1, read: 2}),
+  #         len: uint16)
+  #
+  #       # add header as an unnamed field; adds MyUnion#type, MyUnion#len
+  #       member header
+  #
+  #       member :hello, struct(header:, version: string)
+  #       member :read, struct(header:, offset: uint64, size: uint64)
+  #       member :raw, string(trim: false)
+  #
+  #       # dynamic size based on the len in header
+  #       size { |union| header.size + union[:len] }
+  #     end
+  #   end
+  #
+  # @example programmatic approach building a union from data
+  #   # include helpers for `uint32`, `string`, and `array` methods
+  #   include CTypes::Helpers
+  #
+  #   # data loaded from elsewhere
+  #   fields = [
+  #     {name: :id, type: uin32},
+  #     {name: :name, type: string(256)},
+  #   ]
+  #
+  #   # create a builder instance
+  #   b = CTypes::Union.builder          # => #<CTypes::Union::Builder ...>
+  #
+  #   # populate the fields in the builder
+  #   fields.each do |field|
+  #     b.member(field[:name], field[:type])
+  #   end
+  #
+  #   # build the Union type
+  #   t = b.build                         # => #<CTypes::Union ...>
+  class Union::Builder
+    include Helpers
+
+    def initialize(type_lookup: CTypes.type_lookup)
+      @type_lookup = type_lookup
+      @fields = []
+      @field_names = Set.new
+      @schema = []
+      @size = 0
+      @fixed_size = true
+    end
+
+    # build a {Union} instance with the layout configured in this builder
+    # @return [Union] bitfield with the layout defined in this builder
+    def build
+      k = Class.new(Union)
+      k.send(:apply_layout, self)
+      k
+    end
+
+    # @api private
+    def result
+      dry_type = Dry::Types["coercible.hash"]
+        .schema(@schema)
+        .strict
+        .default(@default.freeze)
+      [@name, @fields.freeze, dry_type, @size, @fixed_size, @endian]
+    end
+
+    # set the name of this union for use in pretty-printing
+    def name(value)
+      @name = value.dup.freeze
+      self
+    end
+
+    # set the endian of this union
+    def endian(value)
+      @endian = Endian[value]
+      self
+    end
+
+    # declare a member in the union
+    # @param name name of the member
+    # @param type [CTypes::Type] type of the field
+    #
+    # This function supports the use of {Struct} and {Union} types for
+    # declaring unnamed fields (ISO C11).  See example below for more details.
+    #
+    # @example declare named union members
+    #   member(:word, uint32)
+    #   member(:bytes, array(uint8, 4))
+    #   member(:half_words, array(uint16, 2))
+    #   member(:header, struct(type: uint16, len: uint16))
+    #
+    # @example add an unnamed field (ISO C11)
+    #   include CTypes::Helpers
+    #
+    #   # declare the type to be used in the unnamed field
+    #   header = struct(id: uint32, len: uint32)
+    #
+    #   # create our union type with an unnamed field
+    #   t = union do
+    #     # add the unnamed field, in this case the header type
+    #     member header
+    #     member :raw, string
+    #     size { |union| header.size + union.len }
+    #   end
+    #
+    #   # now unpack an instance of the union type
+    #   packet = t.unpack("\x01\0\0\0\x13\0\0\0hello worldXXX")
+    #
+    #   # access the unnamed field attributes
+    #   p.id    # => 1
+    #   p.len   # => 19
+    def member(name, type = nil)
+      # named field
+      if type
+        name = name.to_sym
+        @fields << [name, type].freeze
+        @field_names << name
+        @schema << Dry::Types::Schema::Key
+          .new(type.dry_type.type, name, required: false)
+        @default ||= {name => type.default_value}
+
+      # unnamed field
+      else
+        type = name
+        dry_keys = type.dry_type.keys or
+          raise Error, "unsupported type for unnamed field: %p" % [type]
+        names = dry_keys.map(&:name)
+
+        if (duplicate = names.any? { |n| @field_names.include?(n) })
+          raise Error, "duplicate field name %p in unnamed field: %p" %
+            [duplicate, type]
+        end
+
+        @fields << [names, type].freeze
+        @field_names += names
+        @schema += dry_keys.map do |key|
+          # for all of the keys in the type, we need to create an equivalent
+          # Key where the key is omittable.
+          #
+          # note: we strip the default value off the dry type here when defining
+          # the schema for our own dry type.  If we do not do this, `dry_type[{}]`
+          # has every member in it, resulting in "only one member" error being
+          # raised in Union.pack when the union is nested within a struct.
+          #
+          # Example:
+          #   struct(id: uint8, value: union(byte: uint8, word: uint32))
+          #     .pack({value: byte: 1})
+          Dry::Types::Schema::Key.new(key.type.type, key.name, required: false)
+        end
+
+        @default ||= type.default_value
+      end
+
+      # fix up the size
+      @size = type.size if @size.is_a?(Integer) && type.size > @size
+      @fixed_size &&= type.fixed_size?
+      self
+    end
+
+    # Add a proc for determining Union size based on decoded bytes
+    # @param block block will be called to determine struct size in bytes
+    #
+    # When unpacking a variable length {Union}, the size proc is passed a
+    # frozen {Union} instance with the entire input buffer.  The size proc will
+    # then unpack only those members it needs to calculate the total union
+    # size, and return the union size in bytes.
+    #
+    # @example variable length type-length-value (TLV) union
+    #   CTypes::Helpers.struct do
+    #     # TLV message header with some fixed types
+    #     header = struct(
+    #       msg_type: enum(uint8, {invalid: 0, hello: 1, read: 2}),
+    #       len: uint16)
+    #
+    #     member :header, header
+    #     member :hello, struct(header:, version: string)
+    #     member :read, struct(header:, offset: uint64, size: uint64)
+    #     member :raw, string(trim: false)
+    #
+    #     # the header#len field contains the length of the remaining union
+    #     # bytes after the header.  So we add the header size, and the value
+    #     # in header.len to get the total union size.
+    #     size { |union| header.size + union.header.len }
+    #   end
+    def size(&block)
+      @fixed_size = false
+      @size = block
+      self
+    end
+
+    # used for custom type resolution
+    # @see CTypes.using_type_lookup
+    def method_missing(name, *args, &block)
+      if @type_lookup && args.empty? && block.nil?
+        type = @type_lookup.call(name)
+        return type if type
+      end
+      super
+    end
+  end
+end