libcbor 0.1.0.pre.alpha → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 72e98b82d68080ed07cff8821dc4a1416bc3a9f4
-  data.tar.gz: 99c9cfbfd0952ce27307a538c2983f2e8a0831f0
+  metadata.gz: 524d81700b2d1815f92ece4273209b6f45810944
+  data.tar.gz: ac5b8b07b2e7084fc8f2ff7c5788215106681423
 SHA512:
-  metadata.gz: d7e39fb6fa4221c4bc220612b6b1b65e9f572e19723dfb83dcff4d51d3caa75c86dd667dc9570b506cf386115280a1ce7154c313a8f67aaf37d74cdde468b622
-  data.tar.gz: 5f03642c8f5505fa28a2a950e4706b59333e840cf3fa274511de0aef460fecc3e2f120b4bce89af9183e151ed628384bbbc5ba487d8e0c5611d36bfca37f290c
+  metadata.gz: 6ffd0d3137cdd3334fc547de1b1a882937bcbaa2c54483be4e9ad832a02a4416980690e02da5f178cd69269217cdfd4efd0c2f15a1dfb0afd129b673fe5250e0
+  data.tar.gz: bacc20d6e15f56bc2d17474bbdab5ed299425db510a13236d0682402cbf09f9d5bd5211a451dafdf68d1e7b9056c56a8a0c5da97711f65650e1d1a6e7167a758

data/.travis.yml

@@ -1,16 +1,24 @@
 language: ruby
 rvm:
-  - jruby
-  - rbx-2.1.1
+  #- rbx-2.1.1
   - 2.0.0
   - 2.1.1
   - 2.2.1
 script: bundle exec rspec spec
 before_install:
-  - wget https://github.com/PJK/libcbor/archive/master.zip
-  - unzip master.zip
-  - cd libcbor-master
+  - sudo add-apt-repository ppa:ubuntu-toolchain-r/test -y
+  - sudo apt-get update -qq
+  - sudo apt-get -qq install gcc-4.9
+  - sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-4.9 90
+  - git clone https://github.com/PJK/libcbor.git
+  - cd libcbor
+  - git submodule update --init test/cmocka
+  - cd test
+  - mkdir cmocka_build && cd cmocka_build
+  - cmake ../cmocka
+  - make -j 4
+  - sudo make install
+  - cd ../..
   - cmake .
-  - make cbor cbor_shared
   - sudo make install
   - cd ..

data/.yardopts

@@ -0,0 +1 @@
+yardoc lib/**/*rb -M redcarpet

data/README.md

@@ -1,11 +1,21 @@
 # libcbor
 
