arpie 0.0.6 → 0.1.0

data/.gitignore

@@ -0,0 +1,4 @@
+doc
+pkg
+.yardoc
+Gemfile.lock

data/.yardopts

@@ -0,0 +1 @@
+--no-private lib/**/*.rb - *.rdoc LICENCE

data/{BINARY_SPEC → BINARY.rdoc}

@@ -8,8 +8,8 @@ What a mouthful.
 Let's try with an example:
 
   class MyBinary < Arpie::Binary
-    field :status, :uint8
-    field :name,   :string,  :sizeof => :uint8
+    uint8 :status
+    string :name, :sizeof => :uint8
   end
 
 Looks simple enough, doesn't it?
@@ -27,6 +27,15 @@ This works both ways, of course:
   irb(main):006:0> a[0].to
   => "\001\005Arpie"
 
+== Shorter notation for field definitions
+
+Note that calling
+
+  field :name, :type
+
+is equivalent to
+
+  type :name
 
 == Usage within Arpie::Protocol
 
@@ -83,19 +92,19 @@ You can actually specify a field or virtual that was defined before the currentl
 Example:
 
   class Inner < Arpie::Binary
-    field :sz, :uint8
-    field :ls, :list, :of => :uint8, :length => :sz
+    uint8 :sz
+    list :ls, :of => :uint8, :length => :sz
   end
 
   class Outer < Arpie::Binary
-    field :totalsz, :uint8
+    uint8 :totalsz
 
-    field :bytes, :bytes, :length => :totalsz do
-      field :content, :list, :of => Inner,
+    bytes :bytes, :length => :totalsz do
+      list :content, :of => Inner,
         :length => :all
     end
 
-    field :end, :uint8
+    uint8 :end
   end
 
 Note that fields defined this way will NOT update their "length referral" - you will have to
@@ -105,26 +114,34 @@ do that manually.
 This includes a prefixed "non-visible" field, which will be used to determine the
 actual expected length of the data. Example:
 
-  field :blurbel, :bytes, :sizeof => :lint16
+  bytes :blurbel, :sizeof => :lint16
 
 Will expect a network-order short (16 bits), followed by the amout of bytes the short resolves to.
 
 If the field type given in :sizeof requires additional parameters, you can pass them with
 :sizeof_opts (just like with :list - :of).
 
+=== :mod
+Certain packed types (namely, numerics), allow for :mod, which will apply
+a fixed modificator to the read/written value. Example:
+
+  string :test, :sizeof => :uint8, :sizeof_opts => { :mod => -1 }
+
+This will always cut off the last character.
+
 === :list
 
 A :list is an array of arbitary, same-type elements. The element type is given in the :list-specific
 :of parameter:
 
-  field :my_list, :list, :of => :lint16
+  list :my_list, :of => :lint16
 
 This will complain of not being able to determine the size of the list - pass either a :sizeof,
 or a :length parameter, described as above.
 
 If your :of requires additional argument (a list of lists, for example), you can pass theses with :of_opts:
 
-  field :my_list_2, :list, :sizeof => :uint8, :of => :string,
+  list :my_list_2, :sizeof => :uint8, :of => :string,
     :of_opts => { :sizeof, :nint16 }
 
 === :bitfield
@@ -132,9 +149,9 @@ If your :of requires additional argument (a list of lists, for example), you can
 The bitfield type unpacks one or more bytes into their bit values, for individual addressing:
 
   class TestClass < Arpie::Binary
-    field :flags, :msb_bitfield, :length => 8 do
-      field :bool_1, :bit
-      field :compound, :bit, :length => 7
+    msg_bitfield :flags, :length => 8 do
+      bit :bool_1
+      bit :compound, :length => 7
       # Take care not to leave any bits unmanaged - weird things happen otherwise.
     end
   end
@@ -155,9 +172,15 @@ This is pretty much all that you can do with it, for now.
 The fixed type allows defining fixed strings that are always the same, both acting as a filler
 and a safeguard (it will complain if it does not match):
 
