rasn1 0.16.2 → 0.17.0

data/lib/rasn1/model.rb

@@ -6,6 +6,8 @@
 # Copyright (C) 2024 LemonTree55 <lenontree@proton.me>
 # This program is published under MIT license.
 
+require_relative 'model/accel'
+
 module RASN1
   # @abstract
   # {Model} class is a base class to define ASN.1 models.
@@ -16,7 +18,8 @@ module RASN1
   #    room  [0] IMPLICIT INTEGER OPTIONAL,
   #    house [1] EXPLICIT INTEGER DEFAULT 0
   #  }
-  # you may create your model like this:
+  #
+  # You may create your model like this:
   #  class Record < RASN1::Model
   #    sequence(:record,
   #             content: [integer(:id),
@@ -24,6 +27,15 @@ module RASN1
   #                       integer(:house, explicit: 1, default: 0)])
   #  end
   #
+  # You may also use block style definition:
+  #  class Record < RASN1::Model
+  #    sequence :record do
+  #      integer :id
+  #      integer :room, implicit: 0, optional: true
+  #      integer :house, explicit: 1, default: 0
+  #    end
+  #  end
+  #
   # In a model, each element must have a unique name.
   #
   # === Parse a DER-encoded string
@@ -47,10 +59,12 @@ module RASN1
   # == Create a more complex model
   # Models may be nested. For example:
   #  class Record2 < RASN1::Model
-  #    sequence(:record2,
-  #             content: [boolean(:rented, default: false),
-  #                       model(:a_record, Record)])
+  #    sequence :record2 do
+  #      boolean :rented, default: false)
+  #      model :a_record, Record
+  #    end
   #  end
+  #
   # Set values like this:
   #  record2 = Record2.new
   #  record2[:rented] = true
@@ -67,26 +81,37 @@ module RASN1
   # this method.
   # @author Sylvain Daubert
   # @author adfoster-r7 ModelValidationError, track source location for dynamic class methods
+  # @since 0.17 block notation
   class Model # rubocop:disable Metrics/ClassLength
     # @private Base Element
-    BaseElem = Struct.new(:name, :proc, :content) do
-      # @param [String,Symbol] name
-      # @param [Proc] proc
-      # @param [Array,nil] content
-      def initialize(name, proc, content)
+    class BaseElem
+      attr_accessor :name
+      attr_reader :proc, :content, :block
+
+      # @param name [String,Symbol]
+      # @param proc [Proc]
+      # @param content [Array,nil]
+      def initialize(name, proc, content, &block)
+        @name = name
+        @proc = proc
+        @content = content
+        @block = block
         check_duplicates(content.map(&:name) + [name]) unless content.nil?
-        super
       end
 
       private
 
-      # @return [Array<String>] The duplicate names found in the array
+      # @param names [Array<String, Symbol>]
+      # @return [Array<String,Symbol>] The duplicate names found in the array
       def find_all_duplicate_names(names)
         names.group_by { |name| name }
              .select { |_name, values| values.length > 1 }
              .keys
       end
 
+      # @param names [Array<String, Symbol>]
+      # @return [void]
+      # @raise [ModelValidationError] duplicate names in model definition
       def check_duplicates(names)
         duplicates = find_all_duplicate_names(names)
         raise ModelValidationError, "Duplicate name #{duplicates.first} found" if duplicates.any?
@@ -107,184 +132,42 @@ module RASN1
     # @private Sequence types
     SEQUENCE_TYPES = [Types::Sequence, Types::SequenceOf, Types::Set, Types::SetOf].freeze
 