-The Ruby bindings for [libcbor](https://github.com/PJK/libcbor)
+[![Build Status](https://travis-ci.org/PJK/libcbor-ruby.svg?branch=master)](https://travis-ci.org/PJK/libcbor-ruby)
+[![Coverage Status](https://coveralls.io/repos/PJK/libcbor-ruby/badge.svg?branch=master)](https://coveralls.io/r/PJK/libcbor-ruby?branch=master)
 
+The Ruby bindings for [libcbor](https://github.com/PJK/libcbor). Provides [CBOR](http://cbor.io/)
+encoding and decoding features, including streaming.
+
+## Important resources
+
+ - [libcbor](http://libcbor.org/)
+ - [API reference](http://www.rubydoc.info/gems/libcbor/)
+ - [git repository](https://github.com/PJK/libcbor-ruby)
+ - [rubygems.org page](https://rubygems.org/gems/libcbor)
 
 ## Installation
 
-Make sure that `libffi-dev` is present on your system.
+Make sure that `libffi-dev` and `libcbor` are present on your system.
 
 Add this line to your application's Gemfile:
 
@@ -23,12 +33,90 @@ Or install it yourself as:
 
 ## Usage
 
+Include the library using
+
+```ruby
+include 'libcbor/all'
+```
+
+You can then encode objects
+
+```ruby
+{ 'key' => 42 }.to_cbor
+# => "\xA1ckey\x18*"
+```
+
+... as well as decode serialized data
+
+```ruby
+CBOR.decode("\xA1ckey\x18*")
+# => {"key"=>42}
+```
+
+*libcbor* also comes with streaming features. When decoding, you can specify
+callbacks and handle the input as desired. The following example illustrates
+how to integrate *libcbor* with [EventMachine](https://github.com/eventmachine/eventmachine):
+
+```ruby
+#!/usr/bin/env ruby
+
+# Listens for connections, asynchronously receives data, replies with
+# pretty-printed arrays (works for indefinite arrays with integers only for
+# the sake of simplicity)
+#
+# Make sure to install EventMachine first (`$ gem install eventmachine`)
+#
+# Start with
+# $ ./examples/network_streaming.rb
+#
+# Then send data from the example file using netcat or a similar tool:
+# $ netcat localhost 9000 < examples/data/indef_array.cbor
+#
+# The file from the example contains the CBOR representation of
+#   [_ [_ 1, 2], 3, [_ 4, [_ 5]]]
+# Terminate with ^c
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..'))
+require 'lib/libcbor'
+require 'rubygems'
+require 'eventmachine'
+
+class CBORPrinter < EM::Connection
+	def print(what)
+		send_data('  ' * @nesting + what.to_s + "\n")
+	end
+
+	def initialize
+		@nesting = 0
+		@reader = CBOR::Streaming::BufferedDecoder.new(
+			array_start: ->() { print '['; @nesting += 1 },
+			integer: ->(val) { print val },
+			break: ->() {
+				@nesting -= 1; print ']'
+				close_connection_after_writing if @nesting == 0
+			}
+		)
+	end
+
+	def receive_data(data)
+		@reader << data
+	end
+end
+
+EventMachine.run do
+	Signal.trap('INT')  { EventMachine.stop }
+	EventMachine.start_server('0.0.0.0', 9000, CBORPrinter)
+end
+```
+
+Streaming encoding is possible as well. Check out the `examples` directory and the
+[documentation]() for more examples.
 
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `bin/console` for an interactive prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release` to create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`.
 
 ## Contributing
 
@@ -37,3 +125,16 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create a new Pull Request
+
+
+## License
+
+The MIT License (MIT)
+
+Copyright (c) Pavel Kalvoda, 2015
+
+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/bin/console

@@ -1,14 +1,12 @@
 #!/usr/bin/env ruby
 
 require "bundler/setup"
-require "libcbor"
+require "libcbor/all"
 
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.
 
 # (If you use this, don't forget to add pry to your Gemfile!)
-# require "pry"
-# Pry.start
+require "pry"
+Pry.start
 
-require "irb"
-IRB.start

data/examples/converter.rb

@@ -0,0 +1,38 @@
+#!/usr/bin/env ruby
+
+# CBOR <-> JSON converter. Works for compatible constructs only.
+# Make sure to install trollop (`$ gem install trollop`) before using this.
+#
+# Usage:
+# $ cat examples/data/indef_array.cbor | ./examples/converter.rb | ./examples/converter.rb --to-cbor | ./examples/converter.rb
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..'))
+require 'lib/libcbor/all'
+require 'trollop'
+require 'json'
+
+opts = Trollop::options do
+	banner <<-EOS
+Converts between JSON and CBOR. Uses STDIN and STDOUT for I/O
+
+Usage:
+       converter [options]
+
+where [options] are:
+	EOS
+
+	opt :to_json,
+		'Convert from CBOR to JSON. Otherwise, convert from JSON to CBOR',
+		default: true
+	opt :to_cbor,
+		'Convert from JSON to CBOR',
+		default: false
+end
+opts[:to_json] = !opts[:to_cbor]
+
+if opts[:to_json]
+	puts CBOR.decode($stdin.read).to_json
+else
+	print CBOR.encode(JSON.load($stdin.read))
+end
+

data/examples/data/indef_array.cbor

@@ -0,0 +1 @@
+��
������

data/examples/load_file.rb

@@ -8,4 +8,4 @@ $LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..'))
 require 'lib/libcbor'
 require 'pp'
 
-ARGV.each { |_| PP.pp  CBOR.decode(IO.read(_)) }
+ARGV.each { |_| PP.pp CBOR.decode(IO.read(_)) }

data/examples/network_streaming.rb

@@ -0,0 +1,49 @@
+#!/usr/bin/env ruby
+
+# Listens for connections, asynchronously receives data, replies with
+# pretty-printed arrays (works for indefinite arrays with integers only for
+# the sake of simplicity)
+#
+# Make sure to install EventMachine first (`$ gem install eventmachine`)
+#
+# Start with
+# $ ./examples/network_streaming.rb
+#
+# Then send data from the example file using netcat or a similar tool:
+# $ netcat localhost 9000 < examples/data/indef_array.cbor
+#
+# The file from the example contains the CBOR representation of
+#   [_ [_ 1, 2], 3, [_ 4, [_ 5]]]
+# Terminate with ^c
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..'))
+require 'lib/libcbor'
+require 'rubygems'
+require 'eventmachine'
+
+class CBORPrinter < EM::Connection
+	def print(what)
+		send_data('  ' * @nesting + what.to_s + "\n")
+	end
+
+	def initialize
+		@nesting = 0
+		@reader = CBOR::Streaming::BufferedDecoder.new(
+			array_start: ->() { print '['; @nesting += 1 },
+			integer: ->(val) { print val },
+			break: ->() {
+				@nesting -= 1; print ']'
+				close_connection_after_writing if @nesting == 0
+			}
+		)
+	end
+
+	def receive_data(data)
+		@reader << data
+	end
+end
+
+EventMachine.run do
+	Signal.trap('INT')  { EventMachine.stop }
+	EventMachine.start_server('0.0.0.0', 9000, CBORPrinter)
+end

data/lib/libcbor.rb

@@ -8,33 +8,59 @@ require 'libcbor/inner/lib_cbor'
 require 'libcbor/inner/lib_c'
 require 'libcbor/cache'
 require 'libcbor/tag'
+require 'libcbor/simple_value'
+require 'libcbor/byte_string'
 require 'libcbor/helpers'
-require 'libcbor/cbor_item'
+require 'libcbor/item'
+require 'libcbor/streaming'
 require 'libcbor/streaming/callback_simplifier'
 require 'libcbor/streaming/buffered_decoder'
 require 'libcbor/streaming/encoder'
 
+# Provides encoding, decoding, and streaming interaction with CBOR data.
+# Please refer to {file:README.md} for an overview and a short tutorial.
 module CBOR
+	# Thrown when the decoded data is either invalid or not well-formed
 	class DecodingError < StandardError; end
 
-	def self.encode(obj)
-		obj.to_cbor
+	# Encodes the given object to CBOR representation
+	# Custom semantics are supported - the object has to to provide the +to_cbor+ method
+	# In case {CBOR.method_name} is not +to_cbor+, provide the custom method instead.
+	#
+	# @param [Fixnum, String, Float, Array, Map, Tag, TrueClass, FalseClass, NilClass, #to_cbor] object the object to encode
+	# @return [String] the CBOR representation
+	def self.encode(object)
+		object.to_cbor
 	end
 
-	def method_name
+	# The name of the method that is used for encoding objects. Defaults to +:to_cbor+
+	#
+	# @return [Symbol] the method name
+	def self.method_name
 		@@method_name
 	end
 
+	# Load the extensions for the core classes
+	#
+	# @param [Symbol] name the name to use for the encoding method. If not provided, +to_cbor+ will be used
+	# @return [Array] list of the patched classes
 	def self.load!(name = nil)
-		@@method_name = name
-		%w{Fixnum Float Array Hash String TrueClass FalseClass NilClass Tag}.each do |klass|
-			const_get(klass).send(:include, const_get('::CBOR::' + klass + 'Helper'))
+		@@method_name = name || :to_cbor
+		%w{Fixnum Float Array Hash String TrueClass FalseClass NilClass Tag ByteString}.each do |klass|
+			kklass = const_get(klass)
+			kklass.send(:include, const_get('::CBOR::' + klass + 'Helper'))
+			kklass.send(:alias_method, method_name, :__libcbor_to_cbor)
 		end
 	end
 
+	# Deserialize CBOR
+	#
+	# @param [String] data
+	# @return [Fixnum, String, Float, Array, Map, Tag, TrueClass, FalseClass, NilClass] resulting object
+	# @raise [DecodingError] when presented with invalid data
 	def self.decode(data)
 		res = FFI::MemoryPointer.new LibCBOR::CborLoadResult
-		CBORItem.new(
+		Item.new(
 			LibCBOR.cbor_load(FFI::MemoryPointer.from_string(data), data.bytes.count, res).
 				tap { |ptr| raise DecodingError if ptr.null? }
 		).value

data/lib/libcbor/all.rb

@@ -0,0 +1,5 @@
+# Convenience include helper. Enables
+#		require 'libcbor/all'
+
+require 'libcbor'
+CBOR.load!

data/lib/libcbor/byte_string.rb

@@ -0,0 +1,5 @@
+module CBOR
+	# Represents CBOR byte strings, as opposed to default string
+	class ByteString < ::String
+	end
+end

data/lib/libcbor/cache.rb

@@ -3,22 +3,38 @@ module CBOR
 	class Cache
 		@@bfr = FFI::Buffer.new(:uchar, 1)
 
+		# Returns encoded equivalent
+		#
+		# @param [Bool] +true+ or +false+
+		# @return [String] The CBOR equivalent
 		def self.get_bool(val)
 			@@bfr.get_bytes(0, LibCBOR.cbor_encode_bool(val, @@bfr, 1))
 		end
 
+		# Returns encoded null (+nil+) equivalent
+		#
+		# @return [String] The CBOR equivalent
 		def self.get_null
 			@@bfr.get_bytes(0, LibCBOR.cbor_encode_null(@@bfr, 1))
 		end
 
+		# Returns cached encoded +true+ equivalent
+		#
+		# @return [String] The CBOR equivalent
 		def self.true
 			@@true ||= get_bool(true)
 		end
 
+		# Returns cached encoded +false+ equivalent
+		#
+		# @return [String] The CBOR equivalent
 		def self.false
 			@@false ||= get_bool(false)
 		end
 
+		# Returns cached encoded +nil+ equivalent
+		#
+		# @return [String] The CBOR equivalent
 		def self.nil
 			@@null ||= get_null
 		end

data/lib/libcbor/helpers.rb

@@ -1,6 +1,10 @@
 module CBOR
+	# Provides the {#to_cbor} (or equivalent) method for Fixnums
 	module FixnumHelper
-		def to_cbor
+		# Encodes Fixnums. Width and signedness are handled automatically.
+		#
+		# @return [String] The CBOR representation
+		def __libcbor_to_cbor
 			@@bfr ||= FFI::Buffer.new(:uchar, 9)
 			if self >= 0
 				@@bfr.get_bytes(0, LibCBOR.cbor_encode_uint(self, @@bfr, 9))
@@ -10,15 +14,26 @@ module CBOR
 		end
 	end
 
+	# Provides the {#to_cbor} (or equivalent) method for Floats
 	module FloatHelper
-		def to_cbor
+		# Encodes Floatss. Width and precision are handled automatically
+		#
+		# @return [String] The CBOR representation
+		def __libcbor_to_cbor
 			@@bfr ||= FFI::Buffer.new(:uchar, 9)
 			@@bfr.get_bytes(0, LibCBOR.cbor_encode_single(self, @@bfr, 9))
 		end
 	end
 
+	# Provides the {#to_cbor} (or equivalent) method for Stringss
 	module StringHelper
-		def to_cbor
+		# Encodes Strings. The result is always a definite string.
+		#
+		# The string is assumed to be a valid UTF-8 string. The precondition
+		# is not verified.
+		#
+		# @return [String] The CBOR representation
+		def __libcbor_to_cbor
 			@@item ||= LibCBOR.cbor_new_definite_string
 			string = FFI::MemoryPointer.from_string(self)
 			out_bfr = FFI::MemoryPointer.new :pointer
@@ -31,51 +46,99 @@ module CBOR
 		end
 	end
 
+
+	module ByteStringHelper
+		# Encodes {ByteString}s. The result is always a definite string.
+		#
+		# @return [String] The CBOR representation
+		def __libcbor_to_cbor
+			@@item ||= LibCBOR.cbor_new_definite_bytestring
+			string = FFI::MemoryPointer.from_string(self)
+			out_bfr = FFI::MemoryPointer.new :pointer
+			out_bfr_len = FFI::MemoryPointer.new :size_t
+			LibCBOR.cbor_bytestring_set_handle(@@item, string, bytes.length)
+			res_len = LibCBOR.cbor_serialize_alloc(@@item, out_bfr, out_bfr_len)
+			out_bfr.read_pointer.get_bytes(0, res_len).tap do
+				LibC.free(out_bfr.read_pointer)
+			end
+		end
+	end
+
+	# Provides the {#to_cbor} (or equivalent) method for Arrayss
 	module ArrayHelper
-		def to_cbor
+		# Encodes Arrayss. The resulting item is always a definite array.
+		#
+		# The members are encoded recursively using the +to_cbor+ method or its equivalent
+		#
+		# @return [String] The CBOR representation
+		def __libcbor_to_cbor
 			@@bfr ||= FFI::Buffer.new(:uchar, 9)
 			header = @@bfr.get_bytes(0, LibCBOR.cbor_encode_array_start(count, @@bfr, 9))
 			each do |member|
-				header += member.to_cbor
+				header += member.public_send(CBOR.method_name)
 			end
 			header
 		end
 	end
 
+	# Provides the {#to_cbor} (or equivalent) method for Hashes
 	module HashHelper
-		def to_cbor
+		# Encodes Hashes. The resulting item is always a definite map.
+		#
+		# The members are encoded recursively using the +to_cbor+ method or its equivalent
+		#
+		# @return [String] The CBOR representation
+		def __libcbor_to_cbor
 			@@bfr ||= FFI::Buffer.new(:uchar, 9)
 			header = @@bfr.get_bytes(0, LibCBOR.cbor_encode_map_start(count, @@bfr, 9))
 			each do |member|
-				header += member.first.to_cbor
-				header += member.last.to_cbor
+				header += member.first.public_send(CBOR.method_name)
+				header += member.last.public_send(CBOR.method_name)
 			end
 			header
 		end
 	end
 
+	# Provides the {#to_cbor} (or equivalent) method for Tags
 	module TagHelper
-		def to_cbor
+		# Encodes Tags.
+		#
+		# The {Tag#item} is encoded recursively using the +to_cbor+ method or its equivalent
+		#
+		# @return [String] The CBOR representation
+		def __libcbor_to_cbor
 			@@bfr ||= FFI::Buffer.new(:uchar, 9)
 			header = @@bfr.get_bytes(0, LibCBOR.cbor_encode_tag(value, @@bfr, 9))
-			header + item.to_cbor
+			header + item.public_send(CBOR.method_name)
 		end
 	end
 
+	# Provides the {#to_cbor} (or equivalent) method for +true+
 	module TrueClassHelper
-		def to_cbor
+		# Encodes +true+s.
+		#
+		# @return [String] The CBOR representation
+		def __libcbor_to_cbor
 			Cache.true
 		end
 	end
 
+	# Provides the {#to_cbor} (or equivalent) method for +false+
 	module FalseClassHelper
-		def to_cbor
+		# Encodes +false+s.
+		#
+		# @return [String] The CBOR representation
+		def __libcbor_to_cbor
 			Cache.false
 		end
 	end
 
+	# Provides the {#to_cbor} (or equivalent) method for +nil+
 	module NilClassHelper
-		def to_cbor
+		# Encodes +nil+s.
+		#
+		# @return [String] The CBOR representation
+		def __libcbor_to_cbor
 			Cache.nil
 		end
 	end

data/lib/libcbor/inner/lib_c.rb

@@ -1,4 +1,4 @@
-# Provides
+# Provides native memory management
 module CBOR::LibC
 	extend FFI::Library
 	ffi_lib FFI::Library::LIBC

data/lib/libcbor/inner/lib_cbor.rb

@@ -1,25 +1,36 @@
 module CBOR
+	# Provides low-level binding for the native functions
 	module LibCBOR
 		extend FFI::Library
-		ffi_lib 'cbor'
+		ffi_lib ['cbor', 'libcbor.so.1', '/usr/local/lib/libcbor.so']
 
+		# The +cbor_item_t *+ handle type
 		CborItemTRef = typedef :pointer, :cbor_item_t_ref
+
+		# The CBOR types enum mapping
+		Type = enum(:uint, :negint, :bytestring, :string, :array, :map, :tag, :float_ctrl)
+
+
 		typedef :pointer, :cbor_item_t_ref_array
 		typedef :pointer, :buffer
 		typedef :pointer, :memblock # unsigned char * - string & bytestring handles, raw blocks
 
+		# Possible error codes for the +cbor_error+
 		ErrorCode = enum(:none, :notenoughdata, :nodata, :malformated, :memerror, :syntaxerror)
 
+		# Represents +cbor_error+ decoding error
 		class CborError < FFI::Struct
 			layout :position, :size_t,
 				:code, ErrorCode
 		end
 
+		# Represents +cbor_load_result+ struct
 		class CborLoadResult < FFI::Struct
 			layout :error, CborError,
 				:read, :size_t
 		end
 
+		# Represents +cbor_pair+ for map manipualtion
 		class CborPair < FFI::Struct
 			layout :key, CborItemTRef,
 				:value, CborItemTRef
@@ -44,10 +55,11 @@ module CBOR
 		attach_function :cbor_serialize_alloc, [:pointer, :pointer, :pointer], :size_t
 
 		attach_function :cbor_new_definite_string, [], :pointer
+		attach_function :cbor_new_definite_bytestring, [], :pointer
 		# void cbor_string_set_handle(cbor_item_t *item, unsigned char *data, size_t length);
 		attach_function :cbor_string_set_handle, [:pointer, :pointer, :size_t], :void
+		attach_function :cbor_bytestring_set_handle, [:pointer, :pointer, :size_t], :void
 
-		Type = enum(:uint, :negint, :bytestring, :string, :array, :map, :tag, :float_ctrl)
 
 		attach_function :cbor_typeof, [:cbor_item_t_ref], Type
 		attach_function :cbor_load, [:buffer, :size_t, :cbor_load_result_ref], :cbor_item_t_ref
@@ -56,9 +68,15 @@ module CBOR
 
 		attach_function :cbor_string_length, [:cbor_item_t_ref], :size_t
 		attach_function :cbor_string_handle, [:cbor_item_t_ref], :memblock
+		attach_function :cbor_string_is_definite, [:cbor_item_t_ref], :bool
+		attach_function :cbor_string_chunks_handle, [:cbor_item_t_ref], :cbor_item_t_ref_array
+		attach_function :cbor_string_chunk_count, [:cbor_item_t_ref], :size_t
 
 		attach_function :cbor_bytestring_length, [:cbor_item_t_ref], :size_t
 		attach_function :cbor_bytestring_handle, [:cbor_item_t_ref], :memblock
+		attach_function :cbor_bytestring_is_definite, [:cbor_item_t_ref], :bool
+		attach_function :cbor_bytestring_chunks_handle, [:cbor_item_t_ref], :cbor_item_t_ref_array
+		attach_function :cbor_bytestring_chunk_count, [:cbor_item_t_ref], :size_t
 
 		attach_function :cbor_array_size, [:cbor_item_t_ref], :size_t
 		attach_function :cbor_array_handle, [:cbor_item_t_ref], :cbor_item_t_ref_array
@@ -84,6 +102,7 @@ module CBOR
 		callback :cbor_double_callback, [:pointer, :double], :void
 		callback :cbor_bool_callback, [:pointer, :bool], :void
 
+		# The +cbor_callbacks+ callback bundle equivalent
 		class CborCallbacks < FFI::Struct
 			layout :uint8, :cbor_int8_callback,
 				:uint16, :cbor_int16_callback,
@@ -120,8 +139,10 @@ module CBOR
 				:indef_break, :cbor_simple_callback
 		end
 
+		# High-level decoder status enum mapping
 		DecoderStatus = enum(:finished, :not_enough_data, :buffer_error, :error)
 
+		# Represents +cbor_decoder_result+ struct
 		class CborDecoderResult < FFI::Struct
 			layout :read, :size_t,
 				:status, DecoderStatus

data/lib/libcbor/item.rb

@@ -0,0 +1,119 @@
+module CBOR
+	# Wraps native +cbor_item_t *+ to allow extracting Ruby objects
+	#
+	# Takes responsibility for high-level native interfacing and object
+	# lifetime management.
+	#
+	# @attr [FFI::Pointer] handle Native memory handle
+	class Item < Struct.new(:handle)
+		# Type of the underlying item
+		#
+		# @return [Symbol] one of {LibCBOR::Type}
+		def type
+			LibCBOR.cbor_typeof(handle)
+		end
+
+		# Ruby representation of the {Item}
+		#
+		# Arrays and hash maps are constructed recursively
+		#
+		# @return [Fixnum, String, Float, Array, Map, Tag, TrueClass, FalseClass, NilClass] Value extracted from the {#handle}
+		def value
+			case type
+				when :uint
+					LibCBOR.cbor_get_int(handle)
+				when :negint
+					-LibCBOR.cbor_get_int(handle) - 1
+				when :string
+					load_string
+				when :bytestring
+					load_bytestring
+				when :array
+					LibCBOR
+						.cbor_array_handle(handle)
+						.read_array_of_type(LibCBOR::CborItemTRef, :read_pointer, LibCBOR.cbor_array_size(handle))
+						.map { |item| Item.new(item).value }
+				when :map
+					pairs_handle = LibCBOR.cbor_map_handle(handle)
+					Hash[LibCBOR.cbor_map_size(handle).times.map { |idx|
+						pair = LibCBOR::CborPair.new(pairs_handle + LibCBOR::CborPair.size * idx)
+						[pair[:key], pair[:value]].map { |ptr| Item.new(ptr).value }
+					}]
+				when :tag
+					Tag.new(
+						LibCBOR.cbor_tag_value(handle),
+						Item.new(LibCBOR.cbor_tag_item(handle)).value
+					)
+				when :float_ctrl
+					load_float
+				else
+					raise 'Unknown type - the FFI enum mapping is probably broken. Please report this bug.'
+			end
+		end
+
+		protected
+
+		# Loads float, doesn't check the type
+		#
+		# @return [Float] the result
+		def load_float
+			if LibCBOR.cbor_float_ctrl_is_ctrl(handle)
+				case ctr_val = LibCBOR.cbor_ctrl_value(handle)
+					when 20
+						false
+					when 21
+						true
+					when 22
+						nil
+					else
+						SimpleValue.new(ctr_val)
+				end
+			else
+				LibCBOR.cbor_float_get_float(handle)
+			end
+		end
+
+		# Loads string, doesn't check the type
+		#
+		# If the underlying string is indefinite, the concatenation of its chunks is returned
+		#
+		# @return [String] the result
+		def load_string
+			if LibCBOR.cbor_string_is_definite(handle)
+				LibCBOR
+					.cbor_string_handle(handle)
+					.get_string(0, LibCBOR.cbor_string_length(handle))
+			else
+				LibCBOR
+					.cbor_string_chunks_handle(handle)
+					.read_array_of_type(LibCBOR::CborItemTRef, :read_pointer, LibCBOR.cbor_string_chunk_count(handle))
+					.map { |item| Item.new(item).value }
+					.join
+				end
+		end
+
+		# Loads byte string, doesn't check the type
+		#
+		# If the underlying string is indefinite, the concatenation of its chunks is returned
+		#
+		# @return [String] the result
+		def load_bytestring
+			# TODO: DRY - load_string
+			if LibCBOR.cbor_bytestring_is_definite(handle)
+				ByteString.new(
+					LibCBOR
+						.cbor_bytestring_handle(handle)
+						.get_string(0, LibCBOR.cbor_bytestring_length(handle))
+				)
+			else
+				ByteString.new(
+					LibCBOR
+						.cbor_bytestring_chunks_handle(handle)
+						.read_array_of_type(LibCBOR::CborItemTRef, :read_pointer, LibCBOR.cbor_bytestring_chunk_count(handle))
+						.map { |item| Item.new(item).value }
+						.join
+				)
+			end
+		end
+	end
+end

data/lib/libcbor/simple_value.rb

@@ -0,0 +1,10 @@
+module CBOR
+	# Represents Simple value other than those that have native Ruby mapping
+	class SimpleValue < Struct.new(:value)
+		def ==(other)
+			if other.is_a? SimpleValue
+				other.value == value
+			end
+		end
+	end
+end

data/lib/libcbor/streaming.rb

@@ -0,0 +1,5 @@
+module CBOR
+	# Provides streaming encoding and decoding utilities
+	module Streaming
+	end
+end

data/lib/libcbor/streaming/buffered_decoder.rb

@@ -1,6 +1,27 @@
 module CBOR
 	module Streaming
+		# Decodes a stream of data and invokes the appropriate callbacks
+		#
+		# To use it, just initialize it with the desired set of callbacks and start
+		# feeding data to it. Please see {file:examples/network_streaming.rb} for
+		# an example
 		class BufferedDecoder
+			# @param [Hash] callbacks the callbacks to invoke during parsing.
+			# @option callbacks [Proc<Fixnum>] :integer Integers, both positive and negative
+			# @option callbacks [Proc<String>] :string Definite string
+			# @option callbacks [Proc] :chunked_string_start Chunked string. Chunks follow
+			# @option callbacks [Proc<String>] :byte_string Definite byte string
+			# @option callbacks [Proc] :chunked_byte_string_start Chunked byte string. Chunks follow
+			# @option callbacks [Proc<Float>] :float Float
+			# @option callbacks [Proc<length: Fixnum>] :definite_array Definite array
+			# @option callbacks [Proc] :array_start Indefinite array start
+			# @option callbacks [Proc<length: Fixnum>] :definite_map Definite map. Length pairs follow
+			# @option callbacks [Proc] :map_start Indefinite map start
+			# @option callbacks [Proc<value: Fixnum>] :tag Tag. Tagged item follows
+			# @option callbacks [Proc<Bool>] :bool Boolean
+			# @option callbacks [Proc] :null Null
+			# @option callbacks [Proc<value: Fixnum>] :simple Simple value other than +true, false, nil+
+			# @option callbacks [Proc] :break Indefinite item break
 			def initialize(callbacks = {})
 				@callbacks = {
 					integer: Proc.new {},
@@ -23,20 +44,43 @@ module CBOR
 				@proxy = CallbackSimplifier.new(self)
 			end
 
+			# Append data to the internal buffer.
+			#
+			# Parsing will ensue and all the appropriate callbacks will be invoked.
+			# The method will block until all the callbacks have finished.
+			#
+			# @param [String] data CBOR input data
+			# @return [void]
+			# @raise [DecodingError] if the decoder encountered a invalid input
 			def <<(data)
 				@buffer += data
 				loop do
-					read = LibCBOR.cbor_stream_decode(
+					result = LibCBOR.cbor_stream_decode(
 						FFI::MemoryPointer.from_string(@buffer),
 						@buffer.bytes.length,
 						@proxy.callback_set.to_ptr,
 						nil
-					)[:read]
-					break if read == 0
+					)
+					read = result[:read]
+
+					break if read == 0 && result[:status] == :not_enough_data
+
+					unless result[:status] == :finished
+						raise DecodingError, "Invalid input near byte #{read} of the buffer."
+					end
+
 					@buffer = @buffer[read .. -1]
+
+					break if buffer.empty?
 				end
 			end
 
+			# @api private
+			# Invocation target for the callback proxy. Do not use.
+			#
+			# @param [Symbol] name Callback name
+			# @param [Array] args Arguments to pass on
+			# @return [void]
 			def callback(name, *args)
 				callbacks[name].call(*args)
 			end

data/lib/libcbor/streaming/callback_simplifier.rb

@@ -1,7 +1,12 @@
 module CBOR
 	module Streaming
+		# @api private
 		# Abstracts aways callback specifics, such as integer width
 		class CallbackSimplifier < Struct.new(:target)
+			# Returns the appropriate callback set targeting {#target}. Cached for the
+			# give instance.
+			#
+			# @return [LibCBOR::CborCallbacks] Callback set that enables forwarding
 			def callback_set
 				@cset ||= build_callback_set
 			end

data/lib/libcbor/streaming/encoder.rb

@@ -1,34 +1,79 @@
 module CBOR
 	module Streaming
-		class Encoder < Struct.new(:target)
+		# Provides streaming encoding facilities. Initialize it with an output
+		# object and either feed it encodable objects, or invoke the methods
+		# directly
+		class Encoder
+			# @param [StringIO, Socket, File, #write] stream Output object. Must support
+			#		+write+ method that takes a +String+ as a parametr
+			def initialize(stream)
+				@stream = stream
+			end
+
+			# Serializes and writes an object to the stream
+			#
+			# @param [#to_cbor] object Object to serialize and write
+			# @return [void]
 			def <<(object)
-				target.write(object.to_cbor)
+				stream.write(object.public_send(CBOR.method_name))
 			end
 
+			# Encodes a 'start array' mark. You are responsible for
+			# correctly {#break}ing it
+			#
+			# @return [void]
 			def start_array
-				target.write("\x9f")
+				stream.write("\x9f")
 			end
 
+			# Encodes a 'start map' mark. You are responsible for
+			# correctly {#break}ing it
+			#
+			# @return [void]
 			def start_map
-				target.write("\xbf")
+				stream.write("\xbf")
 			end
 
+			# Encodes a 'start indefinite string' mark. You are responsible
+			# for correctly {#break}ing it
+			#
+			# @return [void]
 			def start_chunked_string
-				target.write("\x9f")
+				stream.write("\x7f")
 			end
 
+			# Encodes a 'start indefinite byte string' mark. You are responsible
+			# for correctly {#break}ing it
+			#
+			# @return [void]
 			def start_chunked_byte_string
-				target.write("\x5f")
+				stream.write("\x5f")
 			end
 
+			# Encodes a tag with the give +value+.
+			#
+			# You are responsible for correctly supplying the item that
+			# follows (i.e. the one the tag will apply to)
+			#
+			# @param [Fixnum] value Tag value.
+			# @return [void]
 			def tag(value)
 				@@bfr ||= FFI::Buffer.new(:uchar, 9)
-				@@bfr.get_bytes(0, LibCBOR.cbor_encode_tag(value, @@bfr, 9))
+				stream.write(
+					@@bfr.get_bytes(0, LibCBOR.cbor_encode_tag(value, @@bfr, 9))
+				)
 			end
 
+			# Encodes indefinite item break code.
+			#
+			# @return [void]
 			def break
-				target.write("\xff")
+				stream.write("\xff")
 			end
+
+			protected
+
+			attr_accessor :stream
 		end
 	end
 end

data/lib/libcbor/tag.rb

@@ -1,4 +1,13 @@
 module CBOR
+	# Represents a tagged item -- a pair of number and the item
+	#
+	# @attr [Fixnum] value The tag value
+	# @attr [Object] item The tagged item
 	class Tag < Struct.new(:value, :item)
+		def ==(other)
+			if other.is_a? Tag
+				value == other.value && item == other.item
+			end
+		end
 	end
 end

data/lib/libcbor/version.rb

@@ -1,3 +1,4 @@
 module CBOR
-  VERSION = "0.1.0-alpha"
+ 	# The current version. It is completely independent of libcbor's version
+  VERSION = '0.1.0'
 end

data/libcbor.gemspec

@@ -6,7 +6,7 @@ require 'libcbor/version'
 Gem::Specification.new do |spec|
   spec.name          = "libcbor"
   spec.version       = CBOR::VERSION
-  spec.authors       = ["PJK"]
+  spec.authors       = ["Pavel Kalvoda"]
   spec.email         = ["me@pavelkalvoda.com"]
 
   spec.summary       = %q{A Ruby binding for libcbor}
@@ -19,10 +19,14 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
 
-  spec.add_development_dependency "bundler", "> 1.8"
+  spec.add_development_dependency "bundler", "> 1.7"
   spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "rspec", "> 3"
   spec.add_development_dependency "pry"
+  spec.add_development_dependency "yard"
+  spec.add_development_dependency "redcarpet"
+  spec.add_development_dependency "coveralls"
+  spec.add_development_dependency "pry-rescue"
 
   spec.add_runtime_dependency "ffi"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: libcbor
 version: !ruby/object:Gem::Version
-  version: 0.1.0.pre.alpha
+  version: 0.1.0
 platform: ruby
 authors:
-- PJK
+- Pavel Kalvoda
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2015-05-09 00:00:00.000000000 Z
+date: 2015-05-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - '>'
       - !ruby/object:Gem::Version
-        version: '1.8'
+        version: '1.7'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '>'
       - !ruby/object:Gem::Version
-        version: '1.8'
+        version: '1.7'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -66,6 +66,62 @@ dependencies:
     - - '>='
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  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: redcarpet
+  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: coveralls
+  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: pry-rescue
+  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: ffi
   requirement: !ruby/object:Gem::Requirement
@@ -92,26 +148,32 @@ files:
 - .gitignore
 - .rspec
 - .travis.yml
+- .yardopts
 - Gemfile
 - README.md
 - Rakefile
 - bin/console
 - bin/setup
+- examples/converter.rb
 - examples/data/floats.cbor
+- examples/data/indef_array.cbor
 - examples/data/indef_string.cbor
 - examples/data/integer.cbor
 - examples/data/map.cbor
 - examples/data/nested_array.cbor
 - examples/data/tagged_date.cbor
 - examples/load_file.rb
+- examples/network_streaming.rb
 - lib/libcbor.rb
+- lib/libcbor/all.rb
+- lib/libcbor/byte_string.rb
 - lib/libcbor/cache.rb
-- lib/libcbor/cbor_item.rb
 - lib/libcbor/helpers.rb
-- lib/libcbor/inner.rb
 - lib/libcbor/inner/lib_c.rb
 - lib/libcbor/inner/lib_cbor.rb
-- lib/libcbor/inner/prealloc.rb
+- lib/libcbor/item.rb
+- lib/libcbor/simple_value.rb
+- lib/libcbor/streaming.rb
 - lib/libcbor/streaming/buffered_decoder.rb
 - lib/libcbor/streaming/callback_simplifier.rb
 - lib/libcbor/streaming/encoder.rb
@@ -132,9 +194,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>'
+  - - '>='
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubyforge_project: 
 rubygems_version: 2.4.6
@@ -142,3 +204,4 @@ signing_key:
 specification_version: 4
 summary: A Ruby binding for libcbor
 test_files: []
+has_rdoc: 

data/lib/libcbor/cbor_item.rb

@@ -1,64 +0,0 @@
-module CBOR
-	# Wraps native `cbor_item_t *`
-	class CBORItem < Struct.new(:handle)
-		def type
-			LibCBOR.cbor_typeof(handle)
-		end
-
-		def value
-			case type
-				when :uint
-					LibCBOR.cbor_get_int(handle)
-				when :negint
-					-LibCBOR.cbor_get_int(handle) - 1
-				when :string
-					LibCBOR
-						.cbor_string_handle(handle)
-						.get_string(0, LibCBOR.cbor_string_length(handle))
-				when :bytestring
-					LibCBOR
-						.cbor_bytestring_handle(handle)
-						.get_string(0, LibCBOR.cbor_bytestring_length(handle))
-				when :array
-					LibCBOR
-						.cbor_array_handle(handle)
-						.read_array_of_type(LibCBOR::CborItemTRef, :read_pointer, LibCBOR.cbor_array_size(handle))
-						.map { |item| CBORItem.new(item).value }
-				when :map
-					pairs_handle = LibCBOR.cbor_map_handle(handle)
-					Hash[LibCBOR.cbor_map_size(handle).times.map { |idx|
-						pair = LibCBOR::CborPair.new(pairs_handle + LibCBOR::CborPair.size * idx)
-						[pair[:key], pair[:value]].map { |ptr| CBORItem.new(ptr).value }
-					}]
-				when :tag
-					Tag.new(
-						LibCBOR.cbor_tag_value(handle),
-						CBORItem.new(LibCBOR.cbor_tag_item(handle)).value
-					)
-				when :float_ctrl
-					load_float
-				else
-					raise 'Unknown type - the FFI enum mapping is probably broken. Please report this bug.'
-			end
-		end
-
-		protected
-
-		def load_float
-			if LibCBOR.cbor_float_ctrl_is_ctrl(handle)
-				case ctr_val = LibCBOR.cbor_ctrl_value(handle)
-					when 20
-						false
-					when 21
-						true
-					when 22
-						nil
-					else
-						ctr_val
-				end
-			else
-				LibCBOR.cbor_float_get_float(handle)
-			end
-		end
-	end
-end

data/lib/libcbor/inner.rb

@@ -1,28 +0,0 @@
-require 'ffi'
-
-module LibC
-	ffi_lib FFI::Library::LIBC
-	extend FFI::Library
-
-	# memory allocators
-	attach_function :malloc, [:size_t], :pointer
-	attach_function :calloc, [:size_t], :pointer
-	attach_function :valloc, [:size_t], :pointer
-	attach_function :realloc, [:pointer, :size_t], :pointer
-	attach_function :free, [:pointer], :void
-
-	# memory movers
-	attach_function :memcpy, [:pointer, :pointer, :size_t], :pointer
-	attach_function :bcopy, [:pointer, :pointer, :size_t], :void
-
-end # module LibC
-
-module Libcbor
-	extend FFI::Library
-	ffi_lib 'cbor'
-	attach_function :cbor_new_int8, [], :pointer
-	attach_function :cbor_set_uint16, [:pointer, :ushort], :void
-	attach_function :cbor_set_uint8, [:pointer, :uchar], :void
-	attach_function :cbor_serialize, [:pointer, :pointer, :size_t], :size_t
-	puts 'yo'
-end

data/lib/libcbor/inner/prealloc.rb

@@ -1,10 +0,0 @@
-# Provides a fixed, pre-allocated pool of common data items
-# that can be used for quickly encoding atomic values without
-# the need for allocation
-module CBOR
-	class Prealloc
-		def initialize
-
-		end
-	end
-end