boss-protocol 0.0.1 → 0.0.2

data/README.md

@@ -2,26 +2,32 @@
 
 BOSS is acronym for Binary Object Streamable Storage.
 
-The very space-effective, platfomr-independent streamable and traversable typed binary protocol.
-Allow to effectively store small or
-any
-sized
-integers, strings or binary data of any size, floats and doubles, arrays and hashes in a very effective way. It caches
-repeating objects and stores/restores links to objects.
+The very space-effective, platform-independent^ streamable and traversable
+typed binary protocol. Allow to effectively store small or any sized integers,
+strings or binary data of any size, floats and doubles, arrays and hashes in a
+very effective way. It caches repeating objects and stores/restores links to
+objects.
 
-Streamable means that you can use a pipe (tcp/ip, wahtever), put the object at one side and load it on other, one-by-one,
-and caching and links will be restored properly.
+The protocol allow to effectively store texts and binary data of absolutely any
+size, signed integers of absolutely any size, arrays and hashes with no limit
+on items and overall gross size. It is desirable to use build-in compression when
+appropriate.
+
+Streamable means that you can use a pipe (tcp/ip, wahtever), put the object at
+one side and load it on other, one-by-one, and caching and links will be
+restored properly.
 
 Initially, this protocol was intended to be used in secure communications. Its
-main goal was to very effective data sending and is a great replacement for json/boss/whatever. For example, typical
-JSON reduces in size twice with Boss.
+main goal was to very effective data sending and is a great replacement for
+json/boss/whatever. For example, typical JSON reduces in size twice with Boss.
 
 Boss protocol also allow to transparently compress its representations.
 
-*Attention* ruby version is under final development, its streaming support may not work as expected, while the rest
-seem to work just fine.
+*Attention* ruby version is under final development, its streaming support may
+not work as expected, while the rest seem to work just fine.
 
-There are versions in C and Python that are in most part ready.
+There are versions in C and Python that are in most part ready but are parts
+in other systems and need to be extracted first.
 
 ## Installation
 
@@ -37,7 +43,7 @@ Or install it yourself as:
 
     $ gem install boss-protocol
 
-## Usage
+## Simple Usage
 
     1.9.3-p327 :011 > require 'boss-protocol'
      => false
@@ -66,7 +72,42 @@ To use the transparent compression:
     1.9.3-p327 :017 > data == Boss.load(x)
      => true
 
