slow_blink 0.0.4 → 0.0.5

data/lib/slow_blink/message/group.rb

@@ -19,142 +19,281 @@
 
 module SlowBlink::Message
 
-    class StaticGroup
-        
-        def self.implements
-            @implements
-        end
+    # A Group may form a complete message or be nested as a {DynamicGroup}
+    class Group
 
+        # @return [Hash<Field>] group fields
         def self.fields
             @fields
         end
 
-        def self.opt?
-            @opt
-        end
-
+        # @return [Integer,nil] group identifier
         def self.id
             @id
         end
 
+        # @return [String] name of group
         def self.name
             @name
         end
 
-        def self.from_compact!(input)
-            if @opt
-                if input.getPresent!
-                    fields = {}
-                    @fields.each do |f|                    
-                        fields[f.name] = f.from_compact!(input)                            
-                    end
-                    self.new(fields)
-                else
-                    self.new(nil)
-                end
+        # @param input [String] Blink compact form
+        # @param stack [Array] used to measure depth of recursion 
+        # @return [Group, nil]
+        # @raise [Error] recursion depth limit
+        def self.from_compact!(input, stack)            
+
+            fields = {}
+            extensions = []
+
+            if stack.size < @maxRecursion
+                stack << self
             else
-                fields = {}
-                @fields.each do |f|
-                    fields[f.name] = f.from_compact!(input)                        
-                end                
-                self.new(fields)
-            end            
+                raise Error.new "stack limit"
+            end
+            
+            @fields.each do |fn, fd|
+                fields[fn] = fd.from_compact!(input, stack)
+            end
+
+            if input.size > 0                
+                expected = input.getU32!                
+                while extensions.size != expected do
+                    extensions << @extensionObject.from_compact!(input, stack)                    
+                end
+            end
+            
+            if input.size != 0
+                raise Error.new "extra bytes at end of group after extensions"
+            end
+
+            group = self.new(fields)
+
+            extensions.each do |e|
+                group.extension << group
+            end
+
+            stack.pop
+
+            group
+               
         end
 
+        # @return [Array<Group>] group extension objects
+        attr_reader :extension
+
+        # set a field value
+        #
+        # @param name [String] name of field
+        # @param value [Object]
+        # @raise [IndexError, TypeError]
         def []=(name, value)
             if @value[name]
                 @value[name].set(value)
+                self
             else
-                raise "field #{name} is not defined in this group"
-            end                    
+                raise IndexError.new "field #{name} is not defined in this group"            
+            end
         end
 
-        def [](name)
+        # Get a field value
+        #
+        # @param name [String] name of field
+        # @return [Object]
+        # @raise [IndexError, TypeError]
+        def [](name)            
             if @value[name]
-                @value[name].get
+                @value[name].get                
             else
-                raise "field #{name} is not defined in this group"
-            end
+                raise IndexError.new "field #{name} is not defined in this group"
+            end            
         end
 
-        def set(value)            
-            if value
-                self.class.fields.each do |f|
-                    @value[f.name].set(value[f.name])
-                    @empty = false
-                end                    
-            elsif self.class.opt?                
-                @empty = true
+        # Get this group
+        # @return [Group] self
+        def get
+            self
+        end
+
+        # Get the value hash directly
+        # @return [Hash]
+        def fields
+            @value
+        end
+
+        # Set the contents of this group
+        #
+        # This method accepts one of two options:
+        #
+        # First option is a Hash of fields. Values may be literals to be set to fields objects,
+        # or instances of the field objects to completely replace existing field objects
+        #
+        # Second option is a {Group} where #{Group#fields} will be used in the same manner as the first option.
+        #
+        # @param value [Hash, Group] fields to set
+        # @raise [IndexError, TypeError]
+        def set(value)
+            if value.kind_of? Hash
+                value.each do |fn, fv|
+                    if @value[fn]
+                        # replace entire field
+                        if fv.is_a? @value[fn].class
+                            @value[fn] = fv
+                        # set value of field
+                        else
+                            @value[fn].set(fv)
+                        end
+                    else
+                        raise IndexError.new "field '#{fn}' is unknown"
+                    end
+                end
+            # replace @value with value from another instance of self.class
+            elsif value.is_a? self.class
+                @value = value.fields.to_h
             else
