maxcube-client 0.4.1 → 0.5.0

data/lib/maxcube/messages/parser.rb

@@ -2,9 +2,27 @@ require_relative 'handler'
 
 module MaxCube
   module Messages
+    # This module provides methods connected to message parsing only
+    # (i.e. direction Cube -> client).
     module Parser
       include Handler
 
+      # This method should be used each time any +IO+ is read,
+      # which is very useful for parsing purposes.
+      # It contains optional implicit conversion
+      # of binary string data of certain length into integers
+      # (using {PACK_FORMAT})
+      # or into any other explicit format that String#unpack understands.
+      # In addition, it checks whether the read operation succeeded
+      # and raises an exception if not
+      # (this is useful when parsing a message of a specified format).
+      # @param count [Integer] number of bytes to read.
+      #   0 causes to read until EOF.
+      # @param unpack [Boolean, String] if +true+
+      #   it does implicit conversion to integer;
+      #   if String, the format is passed to String#unpack as is.
+      # @return [String, Integer] read data; its type depends on +unpack+.
+      # @raise [IOError] if reading failed (incl. that nothing was read).
       def read(count = 0, unpack = false)
         str = if count.zero?
                 @io.read
@@ -18,8 +36,21 @@ module MaxCube
         str.unpack1(unpack)
       end
 
-      def parse_msg_body(body, hash, parser_type_str)
-        method_str = "parse_#{parser_type_str}_#{@msg_type.downcase}"
+      # Parses message body, i.e. at least message type is already decoded.
+      # It dynamically calls method corresponding to message and parser type.
+      # If message type is not implemented yet, read data is stored as is.
+      # It transforms unhandled +IOError+ exceptions
+      # (probably raised from {#read}) to {InvalidMessageBody}.
+      # @param body [String] message body to be parsed.
+      # @param hash [Hash] hash to store parsed data into.
+      #   It should already contain contents of message head.
+      #   Hash will be modified.
+      # @param parser_type [String] parser type contained in method identifiers.
+      # @return [Hash, nil] resulting hash, or +nil+ in case
+      #   the message type is not implemented yet.
+      # @raise [InvalidMessageBody] if +IOError+ catched.
+      def parse_msg_body(body, hash, parser_type)
+        method_str = "parse_#{parser_type}_#{@msg_type.downcase}"
         if respond_to?(method_str, true)
           return hash.merge!(send(method_str, body))
         end

data/lib/maxcube/messages/serializer.rb

@@ -2,19 +2,43 @@ require_relative 'handler'
 
 module MaxCube
   module Messages
+    # This module provides methods connected to message serializing only
+    # (i.e. direction client -> Cube).
     module Serializer
       include Handler
 
-      def serialize(*args, esize: 0, size: 0, ocount: 0)
+      # Serializes input +args+ into String,
+      # with optional implicit conversion from integer into binary string
+      # (using {PACK_FORMAT}).
+      # In any case, String elements are serialized as they are.
+      # @param args [Array<String, Integer>] input arguments.
+      # @param esize [Integer] output size of binary string
+      #   of each converted integer element.
+      #   Nonzero value enables conversion of integers into binary strings.
+      #   This value is sufficient alone, but it is not suitable in cases
+      #   when more elements are to be grouped together -
+      #   +esize+ is in interval (0,1) in this case.
+      #   Output count (+count+) is assumed to be the same with input count.
+      # @param size [Integer] total output size of binary string
+      #   of converted integer elements.
+      #   Nonzero value enables conversion of integers into binary strings.
+      #   This value is sufficient alone
+      #   if output count is same with input count.
+      # @param count [Integer] output count of converted integer elements.
+      #   +size+ must be specified. 0 means same count as input count.
+      #   It is suitable for cases when input and output counts differ.
+      # @return [String] serialized +args+. If conversion was enabled,
+      #   it may contain binary data.
+      def serialize(*args, esize: 0, size: 0, count: 0)
         return args.join if size.zero? && esize.zero?
 
-        ocount, subcount, subsize = serialize_bounds(args,
-                                                     esize: esize,
-                                                     size: size,
-                                                     ocount: ocount)
+        count, subcount, subsize = serialize_bounds(args,
+                                                    esize: esize,
+                                                    size: size,
+                                                    count: count)
         str = ''
         args.reverse!
-        ocount.times do
+        count.times do
           str << args.pop while args.last.is_a?(String)
           substr = args.pop(subcount).pack(PACK_FORMAT[subsize])
           substr = substr[1..-1] if subsize == 3
