slow_blink 0.0.5 → 0.0.6

data/lib/slow_blink/message/group.rb

@@ -1,42 +1,50 @@
-# Copyright (c) 2016 Cameron Harper
+# @license
+#   
+#   Copyright (c) 2016 Cameron Harper
+#     
+#   Permission is hereby granted, free of charge, to any person obtaining a copy of
+#   this software and associated documentation files (the "Software"), to deal in
+#   the Software without restriction, including without limitation the rights to
+#   use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+#   the Software, and to permit persons to whom the Software is furnished to do so,
+#   subject to the following conditions:
+#   
+#   The above copyright notice and this permission notice shall be included in all
+#   copies or substantial portions of the Software.
 # 
-# Permission is hereby granted, free of charge, to any person obtaining a copy of
-# this software and associated documentation files (the "Software"), to deal in
-# the Software without restriction, including without limitation the rights to
-# use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
-# the Software, and to permit persons to whom the Software is furnished to do so,
-# subject to the following conditions:
-#  
-# The above copyright notice and this permission notice shall be included in all
-# copies or substantial portions of the Software.
-# 
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
-# FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
-# COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
-# IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
-# CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+#   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+#   FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+#   COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+#   IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+#   CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 module SlowBlink::Message
 
+    # @abstract
+    #
     # A Group may form a complete message or be nested as a {DynamicGroup}
     class Group
 
+        # @private
         # @return [Hash<Field>] group fields
         def self.fields
             @fields
         end
 
+        # @api user
         # @return [Integer,nil] group identifier
         def self.id
             @id
         end
 
+        # @api user
         # @return [String] name of group
         def self.name
             @name
         end
 
+        # @private
         # @param input [String] Blink compact form
         # @param stack [Array] used to measure depth of recursion 
         # @return [Group, nil]
@@ -49,7 +57,7 @@ module SlowBlink::Message
             if stack.size < @maxRecursion
                 stack << self
             else
-                raise Error.new "stack limit"
+                raise RecursionLimit
             end
             
             @fields.each do |fn, fd|
@@ -57,14 +65,18 @@ module SlowBlink::Message
             end
 
             if input.size > 0                
-                expected = input.getU32!                
-                while extensions.size != expected do
-                    extensions << @extensionObject.from_compact!(input, stack)                    
+                expected = input.getU32!
+                if expected       
+                    while extensions.size != expected do
+                        extensions << @extensionObject.from_compact!(input, stack)                    
+                    end
+                else
+                    raise ExtensionPadding
                 end
             end
             
             if input.size != 0
-                raise Error.new "extra bytes at end of group after extensions"
+                raise ExtensionPadding
             end
 
             group = self.new(fields)
@@ -79,10 +91,12 @@ module SlowBlink::Message
                
         end
 
-        # @return [Array<Group>] group extension objects
+        # @api user
+        # @return [Array<Group>] extension objects
         attr_reader :extension
 
-        # set a field value
+        # @api user
+        # Finds Field by name and calls {Field#set}(value) 
         #
         # @param name [String] name of field
         # @param value [Object]
@@ -90,13 +104,14 @@ module SlowBlink::Message
         def []=(name, value)
             if @value[name]
                 @value[name].set(value)
-                self
             else
                 raise IndexError.new "field #{name} is not defined in this group"            
             end
+            self
         end
 
-        # Get a field value
+        # @api user
+        # Finds Field by name and calls {Field#get}
         #
         # @param name [String] name of field
         # @return [Object]
@@ -110,27 +125,18 @@ module SlowBlink::Message
         end
 
         # Get this group
-        # @return [Group] self
+        # @return [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
+        # @overload set(value)
+        #   @param value [Hash{String=>Field,Numeric,String,Time,nil}] Hash of {Field} objects or literal values
+        # @overload set(value)
+        #   @param value [Group] a Hash of {Field} objects will be extracted from a Group object by calling {Group#fields}
+        # @return [self]
         # @raise [IndexError, TypeError]
         def set(value)
             if value.kind_of? Hash
@@ -153,11 +159,14 @@ module SlowBlink::Message
             else
                 raise TypeError.new "expecting a Hash or a StaticGroup instance"
             end
+            self
         end
 
+        # @api user
         # Create a Group
         #
