rasn1 0.16.2 → 0.17.0

data/lib/rasn1/tracer.rb

@@ -14,40 +14,48 @@ module RASN1
     # @return [Integer]
     attr_accessor :tracing_level
 
+    # @private
+    # Classes to trace
     TRACED_CLASSES = [Types::Any, Types::Choice, Types::Sequence, Types::SequenceOf, Types::Base].freeze
 
-    # @param [IO] io
+    # @param io [IO] io to use to put traces
     def initialize(io)
       @io = io
       @tracing_level = 0
     end
 
     # Puts +msg+ onto {#io}.
-    # @param [String] msg
+    # @param msg [String]
     # @return [void]
     def trace(msg)
       @io.puts(indent << msg)
     end
 
     # Return identation for given +level+. If +nil+, use {#tracing_level}.
-    # @param [Integer,nil] level
+    # @param level [Integer,nil]
     # @return [String]
     def indent(level=nil)
       level ||= @tracing_level
       '  ' * level
     end
+
+    def higher_tracing_level
+      self.tracing_level += 1
+      yield
+      self.tracing_level -= 1
+    end
   end
 
   # Trace RASN1 parsing to +io+.
   # All parsing methods called in block are traced to +io+. Each ASN.1 element is
   # traced in a line showing element's id, its length and its data.
-  # @param [IO] io
+  # @param io [IO]
+  # @return [void]
   # @example
   #   RASN1.trace do
   #     RASN1.parse("\x02\x01\x01")  # puts "INTEGER id: 2 (0x02), len: 1 (0x01), data: 0x01"
   #   end
   #   RASN1.parse("\x01\x01\xff")    # puts nothing onto STDOUT
-  # @return [void]
   def self.trace(io=$stdout)
     @tracer = Tracer.new(io)
     Tracer::TRACED_CLASSES.each(&:start_tracing)
@@ -62,6 +70,7 @@ module RASN1
   end
 
   # @private
+  # @return [Tracer]
   def self.tracer
     @tracer
   end
@@ -71,6 +80,7 @@ module RASN1
       class << self
         # @private
         # Patch {#do_parse} to add tracing ability
+        # @return [void]
         def start_tracing
           alias_method :do_parse_without_tracing, :do_parse
           alias_method :do_parse, :do_parse_with_tracing
@@ -80,6 +90,7 @@ module RASN1
 
         # @private
         # Unpatch {#do_parse} to remove tracing ability
+        # @return [void]
         def stop_tracing
           alias_method :do_parse, :do_parse_without_tracing
           alias_method :do_parse_explicit, :do_parse_explicit_without_tracing
@@ -88,6 +99,7 @@ module RASN1
 
       # @private
       # Parse +der+ with tracing abillity
+      # @!macro do_parse
       # @see #parse!
       def do_parse_with_tracing(der, ber:)
         ret = do_parse_without_tracing(der, ber: ber)
@@ -95,10 +107,13 @@ module RASN1
         ret
       end
 
+      # @private
+      # Delegate with tracing to explicit type to generate sub-value
+      # @param data [String]
+      # @return [void]
+      # @see #parse!
       def do_parse_explicit_with_tracing(data)
-        RASN1.tracer.tracing_level += 1
-        do_parse_explicit_without_tracing(data)
-        RASN1.tracer.tracing_level -= 1
+        RASN1.tracer.higher_tracing_level { do_parse_explicit_without_tracing(data) }
       end
     end
 
@@ -106,6 +121,7 @@ module RASN1
       class << self
         # @private
         # Patch {#parse!} to add tracing ability
+        # @return [void]
         def start_tracing
           alias_method :parse_without_tracing, :parse!
           alias_method :parse!, :parse_with_tracing
@@ -113,6 +129,7 @@ module RASN1
 
         # @private
         # Unpatch {#parse!} to remove tracing ability
+        # @return [void]
         def stop_tracing
           alias_method :parse!, :parse_without_tracing
         end
@@ -120,6 +137,7 @@ module RASN1
 
       # @private
       # Parse +der+ with tracing abillity
+      # @!macro do_parse
       # @see #parse!
       def parse_with_tracing(der, ber: false)
         RASN1.tracer.trace(self.trace)
@@ -131,6 +149,7 @@ module RASN1
       class << self
         # @private
         # Patch {#der_to_value} to add tracing ability
