elia 1.0.0

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Elia Schito
+
+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.rdoc

@@ -0,0 +1,17 @@
+= elia
+
+Description goes here.
+
+== Note on Patches/Pull Requests
+ 
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+== Copyright
+
+Copyright (c) 2009 Elia Schito. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,46 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "elia"
+    gem.summary = %Q{Elia Schito's utility belt}
+    gem.description = %Q{useful stuff...}
+    gem.email = "perlelia@gmail.com"
+    gem.homepage = "http://github.com/elia/elia"
+    gem.authors = ["Elia Schito"]
+    gem.add_development_dependency "rspec", ">= 1.2.9"
+    gem.files = FileList["[A-Z]*", "{lib,spec}/**/*"]
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :spec => :check_dependencies
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "elia #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+1.0.0

data/lib/bit_fields.rb

@@ -0,0 +1,232 @@
+require 'world_logger'
+
+# 
+# BitFields provides a simple way to extract a values from bit fields, 
+# especially if they don't correspond to standard sizes (such as +char+, +int+, 
+# +long+, etc., see <tt>String#unpack</tt> for further informations).
+# 
+# For example the Primary Header of the Telemetry Frame in the ESA PSS
+# Standard has this specification:
+# 
+# 
+#               |                          TRANSFER FRAME PRIMARY HEADER                              |
+#    ___________|_____________________________________________________________________________________|
+#   |SYNC MARKER| FRAME IDENTIFICATION | MASTER  | VIRTUAL |           FRAME DATA FIELD STATUS        |
+#   |           |----------------------| CHANNEL | CHANNEL |------------------------------------------|
+#   |           |Ver. |S/C.|Virt.|Op.Co| FRAME   | FRAME   |2nd head.|Sync|Pkt ord|Seg.  |First Header|
+#   |           | no. | ID | Chn.| Flag| COUNT   | COUNT   |  flag   |flag|flag   |len.ID|  Pointer   |
+#   |           |_____|____|_____|_____|         |         |_________|____|_______|______|____________|
+#   |           |  2  | 10 |  3  |  1  |         |         |    1    |  1 |   1   |   2  |     11     |
+#   |-----------|----------------------|---------|---------|------------------------------------------|
+#   |    32     |          16          |    8    |    8    |                   16                     |
+# 
+# Will become:
+# 
+#   class PrimaryHeader
+#     include BitFields
+#     field :frame_identification, 'n' do
+#       bit_field :version,                  2
+#       bit_field :spacecraft_id,           10
+#       bit_field :virtual_channel,          3
+#       bit_field :op_control_field_flag,    2
+#     end
+#     
+#     field :master_channel_frame_count
+#     field :virtual_channel_frame_count
+#     
+#     field :frame_data_field_status, 'n' do
+#       bit_field :secondary_header_flag,    1
+#       bit_field :sync_flag,                1
+#       bit_field :packet_order_flag,        1
+#       bit_field :segment_length_id,        2
+#       bit_field :first_header_pointer,    11
+#     end
+#   end
+# 
+# 
+# And can be used like:
+# 
+#   packed_ph = [0b10100111_11111111, 11, 23, 0b10100111_11111111].pack('nCCn') # => "\247\377\v\027\247\377"
+# 
+#   ph = PrimaryHeader.new packed_ph
+#   
+#   ph.virtual_channel_frame_count    # => 23
+#   ph.secondary_header_flag          # => 0b1
+#   ph.sync_flag                      # => 0b0
+#   ph.first_header_pointer           # => 0b111_11111111
+#   
+#   ph[:first_header_pointer]         # => 0b111_11111111
+# 
+# 
+# 
+module BitFields
+  
+  # Collects the fields definitions for later parsing
+  attr_reader :fields
+  
+  # Collects the bit_fields definitions for later parsing
+  attr_reader :bit_fields
+  
+  # Collects the full <tt>String#unpack</tt> directive used to parse the raw value.
+  attr_reader :unpack_recipe
+  
+  
+  ##
+  # Defines a field to be extracted with String#unpack from the raw value
+  # 
+  # +name+                         :: the name of the field (that will be used to access it)
+  # +unpack_recipe+                :: the <tt>String#unpack</tt> directive corresponding to this field (optional, defaults to char: "C")
+  # +bit_fields_definitions_block+ :: the block in which +bit_fields+ can be defined (optional)
+  # 
+  # Also defines the attribute reader method
+  # 
+  def field name, unpack_recipe = 'C', &bit_fields_definitions_block
+    include InstanceMethods # when used we include instance methods
+    logger.debug { self.ancestors.inspect }
+    
+    # Setup class "instance" vars
+    @fields        ||= []
+    @bit_fields    ||= {}
+    @unpack_recipe ||= ""
+    
+    # Register the field definition
+    @unpack_recipe << unpack_recipe
+    @fields        << name
+    
+    # Define the attribute reader
+    class_eval "def #{name}; self.attributes[#{name.inspect}]; end;", __FILE__, __LINE__
+    # define_method(name) { self.fields[name] }
+    
+    # There's a bit-structure too?
+    if block_given?
+      @_current_bit_fields = []
+      
+      bit_fields_definitions_block.call
+      
+      @bit_fields[name] = @_current_bit_fields
+      @_current_bit_fields = nil
+    end
+  end
+  
+  ##
+  # Defines a <em>bit field</em> to be extracted from a +field+
+  # 
+  # +name+  :: the name of the bit field (that will be used to access it)
+  # +width+ :: the number of bits from which this value should be extracted
+  # 
+  def bit_field name, width
+    raise "'bit_field' can be used only inside a 'field' block." if @_current_bit_fields.nil?
+    
+    # Register the bit field definition
+    @_current_bit_fields << [name, width]
+    
+    # Define the attribute reader
+    class_eval "def #{name};  self.attributes[#{name.inspect}];      end\n", __FILE__, __LINE__
+    
+    if  width == 1 or name.to_s =~ /_flag$/
+      # Define a question mark method if the size is 1 bit
+      class_eval "def #{name}?; self.attributes[#{name.inspect}] != 0; end\n", __FILE__, __LINE__
+      
+      # returns nil if no substitution happens...
+      if flag_method_name = name.to_s.gsub!(/_flag$/, '?')
+        # Define another question mark method if ends with "_flag"
+        class_eval "alias #{flag_method_name} #{name}?\n", __FILE__, __LINE__
+      end
+    end
+    
+    logger.debug { @_current_bit_fields.inspect }
+  end
+  
+  
+  module InstanceMethods
+    # Contains the raw string
+    attr_reader :raw
+    
+    # caches the bit field values
+    attr_reader :attributes
+    
+    # caches the bin string unpacked values
+    attr_reader :unpacked
+    
+    # Takes the raw binary string and parses it
+    def initialize bit_string
+      parse_bit_fields(bit_string.dup.freeze)
+    end
+    
+    # Makes defined fields accessible like a +Hash+
+    def [](name) 
+      self.attributes[name]
+    end
+    
+    private
+    
+    def eat_right_bits original_value, bits_number
+      # Filter the original value with the 
+      # proper bitmask to get the rightmost bits
+      new_value = original_value & bit_mask(bits_number)
+      
+      # Eat those rightmost bits 
+      # wich we have just consumed
+      remaning = original_value >> bits_number
+      
+      # Return also the remaning bits
+      return new_value, remaning
+    end
+    
+    # Parses the raw value extracting the defined bit fields
+    def parse_bit_fields raw
+      @raw = raw
+      
+      # Setup
+      unpack_recipe = self.class.unpack_recipe
+      logger.debug "Unpacking #{@raw.inspect} with #{unpack_recipe.inspect}"
+      @unpacked     = @raw.unpack(unpack_recipe)
+      @attributes ||= {}
+      
+      logger.debug { "Parsing #{@raw.inspect} with fields #{self.class.fields.inspect}" }
+      self.class.fields.each_with_index do |name, position|
+        logger.debug { "Parsing field #{name.inspect}" }
+        
+        attributes[name] = @unpacked[position]
+        
+        # We must extract bits from end since 
+        # ruby doesn't have types (and fixed lengths)
+        if bit_definitions = self.class.bit_fields[name]
+          logger.debug { "Parsing value #{attributes[name]} with bit fields #{bit_definitions.inspect}" }
+        
+          bit_value = attributes[name]
+          bit_definitions.reverse.each do |bit_field|
+            logger.debug "Parsing bit field: #{bit_field.inspect} current value: #{bit_value} (#{bit_value.to_s 2})"
+            bit_name, bit_size = *bit_field
+            attributes[bit_name], bit_value = eat_right_bits(bit_value, bit_size)
+          
+            logger.debug {
+              "#{bit_name}: #{attributes[bit_name]} 0b#{attributes[bit_name].to_s(2).rjust(16, '0')}"
+            }
+          end
+        end
+      end
+      
+      @parsed = true
+    end
+    
+    def bit_mask size
+      2 ** size - 1
+    end
+    
+    def to_s
+      raw.to_s
+    end
+    
+    def method_missing name, *args
+      if @raw.respond_to? name
+        @raw.send name, *args
+      else
+        super
+      end
+    end
+    
+    
+  end
+  extend InstanceMethods
+end

data/lib/elia.rb

@@ -0,0 +1,3 @@
+module Elia
+  
+end

data/lib/path_operator.rb

@@ -0,0 +1,15 @@
+module PathOperator
+  def / *others
+    File.join self, *others.map(&:to_s)
+  end
+end
+
+String.class_eval{include PathOperator}
+Symbol.class_eval{include PathOperator}
+
+
+class Pathname
+  def / *others
+    join *others.map(&:to_s)
+  end
+end

data/lib/world_logger.rb

@@ -0,0 +1,24 @@
+require 'logger'
+
+module WorldLogger
+  def self.logger
+    if @logger.nil?
+      @logger ||= Logger.new($stdout)
+      @logger.level = Logger::ERROR
+    end
+    
+    @logger
+  end
+  
+  
+  def logger
+    if self.class.const_defined? :Rails
+      Rails.logger
+    else
+      WorldLogger.logger
+    end
+  end
+  
+end
+
+Object.send :include, WorldLogger

data/spec/lib/bit_fields_spec.rb

@@ -0,0 +1,59 @@
+require File.dirname(__FILE__) + '/../spec_helper'
+require 'bit_fields'
+
+describe BitFields do
+  before :each do
+    @klass = Class.new
+    
+    @klass.class_eval{
+      extend BitFields
+      
+      field :char_value
+      
+      field :short_value, 'S'
+      
+      field :frame_data_field_status, 'S' do
+        bit_field :secondary_header_flag,    1
+        bit_field :sync_flag,                1
+        bit_field :packet_order_flag,        1
+        bit_field :segment_length_id,        2
+        bit_field :first_header_pointer,    11
+      end
+    }
+    @values = [23, 14, 0b10100111_11111111]
+    @bit_string = @values.pack('CSS')
+    @object = @klass.new @bit_string
+  end
+  
+  it 'should create methods in a class' do
+    @object.char_value.should == 23
+    @object.secondary_header_flag.should == 0b1
+    @object.sync_flag.should == 0b0
+    @object.first_header_pointer.should == 0b111_11111111
+  end
+  
+  it 'should act as a Hash' do
+    @object.attributes[:char_value].should == 23
+    @object.attributes[:secondary_header_flag].should == 0b1
+    @object.attributes[:sync_flag].should == 0b0
+    @object.attributes[:first_header_pointer].should == 0b111_11111111
+    
+    @object[:char_value].should == 23
+    @object[:secondary_header_flag].should == 0b1
+    @object[:sync_flag].should == 0b0
+    @object[:first_header_pointer].should == 0b111_11111111
+  end
+  
+  it 'should use raw string to respond to "to_s"' do
+    @object.to_s.should == @object.raw.to_s
+  end
+  
+  it 'should define question mark methods for bit fields of length 1' do
+    @object.should respond_to(:sync_flag?)
+    @object.should respond_to(:sync?)
+    @object.sync_flag?.should == false
+    @object.should respond_to(:secondary_header?)
+    @object.secondary_header?.should == true
+  end
+end
+

data/spec/lib/elia_spec.rb

@@ -0,0 +1,7 @@
+require File.expand_path(File.dirname(__FILE__) + '/../spec_helper')
+
+describe "Elia" do
+  it "passes..." do
+    "passes!"
+  end
+end

data/spec/spec.opts

@@ -0,0 +1 @@
+--color

data/spec/spec_helper.rb

@@ -0,0 +1,9 @@
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'elia'
+require 'spec'
+require 'spec/autorun'
+
+Spec::Runner.configure do |config|
+  
+end

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification 
+name: elia
+version: !ruby/object:Gem::Version 
+  version: 1.0.0
+platform: ruby
+authors: 
+- Elia Schito
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-11-26 00:00:00 +01:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.2.9
+    version: 
+description: useful stuff...
+email: perlelia@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.rdoc
+files: 
+- LICENSE
+- README.rdoc
+- Rakefile
+- VERSION
+- lib/bit_fields.rb
+- lib/elia.rb
+- lib/path_operator.rb
+- lib/world_logger.rb
+- spec/lib/bit_fields_spec.rb
+- spec/lib/elia_spec.rb
+- spec/spec.opts
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://github.com/elia/elia
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Elia Schito's utility belt
+test_files: 
+- spec/lib/bit_fields_spec.rb
+- spec/lib/elia_spec.rb
+- spec/spec_helper.rb