nstrct 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: e2087a496c196012c63735b96ff04f1ab6d51c79
+  data.tar.gz: 669624331f0b1a78b122e926ddc1d703ddaa614f
+SHA512:
+  metadata.gz: ff6574cb663aca80b4bee655b3e7a93a9a60be152b8213636402c39b33ccbcc3e14c8116a5dab061f820167f6a450d28c40ed4c683ff5a8ecf4096ecef57fd1f
+  data.tar.gz: 1929493e6b70b29c39d86bdc1e75e91758f123d445e634f462f7ab7c9b44ab5ae1cdc93b811e569a073cd6ee47a1910af4e093d45a72586fd9c070c0f6da99b3

data/.gitignore

@@ -0,0 +1 @@
+.DS_Store

data/Gemfile

@@ -0,0 +1,6 @@
+source 'http://rubygems.org'
+gemspec
+
+group :test do
+  gem 'rspec'
+end

data/Gemfile.lock

@@ -0,0 +1,26 @@
+PATH
+  remote: .
+  specs:
+    nstrct (0.0.3)
+      digest-crc
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    diff-lcs (1.2.5)
+    digest-crc (0.4.0)
+    rspec (2.14.1)
+      rspec-core (~> 2.14.0)
+      rspec-expectations (~> 2.14.0)
+      rspec-mocks (~> 2.14.0)
+    rspec-core (2.14.7)
+    rspec-expectations (2.14.4)
+      diff-lcs (>= 1.1.3, < 2.0)
+    rspec-mocks (2.14.4)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  nstrct!
+  rspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2013 ElectricFeel Mobility Systems GmbH, Joël Gähwiler
+
+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,40 @@
+# nstrct-ruby
+
+**a multi-purpose binary protocol for instruction interchange**
+
+Interchange formats like json or xml are great to keep data visible, but due to their parse and pack complexity they aren't used in embedded applications. There are alternatives like msgpack or Google's protocol buffer, which allow a more binary representation of data, but these protcols are still heavy and developers tend to rather implement their own 'simple' binary protocols instead of porting or using the big ones. 
+
+The protcol **nstrct** is designed to be an alternative in those situations where a tiny and versatile protocol is needed. The main transportable unit in nstrct are **instructions** which carry a dynamic amount of data in the form of **arguments**. Each instruction is identified by a code between 0-65535 which can be used by two communicating applications to identify the blueprint of the message. Arguments support all standard types of integers(boolean, int8-64, uint8-64, float32/64), strings, and arrays of integers or strings. There is no support for hashes by design to keep the pack and unpacking functions as small as possible. [Check the main repository for the binary layout of the instructions](http://github.com/nstrct/nstrct).
+
+**Start using nstrct by getting the library for your favorite programming language:**
+
+* [C/C++ (nstrct-c)](http://github.com/nstrct/nstrct-c)
+* [Ruby (nstrct-ruby)](http://github.com/nstrct/nstrct-ruby)
+* [Obj-C (nstrct-objc)](http://github.com/nstrct/nstrct-objc)
+* [Java (nstrct-c)](http://github.com/nstrct/nstrct-java)
+
+_This software has been open sourced by [ElectricFeel Mobility Systems Gmbh](http://electricfeel.com) and is further maintained by [Joël Gähwiler](http://github.com/256dpi)._
+
+## Instruction Composing
+
+A simple example:
+
+```ruby
+instruction = Nstrct::Instruction.new(382)
+bytes = instruction.pack
+```
+
+A more complex example:
+
+```ruby
+instruction = Nstrct::Instruction.build_instruction(232, [:boolean, true], [:int8, 2], [:float32, 1.0], [[:uint16], [54, 23, 1973]])
+instruction.pack
+```
+
+## Instruction Processing
+
+```ruby
+instruction = Nstrct::Instruction.parse(bytes)
+instruction.code
+instruction.arguments[0].datatype
+```

data/cross_platform_test

@@ -0,0 +1,83 @@
+#!/usr/bin/env ruby
+
+require 'optparse'
+
+$:.unshift File.expand_path('../lib', __FILE__)
+require 'nstrct'
+
+mode = nil
+
+MIN = {
+  int8: (2**7)*-1,
+  int16: (2**15)*-1,
+  int32: (2**31)*-1,
+  int64: (2**63)*-1
+}
+
+MAX = {
+  uint8: (2**8)-1,
+  uint16: (2**16)-1,
+  uint32: (2**32)-1,
+  uint64: (2**64)-1,
+  float32: 3.4028234663852886*(10**38),
+  float64: 1.7976931348623157*(10**308)
+}
+
+def assert test, exp
+  unless exp
+    puts test
+    exit!
+  end
+end
+
+OptionParser.new do |opts|
+  opts.banner = 'Usage: cross_platform_test [options]'
+  opts.on('-p', '--process', 'process bytes at STDIN and return result') do |p|
+    mode = :process
+  end
+  opts.on('-g', '--generate', 'generate bytes and write to STDOUT') do |g|
+    mode = :generate
+  end
+end.parse!
+
+if mode == :generate
+  i = Nstrct::Instruction.build MAX[:uint16],
+    [:boolean, false],
+    [:int8, MIN[:int8]],
+    [:int16, MIN[:int16]],
+    [:int32, MIN[:int32]],
+    [:int64, MIN[:int64]],
+    [:uint8, MAX[:uint8]],
+    [:uint16, MAX[:uint16]],
+    [:uint32, MAX[:uint32]],
+    [:uint64, MAX[:uint64]],
+    [:float32, MAX[:float32]],
+    [:float64, MAX[:float64]],
+    [:string, 'hello world'],
+    [:string, ''],
+    [[:uint16], [2443, 3443]]
+  buf = Nstrct::Frame.new(i).pack
+  STDOUT.write [buf.size].pack('L>')
+  STDOUT.write buf
+elsif mode == :process
+  length = STDIN.read(4).unpack('L>')[0]
+  i = Nstrct::Frame.parse(STDIN.read(length)).instruction
+  assert '    boolean value error', !i.arguments[0].value
+  assert '    int8 value error', i.arguments[1].value == MIN[:int8]
+  assert '    int16 value error', i.arguments[2].value == MIN[:int16]
+  assert '    int32 value error', i.arguments[3].value == MIN[:int32]
+  assert '    int64 value error', i.arguments[4].value == MIN[:int64]
+  assert '    uint8 value error', i.arguments[5].value == MAX[:uint8]
+  assert '    uint16 value error', i.arguments[6].value == MAX[:uint16]
+  assert '    uint32 value error', i.arguments[7].value == MAX[:uint32]
+  assert '    uint64 value error', i.arguments[8].value == MAX[:uint64]
+  assert '    float32 value error', i.arguments[9].value == MAX[:float32]
+  assert '    float64 value error', i.arguments[10].value == MAX[:float64]
+  assert '    string value error', i.arguments[11].value.eql?('hello world')
+  assert '    empty string value error', i.arguments[12].value.eql?('')
+  assert '    array uint16 value 1 error', i.arguments[13].value[0] == 2443
+  assert '    array uint16 value 2 error', i.arguments[13].value[1] == 3443
+  puts '    tests passed'
+else
+  puts 'please specify a run mode'
+end

data/lib/nstrct.rb

@@ -0,0 +1,3 @@
+require 'nstrct/argument'
+require 'nstrct/instruction'
+require 'nstrct/frame'

data/lib/nstrct/argument.rb

@@ -0,0 +1,149 @@
+module Nstrct
+
+  class Argument
+
+    # Available datatypes and their argument code
+    DATATYPES = {
+      boolean: 1,
+      int8: 10,
+      int16: 11,
+      int32: 12,
+      int64: 13,
+      uint8: 14,
+      uint16: 15,
+      uint32: 16,
+      uint64: 17,
+      float32: 21,
+      float64: 22,
+      string: 31,
+      array: 32
+    }
+
+    # Get the datatype of a argument code
+    def self.datatype_by_for_argument_code code
+      DATATYPES.detect{ |k,v| v == code }[0]
+    end
+
+    # Parse a single value of a buffer
+    def self.parse_value datatype, data
+      case datatype
+        when :boolean
+          return data.slice!(0).unpack('C')[0] == 1
+        when :int8
+          return data.slice!(0).unpack('c')[0]
+        when :int16
+          return data.slice!(0..1).unpack('s>')[0]
+        when :int32
+          return data.slice!(0..3).unpack('l>')[0]
+        when :int64
+          return data.slice!(0..7).unpack('q>')[0]
+        when :uint8
+          return data.slice!(0).unpack('C')[0]
+        when :uint16
+          return data.slice!(0..1).unpack('S>')[0]
+        when :uint32
+          return data.slice!(0..3).unpack('L>')[0]
+        when :uint64
+          return data.slice!(0..7).unpack('Q>')[0]
+        when :float32
+          return data.slice!(0..3).unpack('g')[0]
+        when :float64
+          return data.slice!(0..7).unpack('G')[0]
+        when :string
+          length = data.slice!(0).unpack('C')[0]
+          return length > 0 ? data.slice!(0..length-1) : ''
+        when :array
+          raise 'cannot parse array value directly'
+        else
+          raise "datatype '#{datatype}' not recognized"
+      end
+    end
+
+    # Parse a single argument from a buffer
+    def self.parse data
+      datatype = self.datatype_by_for_argument_code(data.slice!(0).unpack('C')[0])
+      if datatype == :array
+        array_datatype = self.datatype_by_for_argument_code(data.slice!(0).unpack('C')[0])
+        array_num_elements = data.slice!(0).unpack('C')[0]
+        values = []
+        array_num_elements.times do
+          values << self.parse_value(array_datatype, data)
+        end
+        return self.new(array_datatype, values, true)
+      else
+        return self.new(datatype, self.parse_value(datatype, data), false)
+      end
+    end
+
+    attr_reader :datatype, :value, :array
+
+    # Instantiate a new Argument providing its datatype, value and arrayness
+    def initialize datatype, value, array
+      @datatype, @value, @array = datatype, value, array
+    end
+
+    # Pack a single value in a buffer
+    def pack_value datatype, value, data
+      case datatype
+        when :boolean
+          data += [value ? 1 : 0].pack('C')
+        when :int8
+          data += [value].pack('c')
+        when :int16
+          data += [value].pack('s>')
+        when :int32
+          data += [value].pack('l>')
+        when :int64
+          data += [value].pack('q>')
+        when :uint8
+          data += [value].pack('C')
+        when :uint16
+          data += [value].pack('S>')
+        when :uint32
+          data += [value].pack('L>')
+        when :uint64
+          data += [value].pack('Q>')
+        when :float32
+          data += [value].pack('g')
+        when :float64
+          data += [value].pack('G')
+        when :string
+          data += [value.size].pack('C')
+          data += value
+        when :array
+          raise 'cannot pack array value directly'
+        else
+          raise "datatype '#{datatype}' not recognized"
+      end
+      data
+    end
+
+    # Pack a single argument in a buffer
+    def pack
+      data = ''
+      if @array
+        data += [DATATYPES[:array]].pack('C')
+        data += [DATATYPES[@datatype]].pack('C')
+        data += [@value.size].pack('C')
+        @value.each do |val|
+          data = pack_value(@datatype, val, data)
+        end
+      else
+        data += [DATATYPES[datatype]].pack('C')
+        data = pack_value(@datatype, @value, data)
+      end
+      data
+    end
+
+    # Return comparable inspection
+    def inspect
+      if @array
+        "[#{@datatype.inspect}]=#{@value}"
+      else
+        "#{@datatype.inspect}=#{@value}"
+      end
+    end
+
+  end
+
+end

data/lib/nstrct/frame.rb

@@ -0,0 +1,62 @@
+require 'digest/crc32'
+
+module Nstrct
+
+  class Frame
+
+    FRAME_OVERHEAD = 8
+    FRAME_START = 0x55
+    FRAME_END = 0xAA
+
+    def self.crc32 buffer
+      Digest::CRC32.checksum buffer
+    end
+
+    def self.available? buffer
+      if buffer.size >= 1
+        raise 'start of frame invalid' unless buffer.slice(0).unpack('C')[0] == FRAME_START
+        if buffer.size >= 3
+          payload_length = buffer.slice(1..2).unpack('S>')[0]
+          if buffer.size >= (payload_length+FRAME_OVERHEAD)
+            raise 'end of frame invalid' unless buffer.slice(payload_length+FRAME_OVERHEAD-1).unpack('C')[0] == FRAME_END
+            return true
+          end
+        end
+      end
+      false
+    end
+
+    def self.parse buffer
+      raise 'no frame available' unless self.available?(buffer)
+      buffer.slice!(0) # remove start of frame
+      length = buffer.slice!(0..1).unpack('S>')[0]
+      payload = buffer.slice!(0..length-1)
+      checksum = buffer.slice!(0..3).unpack('L>')[0]
+      buffer.slice!(0) # remove end of frame
+      raise 'checksum invalid' unless checksum == crc32(payload)
+      self.new(Instruction.parse(payload))
+    end
+
+    attr_accessor :instruction
+
+    def initialize instruction
+      @instruction = instruction
+    end
+
+    def pack
+      payload = @instruction.pack
+      frame = [FRAME_START].pack('C')
+      frame += [payload.size].pack('S>')
+      frame += payload
+      frame += [Frame.crc32(payload)].pack('L>')
+      frame + [FRAME_END].pack('C')
+    end
+
+    # Return a comparable inspection
+    def inspect
+      "#<Nstrct::Frame instruction=#{@instruction.inspect}>"
+    end
+
+  end
+
+end

data/lib/nstrct/instruction.rb

@@ -0,0 +1,68 @@
+module Nstrct
+
+  class Instruction
+
+    attr_accessor :code, :arguments
+
+    # Parse one message from the data stream.
+    def self.parse data
+      code = data.slice!(0..1).unpack('s>')[0]
+      num_arguments = data.slice!(0).unpack('C')[0]
+      data.slice!(0..1) # num_array_elements
+      arguments = []
+      num_arguments.times do
+        arguments << Nstrct::Argument.parse(data)
+      end
+      self.new(code, arguments)
+    end
+
+    # Build an instruction for a code and some arguments.
+    #
+    #   Message.build_instruction 54, [ :boolean, true], [[:int8], [7, 8, 9]] ]
+    #
+    def self.build code, *args
+      arguments = []
+      args.each do |arg|
+        if arg[0].is_a?(Array)
+          arguments << Nstrct::Argument.new(arg[0][0], arg[1], true)
+        else
+          arguments << Nstrct::Argument.new(arg[0], arg[1], false)
+        end
+      end
+      self.new(code, arguments)
+    end
+
+    # Instantiate a new instruction by its code and alist of arguments
+    def initialize code, arguments=[]
+      @code, @arguments = code, arguments
+    end
+
+    # Get all the arguments values
+    def argument_values
+      @arguments.map{ |arg| arg.value }
+    end
+
+    # get all elements in arrays
+    def array_elements
+      @arguments.inject(0){ |sum, a| sum + (a.array ? a.value.size : 0) }
+    end
+
+    # Pack a single instruction in a buffer
+    def pack
+      message = [@code].pack('s>')
+      message += [@arguments.size].pack('C')
+      message += [array_elements].pack('s>')
+      @arguments.each do |arg|
+        message += arg.pack
+      end
+      message
+    end
+
+    # Return a comparable inspection
+    def inspect
+      "#<Nstrct::Instructon code=#{@code.inspect}, arguments=#{@arguments.inspect}>"
+    end
+
+  end
+
+end

data/lib/nstrct/version.rb

@@ -0,0 +1,3 @@
+module Nstrct
+  VERSION = '0.1.0'
+end

data/nstrct.gemspec

@@ -0,0 +1,21 @@
+$:.push File.expand_path('../lib', __FILE__)
+require 'nstrct/version'
+
+Gem::Specification.new do |s|
+  s.name = 'nstrct'
+  s.version = Nstrct::VERSION
+
+  s.summary = 'a multi-purpose binary protocol for instruction interchange'
+  s.authors = 'Joël Gähwiler'
+  s.email = 'nstrct@256dpi.ch'
+  s.homepage = 'http://github.com/nstrct'
+
+  s.description = "Interchange formats like json or xml are great to keep data visible, but due to their parse and pack complexity they aren't used in embedded applications. There are alternatives like msgpack or Google's protocol buffer, which allow a more binary representation of data, but these protcols are still heavy and developers tend to rather implement their own 'simple' binary protocols instead of porting or using the big ones."
+
+  s.license = 'MIT'
+  
+  s.files = `git ls-files`.split("\n")
+  s.test_files = `git ls-files -- {test,spec,features}/*`.split("\n")
+
+  s.add_runtime_dependency 'digest-crc'
+end

data/spec/protocol_spec.rb

@@ -0,0 +1,27 @@
+require 'spec_helper'
+
+describe Nstrct::Instruction do
+
+  it 'should pack and unpack an empty instruction' do
+    instruction1 = Nstrct::Instruction.new(382, [])
+    instruction2 = Nstrct::Instruction.parse(instruction1.pack)
+    instruction1.inspect.should == instruction2.inspect
+  end
+
+  it 'should pack and unpack an instructionw with arguments' do
+    instruction1 = Nstrct::Instruction.build(232, [:float32, 1.0 ], [:boolean, true], [:int8, 2], [:float32, 1.0], [[:uint16], [54, 23, 1973]])
+    instruction2 = Nstrct::Instruction.parse(instruction1.pack)
+    instruction1.inspect.should == instruction2.inspect
+  end
+
+end
+
+describe Nstrct::Frame do
+
+  it 'should pack and unpack a frame' do
+    frame1 = Nstrct::Frame.new(Nstrct::Instruction.new(132, []))
+    frame2 = Nstrct::Frame.parse(frame1.pack)
+    frame1.inspect.should == frame2.inspect
+  end
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1 @@
+require 'nstrct'

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification
+name: nstrct
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Joël Gähwiler
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-01-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: digest-crc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Interchange formats like json or xml are great to keep data visible,
+  but due to their parse and pack complexity they aren't used in embedded applications.
+  There are alternatives like msgpack or Google's protocol buffer, which allow a more
+  binary representation of data, but these protcols are still heavy and developers
+  tend to rather implement their own 'simple' binary protocols instead of porting
+  or using the big ones.
+email: nstrct@256dpi.ch
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- cross_platform_test
+- lib/nstrct.rb
+- lib/nstrct/argument.rb
+- lib/nstrct/frame.rb
+- lib/nstrct/instruction.rb
+- lib/nstrct/version.rb
+- nstrct.gemspec
+- spec/protocol_spec.rb
+- spec/spec_helper.rb
+homepage: http://github.com/nstrct
+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.0.3
+signing_key: 
+specification_version: 4
+summary: a multi-purpose binary protocol for instruction interchange
+test_files:
+- spec/protocol_spec.rb
+- spec/spec_helper.rb