-  field :blah, :fixed, :value => "FIXED"
+  fixed :blah, :value => "FIXED"
+
+The alias Binary.static does this for you, but works slightly different:
+
+  static "aaa" # autogenerates a name with the assumption you don't want to access it
+  static :asdfg, "asdfg"
 
-The alias Binary.static does this for you.
+Fields declared with the "static" alias have a :default value already set, whereas
+fields of the type :fixed do not.
 
 == Nested Classes
 
@@ -165,11 +188,11 @@ Instead of pre-registered primitive data fiels you can pass in class names:
 
   class Outer < Arpie::Binary
     class Nested < Arpie::Binary
-      field :a, :uint8
-      field :b, :uint8
+      uint8 :a
+      uint8 :b
     end
 
-    field :hah, :list, :of => Nested, :sizeof => :uint8
+    list :hah, :of => Nested, :sizeof => :uint8
   end
 
 == Inline Anonymous Classes
@@ -177,9 +200,9 @@ Instead of pre-registered primitive data fiels you can pass in class names:
 Also, you can specify anonymous nested classes, which can be used to split data of the same type more fine-grainedly:
 
   class TestClass < Arpie::Binary
-    field :outer, :bytes, :length => 16 do
-      field :key1, :bytes, :length => 8
-      field :key2, :bytes, :length => 8
+    bytes :outer, :length => 16 do
+      bytes :key1, :length => 8
+      bytes :key2, :length => 8
     end
   end
 
@@ -205,24 +228,24 @@ A virtual is a field definition that is not actually part of the binary data.
 As you get to parse complex data structures, you might encounter the following case:
 
   class TestClass < Arpie::Binary
-    field :len_a, :uint8
-    field :len_b, :uint8
+    uint8 :len_a
+    uint8 :len_b
 
     field :middle, :something
 
-    field :matrix, :list, :of => :uint8, :length => (value of :len_a * :len_b)
+    list :matrix, :of => :uint8, :length => (value of :len_a * :len_b)
   end
 
 In this case, you will need to use a virtual attribute:
 
   class TestClass < Arpie::Binary
-    field :len_a, :uint8
-    field :len_b, :uint8
+    uint8 :len_a
+    uint8 :len_b
 
     field :middle, :something
 
     virtual :v_len, :uint16 do |o| o.len_a * o.len_b end
-    field :hah, :list, :of => Nested, :length => :v_len
+    list :hah, :of => Nested, :length => :v_len
 
     pre_to do |o|
       o.len_a = 4
@@ -235,6 +258,28 @@ virtual attributes are one-way - obviously they cannot be used to write out data
 
 That is what the pre_to is for - it recalculates len_a and len_b to your specifications.
 
+== Self-documenting Arpie::Binary
+
+Every Arpie::Binary is self-documenting, as is this example:
+
+  class Doc < Arpie::Binary
+    describe "a document"
+    string :author, :sizeof => :uint16,
+      :description => "The author"
+    string :text, :sizeof => :uint16,
+      :description => "The document text"
+  end
+
+  puts Doc.describe
+
+Will produce output like this:
+
+  Binary:    a document
+
+  Fields:    NAME                      TYPE            WIDTH           OF              DESCRIPTION
+             author                    string          uint16                          The author
+             text                      string          uint16                          The document text
+
 == hooks
 
 Binary provides several hooks that can be used to mangle data in the transformation process.

data/Gemfile

@@ -0,0 +1,8 @@
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'rake', '>= 0.8.7'
+
+gem 'rspec', :groups => [:development, :test] 
+gem 'yard', :groups => [:development]

data/LICENCE

@@ -0,0 +1,15 @@
+Copyright Bernhard Stoeckner <le@e-ix.net> and contributors. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are
+permitted provided that the following conditions are met:
+
+   1. Redistributions of source code must retain the above copyright notice, this list of
+      conditions and the following disclaimer.
+
+   2. Redistributions in binary form must reproduce the above copyright notice, this list
+      of conditions and the following disclaimer in the documentation and/or other materials
+      provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES,
+INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+FOR A PARTICULAR PURPOSE.