-    # Define helper methods to define models
-    module Accel
-      # @return [Hash]
-      attr_reader :options
-
-      # Use another model in this model
-      # @param [String,Symbol] name
-      # @param [Class] model_klass
-      # @return [Elem]
-      def model(name, model_klass)
-        @root = ModelElem.new(name, model_klass)
-      end
-
-      # Use a {Wrapper} around a {Types::Base} or a {Model} object
-      # @param [Types::Base,Model] element
-      # @param [Hash] options
-      # @return [WrapElem]
-      # @since 0.12
-      def wrapper(element, options={})
-        @root = WrapElem.new(element, options)
-      end
-
-      # Update options of root element.
-      # May be used when subclassing.
-      #  class Model1 < RASN1::Model
-      #    sequence :seq, implicit: 0,
-      #             content: [bool(:bool), integer(:int)]
-      #  end
-      #
-      #  # same as Model1 but with implicit tag set to 1
-      #  class Model2 < Model1
-      #    root_options implicit: 1
-      #  end
-      # @param [Hash] options
-      # @return [void]
-      # @since 0.12.0 may change name through +:name+
-      def root_options(options)
-        @options = options
-        return unless options.key?(:name)
-
-        @root = @root.dup
-        @root.name = options[:name]
-      end
-
-      # On inheritance, create +@root+ class variable
-      # @param [Class] klass
-      # @return [void]
-      def inherited(klass)
-        super
-        root = @root
-        klass.class_eval { @root = root }
-      end
-
-      # @private
-      # @param [String,Symbol] accel_name
-      # @param [Class] klass
-      # @since 0.11.0
-      # @since 0.12.0 track source location on error (adfoster-r7)
-      def define_type_accel_base(accel_name, klass)
-        singleton_class.class_eval <<-EVAL, __FILE__, __LINE__ + 1
-          def #{accel_name}(name, options={}) # def sequence(name, type, options)
-            options[:name] = name
-            proc = proc do |opts|
-              #{klass}.new(options.merge(opts)) # Sequence.new(options.merge(opts))
-            end
-            @root = BaseElem.new(name, proc, options[:content])
-          end
-        EVAL
-      end
-
-      # @private
-      # @param [String,Symbol] accel_name
-      # @param [Class] klass
-      # @since 0.11.0
-      # @since 0.12.0 track source location on error (adfoster-r7)
-      def define_type_accel_of(accel_name, klass)
-        singleton_class.class_eval <<-EVAL, __FILE__, __LINE__ + 1
-          def #{accel_name}_of(name, type, options={}) # def sequence_of(name, type, options)
-            options[:name] = name
-            proc = proc do |opts|
-              #{klass}.new(type, options.merge(opts)) # SequenceOf.new(type, options.merge(opts))
-            end
-            @root = BaseElem.new(name, proc, nil)
-          end
-        EVAL
-      end
-
-      # Define an accelarator to access a type in a model definition
-      # @param [String] accel_name
-      # @param [Class] klass class to instanciate
-      # @since 0.11.0
-      # @since 0.12.0 track source location on error (adfoster-r7)
-      def define_type_accel(accel_name, klass)
-        if klass < Types::SequenceOf
-          define_type_accel_of(accel_name, klass)
-        else
-          define_type_accel_base(accel_name, klass)
-        end
-      end
-
-      # @param [Symbol,String] name name of object in model
-      # @param [Hash] options
-      # @return [Elem]
-      # @note This method is named +objectid+ and not +object_id+ to not override
-      #   +Object#object_id+.
-      # @see Types::ObjectId#initialize
-      def objectid(name, options={})
-        options[:name] = name
-        proc = proc { |opts| Types::ObjectId.new(options.merge(opts)) }
-        @root = BaseElem.new(name, proc, nil)
-      end
-
-      # @param [Symbol,String] name name of object in model
-      # @param [Hash] options
-      # @return [Elem]
-      # @see Types::Any#initialize
-      def any(name, options={})
-        options[:name] = name
-        proc = proc { |opts| Types::Any.new(options.merge(opts)) }
-        @root = BaseElem.new(name, proc, nil)
-      end
-
-      # Give type name (aka class name)
-      # @return [String]
-      def type
-        return @type if defined? @type
-
-        @type = self.to_s.gsub(/.*::/, '')
-      end
-
-      # Parse a DER/BER encoded string
-      # @param [String] str
-      # @param [Boolean] ber accept BER encoding or not
-      # @return [Model]
-      # @raise [ASN1Error] error on parsing
-      def parse(str, ber: false)
-        model = new
-        model.parse!(str, ber: ber)
-        model
-      end
-    end
-
     extend Accel
 
     # @!method sequence(name, options)
     #  @!scope class
-    #  @param [Symbol,String] name name of object in model
-    #  @param [Hash] options
+    #  @param name [Symbol,String] name of object in model
+    #  @param options [Hash]
     #  @return [Elem]
     #  @see Types::Sequence#initialize
     # @!method set(name, options)
     #  @!scope class
-    #  @param [Symbol,String] name name of object in model
-    #  @param [Hash] options
+    #  @param name [Symbol,String] name of object in model
+    #  @param options [Hash]
     #  @return [Elem]
     #  @see Types::Set#initialize
     # @!method choice(name, options)
     #  @!scope class