-Streaming docs are in progress. Please wait.
+## Streaming sample
+
+Cehck the code in samples folder.
+
+This sample shows boss object passing between 2 forked processes:
+
+    if fork
+      wr.close
+      if true
+        # You can do it with block:
+        Boss::Parser.new(rd).each { |obj| puts "Got an object: #{obj}" }
+      else
+        # You can do it without block too:
+        input = Boss::Parser.new rd
+        puts "Got an object: #{input.get}" while !input.eof?
+      end
+      rd.close
+      Process.wait
+    else
+      rd.close
+      out = Boss::Formatter.new wr
+      out << ["Foo", "bar"]
+      out.put_compressed "Zz"*62
+      out << ["Hello", "world", "!"]
+      out << { "Thats all" => "folks!" }
+      wr.close
+    end
+
+Boss ways in the sample are identical; second one (with get) may be sometimes
+more convenient, say, to terminate object polling on some condition before eof.
+
+So, all you need is IO-like object that provide io.read(length) and io.write(data) to
+read/write binary data. Usual files, pipes, tcp sockets, stringIO - everything is ok.
+
+The protocol could be very effectively used to form higher level protocols over the
+network as it caches data on the fly and can provide links (if used with
 
 ## Contributing
 

data/boss-protocol.gemspec

@@ -9,7 +9,7 @@ Gem::Specification.new do |gem|
   gem.authors       = ["sergeych"]
   gem.email         = ["real.sergeych@gmail.com"]
   gem.description   = %q{Binary streamable bit-effective protocol to effectively store object tree hierarchies}
-  gem.summary       = %q{Traversable and streamable to some extend protocol supports lists, hashes, caching,
+  gem.summary       = %q{Traversable and streamable to protocol supports lists, hashes, caching,
 compression and more}
   gem.homepage      = ""
 

data/lib/boss-protocol.rb

@@ -44,8 +44,12 @@ require 'bzip2'
 # No object serialization yet, no callables and bound methods - these appear to be
 # non portable between platoforms.
 #
+# Please note that most of this code was developed in 2008 so it is kind of old ;)
+# though working.
+
 module Boss
-  # Basic types
+
+                # Basic types
   TYPE_INT   = 0
   TYPE_EXTRA = 1
   TYPE_NINT  = 2
@@ -104,6 +108,10 @@ module Boss
       @cache = { nil => 0 }
     end
 
+    ##
+    # same as put but automatically select and use proper compression. Parser.get
+    # will automatically decompress.
+    #
     def put_compressed ob
       data = Boss.dump(ob)
       whdr TYPE_EXTRA, TCOMPRESSED
@@ -186,10 +194,9 @@ module Boss
 
     ##
     # Get the result as string, may not work if
-    # some specific IO instance is passsed to constructor.
-    # works well with default contructor or StringIO
+    # some specific IO instance is passed to constructor.
+    # works well with default constructor or StringIO
     def string
-      #      p "string!! #{@io.string}"
       @io.string
     end
 
@@ -261,7 +268,7 @@ module Boss
     # write binary value
     #
     def wbin(bb)
-      @io.syswrite bb
+      @io.write bb
     end
 
     ##
@@ -273,12 +280,10 @@ module Boss
     def wdouble val
       wbin [val].pack('E')
     end
-
-
   end
 
   ##
-  # Parser incapsulates IO-like cource and provides deserializing of
+  # Parser implements IO-like behavior and provides deserializing of
   # BOSS objects. Parser can store multiple root objects and share same
   # object cache for all them
   class Parser
@@ -305,9 +310,9 @@ module Boss
       code, value = rhdr
       case code
         when TYPE_INT
-          return value
+          value
         when TYPE_NINT
-          return -value
+          -value
         when TYPE_EXTRA
           case value
             when TTRUE
@@ -342,18 +347,18 @@ module Boss
           s = rbin value
           s.force_encoding code == TYPE_BIN ? Encoding::BINARY : Encoding::UTF_8
           @cache << s
-          return s
+          s
         when TYPE_LIST
           #        p "items", value
           @cache << (list = [])
           value.times { list << get }
-          return list
+          list
         when TYPE_DICT
           @cache << (dict = { })
           value.times { dict[get] = get }
-          return dict
+          dict
         when TYPE_CREF
-          return @cache[value]
+          @cache[value]
         else
           raise UnknownTypeException
       end
@@ -368,7 +373,6 @@ module Boss
     ##
     # yields all objects in the stream
     def each
-      @io.rewind
       yield get until eof?
     end
 
@@ -421,8 +425,12 @@ module Boss
       rbin(8).unpack('E')[0]
     end
 
+    def rfloat
+      rbin(4).unpack('e')[0]
+    end
+
     def rbin(length)
-      @io.sysread length
+      @io.read length
     end
   end
 
@@ -462,6 +470,10 @@ module Boss
     f.string
   end
 
+  ##
+  # Just like Boss.dump but automatically use proper compression
+  # depending on the data size. Boss.load or Boss.load_all will
+  # automatically decompress the data
   def Boss.dump_compressed(*roots)
     f = f = Formatter.new
     roots.each { |r| f.put_compressed r }

data/lib/boss-protocol/version.rb

@@ -1,3 +1,3 @@
 module Boss
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

data/samples/testp.rb

@@ -0,0 +1,25 @@
+require '../lib/boss-protocol'
+
+rd, wr = IO.pipe
+
+if fork
+  wr.close
+  if false
+    # You can do it with block:
+    Boss::Parser.new(rd).each { |obj| puts "Got an object: #{obj}" }
+  else
+    # You can do it without block too:
+    input = Boss::Parser.new rd
+    puts "Got an object: #{input.get}" while !input.eof?
+  end
+  rd.close
+  Process.wait
+else
+  rd.close
+  out = Boss::Formatter.new wr
+  out << ["Foo", "bar"]
+  out.put_compressed "Zz"*62
+  out << ["Hello", "world", "!"]
+  out << { "Thats all" => "folks!" }
+  wr.close
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: boss-protocol
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -60,6 +60,7 @@ files:
 - boss-protocol.gemspec
 - lib/boss-protocol.rb
 - lib/boss-protocol/version.rb
+- samples/testp.rb
 - spec/boss_spec.rb
 - spec/spec_helper.rb
 homepage: ''
@@ -85,8 +86,8 @@ rubyforge_project:
 rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
-summary: Traversable and streamable to some extend protocol supports lists, hashes,
-  caching, compression and more
+summary: Traversable and streamable to protocol supports lists, hashes, caching, compression
+  and more
 test_files:
 - spec/boss_spec.rb
 - spec/spec_helper.rb