data/PROTOCOLS.rdoc

@@ -0,0 +1,46 @@
+== Writing custom Protocols
+
+You can use arpies Protocol layer to write your custom protocol parser/emitters.
+Consider the following, again very contrived, example. You have a linebased wire format,
+which sends regular object updates in multiple lines, each holding a property to be updated.
+What objects get updated is not relevant to this example.
+
+For this example, we'll be using the SeparatorProtocol already contained in protocols.rb as
+a base.
+
+  class AssembleExample < Arpie::Protocol
+
+    def from binary
+      # The wire format is simply a collection of lines
+      # where the first one is a number containing the
+      # # of lines to expect.
+      assemble! binary do |binaries, meta|
+        binaries.size >= 1 or incomplete!
+        binaries.size - 1 >= binaries[0].to_i or incomplete!
+
+        # Here, you can wrap all collected updates in
+        # whatever format you want it to be. We're just
+        # "joining" them to be a single array.
+        binaries.shift
+        binaries
+      end
+    end
+
+    def to object
+      yield object.size
+      object.each {|oo|
+        yield oo
+      }
+    end
+  end
+
+  p = Arpie::ProtocolChain.new(
+        AssembleExample.new,
+        Arpie::SeparatorProtocol.new
+      )
+  r, w = IO.pipe
+
+  p.write_message(w, %w{we want to be assembled})
+
+  p p.read_message(r)
+  # => ["we", "want", "to", "be", "assembled"]

data/README.rdoc