-        # @param fields [Hash] associative array of slow blink objects or native values
+        # @note calls {#set}(fields)
+        # @param fields [Hash]
         def initialize(fields={})
             @extension = []            
             @fields = self.class.fields
@@ -167,15 +176,17 @@ module SlowBlink::Message
             end            
             set(fields)        
         end
-        
+
+        # @return [String] Blink Protocol compact form
         def encode_compact
             if self.class.id
                 to_compact("")            
             else
-                raise Error.new "cannot encode a group without an ID"
+                raise UntaggedGroup.new "cannot encode a group without an ID"
             end
         end
 
+        # @private
         def to_compact(out)            
             group = "".putU64(self.class.id)
             @value.each do |fn, fv|
@@ -187,7 +198,7 @@ module SlowBlink::Message
                     #if e.is_a? @extensionObject
                         e.to_compact(group)
                     #else
-                     #   raise Error.new "cannot convert unknown extension object to compact form"
+                     #   raise EncodingError.new "cannot convert unknown extension object to compact form"
                     #end
                 end
             end
@@ -195,18 +206,31 @@ module SlowBlink::Message
             out << group            
         end
 
+        protected
+
+            # Get the value hash directly
+            # @return [Hash{String => Field}]
+            def fields
+                @value
+            end
+
     end
 
+    # @abstract
+    #
     # A StaticGroup is a kind of {Group} that can only exist as the contents of a {Field}
     class StaticGroup < Group
 
+        # @private
+        #
         # @note optionality affects how instances of this type are encoded
         #
         # @return [true,false] is optional
         def self.opt?
             @opt
         end
-    
+
+        # @private
         # @param input [String] Blink compact form
         # @param stack [Array] used to measure depth of recursion 
         # @return [Group, nil]
@@ -216,7 +240,7 @@ module SlowBlink::Message
             if stack.size < @maxRecursion
                 stack << self
             else
-                raise Error.new "stack limit"   
+                raise RecursionLimit
             end
         
             if @opt
@@ -239,12 +263,13 @@ module SlowBlink::Message
             
         end
 
-        # @note {StaticGroup} cannot have extensions therefore this method will raise a NoMethodError
+        # @note StaticGroup does not have extensions
         # @raise [NoMethodError]
         def extension
-            raise NoMethodError.new "static groups cannot have extensions"
+            raise NoMethodError.new "StaticGroup does not implement #{__method__}"
         end
         
+        # @private
         def to_compact(out)
             if self.class.opt?
                 out.putPresent
@@ -255,8 +280,16 @@ module SlowBlink::Message
             out            
         end
 
+        # @note StaticGroup cannot be encoded as a top level message
+        # @raise [NoMethodError]
+        def encode_compact
+            raise NoMethodError.new "StaticGroup does not inmplement #{__method__}"
+        end
+
     end
 
+    # @abstract
+    #
     # A DynamicGroup has a {Group} which has a {Group.id} that appears in {DynamicGroup.permitted} list
     class DynamicGroup
 
@@ -275,6 +308,7 @@ module SlowBlink::Message
             @permitted
         end
 
+        # @private
         # @param input [String] Blink compact form
         # @param stack [Array] used to measure depth of recursion 
         # @return [Group, nil]
@@ -284,7 +318,7 @@ module SlowBlink::Message
             if stack.size < @maxRecursion
                 stack << self
             else
-                raise Error.new "stack limit"
+                raise RecursionLimit
             end
         
             buf = input.getBinary!
@@ -295,13 +329,13 @@ module SlowBlink::Message
                     if @permitted.include? group.id
                         result = self.new(group.from_compact!(buf, stack))
                     else
-                        raise Error.new "W15: Group is known but unexpected"
+                        raise WeakError15.new "W15: Group is known but unexpected"
                     end
                 else
-                    raise Error.new "W2: Group id #{group.id} is unknown"
+                    raise WeakError2.new "W2: Group id #{group.id} is unknown"
                 end
             else
-                raise Error.new "W5: Value cannot be null"                
+                raise WeakError5.new "W5: Value cannot be null"                
             end
 
             stack.pop
@@ -316,7 +350,7 @@ module SlowBlink::Message
                 if self.class.permitted.include? value.class.id
                     @value = value
                 else                        
-                    raise "group valid but not expected"
+                    raise TypeError.new "group is known but compatible with schema"
                 end
             # native values
             elsif value.kind_of? Hash
@@ -337,11 +371,12 @@ module SlowBlink::Message
             @value.extension
         end
 