@@ -25,12 +49,26 @@ module MaxCube
         str
       end
 
-      def write(*args, esize: 0, size: 0, ocount: 0)
-        @io.write(serialize(*args, esize: esize, size: size, ocount: ocount))
+      # It serializes +args+ with {#serialize}
+      # and writes it into internal +IO+ variable.
+      def write(*args, esize: 0, size: 0, count: 0)
+        @io.write(serialize(*args, esize: esize, size: size, count: count))
       end
 
-      def serialize_hash_body(hash, serializer_type_str)
-        method_str = "serialize_#{serializer_type_str}_#{@msg_type.downcase}"
+      # Serializes message body,
+      # i.e. message head has been already serialized.
+      # It dynamically calls method corresponding to message
+      # and serializer type.
+      # If message type is not implemented yet,
+      # it is unclear how to serialize the +hash+,
+      # so an exception is raised.
+      # @param hash [Hash] hash with message contents to serialize.
+      # @param serializer_type [String] serializer type
+      #   contained in method identifiers.
+      # @return [String] resulting message string.
+      # @raise [InvalidMessageType] if the message type is not implemented yet.
+      def serialize_hash_body(hash, serializer_type)
+        method_str = "serialize_#{serializer_type}_#{@msg_type.downcase}"
         return send(method_str, hash) if respond_to?(method_str, true)
         raise InvalidMessageType
           .new(@msg_type, 'serialization of message type' \
@@ -39,20 +77,30 @@ module MaxCube
 
       private
 
-      def serialize_bounds(args, esize: 0, size: 0, ocount: 0)
+      # Helper method called by {#serialize}
+      # that evaluates necessary counts and sizes
+      # for purposes of integer elements conversion in loop.
+      # @return [[count, subcount, subsize]]
+      #   +count+ is output count of converted elements
+      #   (0 if +args+ array is empty),
+      #   +subcount+ is number of elements
+      #   to be converted together in each step,
+      #   +subsize+ is output size in bytes
+      #   to which to convert elements in each step into.
+      def serialize_bounds(args, esize: 0, size: 0, count: 0)
         icount = args.size - args.count { |a| a.is_a?(String) }
         return 0 if icount.zero?
         if esize.zero?
-          ocount = icount if ocount.zero?
-          subsize = size / ocount
+          count = icount if count.zero?
+          subsize = size / count
         else
           size = icount * esize
-          ocount = size / esize
+          count = size / esize
           subsize = esize
         end
-        subcount = icount / ocount
+        subcount = icount / count
 
-        [ocount, subcount, subsize]
+        [count, subcount, subsize]
       end
     end
   end

data/lib/maxcube/messages/tcp.rb

@@ -2,16 +2,20 @@ require 'maxcube/messages'
 
 module MaxCube
   module Messages
-    # Structure of message:
-    # * Starts with single letter followed by ':'
-    # * Ends with "\r\n"
-    # Example (unencoded):
-    # X:message\r\n
-    # As all messages are being split by "\r\n",
+    # This module contains classes aimed onto TCP messages of Cube protocol.
+    #
+    # Structure of every TCP Cube message:
+    # * Starts with single letter followed by +:+
+    # * Ends with +\\r\\n+
+    # * Except of the end, it contains only printable characters.
+    # As all messages are being split by +\\r\\n+,
     # it does not occur in single message processing,
     # only in raw data processing.
+    # @example
+    #   X:message\r\n
     module TCP
-      # Without "\r\n", with it it is 1900
+      # Maximum length of TCP Cube message
+      # without +\\r\\n+ (with it it would be 1900)
       MSG_MAX_LEN = 1898
     end
   end

data/lib/maxcube/messages/tcp/handler.rb

@@ -4,34 +4,60 @@ require 'maxcube/messages/handler'
 module MaxCube
   module Messages
     module TCP
+      # Extends {Messages::Handler} of routines connected to TCP Cube messages.
       module Handler
         include Messages::Handler
 
+        # Validates whether message satisfies {MSG_MAX_LEN}.
+        # @param msg [String] input message.
+        # @return [Boolean] whether message length is valid.
         def valid_tcp_msg_length(msg)
           msg.length.between?(2, MSG_MAX_LEN)
         end
 
+        # As {#valid_tcp_msg_length}, but raises exception
+        # if message length is not valid.
+        # @param msg [String] input message.
+        # @return [Integer] message length.
+        # @raise [InvalidMessageLength] if message length is not valid.
         def check_tcp_msg_length(msg)
           raise InvalidMessageLength unless valid_tcp_msg_length(msg)
           msg.length
         end
 
+        # Validates whether message satisfies TCP Cube format (see {TCP}).
+        # @param msg [String] input message.
+        # @return [Boolean] whether message format is valid.
         def valid_tcp_msg_format(msg)
           msg =~ /\A[[:alpha:]]:[[:print:]]*\z/
         end
 
+        # As {#valid_tcp_msg_format}, but raises exception
+        # if message format is not valid.
+        # @param msg [String] input message.
+        # @return [String] input message.
+        # @raise [InvalidMessageFormat] if message format is not valid.
         def check_tcp_msg_format(msg)
           raise InvalidMessageFormat unless valid_tcp_msg_format(msg)
           msg
         end
 
-        # Check single message validity, already without "\r\n" at the end
+        # Validates whether given message is a valid TCP Cube message.
+        # It calls {#valid_tcp_msg_length},
+        # {#valid_tcp_msg_format} and {#valid_msg}.
+        # @param msg [String] input message.
+        # @return [Boolean] whether message is valid.
         def valid_tcp_msg(msg)
           valid_tcp_msg_length(msg) &&
             valid_tcp_msg_format(msg) &&
             valid_msg(msg)
         end
 
+        # As {#valid_tcp_msg}, but raises exception if message is not valid.
+        # It calls {#check_tcp_msg_length},
+        # {#check_tcp_msg_format} and {#check_msg}.
+        # @param msg [String] input message.
+        # @return [String] input message.
         def check_tcp_msg(msg)
           check_tcp_msg_length(msg)
           check_tcp_msg_format(msg)
@@ -39,28 +65,50 @@ module MaxCube
           msg
         end
 
+        # Validates whether given hash with message contents
+        # is valid for TCP Cube messaging purposes.
+        # It only calls {#valid_hash}.
+        # @param hash [Hash] input hash.
+        # @return [Boolean] whether hash is valid.
         def valid_tcp_hash(hash)
           valid_hash(hash)
         end
 
+        # As {#valid_tcp_hash}, but raises exception if hash is not valid.
+        # It only calls {#check_hash}.
+        # @param hash [Hash] input hash.
+        # @return [Hash] input hash.
         def check_tcp_hash(hash)
           check_hash(hash)
           hash
         end
 
+        # Validates whether input raw data
+        # containing multiple separated TCP Cube messages is valid.
+        # It only checks +\\r\\\n+ stuff.
+        # It does not validate data type ({#valid_data_type}), yet?
+        # It does not validate particular messages.
+        # @param raw_data [String] input data with multiple separated messages.
+        # @return [Boolean] whether input data is valid.
         def valid_tcp_data(raw_data)
           return true if raw_data.empty?
           raw_data[0..1] != "\r\n" && raw_data.chars.last(2).join == "\r\n"
         end
 
+        # As {#valid_tcp_data}, but raises exception if raw data is not valid.
+        # @param raw_data [String] input data with multiple separated messages.
+        # @return [String] input data.
+        # @raise [InvalidMessageFormat] if input data is not valid.
         def check_tcp_data(raw_data)
-          # check_data_type(raw_data)
           raise InvalidMessageFormat unless valid_tcp_data(raw_data)
           raw_data
         end
 
         private
 
+        # Tells how to get message type from a message.
+        # @param msg [String] input message.
+        # @return [String] message type.
         def msg_msg_type(msg)
           msg.chr
         end

data/lib/maxcube/messages/tcp/parser.rb

@@ -4,35 +4,36 @@ require 'maxcube/messages/parser'
 module MaxCube
   module Messages
     module TCP
+      # Extends {Messages::Parser} and {TCP::Handler} of routines
+      # connected to TCP Cube messages parsing.
       class Parser
-        include Handler
+        include TCP::Handler
         include Messages::Parser
 
-        %w[a c f h l m n s].each { |f| require_relative 'type/' << f }
+        %w[a c f h l m n s].each do |f|
+          require_relative 'type/' << f
+          include const_get('Message' << f.upcase)
+        end
 
+        # Known message types in the direction Cube -> client.
         MSG_TYPES = %w[H F L C M N A E D b g j p o v w S].freeze
 
-        include MessageA
-        include MessageC
-        include MessageF
-        include MessageH
-        include MessageL
-        include MessageM
-        include MessageN
-        include MessageS
-
-        # Process set of messages - raw data separated by "\r\n"
-        # @param [String, #read] raw data from a Cube
+        # Processes set of messages - raw data separated by +\\r\\n+.
+        # Calls {#check_tcp_data}
+        # and maps {#parse_tcp_msg} on each message.
+        # @param raw_data [String] raw data from a Cube
         # @return [Array<Hash>] particular message contents
         def parse_tcp_data(raw_data)
           check_tcp_data(raw_data)
           raw_data.split("\r\n").map(&method(:parse_tcp_msg))
         end
 
-        # Parse single message already without "\r\n"
-        # @param [String, #read] single message data without "\r\n"
-        # @return [Hash] particular message parts separated into hash,
-        #                which should be human readable
+        # Parses single message already without +\\r\\n+.
+        # Subsequently calls {#check_tcp_msg},
+        # {#parse_msg_body}
+        # and {#check_tcp_hash}.
+        # @param msg [String] input message (without +\\r\\n+).
+        # @return [Hash] particular message contents separated into hash.
         def parse_tcp_msg(msg)
           check_tcp_msg(msg)
           body = msg.split(':')[1] || ''

data/lib/maxcube/messages/tcp/serializer.rb

@@ -4,38 +4,37 @@ require 'maxcube/messages/serializer'
 module MaxCube
   module Messages
     module TCP
+      # Extends {Messages::Serializer} and {TCP::Handler} of routines
+      # connected to TCP Cube messages serializing.
       class Serializer
-        include Handler
+        include TCP::Handler
         include Messages::Serializer
 
-        %w[a c f l m n q s t u z].each { |f| require_relative 'type/' << f }
+        %w[a c f l m n q s t u z].each do |f|
+          require_relative 'type/' << f
+          include const_get('Message' << f.upcase)
+        end
 
+        # Known message types in the direction client -> Cube.
         MSG_TYPES = %w[u i s m n x g q e d B G J P O V W a r t l c v f z].freeze
 
-        include MessageA
-        include MessageC
-        include MessageF
-        include MessageL
-        include MessageM
-        include MessageN
-        include MessageQ
-        include MessageS
-        include MessageT
-        include MessageU
-        include MessageZ
-
-        # Send set of messages separated by "\r\n"
-        # @param [Array<Hash>] particular message contents
-        # @return [String] raw data for a Cube
+        # Generates set of messages separated by +\\r\\n+.
+        # Calls {#check_tcp_data}
+        # and maps {#serialize_tcp_hash} on each hash.
+        # @param hashes [Array<Hash>] particular message contents.
+        # @return [String] raw data for a Cube.
         def serialize_tcp_hashes(hashes)
           raw_data = hashes.map(&method(:serialize_tcp_hash)).join
           check_tcp_data(raw_data)
         end
 
-        # Serialize data from hash into message with "\r\n" at the end
-        # @param [Hash, #read] particular human readable message parts
-        #                      (it is assumed to contain valid data)
-        # @return [String] single message data with "\r\n" at the end
+        # Serializes data from a single hash
+        # into TCP Cube message with +\\r\\n+ at the end.
+        # Subsequently calls {#check_tcp_hash},
+        # {#serialize_hash_body}
+        # and {#check_tcp_msg}.
+        # @param hash [Hash] particular message contents separated into hash.
+        # @return [String] output message (with +\\r\\n+).
         def serialize_tcp_hash(hash)
           check_tcp_hash(hash)
           msg = "#{@msg_type}:" << serialize_hash_body(hash, 'tcp')

data/lib/maxcube/messages/tcp/type/a.rb

@@ -3,12 +3,12 @@ module MaxCube
   module Messages
     module TCP
       class Parser
+        # Acknowledgement message to previous command
+        # e.g. factory reset (a), delete a device (t), wake up (z).
+        # Does not contain any data.
         module MessageA
           private
 
-          # Acknowledgement message to previous command
-          # e.g. factory reset (a), delete a device (t), wake up (z)
-          # Ignore all contents of the message
           def parse_tcp_a(_body)
             {}
           end
@@ -16,12 +16,12 @@ module MaxCube
       end
 
       class Serializer
+        # Factory reset command.
+        # Does not contain any data.
+        # Acknowledgement (A) follows.
         module MessageA
           private
 
-          # Factory reset command
-          # Does not contain any data
-          # Acknowledgement (A) follows
           def serialize_tcp_a(_hash)
             ''
           end