cmf 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7d43c85f9f8a13b3ae30b2e40bb7a2a3e0e3c6b4e33b66601fe3046b97ac0fff
+  data.tar.gz: 60418ee593ef0ccb2ce0703391c0069416052d3de8197b26502cc2000e065f9e
+SHA512:
+  metadata.gz: 501e955c266464d3511b50baf33cd48b0dc054db355f4ebad9c830549ce2c9c9fbec2bc60dd5ce0ccba13ac415f2fc1f6aa57f4d16a3b22ea5e7dcfe90edf522
+  data.tar.gz: '0597cae488986a886be443187350af2f385dd5e5a7b635942b64e6378d0d49a89051fe24b2fe282bff05be21b02692300e463a4f35b22b16a9d3fe9d617e528f'

data/.gitignore

@@ -0,0 +1,7 @@
+.ruby-version
+.ruby-gemset
+Gemfile.lock
+*.gem
+coverage/
+doc/
+.yardoc/

data/.travis.yml

@@ -0,0 +1,11 @@
+script: "rspec"
+language: "ruby"
+sudo: false
+rvm:
+  - 2.0
+  - 2.1
+  - 2.2
+  - 2.3
+  - 2.4
+  - 2.5
+  - jruby

data/.yardopts

@@ -0,0 +1,7 @@
+--readme README.md
+--markup markdown
+lib/cmf.rb
+lib/cmf/*.rb
+-
+CHANGELOG.md
+LICENSE

data/CHANGELOG.md

@@ -0,0 +1,42 @@
+Change log
+====
+
+This gem follows [Semantic Versioning 2.0.0](http://semver.org/spec/v2.0.0.html).
+All classes and public methods are part of the public API.
+
+1.0.0
+----
+Released on 2018-04-10
+
+All core functionality is implemented:
+
+- `CMF` module methods:
+  - `CMF.build`
+  - `CMF.build_hex`
+  - `CMF.parse`
+  - `CMF.parse_hex`
+- `CMF::Builder` class, with the following methods:
+  - `add`
+  - `add_bool`
+  - `add_bytes`
+  - `add_double` (also aliased as `add_float`)
+  - `add_int`
+  - `add_string`
+  - `reset`
+  - `to_hex`
+  - `to_octet`
+  - `dictionary` read-only attribute
+- `CMF::Parser` class, with the following methods:
+  - `each`
+  - `message=`
+  - `message_hex=`
+  - `next_pair`
+  - `parse`
+  - `parse_hex`
+  - `inverted_dictionary` read-only attribute
+- `CMF::Varint` class, with the following methods:
+  - `deserialize`
+  - `serialize`
+- `CMF::Dictionary.validate` helper method
+- `CMF::Type` constants
+- `MalformedMessageError` class

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2018 Stephen McCarthy
+
+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.

data/README.md

@@ -0,0 +1,76 @@
+# CMF
+
+[![Build Status](https://travis-ci.org/jamoes/cmf.svg?branch=master)](https://travis-ci.org/jamoes/cmf)
+
+## Description
+
+This library builds and parses messages in the [Compact Message Format (CMF)](http://flowee.org/docs/api/protocol-spec/).
+
+CMF is a binary format that has the speed and compact size of a binary format combined with the provably correct markup and type-safety of formats like XML and JSON.
+
+A CMF message is a flat list of tokens. Each token is comprised of 3 elements: a tag name, a type, and a value. Tag names are written to the message as numbers, so an external schema dictionary is typically used to map the tag numbers to names.
+
+Each CMF token is completely self-contained. Even a reader that doesn't know the schema of the message it is parsing can still extract all tokens from the message. This makes the format exceptionally useful for extensibility because a reader can just skip over unknown tokens.
+
+## Installation
+
+This library is distributed as a gem named [cmf](https://rubygems.org/gems/cmf)
+at RubyGems.org.  To install it, run:
+
+    gem install cmf
+
+## Usage
+
+First, require the gem:
+
+```ruby
+require 'cmf'
+```
+
+Next, we'll build and parse a simple message with two tokens. The message will contain the string `"Proxima Centauri"`, associated with the tag `0`, and the floating point number `4.2421` associated with the tag `1`.
+
+```ruby
+message = CMF.build({0 => "Proxima Centauri", 1 => 4.2421})
+# => "\x02\x10Proxima Centauri\x0EGr\xF9\x0F\xE9\xF7\x10@"
+
+CMF.parse(message)
+# => {0=>"Proxima Centauri", 1=>4.2421}
+```
+
+Rather than using the tags `0`, and `1`, we can define a schema dictionary which maps human-readable names to tag numbers.
+
+```ruby
+dictionary = {star: 0, distance: 1}
+message = CMF.build({star: "Proxima Centauri", distance: 4.2421}, dictionary)
+# => "\x02\x10Proxima Centauri\x0EGr\xF9\x0F\xE9\xF7\x10@"
+
+CMF.parse(message, dictionary)
+# => {:star=>"Proxima Centauri", :distance=>4.2421}
+```
+
+For more flexibility in parsing and building messages, you can use the `CMF::Builder` and `CMF::Parser` classes.
+
+```ruby
+builder = CMF::Builder.new(dictionary)
+builder.add(:star, "Proxima Centauri")
+builder.add(:distance, 4.2421)
+message = builder.to_octet
+
+parser = CMF::Parser.new(dictionary)
+parser.message = message
+parser.next_pair # => [:star, "Proxima Centauri"]
+parser.next_pair # => [:distance, 4.2421]
+parser.next_pair # => nil
+
+parser.message = message     ##
+parser.each do |tag, value|  # star: Proxima Centauri
+  puts "#{tag}: #{value}"    # distance: 4.2421
+end                          ##
+```
+## Supported platforms
+
+Ruby 2.0 and above, including jruby.
+
+## Documentation
+
+For complete documentation, see the [CMF page on RubyDoc.info](http://rubydoc.info/gems/cmf).

data/Rakefile

@@ -0,0 +1,25 @@
+task 'default' => 'spec'
+
+desc 'Run specs'
+task 'spec' do
+  sh 'rspec'
+end
+
+desc 'Run specs and generate coverage report'
+task 'coverage' do
+  ENV['COVERAGE'] = 'Y'
+  Rake::Task['spec'].invoke
+end
+
+desc 'Print out lines of code and related statistics.'
+task 'stats' do
+  puts 'Lines of code and comments (including blank lines):'
+  sh "find lib -type f | xargs wc -l"
+  puts "\nLines of code (excluding comments and blank lines):"
+  sh "find lib -type f | xargs cat | sed '/^\s*#/d;/^\s*$/d' | wc -l"
+end
+
+desc 'Generate documentation'
+task 'doc' do
+  sh 'yardoc'
+end

data/certs/jamoes.pem

@@ -0,0 +1,21 @@
+-----BEGIN CERTIFICATE-----
+MIIDeDCCAmCgAwIBAgIBATANBgkqhkiG9w0BAQUFADBBMRMwEQYDVQQDDApzam1j
+Y2FydGh5MRUwEwYKCZImiZPyLGQBGRYFZ21haWwxEzARBgoJkiaJk/IsZAEZFgNj
+b20wHhcNMTgwNDExMDAxMzI4WhcNMTkwNDExMDAxMzI4WjBBMRMwEQYDVQQDDApz
+am1jY2FydGh5MRUwEwYKCZImiZPyLGQBGRYFZ21haWwxEzARBgoJkiaJk/IsZAEZ
+FgNjb20wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDOk2n/6xgIgrG7
+avtiI8I9DtcdA326qWYpdQSDLhpSsLNiqiIpo8KF1Zfy3lnAj6JBBIbjiaUsbA/i
+Wcip0307dHNXZjr+AgYcL7OEp8EBkfAeZaYWMcVBbjiSxkzYesDxm7nvTOaD317h
+cThBfB9KW1vGEzazomTxSI9sgqCDtWrogMLGag7uTDJ7fKRK6YXz2xncI0uCsmGb
+7vekXpfn0xb6tr4ljSseCsPJHnXK7SKB4dzHsmQJ12A57aaV7C/bGqbQAC6odb6k
+V8dw0fnmHC9OSYjV1b2Xr0VmoiT3YA4XsR0/LbeZvGOyQj8S4eHxgFg7wTVhCkCZ
+D89+p8H5AgMBAAGjezB5MAkGA1UdEwQCMAAwCwYDVR0PBAQDAgSwMB0GA1UdDgQW
+BBQffCJK6PE+9XaH56VJoFoCl3ECeDAfBgNVHREEGDAWgRRzam1jY2FydGh5QGdt
+YWlsLmNvbTAfBgNVHRIEGDAWgRRzam1jY2FydGh5QGdtYWlsLmNvbTANBgkqhkiG
+9w0BAQUFAAOCAQEApvFGCB9uyF1mh1UV77YICagARejAIOhzOcZXjlpulI9xXjQY
+0QK6P1GdwwE/pgT7YjfJR7VNFobare4WdfCzoWCFc34t2vJwrqkkOB3U7v3TjB+p
+z/o2pZKLpNEL4bYJBEbd+vAad/nP1v5e2sCmLm86vSoOwiyQnifmP6PSORObbJF4
+455zxYw1un6NfN0m+pnIKwvshKoOCgI05VJGtEolJoo42fnolmNxa2t6B30Mfmf+
+kts216EGG4oP6dVuZmf2Ii2F4lQTBDdZM/cisW8jCkO7KeEzJAPhIw1JJwHltHya
+0TpOI3t2Mz/FJ+rudtz9PJ/d8QvhrF7M7+qH4w==
+-----END CERTIFICATE-----

data/cmf.gemspec

@@ -0,0 +1,26 @@
+require File.expand_path('../lib/cmf/version', __FILE__)
+
+Gem::Specification.new do |s|
+  s.name        = 'cmf'
+  s.version     = CMF::VERSION
+  s.authors     = ['Stephen McCarthy']
+  s.email       = 'sjmccarthy@gmail.com'
+  s.summary     = 'Builds and parses messages in the Compact Message Format (CMF)'
+  s.homepage    = 'https://github.com/jamoes/cmf'
+  s.license     = 'MIT'
+
+  s.cert_chain  = ['certs/jamoes.pem']
+  s.signing_key = File.expand_path("~/.ssh/gem-private_key.pem") if $0 =~ /gem\z/
+
+  s.files       = `git ls-files`.split("\n")
+  s.executables = s.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  s.test_files  = s.files.grep(%r{^(test|spec|features)/})
+
+  s.add_development_dependency 'bundler', '~> 1'
+  s.add_development_dependency 'rake', '~> 12'
+  s.add_development_dependency 'rspec', '~> 3.7'
+  s.add_development_dependency 'simplecov', '~> 0'
+  s.add_development_dependency 'yard', '~> 0.9.12'
+  s.add_development_dependency 'markdown', '~> 1'
+  s.add_development_dependency 'redcarpet', '~> 3' unless RUBY_PLATFORM == 'java'
+end

data/lib/cmf.rb

@@ -0,0 +1,48 @@
+require 'cmf/builder.rb'
+require 'cmf/dictionary.rb'
+require 'cmf/malformed_message_error.rb'
+require 'cmf/parser.rb'
+require 'cmf/type.rb'
+require 'cmf/varint.rb'
+require 'cmf/version.rb'
+
+# The top-level module for the cmf gem.
+module CMF
+  # Builds a CMF message from an object.
+  #
+  # @param obj [Hash,#each] The object to be built into a CMF message. Can be
+  #     a hash, or any object that responds to `.each` and yields (tag, value)
+  #     pairs.
+  # @param dictionary [Hash,Array] Optional. The dictionary mapping tag
+    #     names to numbers. See {Dictionary.validate}.
+  # @return [String] An octet string, each character representing one byte of
+  #     the CMF message.
+  def self.build(obj, dictionary = nil)
+    Builder.new(dictionary).build(obj).to_octet
+  end
+
+  # Builds hex-encoded a CMF message from an object.
+  #
+  # @see #CMF.build
+  # @return [String] A hex string, every 2 characters representing one byte of
+  #     the CMF message.
+  def self.build_hex(obj, dictionary = nil)
+    Builder.new(dictionary).build(obj).to_hex
+  end
+
+  # Parses a CMF message into an object.
+  #
+  # @param message [String] A CMF message.
+  # @return [Hash] See {Parser.parse}.
+  def self.parse(message, dictionary = nil)
+    Parser.new(dictionary).parse(message)
+  end
+
+  # Parses a hex-encoded CMF message into an object.
+  #
+  # @param message_hex [String] A hex-encoded CMF message.
+  # @return [Hash] See {Parser.parse}.
+  def self.parse_hex(message_hex, dictionary = nil)
+    Parser.new(dictionary).parse_hex(message_hex)
+  end
+end

data/lib/cmf/builder.rb

@@ -0,0 +1,209 @@
+module CMF
+
+  # Instances of the `Builder` class can create CMF messages.
+  #
+  # Basic usage:
+  #
+  #     b = CMF::Builder.new
+  #     b.add(0, "value0")
+  #     b.add(1, "value1")
+  #
+  # The CMF message can be output in octet form (one character per byte):
+  #
+  #     b.to_octet
+  #
+  # or hex form (two characters per byte):
+  #
+  #     b.to_hex
+  #
+  # Method calls can be chained together:
+  #
+  #     CMF::Builder.new.add(0, "value0").add(1, "value1").to_hex
+  #
+  # A dictionary can be used to refer to tags by name rather than number:
+  #
+  #     b = CMF::Builder.new([:tag0, :tag1])
+  #     b.add(:tag0, "value0")
+  #     b.add(:tag1, "value1")
+  #
+  # Messages can be built from an object:
+  #
+  #     b = CMF::Builder.new([:tag0, :tag1])
+  #     b.build({tag0: "value0", tag1: "value1"})
+  class Builder
+    # @return {Hash} The dictionary mapping tag names to numbers.
+    attr_reader :dictionary
+
+    # Creates a new instance of {Builder}.
+    #
+    # @param dictionary [Hash,Array] Optional. The dictionary mapping tag
+    #     names to numbers. See {Dictionary.validate}.
+    def initialize(dictionary = nil)
+      @dictionary = Dictionary.validate(dictionary)
+      reset
+    end
+
+    # Resets the CMF message.
+    #
+    # @return [Builder] self
+    def reset
+      @io = StringIO.new(String.new) # A StringIO with ASCII-8BIT encoding
+
+      self
+    end
+
+    # Adds multiple (tag, value) pairs to the CMF message.
+    #
+    # @param obj [Hash,#each] The object containing (tag, value) pairs. Can be
+    #     a hash, or any object that responds to `.each` and yields
+    #     (tag, value) pairs. Calls {add} for each (tag, value) pair.
+    # @return [Builder] self
+    # @see #add
+    def build(obj)
+      obj.each do |key, values|
+        Array(values).each do |value|
+          add(key, value)
+        end
+      end
+
+      self
+    end
+
+    # Adds a (tag, value) pair to the CMF message.
+    #
+    # @param tag [Integer,Object] Must be an integer or a key in the
+    #     dictionary.
+    # @param value [String,Integer,Boolean,Float,Object] A string, integer,
+    #     boolean, or float. All other types will be converted to a string by
+    #     calling the `to_s` method on them. Strings with binary (ASCII-8BIT)
+    #     encoding will be added as a {Type::BYTE_ARRAY}. All other strings
+    #     will be added as a {Type::STRING}.
+    # @return [Builder] self
+    def add(tag, value)
+      case value
+      when Integer
+        add_int(tag, value)
+      when String
+        if value.encoding == Encoding::BINARY
+          add_bytes(tag, value)
+        else
+          add_string(tag, value)
+        end
+      when TrueClass, FalseClass
+        add_bool(tag, value)
+      when Float
+        add_double(tag, value)
+      else
+        add_string(tag, value)
+      end
+
+      self
+    end
+
+    # Adds a (tag, integer value) pair to the CMF message.
+    #
+    # @param tag [Integer,Object] Must be an integer or a key in the dictionary.
+    # @param value [Integer,Object] An integer value. Non-integer values will be
+    #     converted to integers by calling the `to_i` method on them.
+    # @return [Builder] self
+    def add_int(tag, value)
+      value = value.to_i
+      type = Type::POSITIVE_NUMBER
+      if value < 0
+        type = Type::NEGATIVE_NUMBER
+        value *= -1
+      end
+
+      write_tag(tag, type)
+      Varint.serialize(@io, value.abs)
+
+      self
+    end
+
+    # Adds a (tag, string value) pair to the CMF message.
+    #
+    # @param tag [Integer,Object] Must be an integer or a key in the dictionary.
+    # @param value [String,Object] A string value. Non-string values will be
+    #     converted to strings by calling the `to_s` method on them.
+    # @return [Builder] self
+    def add_string(tag, value)
+      value = value.to_s
+      write_tag(tag, Type::STRING)
+      Varint.serialize(@io, value.bytesize)
+      @io << value
+
+      self
+    end
+
+    # Adds a (tag, byte_array value) pair to the CMF message.
+    #
+    # @param tag [Integer,Object] Must be an integer or a key in the dictionary.
+    # @param value [String,Object] A string value. Non-string values will be
+    #     converted to strings by calling the `to_s` method on them.
+    # @return [Builder] self
+    def add_bytes(tag, value)
+      value = value.to_s
+      write_tag(tag, Type::BYTE_ARRAY)
+      Varint.serialize(@io, value.bytesize)
+      @io << value
+
+      self
+    end
+
+    # Adds a (tag, boolean value) pair to the CMF message.
+    #
+    # @param tag [Integer,Object] Must be an integer or a key in the dictionary.
+    # @param value [Boolean,Object] A boolean value. Non-boolean values will be
+    #     converted to boolean by testing their truthiness.
+    # @return [Builder] self
+    def add_bool(tag, value)
+      write_tag(tag, value ? Type::BOOL_TRUE : Type::BOOL_FALSE)
+
+      self
+    end
+
+    # Adds a (tag, float value) pair to the CMF message.
+    #
+    # @param tag [Integer,Object] Must be an integer or a key in the dictionary.
+    # @param value [Float,Object] A float value. Non-float values will be
+    #     converted to floats by calling the `to_f` method on them.
+    # @return [Builder] self
+    def add_double(tag, value)
+      write_tag(tag, Type::DOUBLE)
+      @io << [value.to_f].pack('E')
+
+      self
+    end
+    alias_method :add_float, :add_double
+
+    # @return [String] An octet string, each character representing one byte
+    #     of the CMF message.
+    def to_octet
+      @io.string
+    end
+
+    # @return [String] A hex string, every 2 characters representing one byte
+    #     of the CMF message.
+    def to_hex
+      to_octet.unpack('H*').first
+    end
+
+    private
+
+    def write_tag(tag, type)
+      if !tag.is_a?(Integer)
+        @dictionary[tag] or raise ArgumentError, "Tag '#{tag}' not found in dictionary"
+        tag = @dictionary[tag]
+      end
+      tag >= 0 or raise ArgumentError, "Invalid tag value #{tag}. Must be >= 0"
+      (type >= 0 && type <= 6) or raise ArgumentError, "Invalid type"
+
+      if tag >= 31
+        @io.putc(type | 0xF8)
+        Varint.serialize(@io, tag)
+      else
+        @io.putc((tag << 3) + type)
+      end
+    end
+  end
+end

data/lib/cmf/dictionary.rb

@@ -0,0 +1,45 @@
+module CMF
+
+  # Provides functionality for validating the `dictionary` argument passed to {Builder} and {Parser}.
+  module Dictionary
+
+    # Validates a dictionary, and optionally converts it from array form to
+    # hash form.
+    #
+    # @param dictionary [Hash,Array] The dictionary mapping tag names to
+    #     numbers. For example:
+    #
+    #         {name: 0, address: 1, email: 2}
+    #
+    #     Arrays will be converted to hashes with each array value mapping to
+    #     its index. The following is equivalent to the above example:
+    #
+    #         [:name, :address, :email]
+    #
+    # @return [Hash] A dictionary mapping tag names to numbers.
+    #
+    # @raise [TypeError] if any dictionary keys are integers.
+    # @raise [TypeError] if any dictionary values are not integers.
+    # @raise [ArgumentError] if dictionary values are not unique.
+    # @raise [ArgumentError] if any dictionary values are negative.
+    def self.validate(dictionary)
+      return {} if dictionary.nil?
+
+      if dictionary.is_a? Array
+        dictionary = dictionary.map.with_index {|s, i| [s, i]}.to_h
+      end
+
+      dictionary.is_a? Hash or raise TypeError, "Dictionary must be an Array or Hash"
+      dictionary.keys.each do |k|
+        !k.is_a?(Integer) or raise TypeError, "Invalid dictionary key #{k}. Must not be an integer"
+      end
+      dictionary.values.each do |v|
+        v.is_a?(Integer) or raise TypeError, "Invalid dictionary value #{v}. Must all be an integer"
+        v >= 0 or raise ArgumentError, "Invalid dictionary value #{v}. Must be >= 0"
+      end
+      dictionary.values.size == dictionary.values.uniq.size or raise ArgumentError, "Dictionary values must be unique"
+
+      dictionary
+    end
+  end
+end

data/lib/cmf/malformed_message_error.rb

@@ -0,0 +1,5 @@
+module CMF
+  # Raised whenever the {Parser} encounters a malformed CMF message.
+  class MalformedMessageError < StandardError
+  end
+end

data/lib/cmf/parser.rb

@@ -0,0 +1,164 @@
+module CMF
+
+  # Instances of the `Parser` class can parse CMF messages.
+  #
+  # Basic usage:
+  #
+  #     p = CMF::Parser.new
+  #     p.parse("\x04\r")   # {0=>true, 1=>false}
+  #     p.parse_hex("040d") # {0=>true, 1=>false}
+  #
+  # Using a dictionary:
+  #
+  #     p = CMF::Parser.new([:tag0, :tag1])
+  #     p.parse_hex("040d") # {:tag0=>true, :tag1=>false}
+  #
+  # If a tag is found multiple times in the message, its values will be stored
+  # in an array in the parsed object.
+  #
+  #     CMF::Parser.new.parse_hex("040504") # {0=>[true, false, true]}
+  #
+  # Using {next_pair}:
+  #
+  #     p = CMF::Parser.new
+  #     p.message_hex = "040d"
+  #     p.next_pair # [0, true]
+  #     p.next_pair # [1, false]
+  #     p.next_pair # nil
+  #
+  # Using {each}:
+  #
+  #     p = CMF::Parser.new
+  #     p.messge_hex = "040d"
+  #     p.each { |k, v| puts "#{k}: #{v}" }
+  class Parser
+    # @return {Hash} The inverted dictionary, mapping numbers to tag names.
+    attr_reader :inverted_dictionary
+
+    # Creates a new instance of {Parser}.
+    #
+    # @param dictionary [Hash,Array] Optional. The dictionary mapping tag
+    #     names to numbers. See {Dictionary.validate}.
+    def initialize(dictionary = nil)
+      @inverted_dictionary = Dictionary.validate(dictionary).invert
+      @io = StringIO.new
+    end
+
+    # Sets a new CMF message.
+    #
+    # @param message [String] The CMF message in octet form.
+    def message=(message)
+      @io = StringIO.new(message)
+    end
+
+    # Sets a new CMF message from a hex string.
+    #
+    # @param message_hex [String] The hex-encoded CMF message.
+    def message_hex=(message_hex)
+      self.message = [message_hex].pack('H*')
+    end
+
+    # Parses a CMF message into an object.
+    #
+    # @param message [String] The message to parse. If none provided, this
+    #     parser's existing message (defined from {message=} or {message_hex=}
+    #     will be parsed.
+    # @return [Hash] A hash mapping the messages tags to their values. For each
+    #     tag, if the tag number is found in the dictionary, its associated
+    #     tag name will be used as hash key. If a tag is found multiple times
+    #     in the message, its values will be stored in an array in the parsed
+    #     object.
+    def parse(message = nil)
+      self.message = message if message
+
+      obj = {}
+      each do |key, value|
+        if obj.has_key?(key)
+          obj[key] = Array(obj[key])
+          obj[key] << value
+        else
+          obj[key] = value
+        end
+      end
+
+      obj
+    end
+
+    # Parses a hex-encoded CMF message into an object.
+    #
+    # @param message_hex [String] A hex-encoded CMF message.
+    # @return [Hash] See {parse}.
+    def parse_hex(message_hex)
+      self.message_hex = message_hex
+
+      parse
+    end
+
+    # Calls the given block once for each pair found in the message.
+    #
+    # @yieldparam [Integer,Object] tag The pair's tag. An integer, or the
+    #     associated value found in the dictionary.
+    # @yieldparam [String,Integer,Boolean,Float] value The pair's value.
+    # @return [Enumerator] If no block is given.
+    # @see #next_pair
+    def each
+      return to_enum(:each) unless block_given?
+      loop do
+        pair = next_pair
+        break if pair.nil?
+        yield(pair[0], pair[1])
+      end
+    end
+
+    # Returns the next pair in the message, or nil if the whole message has been
+    # parsed.
+    #
+    # @return [Array,nil] A (tag, value) pair. The tag will be an integer, or
+    #     the associated value found in the dictionary. The value will be
+    #     converted to the corresponding type defined in the message. If the
+    #     value's type is {Type::STRING}, the value will be a string with UTF-8
+    #     encoding. If the value's type is {Type::BYTE_ARRAY}, the value will
+    #     be a string with binary (ASCII-8BIT) encoding.
+    #
+    # @raise [MalformedMessageError] if the CMF message cannot be parsed, or if
+    #     it is malformed in any way.
+    def next_pair
+      return nil if @io.eof?
+
+      byte = @io.getbyte
+      type = byte & 0x07
+      tag = byte >> 3
+      if tag == 31
+        tag = Varint.deserialize(@io)
+      end
+
+      if @inverted_dictionary[tag]
+        tag = @inverted_dictionary[tag]
+      end
+
+      case type
+      when Type::POSITIVE_NUMBER
+        [tag, Varint.deserialize(@io)]
+      when Type::NEGATIVE_NUMBER
+        [tag, -Varint.deserialize(@io)]
+      when Type::STRING, Type::BYTE_ARRAY
+        length = Varint.deserialize(@io)
+        s = @io.read(length)
+        s.bytesize == length or raise MalformedMessageError, "Unexpected end of stream"
+        s = s.force_encoding(Encoding::UTF_8) if type == Type::STRING
+        [tag, s]
+      when Type::BOOL_TRUE
+        [tag, true]
+      when Type::BOOL_FALSE
+        [tag, false]
+      when Type::DOUBLE
+        s = @io.read(8)
+        s.bytesize == 8 or raise MalformedMessageError, "Unexpected end of stream"
+        [tag, s.unpack('E').first]
+      else
+        raise MalformedMessageError, "Unknown type"
+      end
+
+    end
+  end
+end

data/lib/cmf/type.rb

@@ -0,0 +1,27 @@
+module CMF
+
+  # Defines the enum value for all types that can be stored in a CMF message.
+  module Type
+    # Varint encoded integer.
+    POSITIVE_NUMBER = 0
+
+    # The value is multiplied by -1 and then serialized in the same manner
+    # as a POSITIVE_NUMBER.
+    NEGATIVE_NUMBER = 1
+
+    # Varint length (in bytes) first, then the UTF-8 encoded string.
+    STRING          = 2
+
+    # Varint length (in bytes) first, then the binary encoded string.
+    BYTE_ARRAY      = 3
+
+    # True value, no additional data stored.
+    BOOL_TRUE       = 4
+
+    # False value, no additional data stored.
+    BOOL_FALSE      = 5
+
+    # Double-precision (8 bytes) little-endian floating-point number.
+    DOUBLE          = 6
+  end
+end

data/lib/cmf/varint.rb

@@ -0,0 +1,45 @@
+module CMF
+  # Provides functionaly for serializing and deserializing variable-width
+  # encoded integers (varint).
+  class Varint
+
+    # Serializes an integer into a varint.
+    #
+    # @param io [StringIO] The IO stream where the serialized varint will be
+    #     written.
+    # @param n [Integer] The integer to serialize.
+    # @return [nil]
+    def self.serialize(io, n)
+      n.is_a?(Integer) or raise TypeError, "Invalid Varint value #{n}. Must be an integer"
+      n >= 0 or raise ArgumentError, "Invalid Varint value #{n}. Must be >= 0"
+
+      data = []
+      mask = 0
+      begin
+        data.push((n & 0x7F) | mask)
+        n = (n >> 7) - 1
+        mask = 0x80
+      end while n >= 0
+
+      data.reverse_each do |byte|
+        io.putc(byte)
+      end
+
+      nil
+    end
+
+    # Deserializes a varint into a integer.
+    #
+    # @param io [StringIO] The IO stream that will be read from to deserialize.
+    # @return [Integer] The deserialized integer.
+    def self.deserialize(io)
+      result = 0
+      io.each_byte do |byte|
+        result = (result << 7) | (byte & 0x7F)
+        return result if (byte & 0x80) == 0
+        result += 1
+      end
+      raise CMF::MalformedMessageError, "Unexpected end of stream"
+    end
+  end
+end

data/lib/cmf/version.rb

@@ -0,0 +1,4 @@
+module CMF
+  # This gem's version.
+  VERSION = '1.0.0'
+end

data/spec/builder_spec.rb

@@ -0,0 +1,74 @@
+require 'spec_helper'
+require 'messages'
+
+describe CMF::Builder do
+
+  MESSAGES.each do |obj, encoded_output, dictionary|
+    it "Builds message #{encoded_output}" do
+      expect(CMF.build_hex(obj, dictionary)).to eq encoded_output
+    end
+  end
+
+  it 'Builds octet message' do
+    expect(CMF.build({0 => false})).to eq("\x05".force_encoding(Encoding::BINARY))
+  end
+
+  describe '#reset' do
+    it 'resets the message' do
+      builder = CMF::Builder.new
+      builder.add(0, 0)
+      builder.reset
+      expect(builder.to_hex).to eq ''
+    end
+  end
+
+  describe '#add' do
+    it 'raises when tag not found in dictionary' do
+      expect { CMF::Builder.new.add(:tag, 0) }.to raise_error(ArgumentError)
+    end
+
+    it 'raises when tag is negative' do
+      expect { CMF::Builder.new.add(-1, 0) }.to raise_error(ArgumentError)
+    end
+
+    it 'accepts chained calls' do
+      expect(CMF::Builder.new.add(0, true).add(0, false).to_hex).to eq "0405"
+    end
+
+    it 'converts unknown input type to a string' do
+      expect(CMF::Builder.new.add(0, []).to_hex).to eq "02025b5d"
+    end
+  end
+
+  describe '#add_int' do
+    it 'converts non-int input to an int' do
+      expect(CMF::Builder.new.add_int(15, "6512").to_hex).to eq "78b170"
+      expect(CMF::Builder.new.add_int(15, 6512.1).to_hex).to eq "78b170"
+    end
+  end
+
+  describe '#add_string' do
+    it 'converts non-string input to a string' do
+      expect(CMF::Builder.new.add_string(0, []).to_hex).to eq "02025b5d"
+    end
+  end
+
+  describe '#add_bytes' do
+    it 'converts non-string input to a string' do
+      expect(CMF::Builder.new.add_bytes(0, []).to_hex).to eq "03025b5d"
+    end
+  end
+
+  describe '#add_bool' do
+    it 'converts non-bool input to a bool' do
+      expect(CMF::Builder.new.add_bool(0, []).to_hex).to eq "04"
+      expect(CMF::Builder.new.add_bool(0, nil).to_hex).to eq "05"
+    end
+  end
+
+  describe '#add_double' do
+    it 'converts non-double input to a double' do
+      expect(CMF::Builder.new.add_double(0, "1.1").to_hex).to eq "069a9999999999f13f"
+    end
+  end
+end

data/spec/dictionary_spec.rb

@@ -0,0 +1,34 @@
+require 'spec_helper'
+
+describe CMF::Dictionary do
+  describe '#validate' do
+    it 'validates nil dictionary' do
+      expect(CMF::Dictionary.validate(nil)).to eq({})
+    end
+
+    it 'validates array dictionary' do
+      expect(CMF::Dictionary.validate([:tag0, :tag1, :tag2])).to eq({tag0: 0, tag1: 1, tag2: 2})
+    end
+
+    it 'validates hash dictionary' do
+      expect(CMF::Dictionary.validate({tag0: 0, tag1: 1, tag2: 2})).to eq({tag0: 0, tag1: 1, tag2: 2})
+    end
+
+    it 'does not allow integer keys' do
+      expect { CMF::Dictionary.validate({100 => 0, tag1: 1}) }.to raise_error(TypeError)
+    end
+
+    it 'requires integer values' do
+      expect { CMF::Dictionary.validate({tag0: 0, tag1: "foo"}) }.to raise_error(TypeError)
+    end
+
+    it 'does not allow duplicate values' do
+      expect { CMF::Dictionary.validate({tag0: 0, tag1: 0}) }.to raise_error(ArgumentError)
+    end
+
+    it 'does not allow duplicate values' do
+      expect { CMF::Dictionary.validate({tag0: 0, tag1: 0}) }.to raise_error(ArgumentError)
+    end
+
+  end
+end

data/spec/messages.rb

@@ -0,0 +1,30 @@
+MESSAGES =
+  [
+    [{15 => 6512}, "78b170"],
+    [{tag15: 6512}, "78b170", {tag15: 15}],
+    [{129 => 6512}, "f88001b170"],
+    [{0 => -1}, "0101"],
+    [{0 => "text"}, "020474657874"],
+    [{0 => "text".force_encoding(Encoding::BINARY)}, "030474657874"],
+    [{0 => true}, "04"],
+    [{0 => false}, "05"],
+    [{0 => 3.1415}, "066f1283c0ca210940"],
+    [
+      {
+        1 => "Föo",
+        200 => "hihi".force_encoding(Encoding::BINARY),
+        3 => true,
+        40 => false,
+      },
+      "0a0446c3b66ffb804804686968691cfd28"
+    ],
+    [
+      {
+        2 => true,
+        tag1: [false, 5, "text", "bytes".force_encoding(Encoding::BINARY), 1.11],
+        tag0: 100,
+      },
+      "140d08050a04746578740b0562797465730ec3f5285c8fc2f13f0064",
+      [:tag0, :tag1]
+    ]
+  ]

data/spec/parser_spec.rb

@@ -0,0 +1,36 @@
+require 'spec_helper'
+require 'messages'
+
+describe CMF::Parser do
+
+  MESSAGES.each do |obj, encoded_output, dictionary|
+    it "Parses message #{encoded_output}" do
+      expect(CMF.parse_hex(encoded_output, dictionary)).to eq obj
+    end
+  end
+
+  # Invalid messages:
+  [
+    '00', # Number type, but no data.
+    '00ff', # Number type, but invalid varint data.
+    '0700', # Unknown type.
+    '020261', # String type, but string data is less than length.
+    '069a9999999999b9', # Double type, but only 7 bytes of data.
+  ].each do |invalid_message|
+    it "Raises on invalid message: #{invalid_message}" do
+      expect { CMF.parse_hex(invalid_message) }.to raise_error(CMF::MalformedMessageError)
+    end
+  end
+
+  it 'Parses hex' do
+    p = CMF::Parser.new
+    p.message_hex = '05'
+
+    expect(p.parse).to eq({0 => false})
+    expect(p.parse_hex('05')).to eq({0 => false})
+  end
+
+  it 'Parses octet' do
+    expect(CMF.parse("\x04")).to eq({0 => true})
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,6 @@
+if ENV['COVERAGE']
+  require 'simplecov'
+  SimpleCov.start
+end
+
+require 'cmf'

data/spec/varint_spec.rb

@@ -0,0 +1,50 @@
+require 'spec_helper'
+
+describe CMF::Varint do
+
+  number_encodings = {
+    0X7F   => [0x7f],
+    0X80   => [0x80, 0x00],
+    0xFF   => [0x80, 0x7F],
+    0x407F => [0xFF, 0x7F],
+    0X4080 => [0x80, 0x80, 0x00],
+  }
+
+  describe '#serialize' do
+    it 'serializes values correctly' do
+      number_encodings.each do |number, encoded_number|
+        io = StringIO.new(String.new)
+        CMF::Varint.serialize(io, number)
+
+        expect(io.string).to eq encoded_number.pack('c*')
+      end
+    end
+
+    it 'does not serialize negative numbers' do
+      io = StringIO.new(String.new)
+      expect { CMF::Varint.serialize(io, -1) }.to raise_error(ArgumentError)
+    end
+
+    it 'Raises on invalid type' do
+      io = StringIO.new(String.new)
+      expect { CMF::Varint.serialize(io, "") }.to raise_error(TypeError)
+    end
+  end
+
+  describe '#deserialize' do
+    it 'deserializes values correctly' do
+      number_encodings.invert.each do |encoded_number, number|
+        io = StringIO.new(encoded_number.pack('c*'))
+        decoded_number = CMF::Varint.deserialize(io)
+
+        expect(number).to eq decoded_number
+      end
+    end
+
+    it 'raises an error if the stream ends early' do
+      io = StringIO.new([0x80].pack('c*'))
+      expect { CMF::Varint.deserialize(io) }.to raise_error(CMF::MalformedMessageError)
+    end
+  end
+
+end

metadata

@@ -0,0 +1,193 @@
+--- !ruby/object:Gem::Specification
+name: cmf
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Stephen McCarthy
+autorequire: 
+bindir: bin
+cert_chain:
+- |
+  -----BEGIN CERTIFICATE-----
+  MIIDeDCCAmCgAwIBAgIBATANBgkqhkiG9w0BAQUFADBBMRMwEQYDVQQDDApzam1j
+  Y2FydGh5MRUwEwYKCZImiZPyLGQBGRYFZ21haWwxEzARBgoJkiaJk/IsZAEZFgNj
+  b20wHhcNMTgwNDExMDAxMzI4WhcNMTkwNDExMDAxMzI4WjBBMRMwEQYDVQQDDApz
+  am1jY2FydGh5MRUwEwYKCZImiZPyLGQBGRYFZ21haWwxEzARBgoJkiaJk/IsZAEZ
+  FgNjb20wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDOk2n/6xgIgrG7
+  avtiI8I9DtcdA326qWYpdQSDLhpSsLNiqiIpo8KF1Zfy3lnAj6JBBIbjiaUsbA/i
+  Wcip0307dHNXZjr+AgYcL7OEp8EBkfAeZaYWMcVBbjiSxkzYesDxm7nvTOaD317h
+  cThBfB9KW1vGEzazomTxSI9sgqCDtWrogMLGag7uTDJ7fKRK6YXz2xncI0uCsmGb
+  7vekXpfn0xb6tr4ljSseCsPJHnXK7SKB4dzHsmQJ12A57aaV7C/bGqbQAC6odb6k
+  V8dw0fnmHC9OSYjV1b2Xr0VmoiT3YA4XsR0/LbeZvGOyQj8S4eHxgFg7wTVhCkCZ
+  D89+p8H5AgMBAAGjezB5MAkGA1UdEwQCMAAwCwYDVR0PBAQDAgSwMB0GA1UdDgQW
+  BBQffCJK6PE+9XaH56VJoFoCl3ECeDAfBgNVHREEGDAWgRRzam1jY2FydGh5QGdt
+  YWlsLmNvbTAfBgNVHRIEGDAWgRRzam1jY2FydGh5QGdtYWlsLmNvbTANBgkqhkiG
+  9w0BAQUFAAOCAQEApvFGCB9uyF1mh1UV77YICagARejAIOhzOcZXjlpulI9xXjQY
+  0QK6P1GdwwE/pgT7YjfJR7VNFobare4WdfCzoWCFc34t2vJwrqkkOB3U7v3TjB+p
+  z/o2pZKLpNEL4bYJBEbd+vAad/nP1v5e2sCmLm86vSoOwiyQnifmP6PSORObbJF4
+  455zxYw1un6NfN0m+pnIKwvshKoOCgI05VJGtEolJoo42fnolmNxa2t6B30Mfmf+
+  kts216EGG4oP6dVuZmf2Ii2F4lQTBDdZM/cisW8jCkO7KeEzJAPhIw1JJwHltHya
+  0TpOI3t2Mz/FJ+rudtz9PJ/d8QvhrF7M7+qH4w==
+  -----END CERTIFICATE-----
+date: 2018-04-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '12'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.7'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.12
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.12
+- !ruby/object:Gem::Dependency
+  name: markdown
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1'
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3'
+description: 
+email: sjmccarthy@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".travis.yml"
+- ".yardopts"
+- CHANGELOG.md
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- certs/jamoes.pem
+- cmf.gemspec
+- lib/cmf.rb
+- lib/cmf/builder.rb
+- lib/cmf/dictionary.rb
+- lib/cmf/malformed_message_error.rb
+- lib/cmf/parser.rb
+- lib/cmf/type.rb
+- lib/cmf/varint.rb
+- lib/cmf/version.rb
+- spec/builder_spec.rb
+- spec/dictionary_spec.rb
+- spec/messages.rb
+- spec/parser_spec.rb
+- spec/spec_helper.rb
+- spec/varint_spec.rb
+homepage: https://github.com/jamoes/cmf
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.6
+signing_key: 
+specification_version: 4
+summary: Builds and parses messages in the Compact Message Format (CMF)
+test_files:
+- spec/builder_spec.rb
+- spec/dictionary_spec.rb
+- spec/messages.rb
+- spec/parser_spec.rb
+- spec/spec_helper.rb
+- spec/varint_spec.rb