-                raise "this group cannot be NULL"
+                raise TypeError.new "expecting a Hash or a StaticGroup instance"
             end
         end
 
-        def get
-            @value
+        # Create a Group
+        #
+        # @param fields [Hash] associative array of slow blink objects or native values
+        def initialize(fields={})
+            @extension = []            
+            @fields = self.class.fields
+            @value = {}
+            self.class.fields.each do |fn, fd|
+                @value[fn] = fd.new(nil)
+            end            
+            set(fields)        
+        end
+        
+        def encode_compact
+            if self.class.id
+                to_compact("")            
+            else
+                raise Error.new "cannot encode a group without an ID"
+            end
         end
 
-        def initialize(fields)
-            empty = false
-            @value = self.class.fields.inject({}) do |value, f|                        
-                value[f.name] = f.new(nil)
-            end                            
-            if fields
-                set(fields.to_h)            
+        def to_compact(out)            
+            group = "".putU64(self.class.id)
+            @value.each do |fn, fv|
+                fv.to_compact(group)
             end
+            if @extension.size > 0
+                group.putU32(@extension.size)
+                @extension.each do |e|
+                    #if e.is_a? @extensionObject
+                        e.to_compact(group)
+                    #else
+                     #   raise Error.new "cannot convert unknown extension object to compact form"
+                    #end
+                end
+            end
+            out.putU32(group.size)
+            out << group            
         end
 
-        def fields
-            @value
+    end
+
+    # A StaticGroup is a kind of {Group} that can only exist as the contents of a {Field}
+    class StaticGroup < Group
+
+        # @note optionality affects how instances of this type are encoded
+        #
+        # @return [true,false] is optional
+        def self.opt?
+            @opt
         end
+    
+        # @param input [String] Blink compact form
+        # @param stack [Array] used to measure depth of recursion 
+        # @return [Group, nil]
+        # @raise [Error] recursion depth limit
+        def self.from_compact!(input, stack)
 
-        def to_compact(out)
-            if @value
-                if self.class.opt?
-                    out.putPresent
-                    self.class.fields.each do |f|
-                        @value[f.name].to_compact(out)
-                    end
-                    out                    
-                else
-                    self.class.fields.each do |f|
-                        @value[f.name].to_compact(out)
-                    end
-                    out                                        
+            if stack.size < @maxRecursion
+                stack << self
+            else
+                raise Error.new "stack limit"   
+            end
+        
+            if @opt
+                present = input.getPresent
+            else
+                present = true
+            end
+            if present
+                fields = {}
+                @fields.each do |fn, fd|
+                    fields[fn] = fd.from_compact!(input, stack)
                 end
+                result = self.new(fields)            
             else
-                out.putPresent(false)
+                nil
             end
+
+            stack.pop
+            result
+            
         end
 
-        def to_h
-            @value
+        # @note {StaticGroup} cannot have extensions therefore this method will raise a NoMethodError
+        # @raise [NoMethodError]
+        def extension
+            raise NoMethodError.new "static groups cannot have extensions"
+        end
+        
+        def to_compact(out)
+            if self.class.opt?
+                out.putPresent
+            end
+            @value.each do |fn, fv|
+                fv.to_compact(out)
+            end
+            out            
         end
 
     end
 
+    # A DynamicGroup has a {Group} which has a {Group.id} that appears in {DynamicGroup.permitted} list
     class DynamicGroup
-    
+
+        # @return [Hash] Hash of all groups referenced by name
         def self.groups
             @groups
         end
 