@@ -0,0 +1,17 @@
+= What's this?
+
+Arpie is a toolkit for handling binary data, network protocols, file formats, and
+similar.
+
+It provides:
+
+- a DSL-like syntax for describing file formats (see {file:BINARY})
+- stackable protocols that can be used to abstract layers of on-wire data (see {file:PROTOCOLS})
+- some bits and glue to put it all together (for example, with eventmachine)
+
+== Getting started
+
+arpie is packaged up as a gem - just do <tt>gem install arpie</tt>
+to get the newest version.
+
+The latest source is available through git[https://github.com/elven/arpie].

data/Rakefile

@@ -1,116 +1,8 @@
-require "rake"
-require "rake/clean"
-require "rake/gempackagetask"
-begin
-  require "hanna/rdoctask"
-rescue LoadError
-  require "rake/rdoctask"
-end
-require "fileutils"
-include FileUtils
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+require 'rspec/core/rake_task'
+require 'yard'
 
-##############################################################################
-# Configuration
-##############################################################################
-NAME = "arpie"
-VERS = "0.0.6"
-CLEAN.include ["**/.*.sw?", "pkg", ".config", "rdoc", "coverage"]
-RDOC_OPTS = ["--quiet", "--line-numbers", "--inline-source", '--title', \
-  "#{NAME}: A high-performing layered networking protocol framework. Simple to use, simple to extend.", \
-  '--main', 'README']
+YARD::Rake::YardocTask.new
 
-DOCS = ["README", "COPYING", "BINARY_SPEC"]
-
-Rake::RDocTask.new do |rdoc|
-  rdoc.rdoc_dir = "rdoc"
-  rdoc.options += RDOC_OPTS
-  rdoc.rdoc_files.add DOCS + ["doc/*.rdoc", "lib/**/*.rb"]
-end
-
-desc "Packages up #{NAME}"
-task :package => [:clean]
-
-spec = Gem::Specification.new do |s|
-  s.name = NAME
-  s.rubyforge_project = "#{NAME}"
-  s.version = VERS
-  s.platform = Gem::Platform::RUBY
-  s.has_rdoc = true
-  s.extra_rdoc_files = DOCS + Dir["doc/*.rdoc"]
-  s.rdoc_options += RDOC_OPTS + ["--exclude", "^(examples|extras)\/"]
-  s.summary = "A high-performing layered networking protocol framework. Simple to use, simple to extend."
-  s.description = s.summary
-  s.author = "Bernhard Stoeckner"
-  s.email = "elven@swordcoast.net"
-  s.homepage = "http://#{NAME}.elv.es"
-  s.executables = []
-  s.required_ruby_version = ">= 1.8.4"
-  s.files = %w(COPYING README Rakefile) + Dir.glob("{bin,doc,spec,lib,tools,scripts,data}/**/*")
-  s.require_path = "lib"
-  s.bindir = "bin"
-  s.add_dependency('uuidtools', '>= 2.0.0')
-end
-
-Rake::GemPackageTask.new(spec) do |p|
-  p.need_tar = true
-  p.gem_spec = spec
-end
-
-desc "Install #{NAME} gem"
-task :install do
-  sh %{rake package}
-  sh %{sudo gem1.8 install pkg/#{NAME}-#{VERS}}
-end
-
-desc "Regenerate proto classes"
-task :protoc do
-  sh %{rprotoc --out=lib/arpie arpie.proto}
-end
-
-desc "Install #{NAME} gem without docs"
-task :install_no_docs do
-  sh %{rake package}
-  sh %{sudo gem1.8 install pkg/#{NAME}-#{VERS} --no-rdoc --no-ri}
-end
-
-desc "Uninstall #{NAME} gem"
-task :uninstall => [:clean] do
-  sh %{sudo gem1.8 uninstall #{NAME}}
-end
-
-desc "Upload #{NAME} gem to rubyforge"
-task :release => [:package] do
-  sh %{rubyforge login}
-  sh %{rubyforge add_release #{NAME} #{NAME} #{VERS} pkg/#{NAME}-#{VERS}.tgz}
-  sh %{rubyforge add_file #{NAME} #{NAME} #{VERS} pkg/#{NAME}-#{VERS}.gem}
-end
-
-require "spec/rake/spectask"
-
-desc "Run specs with coverage"
-Spec::Rake::SpecTask.new("spec") do |t|
-  t.spec_files = FileList["spec/*_spec.rb"]
-  t.spec_opts  = File.read("spec/spec.opts").split("\n")
-  t.rcov_opts  = File.read("spec/rcov.opts").split("\n")
-  t.rcov = true
-end
-
-desc "Run specs without coverage"
-task :default => [:spec_no_cov]
-Spec::Rake::SpecTask.new("spec_no_cov") do |t|
-  t.spec_files = FileList["spec/*_spec.rb"]
-  t.spec_opts  = File.read("spec/spec.opts").split("\n")
-end
-
-desc "Run rcov only"
-Spec::Rake::SpecTask.new("rcov") do |t|
-  t.rcov_opts  = File.read("spec/rcov.opts").split("\n")
-  t.spec_opts  = File.read("spec/spec.opts").split("\n")
-  t.spec_files = FileList["spec/*_spec.rb"]
-  t.rcov = true
-end
-
-desc "check documentation coverage"
-task :dcov do
-  sh "find lib -name '*.rb' | xargs dcov"
-end
+RSpec::Core::RakeTask.new(:spec)

data/arpie.gemspec

@@ -0,0 +1,26 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/arpie/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Bernhard Stoeckner"]
+  gem.email         = ["le@e-ix.net"]
+  gem.description   = %q{Toolkit for handling binary data, network protocols, file formats, and similar}
+  gem.summary       = gem.description
+  gem.homepage      = "https://github.com/elven/arpie"
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "arpie"
+  gem.require_paths = ["lib"]
+  gem.version       = Arpie::VERSION
+
+  gem.post_install_message = "
+    You have installed arpie 0.1.0 or greater. This breaks
+    compatibility with previous versions (0.0.x).
+
+    Specifically, it removes all client/server code, and
+    XMLRPC integration, since EventMachine and similar does
+    all that in a much cleaner and more efficient way.
+  "
+end