-    #  @param [Symbol,String] name name of object in model
-    #  @param [Hash] options
+    #  @param name [Symbol,String] name of object in model
+    #  @param options [Hash]
     #  @return [Elem]
     #  @see Types::Choice#initialize
     %w[sequence set choice].each do |type|
-      self.define_type_accel_base(type, Types.const_get(type.capitalize))
+      self.define_type_accel_container(type, Types.const_get(type.capitalize))
     end
 
     # @!method sequence_of(name, type, options)
     #  @!scope class
-    #  @param [Symbol,String] name name of object in model
-    #  @param [Model, Types::Base] type type for SEQUENCE OF
-    #  @param [Hash] options
+    #  @param name [Symbol,String] name of object in model
+    #  @param type [Model, Types::Base] type for SEQUENCE OF
+    #  @param options [Hash]
     #  @return [Elem]
     #  @see Types::SequenceOf#initialize
     # @!method set_of(name, type, options)
     #  @!scope class
-    #  @param [Symbol,String] name name of object in model
-    #  @param [Model, Types::Base] type type for SET OF
-    #  @param [Hash] options
+    #  @param name [Symbol,String] name of object in model
+    #  @param type [Model, Types::Base] type for SET OF
+    #  @param options [Hash]
     #  @return [Elem]
     #  @see Types::SetOf#initialize
     %w[sequence set].each do |type|
@@ -293,80 +176,80 @@ module RASN1
 
     # @!method boolean(name, options)
     #  @!scope class
-    #  @param [Symbol,String] name name of object in model
-    #  @param [Hash] options
+    #  @param name [Symbol,String] name of object in model
+    #  @param options [Hash]
     #  @return [Elem]
     #  @see Types::Boolean#initialize
     # @!method integer(name, options)
     #  @!scope class
-    #  @param [Symbol,String] name name of object in model
-    #  @param [Hash] options
+    #  @param name [Symbol,String] name of object in model
+    #  @param options [Hash]
     #  @return [Elem]
     #  @see Types::Integer#initialize
     # @!method bit_string(name, options)
     #  @!scope class
-    #  @param [Symbol,String] name name of object in model
-    #  @param [Hash] options
+    #  @param name [Symbol,String] name of object in model
+    #  @param options [Hash]
     #  @return [Elem]
     #  @see Types::BitString#initialize
     # @!method bmp_string(name, options)
     #  @!scope class
-    #  @param [Symbol,String] name name of object in model
-    #  @param [Hash] options
+    #  @param name [Symbol,String] name of object in model
+    #  @param options [Hash]
     #  @return [Elem]
     #  @see Types::BmpString#initialize
     # @!method octet_string(name, options)
     #  @!scope class
-    #  @param [Symbol,String] name name of object in model
-    #  @param [Hash] options
+    #  @param name [Symbol,String] name of object in model
+    #  @param options [Hash]
     #  @return [Elem]
     #  @see Types::OctetString#initialize
     # @!method null(name, options)
     #  @!scope class
-    #  @param [Symbol,String] name name of object in model
-    #  @param [Hash] options
+    #  @param name [Symbol,String] name of object in model
+    #  @param options [Hash]
     #  @return [Elem]
     #  @see Types::Null#initialize
     # @!method enumerated(name, options)
     #  @!scope class
-    #  @param [Symbol,String] name name of object in model
-    #  @param [Hash] options
+    #  @param name [Symbol,String] name of object in model
+    #  @param options [Hash]
     #  @return [Elem]
     #  @see Types::Enumerated#initialize
     # @!method universal_string(name, options)
     #  @!scope class
-    #  @param [Symbol,String] name name of object in model
-    #  @param [Hash] options
+    #  @param name [Symbol,String] name of object in model
+    #  @param options [Hash]
     #  @return [Elem]
     #  @see Types::UniversalString#initialize
     # @!method utf8_string(name, options)
     #  @!scope class
-    #  @param [Symbol,String] name name of object in model
-    #  @param [Hash] options
+    #  @param name [Symbol,String] name of object in model
+    #  @param options [Hash]
     #  @return [Elem]
     #  @see Types::Utf8String#initialize
     # @!method numeric_string(name, options)
     #  @!scope class
-    #  @param [Symbol,String] name name of object in model
-    #  @param [Hash] options
+    #  @param name [Symbol,String] name of object in model
+    #  @param options [Hash]
     #  @return [Elem]
     #  @see Types::NumericString#initialize
     # @!method printable_string(name, options)
     #  @!scope class