+        # @return [void]
         def start_tracing
           alias_method :der_to_value_without_tracing, :der_to_value
           alias_method :der_to_value, :der_to_value_with_tracing
@@ -138,6 +157,7 @@ module RASN1
 
         # @private
         # Unpatch {#der_to_value} to remove tracing ability
+        # @return [void]
         def stop_tracing
           alias_method :der_to_value, :der_to_value_without_tracing
         end
@@ -145,10 +165,9 @@ module RASN1
 
       # @private
       # der_to_value +der+ with tracing abillity
+      # @!macro do_parse
       def der_to_value_with_tracing(der, ber: false)
-        RASN1.tracer.tracing_level += 1
-        der_to_value_without_tracing(der, ber: ber)
-        RASN1.tracer.tracing_level -= 1
+        RASN1.tracer.higher_tracing_level { der_to_value_without_tracing(der, ber: ber) }
       end
     end
 
@@ -156,6 +175,7 @@ module RASN1
       class << self
         # @private
         # Patch {#der_to_value} to add tracing ability
+        # @return [void]
         def start_tracing
           alias_method :der_to_value_without_tracing, :der_to_value
           alias_method :der_to_value, :der_to_value_with_tracing
@@ -163,6 +183,7 @@ module RASN1
 
         # @private
         # Unpatch {#der_to_value} to remove tracing ability
+        # @return [void]
         def stop_tracing
           alias_method :der_to_value, :der_to_value_without_tracing
         end
@@ -170,10 +191,9 @@ module RASN1
 
       # @private
       # der_to_value +der+ with tracing abillity
+      # @!macro do_parse
       def der_to_value_with_tracing(der, ber: false)
-        RASN1.tracer.tracing_level += 1
-        der_to_value_without_tracing(der, ber: ber)
-        RASN1.tracer.tracing_level -= 1
+        RASN1.tracer.higher_tracing_level { der_to_value_without_tracing(der, ber: ber) }
       end
     end
   end

data/lib/rasn1/types/any.rb

@@ -10,7 +10,24 @@ module RASN1
   module Types
     # ASN.1 ANY: accepts any types
     #
+    # ANY is often used with an {ObjectId} to detect real type.
+    #
+    # On encoding, ANY is replaced by its values (which must be an RASN1 type).
     # If `any#value` is `nil` and Any object is not {#optional?}, `any` will be encoded as a {Null} object.
+    #
+    # @example Parsing with any model
+    #   class AnyModel < RASN1::Model
+    #     sequence :seq,
+    #              content: [objectid(:id), any(:data)]
+    #   end
+    #   model = AnyModel.new
+    #   model.parse!("\x30\x09\x06\x03\x2a\x03\x04\x02\x02\x01\xff")
+    #   model[:id].value    #=> "1.2.3.4"
+    #   model[:data].value  #=> "\x02\x02\x01\xff"
+    #   # As we knwon object with id 1.2.3.4 is an integer, with then parse data as such
+    #   data = RASN1::Types::Integer.new
+    #   data.parse!(model[:data].value)
+    #   data.value          #=> 511
     # @author Sylvain Daubert
     class Any < Base
       # @return [String] DER-formated string
@@ -27,21 +44,22 @@ module RASN1
         end
       end
 
+      # @return [Boolean]
       def can_build?
         value? || !optional?
       end
 
       # Parse a DER string. This method updates object: {#value} will be a DER
       # string.
-      # @param [String] der DER string
-      # @param [Boolean] ber if +true+, accept BER encoding
+      # @param der [String] DER string
+      # @param ber [Boolean] if +true+, accept BER encoding
       # @return [Integer] total number of parsed bytes
       def parse!(der, ber: false)
         total_length, _data = do_parse(der, ber: ber)
         total_length
       end
 
-      # @param [::Integer] level
+      # @param level [::Integer]
       # @return [String]
       def inspect(level=0)
         str = common_inspect(level)
@@ -66,6 +84,7 @@ module RASN1
 
       private
 
+      # @param level [Integer]
       def common_inspect(level)
         lvl = [0, level].max
         str = '  ' * lvl
@@ -77,6 +96,7 @@ module RASN1
       end
 
       # @private
+      # @!macro do_parse
       # @see Types::Base#do_parse
       def do_parse(der, ber: false)
         if der.empty?
@@ -96,6 +116,7 @@ module RASN1
         [total_length, real_value]
       end
 
+      # @return [String]
       def trace_any
         msg_type(no_id: true) << trace_data(value)
       end