packed_struct 0.1.0

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2013 Jeremy Rodi
+
+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,33 @@
+# PackedStruct
+
+`PackedStruct` is a way to define packing strings (see [`Array#pack`](http://ruby-doc.org/core-2.0/Array.html#method-i-pack)).
+It was created after @charliesome suggested [a format](https://gist.github.com/redjazz96/6dda0554f62e4f77253a) for defining these strings, but never finished it.
+
+The basic way of defining a packed struct is such:
+
+```Ruby
+class RconPacket
+  include PackedStruct
+  struct_layout :packet do
+    little_endian signed size[32] # defaults to a number of size 32.
+    little_endian signed id[32]
+    little_endian signed type[32]
+    string body[size]
+    null
+  end
+end
+```
+
+This can be accessed as:
+
+```Ruby
+RconPacket.structs[:packet].pack(size: 11, id: 1, type: 0, body: "hello world")
+# => "\v\x00\x00\x00\x01\x00\x00\x00\x00\x00\x00\x00hello world\x00"
+```
+
+You can also unpack strings.
+
+```Ruby
+RconPacket.structs[:packet].unpack("\v\x00\x00\x00\x01\x00\x00\x00\x00\x00\x00\x00hello world\x00")
+# => {:size => 11, :id => 1, :type => 0, :body => "hello world"}
+```

data/lib/packed_struct.rb

@@ -0,0 +1,25 @@
+require 'packed_struct/package'
+require 'packed_struct/directive'
+
+module PackedStruct
+
+  def structs
+    @structs ||= {}
+  end
+
+  def struct_layout(name = nil, &block)
+    structs[name] = Package.new
+    structs[name].instance_exec &block
+
+    if name == nil
+      @structs = structs[name]
+    end
+
+    structs
+  end
+
+  def self.included(reciever)
+    reciever.extend self
+  end
+
+end

data/lib/packed_struct/directive.rb

@@ -0,0 +1,355 @@
+module PackedStruct
+
+  # Contains information about a directive.  A directive can be a name
+  # of the type, the endian(ness) of the type, the type of the type
+  # (short, int, long, etc.), and the signed(ness) of the type.
+  class Directive
+
+    # The name of the directive.  This is passed as the first value of
+    # the directive; from {Package}, it is the name of the method call.
+    #
+    # @return [Symbol]
+    attr_reader :name
+
+    # The arguments passed to the directive.
+    #
+    # @return [Array<Object>]
+    attr_reader :options
+
+    # The tags the directive has, such as type, signed(ness),
+    # endian(ness), and size.  Not filled until {#to_s} is called.
+    #
+    # @return [Hash]
+    attr_accessor :tags
+
+    # The children of this directive.  If this directive has a parent,
+    # this is nil.
+    #
+    # @return [nil, Array<Directive>]
+    attr_reader :subs
+
+    # The parent of this directive.  The relationship is such that
+    # +parent.subs.include?(self)+ is true.  If this has a parent, it
+    # is nil.
+    #
+    # @return [nil, Directive]
+    attr_accessor :parent
+
+    # The value this directive holds.  Only for use when packing.
+    #
+    # @return [nil, Object]
+    attr_writer :value
+
+    # @!parse
+    #   attr_reader :value
+    def value
+      @value || (@tags[:original].value if @tags[:original])
+    end
+
+    # Initialize the directive.
+    #
+    # @param name [Symbol] the name of the directive.
+    def initialize(name, *arguments)
+      @name = name
+
+      @options = arguments
+      @tags    = {}
+      @subs    = []
+      @parent  = nil
+      @value   = nil
+
+      if arguments.first.is_a? Directive
+        arguments.first.add_child(self)
+        @subs = nil
+      end
+    end
+
+    # Add a child to this (or its parent's) directive.  If this is a
+    # child itself, it adds it to the parent of this.  Invalidates the
+    # caches for {#sub_names} and {#to_s}
+    #
+    # @param child [Directive] the child to add.
+    # @return [Directive] the child.
+    def add_child(child)
+      if @parent
+        @parent.add_child(child)
+      else
+        @_str = nil
+        @_sub_types = nil
+        @subs << child
+        child.parent = self
+        child
+      end
+    end
+
+    # Set the size of this directive.
+    #
+    # @return [self]
+    def [](size)
+      @tags[:size] = size
+      self
+    end
+
+    # Turn the directive into a string.  Analyzes the subs before
+    # determining information, then outputs that.  Caches the value
+    # until {#add_child} is next called.
+    #
+    # @return [String]
+    def to_s
+      return "" unless @subs
+      @subs.compact!
+      @tags[:signed]   = determine_signed
+      @tags[:type]     = determine_type
+      @tags[:endian]   = determine_endian
+      "#{make_directive}#{make_length}"
+    end
+
+    # Inspects the directive.
+    #
+    # @return [String]
+    def inspect
+      "#<#{self.class.name}:#{name}>"
+    end
+
+    # To show the size of something else, relative to this directive.
+    #
+    # @return [Directive]
+    def -(other)
+      dir = dup
+      dir.tags = tags.dup
+      dir.tags[:original   ] = self
+      dir.tags[:size_modify] = -other
+      dir
+    end
+
+    # To show the size of something else, relative to this directive.
+    #
+    # @return [Directive]
+    def +(other)
+      dir = dup
+      dir.tags = tags.dup
+      dir.tags[:original   ] = self
+      dir.tags[:size_modify] = +other
+      dir
+    end
+
+    private
+
+    # Returns all of the names of the subs, and caches it.
+    #
+    # @param force [Boolean] force reloading the names of the subs.
+    # @return [Array<Symbol>]
+    def sub_names(force = false)
+      if @_sub_types && !force
+        @_sub_types
+      else
+        @subs.map(&:name) + [@name]
+      end
+    end
+
+    # Determines the size of the directive by checking if it's in the
+    # tags, or by searching the subs.
+    #
+    # @return [Numeric]
+    def size
+      case @tags[:size]
+      when Directive
+        (@tags[:size].value || 0) + (@tags[:size].tags[:size_modify] || 0)
+      when Numeric
+        @tags[:size]
+      when nil
+        @subs.select { |s| s && s.tags[:size] }.map { |s| s.tags[:size] }.last
+      end
+    end
+
+    # Determine the type of this directive.  Uses {#sub_names} to
+    # search for matching types.  Defaults to +nil+.
+    #
+    # @return [nil, Symbol] the return value can be any of +:short+,
+    #   +:int+, +:long+, +:string+, +:float+, or +nil+.
+    def determine_type
+      case true
+      when sub_names.include?(:short)
+        :short
+      when sub_names.include?(:int)
+        :int
+      when sub_names.include?(:long)
+        :long
+      when sub_names.include?(:char), sub_names.include?(:string)
+        :string
+      when sub_names.include?(:float)
+        :float
+      when sub_names.include?(:null)
+        :null
+      else
+        nil
+      end
+    end
+
+    # Determines the endianness of this directive.  Uses {#sub_names}
+    # to search for matching names.  Defaults to +:native+.
+    #
+    # @return [Symbol] the return value can be any of +:little+,
+    #   +:big+, or +:native+.
+    def determine_endian
+      case true
+      when sub_names.include?(:little), sub_names.include?(:little_endian),
+        sub_names.include?(:lsb), sub_names.include?(:low)
+        :little
+      when sub_names.include?(:big), sub_names.include?(:big_endian),
+        sub_names.include?(:msb), sub_names.include?(:high),
+        sub_names.include?(:network)
+        :big
+      else
+        :native
+      end
+    end
+
+    # Determines the signedness of this directive.  Uses {#sub_names}
+    # to search for matching names.  Defaults to +:signed+.
+    #
+    # @return [Symbol] the return value can be any of +:unsigned+ or
+    #   +:signed+.
+    def determine_signed
+      if sub_names.include?(:unsigned) && !sub_names.include?(:null)
+        :unsigned
+      else
+        :signed
+      end
+    end
+
+    # Determines the directive to be used in the pack string, using
+    # the type from {#determine_type} to manage it.
+    #
+    # @return [String] the directive for the pack string.
+    def make_directive
+      case @tags[:type]
+      when nil
+        handle_nil_type
+      when :short
+        modify_if_needed "S"
+      when :int
+        modify_if_needed "I"
+      when :long
+        modify_if_needed "L"
+      when :string
+        handle_string_type
+      when :float
+        handle_float_type
+      when :null
+        "x" * (size || 1)
+      else
+        nil
+      end
+    end
+
+    # Determines the length to be added to the pack string.
+    #
+    # @return [String]
+    def make_length
+      if size && ![:null, nil].include?(@tags[:type])
+        size.to_s
+      else
+        ""
+      end
+    end
+
+    # Handles the nil type.  Uses the size to match the type with
+    # the directive.
+    #
+    # @return [String]
+    def handle_nil_type
+      maps = {
+        8  => "C",
+        16 => "S",
+        32 => "L",
+        64 => "Q"
+      }
+
+      raise StandardError,
+        "Cannot make number of #{size} length" unless
+          maps.keys.include?(size)
+
+      modify_if_needed maps[size]
+    end
+
+    # Handles a string type.  If the name of the directive is
+    # +:null+, returns a string containing a number of +x+s (nulls)
+    # exactly equal to the size (or 1, if it doesn't exist).
+    # Otherwise, determines the type of string from the sub names;
+    # types of strings can include +:hex+, +:base64+, +:bit+, or
+    # +:binary+ (defaults to binary).
+    #
+    # @return [String]
+    def handle_string_type
+
+      case true
+      when sub_names.include?(:hex)
+        modify_if_needed "H"
+      when sub_names.include?(:base64)
+        "m"
+      when sub_names.include?(:bit)
+        modify_if_needed "B", false
+      else
+        modify_if_needed "A", false
+      end
+    end
+
+    # Handles float types.  Can handle double- or single- precision
+    # floats, and manage their byte order.
+    #
+    # @return [String]
+    def handle_float_type
+      double = sub_names.include?(:double)
+
+      case @tags[:endian]
+      when :native
+        if double
+          "D"
+        else
+          "F"
+        end
+      when :little
+        if double
+          "E"
+        else
+          "e"
+        end
+      when :big
+        if double
+          "G"
+        else
+          "g"
+        end
+      end
+    end
+
+    # Modifies the given string as needed; it assumes that a lowercase
+    # letter stands for a signed type and the given string stands for
+    # an unsigned type.  It also assumes that "<" added means little
+    # endian, and that ">" added means big endian (and that nothing
+    # added stands for native).
+    #
+    # @param str [String]
+    # @return [String]
+    def modify_if_needed(str, include_endian = true)
+      base = if @tags[:signed] == :signed
+        str.downcase
+      else
+        str
+      end
+
+      base += case @tags[:endian]
+      when :little
+        "<"
+      when :big
+        ">"
+      else
+        ""
+      end if include_endian
+
+      base
+    end
+
+  end
+end

data/lib/packed_struct/package.rb

@@ -0,0 +1,127 @@
+module PackedStruct
+
+  # Manages the struct overall, and keeps track of the directives.
+  # Directives are packed in the order that they are joined, such
+  # that the first one defined is the first one on the string.
+  class Package
+
+    # The list of directives that the package has.
+    #
+    # @return [Array<Directive>]
+    def directives
+      @directives.select! { |x| x.parent.nil? }
+      @directives
+    end
+
+    # Initialize the package.
+    def initialize
+      @directives = []
+    end
+
+    # Turn the package into a string.  Uses the directives (calls
+    # {Directive#to_s} on them), and joins the result.
+    #
+    # @return [String] the string ready for #pack.
+    def to_s
+      @_str ||= directives.map(&:to_s).join(' ')
+    end
+
+    alias_method :to_str, :to_s
+
+    # Packs the given data into a string.  The keys of the data
+    # correspond to the names of the directives.
+    #
+    # @param [Hash<Symbol, Object>] the data.
+    # @return [String] the packed data.
+    def pack(data)
+      values = []
+      data.each do |k, v|
+        values.push([k, v])
+      end
+
+      mapped_directives = @directives.map(&:name)
+
+      values.sort do |a, b|
+        directives.index(a) <=> directives.index(b)
+      end
+
+      pack_with_array(values.map(&:last))
+    end
+
+    # Packs the directives into a string.  Uses an array.
+    # The parameters can either be an array, or a set of values.
+    #
+    # @return [String]
+    def pack_with_array(*array)
+      array.flatten!
+
+      directives.each_with_index { |e, i| e.value = array[i] }
+      out = array.pack(self.to_s)
+      directives.each { |x| x.value = nil }
+      out
+    end
+
+    # Unpacks the given string with the directives.  Returns a hash
+    # containing the values, with the keys being the names of the
+    # directives.
+    #
+    # @param string [String] the packed string.
+    # @return [Hash<Symbol, Object>] the unpacked data.
+    def unpack(string)
+      total = ""
+      parts = {}
+      directives.each_with_index do |directive, i|
+        total << directive.to_s
+        value = string.unpack(total)[i]
+        directive.value = value
+        parts[directive.name] = value
+      end
+
+      directives.each { |x| x.value = nil }
+
+      parts.delete(:null) {}
+      parts
+    end
+
+    # This unpacks the entire string at once.  It assumes that none of
+    # the directives will need the values of other directives.  If
+    # you're not sure what this means, don't use it.
+    #
+    # @param string [String] the packed string.
+    # @return [Hash<Symbol, Object>] the unpacked data.
+    def fast_unpack(string)
+      out = string.unpack(to_s)
+      parts = {}
+
+      directives.each_with_index do |directive, i|
+        parts[directive.name] = out[i]
+      end
+
+      parts.delete(:null) {}
+      parts
+    end
+
+
+    # Inspects the package.
+    #
+    # @return [String]
+    def inspect
+      "#<#{self.class.name}:#{"0x%014x" % directives.map(&:object_id).inject(&:+)}>"
+    end
+
+    # Creates a new directive with the given method and arguments.
+    #
+    # @return [Directive] the new directive.
+    def method_missing(method, *arguments, &block)
+      if @directives.map(&:name).include?(method) && arguments.length == 0
+        @directives.select { |x| x.name == method }.first
+      else
+        @_str = nil
+        directive = Directive.new(method, *arguments)
+        @directives << directive
+        directive
+      end
+    end
+
+  end
+end

data/lib/packed_struct/version.rb

@@ -0,0 +1,5 @@
+module PackedStruct
+
+  # The current version of PackedStruct.
+  VERSION = "0.1.0".freeze
+end

metadata

@@ -0,0 +1,54 @@
+--- !ruby/object:Gem::Specification
+name: packed_struct
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Jeremy Rodi
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-06-26 00:00:00.000000000 Z
+dependencies: []
+description: ! '  Cleans up the string mess when packing items (in Array#pack) and
+  unpacking items (in String#unpack).
+
+'
+email: redjazz96@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- LICENSE
+- lib/packed_struct/version.rb
+- lib/packed_struct/package.rb
+- lib/packed_struct/directive.rb
+- lib/packed_struct.rb
+homepage: http://github.com/redjazz96/packed_struct
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.25
+signing_key: 
+specification_version: 3
+summary: Cleans up the string mess when packing items.
+test_files: []
+has_rdoc: false