+        # @return [Hash] Hash of all tagged groups referenced by ID
+        def self.taggedGroups
+            @taggedGroups
+        end
+
+        # @return [Array<Integer>] Array of group IDs that can be encapsulated by this DynamicGroup
         def self.permitted
             @permitted
         end
 
-        def self.opt?
-            @opt
-        end
+        # @param input [String] Blink compact form
+        # @param stack [Array] used to measure depth of recursion 
+        # @return [Group, nil]
+        # @raise [Error] recursion depth limit
+        def self.from_compact!(input, stack)
 
-        def self.from_compact!(input)
+            if stack.size < @maxRecursion
+                stack << self
+            else
+                raise Error.new "stack limit"
+            end
+        
             buf = input.getBinary!
             if buf.size > 0
                 id = buf.getU64!
-                group = @groups[id]
+                group = @taggedGroups[id]
                 if group
                     if @permitted.include? group.id
-                        self.new(group.from_compact!(buf))
+                        result = self.new(group.from_compact!(buf, stack))
                     else
                         raise Error.new "W15: Group is known but unexpected"
                     end
@@ -162,84 +301,51 @@ module SlowBlink::Message
                     raise Error.new "W2: Group id #{group.id} is unknown"
                 end
             else
-                if self == ModelInstance
-                    raise Error.new "W1: Top level group cannot be null"
-                elsif @opt
-                    self.new(nil)
-                else
-                    raise Error.new "W5: Value cannot be null"
-                end                
+                raise Error.new "W5: Value cannot be null"                
             end
-        end
 
-        def []=(name, value)
-            if @value
-                @value[name] = value
-            else
-                raise "undefined dynamic group"
-            end
-        end
+            stack.pop
+            result
 
-        def [](name)
-            if @value
-                @value[name]
-            else
-                raise "undefined dynamic group"
-            end
         end
 
-        def set(value)
-            if value
-                if self.class.groups.values.include? value.class
-                    if self.class.permitted.include? value.class.id
-                        @value = value
-                    else
-                        raise "group is not a permitted group"
-                    end
-                else
-                    raise "value is not a group instance"
+        def set(value)        
+            # is group one of the groups we understand?
+            if self.class.taggedGroups.values.detect{|g| value.is_a? g} 
+                # is this group permitted?
+                if self.class.permitted.include? value.class.id
+                    @value = value
+                else                        
+                    raise "group valid but not expected"
                 end
-            elsif self.class.opt?
-                @value = nil
+            # native values
+            elsif value.kind_of? Hash
+                @value.set(value)
             else
                 raise
-            end        
+            end
         end
 
+        # @return [Group] contained group
         def get
-            @value
+            @value.get
         end
 
-        def initialize(value)
-            if value
-                set(value)
-            else
-                @value = nil
-            end
-        end               
+        # Calls {Group#extension}
+        # @return [Array]
+        def extension
+            @value.extension
+        end
 
-        def to_compact(out="")
-            if @value
-                group = @value.to_compact("".putU64(@value.class.id))
-                out.putU32(group.size)
-                out << group                    
-            else
-                out.putU32(nil)
-            end
+        # @param value [Group, Hash]
+        def initialize(value)
+            set(value)        
         end
 
-        # @api user
-        #
-        # Encode {Group} as Blink compact form
-        #
-        # @return [String]
-        #
-        def encode_compact
-            to_compact
-        end        
+        def to_compact(out)
+            @value.to_compact(out)                                    
+        end
 
     end
 
-    
-
 end

data/lib/slow_blink/message/integer.rb

@@ -21,70 +21,66 @@ module SlowBlink::Message
 
     class INTEGER
 
-        def self.name
-            @name
-        end
-
-        def self.opt?
-            @opt
-        end
-
+        # @param value [Integer]
+        # @return [true,false] integer value is within permitted range
         def self.in_range?(value)
             @type.class::RANGE.cover? value
         end
 