-    #  @param [Symbol,String] name name of object in model
-    #  @param [Hash] options
+    #  @param name [Symbol,String] name of object in model
+    #  @param options [Hash]
     #  @return [Elem]
     #  @see Types::PrintableString#initialize
     # @!method visible_string(name, options)
     #  @!scope class
-    #  @param [Symbol,String] name name of object in model
-    #  @param [Hash] options
+    #  @param name [Symbol,String] name of object in model
+    #  @param options [Hash]
     #  @return [Elem]
     #  @see Types::VisibleString#initialize
     # @!method ia5_string(name, options)
     #  @!scope class
-    #  @param [Symbol,String] name name of object in model
-    #  @param [Hash] options
+    #  @param name [Symbol,String] name of object in model
+    #  @param options [Hash]
     #  @return [Elem]
     #  @see Types::IA5String#initialize
     Types.primitives.each do |prim|
@@ -380,7 +263,7 @@ module RASN1
     attr_reader :root
 
     # Create a new instance of a {Model}
-    # @param [Hash] args
+    # @param args [Hash]
     def initialize(args={})
       @elements = {}
       generate_root(args)
@@ -390,11 +273,11 @@ module RASN1
 
     # @overload [](name)
     #  Access an element of the model by its name
-    #  @param [Symbol] name
+    #  @param name [Symbol]
     #  @return [Model, Types::Base, Wrapper]
     # @overload [](idx)
     #  Access an element of root element by its index. Root element must be a {Types::Sequence} or {Types::SequenceOf}.
-    #  @param [Integer] idx
+    #  @param idx [Integer]
     #  @return [Model, Types::Base, Wrapper]
     def [](name_or_idx)
       case name_or_idx
@@ -409,8 +292,8 @@ module RASN1
     end
 
     # Set value of element +name+. Element should be a {Types::Base}.
-    # @param [String,Symbol] name
-    # @param [Object] value
+    # @param name [String,Symbol]
+    # @param value [Object]
     # @return [Object] value
     def []=(name, value)
       # Here, use #[] to force generation for lazy elements
@@ -420,7 +303,8 @@ module RASN1
     end
 
     # clone @elements and initialize @root from this new @element.
-    def initialize_copy(_other)
+    # @return [void]
+    def initialize_copy(*)
       @elements = @elements.clone
       @root = @elements[@root_name]
     end
@@ -455,8 +339,8 @@ module RASN1
     end
 
     # Parse a DER/BER encoded string, and modify object in-place.
-    # @param [String] der
-    # @param [Boolean] ber accept BER encoding or not
+    # @param der [String]
+    # @param ber [Boolean] accept BER encoding or not
     # @return [Integer] number of parsed bytes
     # @raise [ASN1Error] error on parsing
     def parse!(der, ber: false)
@@ -464,6 +348,7 @@ module RASN1
     end
 
     # @private
+    # @!macro do_parse
     # @see Types::Base#do_parse
     def do_parse(der, ber: false)
       root.do_parse(der, ber: ber)
@@ -474,8 +359,8 @@ module RASN1
     #  @return [Object,nil]
     # @overload value(name, *args)
     #  Direct access to the value of +name+ (nested) element of model.
-    #  @param [String,Symbol] name
-    #  @param [Array<Integer,String,Symbol>] args more argument to access element. May be
+    #  @param name [String,Symbol]
+    #  @param args [Array<Integer,String,Symbol>] more argument to access element. May be
     #     used to access content of a SequenceOf or a SetOf
     #  @return [Object,nil]
     # @return [Object,nil]
@@ -508,10 +393,11 @@ module RASN1
       end
     end
 
-    # Return a hash image of model
-    # @return [Hash]
     # Delegate some methods to root element
-    # @param [Symbol] meth
+    # @param meth [Symbol]
+    # @param args [Array]
+    # @param kwargs [Hash]
+    # @return [Object]
     def method_missing(meth, *args, **kwargs)
       if root.respond_to?(meth)
         root.send(meth, *args, **kwargs)
@@ -520,18 +406,20 @@ module RASN1
       end
     end
 
+    # @param meth [Symbol]
     # @return [Boolean]
     def respond_to_missing?(meth, *)
       root.respond_to?(meth) || super
     end
 
+    # @param level [Integer]
     # @return [String]
     def inspect(level=0)
       "#{'  ' * level}(#{type}) #{root.inspect(-level)}"
     end
 
     # Objects are equal if they have same class AND same DER
-    # @param [Base] other
+    # @param other [Base]
     # @return [Boolean]
     def ==(other)
       (other.class == self.class) && (other.to_der == self.to_der)