-        # @param value [Group, Hash]
+        # @note calls {#set}(value)
         def initialize(value)
             set(value)        
         end
 
+        # @private
         def to_compact(out)
             @value.to_compact(out)                                    
         end

data/lib/slow_blink/message/integer.rb

@@ -1,24 +1,27 @@
-# Copyright (c) 2016 Cameron Harper
+# @license
+#   
+#   Copyright (c) 2016 Cameron Harper
+#    
+#   Permission is hereby granted, free of charge, to any person obtaining a copy of
+#   this software and associated documentation files (the "Software"), to deal in
+#   the Software without restriction, including without limitation the rights to
+#   use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+#   the Software, and to permit persons to whom the Software is furnished to do so,
+#   subject to the following conditions:
+#   
+#   The above copyright notice and this permission notice shall be included in all
+#   copies or substantial portions of the Software.
 # 
-# Permission is hereby granted, free of charge, to any person obtaining a copy of
-# this software and associated documentation files (the "Software"), to deal in
-# the Software without restriction, including without limitation the rights to
-# use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
-# the Software, and to permit persons to whom the Software is furnished to do so,
-# subject to the following conditions:
-#  
-# The above copyright notice and this permission notice shall be included in all
-# copies or substantial portions of the Software.
-# 
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
-# FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
-# COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
-# IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
-# CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+#   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+#   FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+#   COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+#   IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+#   CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 module SlowBlink::Message
 
+    # @abstract
     class INTEGER
 
         # @param value [Integer]
@@ -55,8 +58,10 @@ module SlowBlink::Message
 
     end
 
+    # @abstract
     class U8 < INTEGER
 
+        # @private
         def self.from_compact!(input, stack)
             value = input.getU8!
             if value
@@ -66,14 +71,17 @@ module SlowBlink::Message
             end
         end
 
+        # @private
         def to_compact(out)
             out.putU8(@value)
         end        
         
     end
 
+    # @abstract
     class U16 < INTEGER
 
+        # @private
         def self.from_compact!(input, stack)
             value = input.getU16!
             if value
@@ -82,15 +90,18 @@ module SlowBlink::Message
                 value
             end
         end
-    
+        
+        # @private
         def to_compact(out)
             out.putU16(@value)
         end
         
     end
 
+    # @abstract
     class U32 < INTEGER
 
+        # @private
         def self.from_compact!(input, stack)
             value = input.getU32!
             if value
@@ -100,14 +111,17 @@ module SlowBlink::Message
             end
         end
 
+        # @private
         def to_compact(out)
             out.putU32(@value)
         end
         
     end
 
+    # @abstract
     class U64 < INTEGER
 
+        # @private
         def self.from_compact!(input, stack)
             value = input.getU64!
             if value
@@ -116,15 +130,18 @@ module SlowBlink::Message
                 value
             end
         end
-    
+
+        # @private
         def to_compact(out)
             out.putU64(@value)
         end
         
     end
 
+    # @abstract
     class I8 < INTEGER
 
+        # @private
         def self.from_compact!(input, stack)
             value = input.getI8!
             if value
@@ -133,15 +150,18 @@ module SlowBlink::Message
                 value
             end
         end
-    
+
+        # @private
         def to_compact(out)
             out.putI8(@value)
         end
         
     end
 
+    # @abstract
     class I16 < INTEGER
-        
+
+        # @private
         def self.from_compact!(input, stack)
             value = input.getI16!
             if value
@@ -150,15 +170,18 @@ module SlowBlink::Message
                 value
             end
         end
-    
+
+        # @private
         def to_compact(out)
             out.putI16(@value)
         end
         
     end
 
+    # @abstract
     class I32 < INTEGER
 
+        # @private
         def self.from_compact!(input, stack)
             value = input.getI32!
             if value
@@ -167,15 +190,18 @@ module SlowBlink::Message
                 value
             end
         end
-    
+
+        # @private
         def to_compact(out)
             out.putI32(@value)
         end
         
     end
 
+    # @abstract
     class I64 < INTEGER
 
+        # @private
         def self.from_compact!(input, stack)
             value = input.getI64!
             if value
@@ -184,7 +210,8 @@ module SlowBlink::Message
                 value
             end
         end
-    
+
+        # @private
         def to_compact(out)
             out.putI64(@value)
         end