bin_struct 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 44d43c8007a5ad33899e5c7ee6a09c306a64a95012bd489ee2d14d69c7e40dcf
-  data.tar.gz: db0b44a68cb8a23b1a5110cb12bb587c4cf4a737b42443f72c0ae9241fffa6c9
+  metadata.gz: b6e644878c67b11f8006b130b0964a2349f0aa66645f2706cb97a20bf1ec6b77
+  data.tar.gz: 0bbf06e91de1bc410888f9c0e79f8caa0b7bb7f7082b5c775186c41c4a3d04db
 SHA512:
-  metadata.gz: 287f8dbf64a09b27b5fe376f9b6a982055713cdb2453ab7dd2b5ec0489678727441a3545427bb9f1f31d0ccc733bcc10e6af703fdc3b85b7cf539614b306bc21
-  data.tar.gz: cc3ba318afa6ac9706d57676256bbebeeec3b4dc52402728777b8c7a7fb89c9de8d893903b3e753d84a25aa6339b9aa919cfd4a223ff1f1a446a2d169047dee2
+  metadata.gz: c1bd8b95ce395af08b53ea41385929e9d06490d4ab21588dd46e02d8ba1d66207879174ec2f3a98400667446956042b581a032d93e8b9b97cc2d8448b20ced44
+  data.tar.gz: b81c04e4ddcf9a4bbe3af1b36735a5221014f69f43ef5d11c166d33e595aa989f0feb436ed2ba5547f42372c636383a5196c302f54548d0525d49057576f2467

data/CHANGELOG.md

@@ -3,6 +3,32 @@
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.5.0 - 2025-02-17
+
+### Added
+
+- Add `String#b` to mimic Ruby's `String`
+- Add a lot of examples in YARD documentation. These examples are checked using yard-doctest.
+
+### Deprecated
+
+- Deprecate `BinStruct.force_binary` and `Struct.force_binary` in favor of Ruby's `String#b`
+
+### Fixed
+
+- Fix `String#to_s` when static_length is set. `#to_s` was not aware of static length option.
+
+## 0.4.0 - 2025-02-13
+
+### Added
+
+- Add `Struct#attribute?` to check existence of an attribute.
+- Add `AbstractTLV.derive` to derive a new subclass from a concrete TLV class.
+
+### Fixed
+
+- Update and fix Yard documentation.
+
 ## 0.3.0 - 2024-12-02
 
 ### Added

data/README.md

