peregrine 0.1.1 → 0.2.0

data/README.md

@@ -1,4 +1,9 @@
 # Peregrine
+[![Build Status](https://travis-ci.org/solucet/peregrine.png?branch=master)][travis]
+[![Coverage Status](https://coveralls.io/repos/solucet/peregrine/badge.png)][coverage]
+[![Gem Version](https://badge.fury.io/rb/peregrine.png)][gem]
+[![Documentation](http://b.repl.ca/v1/yard-docs-blue.png)][yard]
+
 1. _adjective: foreign; alien; wandering, traveling, or migrating._
 2. _noun: a kick-ass falcon._
 
@@ -21,7 +26,7 @@ $ cd peregrine/ && bundle
 ```
 
 ## Documentation
-The framework has been heavily documented with information and should serve you well. If you installed Peregrine from the GitHub repository and installed the development dependencies, you can generate a local copy of its RDoc documentation by running `rake rdoc`.
+The framework has been heavily documented with information and should serve you well. If you installed Peregrine from the GitHub repository and installed the development dependencies, you can generate a local copy of its RDoc documentation by running `rake rdoc`. The documentation is also available [online from RubyDoc][yard].
 
 If you are unfamiliar with Entity-Component design, it is highly recommended that you read about it in addition to reading the documentation for the Peregrine framework. Chris Powell wrote a [great series of tutorials][recf-tutorial] on using EC design in JRuby on his blog which also includes links to further reading on the subject.
 
@@ -31,6 +36,11 @@ Special thanks go to Chris Powell, as the Peregrine framework was conceptually i
 ## License
 Peregrine is made available under the terms of the MIT License. See the included LICENSE file for more information.
 
+
+[coverage]:      https://coveralls.io/r/solucet/peregrine
+[gem]:           http://badge.fury.io/rb/peregrine
 [peregrine]:     https://github.com/solucet/peregrine
 [recf]:          https://github.com/cpowell/ruby-entity-component-framework
-[recf-tutorial]: http://cbpowell.wordpress.com/2012/10/30/
+[recf-tutorial]: http://cbpowell.wordpress.com/2012/10/30/
+[travis]:        https://travis-ci.org/solucet/peregrine
+[yard]:          http://rubydoc.info/gems/peregrine/frames

data/lib/peregrine/entity_manager.rb

@@ -154,6 +154,18 @@ module Peregrine
       removed.extend(Collections::Common, Collections::Systemic)
     end
     
+    # Unwraps the given Package, adding any included System and Entity instances
+    # directly to the EntityManager. Returns +true+ if the package was unwrapped
+    # successfully, +false+ otherwise.
+    def add_package(package)
+      return false unless package.respond_to?(:unwrap)
+      package.unwrap.each do |item|
+        add_system(item) if item.kind_of?(Peregrine::System)
+        add_entity(item) if item.kind_of?(Peregrine::Entity)
+      end
+      true
+    end
+    
     # Presents a human-readable summary of the EntityManager.
     def to_s
       "Entity Manager '#{name}' #{id} " <<

data/lib/peregrine/handlers.rb

@@ -0,0 +1,6 @@
+# Require all Ruby files in the 'handlers/' directory. Using +File.join+ to
+# ensure that all files are properly required regardless of the directory
+# separator in use.
+Dir[File.join(File.dirname(__FILE__), 'handlers', '*.rb')].each do |file|
+  require file
+end

data/lib/peregrine/handlers/component_package.rb

@@ -0,0 +1,34 @@
+module Peregrine
+  module Handlers
+    # This module provides methods which allow Component objects to be wrapped 
+    # and unwrapped for use by an instance of the Package class.
+    module ComponentPackage
+      # Returns +true+ if this package handler can +wrap+ and +unwrap+ the given
+      # object, +false+ otherwise.
+      def self.handles?(object)
+        if object.class == Class
+          object.ancestors.include?(Peregrine::Component)
+        else
+          object.kind_of?(Peregrine::Component)
+        end
+      end
+      
+      # Wraps the given Component into a generic hash.
+      def self.wrap(component)
+        return nil unless handles?(component)
+        { :name => component.name,
+          :tags => component.tags,
+          :type => component.class }
+      end
+      
+      # Unwraps a generic hash into a newly instanced Component.
+      def self.unwrap(hash)
+        return nil unless handles?(hash[:type])
+        hash[:type].new do |component|
+          component.name = hash[:name]
+          component.add_tags(*hash[:tags])
+        end
+      end
+    end
+  end
+end

data/lib/peregrine/handlers/entity_package.rb

@@ -0,0 +1,35 @@
+module Peregrine
+  module Handlers
+    # This module provides methods which allow Entity objects to be wrapped and
+    # unwrapped for use by an instance of the Package class.
+    module EntityPackage
+      # Returns +true+ if this package handler can +wrap+ and +unwrap+ the given
+      # object, +false+ otherwise.
+      def self.handles?(object)
+        if object.class == Class
+          object.ancestors.include?(Peregrine::Entity)
+        else
+          object.kind_of?(Peregrine::Entity)
+        end
+      end
+      
+      # Wraps the given Entity into a generic hash.
+      def self.wrap(entity)
+        return nil unless handles?(entity)
+        { :data => entity.components,
+          :name => entity.name,
+          :tags => entity.tags,
+          :type => entity.class }
+      end
+      
+      # Unwraps a generic hash into a newly instanced Entity.
+      def self.unwrap(hash)
+        return nil unless handles?(hash[:type])
+        hash[:type].new(*hash[:data]) do |entity|
+          entity.name = hash[:name]
+          entity.add_tags(*hash[:tags])
+        end
+      end
+    end
+  end
+end

data/lib/peregrine/handlers/system_package.rb

@@ -0,0 +1,36 @@
+module Peregrine
+  module Handlers
+    # This module provides methods which allow System objects to be wrapped and
+    # unwrapped for use by an instance of the Package class.
+    module SystemPackage
+      # Returns +true+ if this package handler can +wrap+ and +unwrap+ the given
+      # object, +false+ otherwise.
+      def self.handles?(object)
+        if object.class == Class
+          object.ancestors.include?(Peregrine::System)
+        else
+          object.kind_of?(Peregrine::System)
+        end
+      end
+      
+      # Wraps the given System into a generic hash.
+      def self.wrap(system)
+        return nil unless handles?(system)
+        { :name   => system.name,
+          :status => system.enabled?,
+          :tags   => system.tags,
+          :type   => system.class }
+      end
+      
+      # Unwraps a generic hash into a newly instanced System.
+      def self.unwrap(hash)
+        return nil unless handles?(hash[:type])
+        hash[:type].new do |system|
+          system.name = hash[:name]
+          system.disable unless hash[:status]
+          system.add_tags(*hash[:tags])
+        end
+      end
+    end
+  end
+end

data/lib/peregrine/package.rb

@@ -0,0 +1,97 @@
+require 'peregrine/features'
+require 'peregrine/handlers'
+
+module Peregrine
+  # == Summary
+  # 
+  # A Package is essentially a fast and easy way to package multiple commonly
+  # used items into an archive that can quickly recreate new instances of those
+  # items. Packages are especially useful for grouping together Components and
+  # Entities, and can be used to create 'templates' for instantiating objects
+  # that will be used often.
+  # 
+  # == Usage
+  # 
+  # By default, a Package may contain items that are children of the Component,
+  # Entity, and System classes. A single Package may contain any combination of
+  # these items. Items are added to the Package with the +wrap+ method, while
+  # instantiation of wrapped items is performed with the +unwrap+ method. The
+  # +unwrap+ method returns an array of instantiated objects built from the
+  # Package's internal archive of object data.
+  # 
+  # When used in conjunction with the EntityManager's +add_package+ method, the
+  # Package class truly shines.
+  # 
+  # == Example
+  # 
+  # Let's assume that we're building a role-playing game and need a common
+  # template for creating non-playable characters. That package may look
+  # something like this:
+  # 
+  #    include Peregrine
+  #    template = Package.new { |pkg| pkg.name = 'NPC' }
+  #    template.wrap(Entity.new(Renderable, Autonomous, Conversational) do |npc|
+  #      npc.name = 'Generic NPC'
+  #      npc.add_tags(:npc)
+  #    end)
+  #    template.unwrap # => [Entity 'Generic NPC' ... (3)]
+  # 
+  # The newly instanced Entity generated from the package will have a different
+  # ID and UUID each time it is created, but will always have the same name,
+  # components, and tags.
+  class Package
+    include Peregrine::Features
+    
+    # Array of objects used to build instances for the +unwrap+ method.
+    attr_reader :archive
+    
+    # Array of package handling modules used to facilitate wrapping and
+    # unwrapping of objects.
+    attr_reader :handlers
+    
+    # Creates a new Package instance and adds the given objects to the Package.
+    # Yields the newly created Package if a block is given.
+    def initialize(*objects)
+      @archive  = []
+      @handlers = [ Peregrine::Handlers::ComponentPackage,
+                    Peregrine::Handlers::EntityPackage,
+                    Peregrine::Handlers::SystemPackage ]
+      wrap(*objects)
+      yield self if block_given?
+    end
+    
+    # Wraps the given objects into the Package. Returns the array of archived
+    # objects in the Package.
+    def wrap(*objects)
+      objects.each do |object|
+        @handlers.each do |handler|
+          next unless handler.handles?(object)
+          item = handler.wrap(object)
+          @archive.push(item) unless item.nil?
+        end
+      end
+      @archive
+    end
+    
+    # Unwraps all objects in the package into newly instanced objects. Returns
+    # the array of instanced objects. Yields each unwrapped item if a block is
+    # given.
+    def unwrap
+      unwrapped = []
+      @archive.each do |object|
+        @handlers.each do |handler|
+          item = handler.unwrap(object)
+          unwrapped.push(item) unless item.nil?
+        end
+      end
+      unwrapped.each { |item| yield item if block_given? }
+      unwrapped
+    end
+    
+    # Presents a human-readable summary of the Package.
+    def to_s
+      "Package '#{name}' #{id} (#{@archive.size})"
+    end
+    alias :inspect :to_s
+  end
+end

data/lib/peregrine/version.rb

@@ -1,4 +1,4 @@
 module Peregrine
   # Semantic version of the Peregrine framework.
-  VERSION = '0.1.1'
+  VERSION = '0.2.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: peregrine
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-02-11 00:00:00.000000000 Z
+date: 2014-02-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -81,6 +81,11 @@ files:
 - lib/peregrine/features/nameable.rb
 - lib/peregrine/features/taggable.rb
 - lib/peregrine/features.rb
+- lib/peregrine/handlers/component_package.rb
+- lib/peregrine/handlers/entity_package.rb
+- lib/peregrine/handlers/system_package.rb
+- lib/peregrine/handlers.rb
+- lib/peregrine/package.rb
 - lib/peregrine/system.rb
 - lib/peregrine/version.rb
 - lib/peregrine.rb