+        # @return [Integer]
+        def get
+            @value
+        end
+        
+        # Set an Integer value
+        # @param value [Integer]
+        # @raise [RangeError] value is outside of range according to {::in_range?}
+        # @raise [TypeError]
         def set(value)
-            if value
-                if value.kind_of? Integer
-                    if self.class.in_range?(value)
-                        @value = value.to_i
-                    else
-                        raise Error.new "value out of range"
-                    end
+            if value.kind_of? Integer
+                if self.class.in_range?(value)
+                    @value = value.to_i
                 else
-                    raise Error.new "value must be an integer"
+                    raise RangeError.new
                 end
-            elsif self.class.opt?
-                @value = nil
             else
-                raise Error.new "value unacceptable"
-            end
-        end
-        
-        def get
-            @value
+                raise TypeError.new "value must be an integer"
+            end            
         end
 
-        # @param value [Integer, nil]
-        def initialize(value)
-            if value
-                set(value)
-            else
-                @value = nil
-            end
+        # @note calls {#set}(value)
+        def initialize(value)        
+            set(value)
         end
 
-        
     end
 
     class U8 < INTEGER
 
-    
-        def self.from_compact!(input)
-            self.new(input.getU8!)
+        def self.from_compact!(input, stack)
+            value = input.getU8!
+            if value
+                self.new(value)
+            else
+                value
+            end
         end
 
         def to_compact(out)
             out.putU8(@value)
-        end
-        
+        end        
         
     end
 
     class U16 < INTEGER
 
-        def self.from_compact!(input)
-            self.new(input.getU16!)
+        def self.from_compact!(input, stack)
+            value = input.getU16!
+            if value
+                self.new(value)
+            else
+                value
+            end
         end
     
         def to_compact(out)
@@ -95,8 +91,13 @@ module SlowBlink::Message
 
     class U32 < INTEGER
 
-        def self.from_compact!(input)
-            self.new(input.getU32!)
+        def self.from_compact!(input, stack)
+            value = input.getU32!
+            if value
+                self.new(value)
+            else
+                value
+            end
         end
 
         def to_compact(out)
@@ -107,8 +108,13 @@ module SlowBlink::Message
 
     class U64 < INTEGER
 
-        def self.from_compact!(input)
-            self.new(input.getU64!)
+        def self.from_compact!(input, stack)
+            value = input.getU64!
+            if value
+                self.new(value)
+            else
+                value
+            end
         end
     
         def to_compact(out)
@@ -119,8 +125,13 @@ module SlowBlink::Message
 
     class I8 < INTEGER
 
-        def self.from_compact!(input)
-            self.new(input.getI8!)
+        def self.from_compact!(input, stack)
+            value = input.getI8!
+            if value
+                self.new(value)
+            else
+                value
+            end
         end
     
         def to_compact(out)
@@ -131,8 +142,13 @@ module SlowBlink::Message
 
     class I16 < INTEGER
         
-        def self.from_compact!(input)
-            self.new(input.getI16!)
+        def self.from_compact!(input, stack)
+            value = input.getI16!
+            if value
+                self.new(value)
+            else
+                value
+            end
         end
     
         def to_compact(out)
@@ -143,8 +159,13 @@ module SlowBlink::Message
 
     class I32 < INTEGER
 
-        def self.from_compact!(input)
-            self.new(input.getI32!)
+        def self.from_compact!(input, stack)
+            value = input.getI32!
+            if value
+                self.new(value)
+            else
+                value
+            end
         end
     
         def to_compact(out)
@@ -155,8 +176,13 @@ module SlowBlink::Message
 
     class I64 < INTEGER
 
-        def self.from_compact!(input)
-            self.new(input.getI64!)
+        def self.from_compact!(input, stack)
+            value = input.getI64!
+            if value
+                self.new(value)
+            else
+                value
+            end
         end
     
         def to_compact(out)