@@ -540,7 +428,7 @@ module RASN1
     protected
 
     # Initialize model elements from +args+
-    # @param [Hash,Array] args
+    # @param args [Hash,Array]
     # @return [void]
     def lazy_initialize(args)
       case args
@@ -552,7 +440,7 @@ module RASN1
     end
 
     # Initialize an element from a hash
-    # @param [Hash] args
+    # @param args [Hash]
     # @return [void]
     def lazy_initialize_hash(args)
       args.each do |name, value|
@@ -568,7 +456,7 @@ module RASN1
     end
 
     # Initialize an sequence element from an array
-    # @param [Array] ary
+    # @param ary [Array]
     # @return [void]
     def lazy_initialize_array(ary)
       raise Error, 'Only sequence types may be initialized with an array' unless SEQUENCE_TYPES.any? { |klass| root.is_a?(klass) }
@@ -579,7 +467,7 @@ module RASN1
     end
 
     # Give a (nested) element from its name
-    # @param [String, Symbol] name
+    # @param name [String, Symbol]
     # @return [Model, Types::Base, nil]
     def by_name(name)
       elt = self[name]
@@ -597,9 +485,11 @@ module RASN1
 
     private
 
+    # @param args [Hash]
+    # @return [void]
     def generate_root(args)
       opts = args.slice(:name, :explicit, :implicit, :optional, :class, :default, :constructed, :tag_value)
-      root = self.class.class_eval { @root }
+      root = self.class.root
       root_options = self.class.options || {}
       root_options.merge!(opts)
       @root_name = args[:name] || root.name
@@ -607,6 +497,9 @@ module RASN1
       @elements[@root_name] = @root
     end
 
+    # @param elt [BaseElem, ModelElem,WrapElem]
+    # @param opts [Hash]
+    # @return[Types::Base,Model,Wrapper]
     def generate_element(elt, opts={})
       case elt
       when BaseElem
@@ -619,6 +512,9 @@ module RASN1
       end
     end
 
+    # @param elt [WrapElem]
+    # @param opts [Hash]
+    # @return[Wrapper]
     def generate_wrapper_element(elt, opts)
       wrapped = elt.element.is_a?(ModelElem) ? elt.element.klass : generate_element(elt.element)
       options = elt.options.merge(opts)
@@ -629,6 +525,9 @@ module RASN1
       wrapper
     end
 
+    # @param elt [BaseElem]
+    # @param opts [Hash]
+    # @return[Types::Base]
     def generate_base_element(elt, opts)
       element = elt.proc.call(opts)
       return element if elt.content.nil?
@@ -643,6 +542,8 @@ module RASN1
     # @author sdaubert
     # @author lemontree55
     # @author adfoster-r7
+    # @param element [Model, Types::Base, Wrapper,nil]
+    # @return [Hash]
     def private_to_h(element=nil) # rubocop:disable Metrics/CyclomaticComplexity
       my_element = element || root
       value = case my_element
@@ -666,6 +567,8 @@ module RASN1
       end
     end
 
+    # @param elt [Model]
+    # @return [Hash]
     def model_to_h(elt)
       hsh = elt.to_h
       if root.is_a?(Types::Choice)
@@ -675,6 +578,8 @@ module RASN1
       end
     end
 
+    # @param elt [Types::SequenceOf]
+    # @return [Array<Hash>]
     def sequence_of_to_h(elt)
       if elt.of_type < Model
         elt.value&.map { |el| el.to_h.values.first }
@@ -683,6 +588,8 @@ module RASN1
       end
     end
 
+    # @param seq [Types::Sequence]
+    # @return [Hash]
     def sequence_to_h(seq)
       ary = seq.value&.map do |el|
         next if el.optional? && el.value.nil?
@@ -699,6 +606,9 @@ module RASN1
       ary.compact.to_h
     end
 
+    # @param elt [Types::Choice]
+    # @return [Hash]
+    # @raise [ChoiceError] no chosen element
     def choice_to_h(elt)
       raise ChoiceError.new(elt) if elt.chosen.nil?
 
@@ -706,10 +616,14 @@ module RASN1
       { chosen.name => private_to_h(chosen) }
     end
 
+    # @param key [String,Symbol]
+    # @return [Symbol]
     def unwrap_keyname(key)
       key.to_s.delete_suffix('_wrapper').to_sym
     end
 
+    # @param wrap [Wrapper]
+    # @return [Hash]
     def wrapper_to_h(wrap)
       el = wrap.element
       case el