@@ -19,6 +19,89 @@ Or add it to a Gemfile:
 gem 'bin_struct'
 ```
 
+## Usage
+
+### Create a struct
+
+To create a BinStruct, create a new class inheriting from `BinStruct::Struct`. Then, defines struct attributes using `.define_attr`. `.define_bit_attr` may also be used to define bit field attributes.
+
+```ruby
+require 'bin_struct'
+
+class IPHeader < BinStruct::Struct
+  # Define a bir field, defaulting to 0x45, and splitted in 2 sub-fields: version and ihl,
+  # 4-bit size each
+  define_bit_attr :u8, default: 0x45, version: 4, ihl: 4
+  # Define a 8-bit unsigned integer named tos
+  #  1st argument: a symbol to define attribute name
+  #  2nd argument: a class to define attribute type. May be a type provided by BinStruct,
+  #                or a user-defined class inheriting from one of these classes
+  #  others arguments: options. Here, :default defines a default value for the attribute.
+  define_attr :tos, BinStruct::Int8, default: 0
+  # Define a 16-bit unsigned integer named length. Default to 20.
+  define_attr :length, BinStruct::Int16, default: 20
+  # Define a 16-bir unsigned integer named id. It is initialized with a random number
+  define_attr :id, BinStruct::Int16, default: ->(_) { rand(65_535) }
+  # Define a bit field composed of 4 subfields of 1, 1, 1 and 13 bit, respectively
+  define_bit_attr :frag, flag_rsv: 1, flag_df: 1, flag_mf: 1, fragment_offset: 13
+  # Define TTL field, a 8-bit unsigned integer, default to 64
+  define_attr :ttl, BinStruct::Int8, default: 64
+  # Define protocol field (8-bit unsigned integer)
+  define_attr :protocol, BinStruct::Int8
+  # Define checksum field (16-bit unsigned integer), default to 0
+  define_attr :checksum, BinStruct::Int16, default: 0
+  # Source and destination addresses, defined as array of 4 8-bit unsigned integers
+  define_attr :src, BinStruct::ArrayOfInt8, length_from: -> { 4 }
+  define_attr :dst, BinStruct::ArrayOfInt8, length_from: -> { 4 }
+end
+```
+
+### Parse a binary string
+
+```ruby
+# Initialize struct from a binary string
+ip = IPHeader.new.read("\x45\x00\x00\x14\x43\x21\x00\x00\x40\x01\x00\x00\x7f\x00\x00\x01\x7f\x00\x00\x01".b)
+
+# Access some fields
+p ip.version     #=> 4
+p ip.ihl         #=> 5
+p ip.id.to_s(16) #=> "4321"
+p ip.protocol    #=> 1
+p ip.src.map { |byte| byte.to_i }.join('.') #=> "127.0.0.1"
+```
+
+```text
+> p IPHeader.new.read("\x45\x00\x00\x14\x43\x21\x00\x00\x40\x01\x00\x00\x7f\x00\x00\x01\x7f\x00\x00\x01")
+-- IPHeader -----------------------------------------------------------
+          BitAttr8               u8: 69               (0x45)
+                                     version:4 ihl:5
+              Int8              tos: 0                (0x00)
+             Int16           length: 20               (0x0014)
+             Int16               id: 17185            (0x4321)
+         BitAttr16             frag: 0                (0x0000)
+                                     flag_rsv:0 flag_df:0 flag_mf:0 fragment_offset:0
+              Int8              ttl: 64               (0x40)
+              Int8         protocol: 1                (0x01)
+             Int16         checksum: 0                (0x0000)
+       ArrayOfInt8              src: 127,0,0,1
+       ArrayOfInt8              dst: 127,0,0,1
+
+```
+
+### Generate a binary string
+
+```ruby
+# Create a new struct with some fields initialized
+ip = IPHeader.new(tos: 42, id: 0x1234)
+
+# Initialize fields after creation
+ip.src = [192, 168, 1, 1]
+ip.dst = [192, 168, 1, 2]
+
+# Generate binary string
+ip.to_s
+```
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/bin_struct/abstract_tlv.rb

@@ -6,14 +6,11 @@
 # Copyright (C) 2024 LemonTree55 <lenontree@proton.me>
 # This program is published under MIT license.
 
-# BinStruct module
-# @author LemonTree55
 module BinStruct
   # @abstract Base class to define type-length-value data.
   #
-  # ===Usage
-  # To simply define a new TLV class, do:
-  #   MyTLV = PacketGen::Types::AbstractTLV.create
+  # You have to define a concrete class from AbstractTLV
+  #   MyTLV = BinStruct::AbstractTLV.create
   #   MyTLV.define_type_enum 'one' => 1, 'two' => 2
   # This will define a new +MyTLV+ class, subclass of {AbstractTLV}. This class will
   # define 3 attributes:
@@ -23,29 +20,36 @@ module BinStruct
   # +.define_type_enum+ is, here, necessary to define enum hash to be used
   # for +#type+ accessor, as this one is defined as an {Enum}.
   #
-  # This new defined class may now be easily used:
+  # @example Basic usage
+  #   MyTLV = BinStruct::AbstractTLV.create
+  #   MyTLV.define_type_enum 'one' => 1, 'two' => 2
+  #
   #   tlv = MyTLV.new(type: 1, value: 'abcd')  # automagically set #length from value
   #   tlv.type        #=> 1
   #   tlv.human_type  #=> 'one'
   #   tlv.length      #=> 4
   #   tlv.value       #=> "abcd"
   #
-  # ===Advanced usage
-  # Each attribute's type may be changed at generating TLV class:
-  #   MyTLV = PacketGen::Types::AbstractTLV.create(type_class: PacketGen::Types::Int16,
-  #                                                length_class: PacketGen::Types::Int16,
-  #                                                value_class: PacketGen::Header::IP::Addr)
-  #   tlv = MyTLV.new(type: 1, value: '1.2.3.4')
+  # @example Change attribute types
+  #   # Change type for each attribute
+  #   # Type and length are 16-bit big endian integers
+  #   # Value is a OUI
+  #   MyTLV = BinStruct::AbstractTLV.create(type_class: BinStruct::Int16,
+  #                                         length_class: BinStruct::Int16,
+  #                                         value_class: BinStruct::OUI)
+  #   tlv = MyTLV.new(type: 1, value: '01:02:03')
   #   tlv.type        #=> 1
-  #   tlv.length      #=> 4
-  #   tlv.value       #=> '1.2.3.4'
-  #   tlv.to_s        #=> "\x00\x01\x00\x04\x01\x02\x03\x04"
+  #   tlv.length      #=> 3
+  #   tlv.value       #=> '01:02:03'
+  #   tlv.to_s        #=> "\x00\x01\x00\x03\x01\x02\x03"
   #
-  # Some aliases may also be defined. For example, to create a TLV type
-  # whose +type+ attribute should be named +code+:
-  #   MyTLV = PacketGen::Types::AbstractTLV.create(type_class: PacketGen::Types::Int16,
-  #                                                length_class: PacketGen::Types::Int16,
-  #                                                aliases: { code: :type })
+  # @example Using aliases
+  #   # Type and length are 16-bit big endian integers
+  #   # Value is a string
+  #   # code is an alias for type
+  #   MyTLV = BinStruct::AbstractTLV.create(type_class: BinStruct::Int16,
+  #                                         length_class: BinStruct::Int16,
+  #                                         aliases: { code: :type })
   #   tlv = MyTLV.new(code: 1, value: 'abcd')
   #   tlv.code        #=> 1
   #   tlv.type        #=> 1
@@ -77,11 +81,12 @@ module BinStruct
       #   in the desired order.
       # @param [::String] attr_in_length give attributes to compute length on.
       # @return [Class]
+      # @raise [Error] Called on {AbstractTLV} subclass
       def create(type_class: Int8Enum, length_class: Int8, value_class: String,
                  aliases: {}, attr_order: 'TLV', attr_in_length: 'V')
         unless equal?(AbstractTLV)
           raise Error,
-                '.create cannot be called on a subclass of PacketGen::Types::AbstractTLV'
+                '.create cannot be called on a subclass of BinStruct::AbstractTLV'
         end
 
         klass = Class.new(self)
@@ -91,7 +96,7 @@ module BinStruct
         check_attr_in_length(attr_in_length)
         check_attr_order(attr_order)
         generate_attributes(klass, attr_order, type_class, length_class, value_class)
-
+        generate_aliases_for(klass, aliases)
         aliases.each do |al, orig|
           klass.instance_eval do
             alias_method al, orig if klass.method_defined?(orig)
@@ -103,6 +108,50 @@ module BinStruct
       end
       # rubocop:enable Metrics/ParameterLists
 
+      # On inheritage, copy aliases and attr_in_length
+      # @param [Class] klass inheriting class
+      # @return [void]
+      # @since 0.4.0
+      # @author LemonTree55
+      def inherited(klass)
+        super
+
+        aliases = @aliases.clone
+        attr_in_length = @attr_in_length.clone
+
+        klass.class_eval do
+          @aliases = aliases
+          @attr_in_length = attr_in_length
+        end
+      end
+
+      # Derive a new TLV class from an existing one
+      # @param [Class,nil] type_class New class to use for +type+. Unchanged if +nil+.
+      # @param [Class,nil] length_class New class to use for +length+. Unchanged if +nil+.
+      # @param [Class,nil] value_class New class to use for +value+. Unchanged if +nil+.
+      # @return [Class]
+      # @raise [Error] Called on {AbstractTLV} class
+      # @since 0.4.0
+      # @author LemonTree55
+      # @example
+      #   # TLV with type and length on 16 bits, value is a BinStruct::String
+      #   FirstTLV = BinStruct::AbstractTLV.create(type_class: BinStruct::Int16, length_class: BinStruct::Int16)
+      #   # TLV with same type and length classes than FirstTLV, but value is an array of Int8
+      #   SecondTLV = FirstTLV.derive(value_class: BinStruct::ArrayOfInt8)
+      def derive(type_class: nil, length_class: nil, value_class: nil, aliases: {})
+        raise Error, ".derive cannot be called on #{name}" if equal?(AbstractTLV)
+
+        klass = Class.new(self)
+        klass.aliases.merge!(aliases)
+        generate_aliases_for(klass, aliases)
+
+        klass.attr_defs[:type].type = type_class unless type_class.nil?
+        klass.attr_defs[:length].type = length_class unless length_class.nil?
+        klass.attr_defs[:value].type = value_class unless value_class.nil?
+
+        klass
+      end
+
       # @!attribute type
       #   @abstract
       #   Type attribute for real TLV class
@@ -168,6 +217,15 @@ module BinStruct
           end
         end
       end
+
+      def generate_aliases_for(klass, aliases)
+        aliases.each do |al, orig|
+          klass.instance_eval do
+            alias_method al, orig if klass.method_defined?(orig)
+            alias_method :"#{al}=", :"#{orig}=" if klass.method_defined?(:"#{orig}=")
+          end
+        end
+      end
     end
 
     # @!attribute type

data/lib/bin_struct/array.rb

@@ -9,7 +9,7 @@
 require 'forwardable'
 
 module BinStruct
-  # @abstract Base class to define set of {Struct} subclasses.
+  # @abstract Base class to define set of {Structable} subclasses.
   #
   # This class mimics regular Ruby Array, but it is {Structable} and responds to {LengthFrom}.
   #
@@ -44,10 +44,11 @@ module BinStruct
     # @!method clear
     #   Clear array.
     #   @return [void]
+    #   @see #clear!
     # @!method each
     #   Calls the given block once for each element in self, passing that
-    #   element as a parameter. Returns the array itself.
-    #   @return [::Array]
+    #   element as a parameter. Returns the array itself, or an enumerator if no block is given.
+    #   @return [::Array, Enumerator]
     # @method empty?
     #   Return +true+ if contains no element.
     #   @return [Boolean]
@@ -86,6 +87,23 @@ module BinStruct
 
     # @param [Hash] options
     # @option options [Int] counter Int object used as a counter for this set
+    # @example counter example
+    #   # Define a counter
+    #   counter = BinStruct::Int8.new
+    #   counter.to_i # => 0
+    #
+    #   # Define an array with associated counter
+    #   ary = BinStruct::ArrayOfInt8.new(counter: counter)
+    #   # Add 2 elements to arry, increment counter twice
+    #   ary.read([1, 2])
+    #   counter.to_i #=> 2
+    #   # Add a third element
+    #   ary << BinStruct::Int8.new(value: 42)
+    #   counter.to_i #=> 3
+    #
+    #   # push does not increment the counter
+    #   ary.push(BinStruct::Int8.new(value: 100))
+    #   counter.to_i #=> 3
     def initialize(options = {})
       @counter = options[:counter]
       @array = []
@@ -112,6 +130,7 @@ module BinStruct
 
     # Clear array. Reset associated counter, if any.
     # @return [void]
+    # @see #clear
     def clear!
       @array.clear
       @counter&.from_human(0)
@@ -137,7 +156,8 @@ module BinStruct
 
     # @abstract depend on private method +#record_from_hash+ which should be
     #   declared by subclasses.
-    # Add an object to this array. Do not update associated counter.
+    # Add an object to this array. Do not update associated counter. If associated must be incremented, use
+    # {#<<}
     # @param [Object] obj type depends on subclass
     # @return [self]
     # @see #<<
@@ -154,9 +174,11 @@ module BinStruct
 
     # @abstract depend on private method +#record_from_hash+ which should be
     #   declared by subclasses.
-    # Add an object to this array, and increment associated counter, if any
+    # Add an object to this array, and increment associated counter, if any. If associated counter must not be
+    # incremented, use {#push}.
     # @param [Object] obj type depends on subclass
     # @return [self]
+    # @see #push
     def <<(obj)
       push(obj)
       @counter&.from_human(@counter.to_i + 1)
@@ -266,30 +288,65 @@ module BinStruct
   end
 
   # Specialized {Array} to handle serie of {Int8}.
+  # @example
+  #   ary = BinStruct::ArrayOfInt8.new
+  #   ary.read([0, 1, 2])
+  #   ary.to_s #=> "\x00\x01\x02".b
+  #
+  #   ary.read("\x05\x06")
+  #   ary.map(&:to_i) #=> [5, 6]
   class ArrayOfInt8 < Array
     include ArrayOfIntMixin
     set_of Int8
   end
 
   # Specialized {Array} to handle serie of {Int16}.
+  # @example
+  #   ary = BinStruct::ArrayOfInt16.new
+  #   ary.read([0, 1, 2])
+  #   ary.to_s #=> "\x00\x00\x00\x01\x00\x02".b
+  #
+  #   ary.read("\x05\x06")
+  #   ary.map(&:to_i) #=> [0x0506]
   class ArrayOfInt16 < Array
     include ArrayOfIntMixin
     set_of Int16
   end
 
   # Specialized {Array} to handle serie of {Int16le}.
+  # @example
+  #   ary = BinStruct::ArrayOfInt16le.new
+  #   ary.read([0, 1, 2])
+  #   ary.to_s #=> "\x00\x00\x01\x00\x02\x00".b
+  #
+  #   ary.read("\x05\x06")
+  #   ary.map(&:to_i) #=> [0x0605]
   class ArrayOfInt16le < Array
     include ArrayOfIntMixin
     set_of Int16le
   end
 
   # Specialized {Array} to handle serie of {Int32}.
+  # @example
+  #   ary = BinStruct::ArrayOfInt32.new
+  #   ary.read([0, 1, 2])
+  #   ary.to_s #=> "\x00\x00\x00\x00\x00\x00\x00\x01\x00\x00\x00\x02".b
+  #
+  #   ary.read("\x00\x00\x05\x06")
+  #   ary.map(&:to_i) #=> [0x00000506]
   class ArrayOfInt32 < BinStruct::Array
     include ArrayOfIntMixin
     set_of Int32
   end
 
   # Specialized {Array} to handle serie of {Int32le}.
+  # @example
+  #   ary = BinStruct::ArrayOfInt32le.new
+  #   ary.read([0, 1, 2])
+  #   ary.to_s #=> "\x00\x00\x00\x00\x01\x00\x00\x00\x02\x00\x00\x00".b
+  #
+  #   ary.read("\x00\x00\x05\x06")
+  #   ary.map(&:to_i) #=> [0x06050000]
   class ArrayOfInt32le < BinStruct::Array
     include ArrayOfIntMixin
     set_of Int32le

data/lib/bin_struct/bit_attr.rb

@@ -7,21 +7,32 @@
 require 'digest'
 
 module BinStruct
-  # Define a bitfield attribute to embed in a {Struct}.
+  # Define a bitfield attribute to embed in a {Struct}. Use it through {Struct.define_bit_attr}
   #
+  # @example
   #  class MyStruct < BinStruct::Struct
   #    # Create a 32-bit bitfield attribute, with fields a (16 bits), b and c (4 bits each) and d (8 bits).
   #    # a is the leftmost field in bitfield, and d the rightmost one.
-  #    define_attr :int32, BinStruct::BitAttr.create(width: 32, a: 16, b: 4, c: 4, d:8)
+  #    define_bit_attr :int32, width: 32, a: 16, b: 4, c: 4, d:8
   #  end
+  #
+  #  s1 = MyStruct.new(int32: 0x12345678)
+  #  s1.a #=> 0x1234
+  #  s1.b #=> 5
+  #  s1.c #=> 6
+  #  s1.d #=> 0x78
+  #
+  #  s2 = MyStruct.new(a: 0x1234, d: 0x42)
+  #  s2.to_s #=> "\x12\x34\x00\x42".b
   # @since 0.3.0
+  # @abstract Subclasses must de derived using {.create}.
   # @author LemonTree55
   class BitAttr
     include Structable
 
     # @return [Integer] width in bits of bit attribute
     attr_reader :width
-    # @return [Array[Symbol]]
+    # @return [::Array[Symbol]]
     attr_reader :bit_methods
 
     # @private
@@ -79,9 +90,10 @@ module BinStruct
     # @param [Hash{Symbol=>Integer}] opts initialization values for fields, where keys are field names and values are
     #     initialization values
     # @return [self]
+    # @raise [NotImplementedError] raised when called on {BitAttr} class
     def initialize(opts = {})
       parameters = self.class.parameters
-      raise NotImplementedError, '#initialize may only be called on subclass of {self.class}' if parameters.nil?
+      raise NotImplementedError, "#initialize may only be called on subclass of #{self.class}" if parameters.nil?
 
       @width = parameters.width
       @fields = parameters.fields
@@ -110,7 +122,7 @@ module BinStruct
     end
 
     # Populate bit attribute from +str+
-    # @param [::String,nil] str
+    # @param [#to_s,nil] str
     # @return [self]
     def read(str)
       return self if str.nil?
@@ -175,7 +187,7 @@ module BinStruct
       if size == 1
         instance_eval "def #{name}?; @data[#{name.inspect}] != 0; end\n", __FILE__, __LINE__
         instance_eval "def #{name}=(val); v = case val when TrueClass; 1 when FalseClass; 0 else val end; " \
-                      "@data[#{name.inspect}] = v; end", __FILE__, __LINE__ - 2
+                      "@data[#{name.inspect}] = v; end", __FILE__, __LINE__ - 1
         bit_methods << :"#{name}?"
       else
         instance_eval "def #{name}=(val); @data[#{name.inspect}] = val; end", __FILE__, __LINE__

data/lib/bin_struct/cstring.rb

@@ -10,6 +10,9 @@ require 'forwardable'
 
 module BinStruct
   # This class handles null-terminated strings (aka C strings).
+  # # @example
+  #   cstr = BinStruct::CString.new(value: 'abcd')
+  #   cstr.to_s #=> "abcd\x00".b
   # @author Sylvain Daubert (2016-2024)
   # @author LemonTree55
   class CString
@@ -76,14 +79,14 @@ module BinStruct
 
     # @param [Hash] options
     # @option options [Integer] :static_length set a static length for this string
-    # @option options [::String] :value string value (default to +''+)
+    # @option options [::String] :value string value (default to +""+)
     def initialize(options = {})
       register_internal_string(options[:value] || +'')
       @static_length = options[:static_length]
     end
 
     # Populate self from binary string
-    # @param [::String] str
+    # @param [#to_s] str
     # @return [self]
     def read(str)
       s = str.to_s
@@ -102,7 +105,7 @@ module BinStruct
       else
         s = "#{string}\x00"
       end
-      BinStruct.force_binary(s)
+      s.b
     end
 
     # Append the given string to CString
@@ -134,7 +137,7 @@ module BinStruct
     # @param [::String] str
     # @return [self]
     def from_human(str)
-      read str
+      read(str)
     end
 
     # Get human-readable string
@@ -146,8 +149,7 @@ module BinStruct
     private
 
     def register_internal_string(str)
-      @string = str
-      BinStruct.force_binary(@string)
+      @string = str.b
     end
 
     def remove_null_character

data/lib/bin_struct/enum.rb

@@ -12,20 +12,23 @@ module BinStruct
   # An {Enum} type is used to handle an {Int} attribute with limited
   # and named values.
   #
-  # == Simple example
-  #  enum = Int8Enum.new('low' => 0, 'medium' => 1, 'high' => 2})
-  # In this example, +enum+ is a 8-bit attribute which may take one
-  # among three values: +low+, +medium+ or +high+:
-  #  enum.value = 'high'
-  #  enum.value              # => 2
-  #  enum.value = 1
-  #  enum.value              # => 1
-  #  enum.to_human           # => "medium"
-  # Setting an unknown value will raise an exception:
-  #  enum.value = 4          # => raise!
-  #  enum.value = 'unknown'  # => raise!
-  # But {#read} will not raise when reading an outbound value. This
+  # Setting an unknown name will raise an exception:
+  #   enum.value = 'unknown'  # => raise!
+  # But {#read} and {#value=} will not raise when reading/setting an out-of-bound integer. This
   # to enable decoding (or forging) of bad packets.
+  #   enum.read("\x05".b).value # => 5
+  #   enum.value = 4            # => 4
+  #
+  # @example Simple example
+  #   # Define an enum on 8-bit integer. It may take one among
+  #   # three values: low, medium or high
+  #   enum = BinStruct::Int8Enum.new(enum: {'low' => 0, 'medium' => 1, 'high' => 2})
+  #   enum.value = 'high'
+  #   enum.value              # => 2
+  #   enum.value = 1
+  #   enum.value              # => 1
+  #   enum.to_human           # => "medium"
+  #
   # @author Sylvain Daubert (2016-2024)
   # @author LemonTree55
   class Enum < Int

data/lib/bin_struct/int.rb

@@ -55,7 +55,7 @@ module BinStruct
 
     # @abstract
     # @return [::String]
-    # @raise [Error] This is an abstrat method and must be redefined
+    # @raise [Error] This is an abstract method and must be redefined
     def to_s
       raise Error, 'BinStruct::Int#to_s is abstract' unless defined? @packstr
 

data/lib/bin_struct/int_string.rb

@@ -9,6 +9,13 @@
 module BinStruct
   # Provides a class for creating strings preceeded by their length as an {Int}.
   # By default, a null string will have one byte length (length byte set to 0).
+  # == Examples
+  #   # IntString with 8-bit length
+  #   is8 = BinStruct::IntString.new(value: "abcd")
+  #   is8.to_s   # => "\x04abcd"
+  #   # IntString with 16-bit length
+  #   is16 = BinStruct::IntString.new(length_type: BinStruct::Int16le, value: "abcd")
+  #   is16.to_s  # => "\x04\x00abcd"
   # @author Sylvain Daubert (2016-2024)
   # @author LemonTree55
   class IntString

data/lib/bin_struct/length_from.rb

@@ -9,7 +9,7 @@
 module BinStruct
   # This module is a mixin adding +length_from+ capacity to a type.
   # +length_from+ capacity is the capacity, for a type, to gets its
-  # length from another object.
+  # length from another object. For an example, see {String}.
   # @author Sylvain Daubert (2016-2024)
   # @author LemonTree55
   module LengthFrom
@@ -30,7 +30,7 @@ module BinStruct
     # @param [#to_s] str
     # @return [::String]
     def read_with_length_from(str)
-      s = BinStruct.force_binary(str.to_s)
+      s = str.to_s.b
       s[0, sz_to_read]
     end
 

data/lib/bin_struct/oui.rb

@@ -8,10 +8,11 @@
 
 module BinStruct
   # OUI type, defined as a set of 3 bytes
-  #  oui = OUI.new
+  # @example
+  #  oui = BinStruct::OUI.new
   #  oui.from_human('00:01:02')
   #  oui.to_human   # => "00:01:02"
-  #  oui.to_s       # => "\x00\x01\x03"
+  #  oui.to_s       # => "\x00\x01\x02".b
   # @author Sylvain Daubert (2016-2024)
   # @author LemonTree55
   class OUI < Struct

data/lib/bin_struct/string.rb

@@ -10,6 +10,33 @@ require 'forwardable'
 
 module BinStruct
   # This class mimics regular String, but it is {Structable}.
+  #
+  # It may take its length from another field ({LengthFrom} capacity). It may also has a static length
+  # (i.e. string has always the same length, whatever its content is).
+  #
+  # @example Basic example
+  #   str = BinStruct::String.new
+  #   str.read("abc")
+  #   str.to_s #=> "abc".b
+  #
+  # @example LengthFrom example
+  #   class StrLen < BinStruct::Struct
+  #     define_attr :length, BinStruct::Int8
+  #     define_attr :str, BinStruct::String, builder: ->(h, t) { t.new(length_from: h[:length]) }
+  #   end
+  #
+  #   # Length is 3, but rest of data is 4 byte long. Only 3 bytes will be read.
+  #   s = StrLen.new.read("\x03abcd")
+  #   s.length #=> 3
+  #   s.str.to_s #=> "abc".b
+  #   s.to_s # => "\x03abc".b
+  #
+  # @example static length example
+  #   s = BinStruct::String.new(static_length: 10)
+  #   s.sz #=> 10
+  #   s.to_s #=> "\0\0\0\0\0\0\0\0\0\0".b
+  #   s.read("01234567890123456789")
+  #   s.to_s #=> "0123456789".b
   # @author Sylvain Daubert (2016-2024)
   # @author LemonTree55
   class String
@@ -19,7 +46,7 @@ module BinStruct
 
     def_delegators :@string, :[], :length, :size, :inspect, :==,
                    :unpack, :force_encoding, :encoding, :index, :empty?,
-                   :encode, :slice, :slice!, :[]=
+                   :encode, :slice, :slice!, :[]=, :b
 
     # Underlying Ruby String
     # @return [::String]
@@ -32,7 +59,7 @@ module BinStruct
     # @option options [Int,Proc] :length_from object or proc from which
     #   takes length when reading
     # @option options [Integer] :static_length set a static length for this string
-    # @option options [::String] :value string value (default to +''+)
+    # @option options [::String] :value string value (default to +""+)
     def initialize(options = {})
       register_internal_string(options[:value] || +'')
       initialize_length_from(options)
@@ -47,7 +74,7 @@ module BinStruct
     end
 
     # Populate String from a binary String. Limit length using {LengthFrom} or {#static_length}, if one is set.
-    # @param [::String] str
+    # @param [::String,nil] str
     # @return [self]
     def read(str)
       s = read_with_length_from(str)
@@ -83,25 +110,29 @@ module BinStruct
     # @param [#to_s] str
     # @return [self]
     def <<(str)
-      @string << BinStruct.force_binary(str.to_s)
+      @string << str.to_s.b
       self
     end
 
-    # Generate binary string
+    # Generate "binary" string
     # @return [::String]
     def to_s
-      @string
+      if static_length?
+        s = @string[0, static_length]
+        s << ("\x00" * (static_length - s.length))
+        s.b
+      else
+        @string.b
+      end
     end
 
-    alias sz length
     alias to_human to_s
     alias from_human read
 
     private
 
     def register_internal_string(str)
-      @string = str
-      BinStruct.force_binary(@string)
+      @string = str.b
     end
   end
 end

data/lib/bin_struct/struct.rb

@@ -32,8 +32,8 @@ module BinStruct
   # Attributes may also be accessed through {#[]} ans {#[]=}. These methods give access
   # to type object:
   #   mybs = MyBinaryStructure.new
-  #   mybs.attr1     # => Integer
-  #   mybs[:attr1]   # => BinStruct::Int8
+  #   mybs.attr1.class     # => Integer
+  #   mybs[:attr1].class   # => BinStruct::Int8
   #
   # {#initialize} accepts an option hash to populate attributes. Keys are attribute
   # name symbols, and values are those expected by writer accessor.
@@ -57,7 +57,7 @@ module BinStruct
   # +#body+, +#body=+, +#mac_addr+ and +#mac_addr=+.
   #
   # {.define_attr} has many options (third optional Hash argument):
-  # * +:default+ gives default attribute value. It may be a simple value (an Integer
+  # * +:default+ to define default attribute value. It may be a simple value (an Integer
   #   for an Int attribute, for example) or a lambda,
   # * +:builder+ to give a builder/constructor lambda to create attribute. The lambda
   #   takes 2 arguments: {Struct} subclass object owning attribute, and type class as passes
@@ -97,7 +97,7 @@ module BinStruct
   # * {.define_attr_before} and {.define_bit_attr_before} to define a new attribute before an existing one,
   # * {.define_attr_after} and {.define_bit_attr_after} to define a new attribute after an existing onr,
   # * {.remove_attr} to remove an existing attribute,
-  # * {.uptade_attr} to change options of an attribute (but not its type),
+  # * {.update_attr} to change options of an attribute (but not its type),
   #
   # @author Sylvain Daubert (2016-2024)
   # @author LemonTree55
@@ -247,7 +247,7 @@ module BinStruct
       #   class MyHeader < BinStruct::Struct
       #     # define a 16-bit attribute named :flag
       #     # flag1, flag2 and flag3 are 1-bit attributes
-      #     # type and stype are 3-bit attributes. reserved is a 7-bit attribute
+      #     # type and stype are 3-bit attributes, reserved is a 7-bit attribute
       #     define_bit_attr :flags, flag1: 1, flag2: 1, flag3: 1, type: 3, stype: 3, reserved: 7
       #   end
       # A bit attribute of size 1 bit defines 3 methods:
@@ -401,6 +401,15 @@ module BinStruct
       @attributes[attr] = obj
     end
 
+    # Say if struct has given attribute
+    # @param [Symbol] attr attribute name
+    # @return [Boolean]
+    # @since 0.4.0
+    # @author LemonTree55
+    def attribute?(attr)
+      @attributes.key?(attr)
+    end
+
     # Get all attribute names
     # @return [Array<Symbol>]
     def attributes
@@ -434,12 +443,11 @@ module BinStruct
     def read(str)
       return self if str.nil?
 
-      force_binary(str)
       start = 0
       attributes.each do |attr|
         next unless present?(attr)
 
-        obj = self[attr].read(str[start..])
+        obj = self[attr].read(str.b[start..])
         start += self[attr].sz
         self[attr] = obj unless obj == self[attr]
       end
@@ -471,7 +479,7 @@ module BinStruct
     # @return [String]
     def to_s
       attributes.select { |attr| present?(attr) }
-                .map! { |attr| force_binary @attributes[attr].to_s }.join
+                .map! { |attr| @attributes[attr].to_s.b }.join
     end
 
     # Size of object as binary string
@@ -522,6 +530,7 @@ module BinStruct
     # Force str to binary encoding
     # @param [String] str
     # @return [String]
+    # @deprecated Prefer use of Ruby's {::String#b}
     def force_binary(str)
       BinStruct.force_binary(str)
     end
@@ -575,7 +584,7 @@ module BinStruct
     # @return [String]
     def inspect_titleize
       title = self.class.to_s
-      +"-- #{title} #{'-' * (66 - title.length)}\n"
+      "-- #{title} #{'-' * (66 - title.length)}\n"
     end
 
     # @param [:Symbol] attr

data/lib/bin_struct/version.rb

@@ -8,5 +8,5 @@
 
 module BinStruct
   # BinStruct version
-  VERSION = '0.3.0'
+  VERSION = '0.5.0'
 end

data/lib/bin_struct.rb

@@ -8,7 +8,31 @@
 
 require_relative 'bin_struct/version'
 
-# BinStruct module
+# BinStruct module provides classes to easily serialize/deserialize data to/from binary strings.
+# @example Basic example
+#   class MyData < BinStruct::Struct
+#     # Define 2 attributes as a 8-bit integer
+#     define_attr :byte1, BinStruct::Int8
+#     define_attr :byte2, BinStruct::Int8
+#     # Define an attribute as a 16-bit big endian integer
+#     define_attr :word, BinStruct::Int16
+#     # Define a 32-bit little endian integer attribute
+#     define_attr :dword, BinStruct::Int32le
+#     # Define a string prepending with its length (8-bit integer)
+#     define_attr :str, BinStruct::IntString
+#   end
+#
+#   # Generate binary data
+#   mydata = MyData.new(byte1: 1, byte2: 2, word: 3, dword: 4, str: 'abc')
+#   mydata.to_s  #=> "\x01\x02\x00\x03\x04\x00\x00\x00\x03abc".b
+#
+#   # Parse binary data
+#   mydata.read("\x00\xff\x01\x23\x11\x22\x33\x44\x00")
+#   mydata.byte1 #=> 0
+#   mydata.byte2 #=> 255
+#   mydata.word  #=> 0x0123
+#   mydata.dword #=> 0x44332211
+#   mydata.str #=> ""
 # @author LemonTree55
 module BinStruct
   # BinStruct error class
@@ -17,8 +41,9 @@ module BinStruct
   # Force binary encoding for +str+
   # @param [String] str
   # @return [String] binary encoded string
+  # @deprecated Use {::String#b} instead of this method
   def self.force_binary(str)
-    str.dup.force_encoding(Encoding::BINARY)
+    str.b
   end
 end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bin_struct
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - LemonTree55
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-12-02 00:00:00.000000000 Z
+date: 2025-02-17 00:00:00.000000000 Z
 dependencies: []
 description: 'BinStruct is a binary dissector and generator. It eases manipulating
   complex binary data.
@@ -58,7 +58,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.7.0
+      version: 3.0.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="