eidolon 0.1.3 → 0.2.0

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    NDE4MzAyZjFlOWE3ZTJlZmNjNzIxNWFlN2RjOWQ2ZWYxOTA4YTUxOA==
+    OGMzNDAyODEyMGZmOTQwYmJmNzc4NDNiZmU4MWU5MDRhY2Q1NGJlMg==
   data.tar.gz: !binary |-
-    MTJjZGE1YmQ0YjNhNGJmNTY1MzdiZDM5YjNiNDI4MDQyMmI1MmE3Nw==
+    NTNjMDMxMGYwNjliMGI5MDc4YjE0ZjIwODdkZDk4NzA2ZjUxNmZlMA==
 SHA512:
   metadata.gz: !binary |-
-    MDI0YTY3MmMwYmJiOWQ2OThmZjY2MDZlN2U0NWY2N2E2NTc3NmI3NDM5NDMz
-    MzVlNGMxMmYyZjkzNmUwOTg5NzJiMTEyZTJkMDY1MjI1ZGY5ZmY1Yjc0ZTQw
-    MmQ1MGI1YzNhOWY4NjA5ZDBhNjY5ZmZlOTY5YmYxNjRjNjk2NWM=
+    YzEwZjc1MTVmNDhjNmYzNWNlZGNhMzk2ZWFmNjQzZjdlN2JlMjgzZGExODhl
+    MmNlZDRjOGQzNDIyNTQ2N2Y5NGUwNGI3MGNiODYwNzg3MTJmOGRmMmNjMjE0
+    NjU0NjEzMmRlZWU1MjAxZjcyYzM4NTE4MTExYjRkYTBlNWM0NGY=
   data.tar.gz: !binary |-
-    ODJhNGI3NGVmMWViOWQzNzljMzcyZTMxOTYyYjYzYzExMzg1YTU3ZDIzM2I0
-    YWMwNDk5MmNjMmFlYTFlZTRiMTRkOTBkYTA5MDA3N2IxZjRjNWYwZmM3MWE5
-    NmRjZjg1NzA1MWM3YjhjNjZlYjc2NDFkYjhiYzA4MTFmZmVlODM=
+    NjcxZWE5YWM3OTMyODg5MDc2OThmMTE1YmUxOWI0OWFmNmNiNjgxNjY3MTEz
+    MDgzZGM1MTMxZTYxN2IxNzdiZTYyYWUzOTk4MjA5ZDEzZmFlNzBkODFhZDdm
+    Yjg1NTgwMWFhMWRmOTE2NjQzN2JmNmFiYWZlOTM0YmE0ZDk1Mjg=

data/README.md

@@ -23,31 +23,37 @@ require 'eidolon/rgss2'
 require 'eidolon/rgss3'
 ```
 
-Note that only one version may be required this way: attempting to require more than one version of the RGSS data structures will result in superclass mismatches. For this reason, if you potentially need to operate with more than one of the RGSS versions, you should use the core Eidolon module; essentially, the usage of this module allows you to dynamically create and destroy the needed RPG data structures whenever they are required. See the included documentation for more detailed information about the usage of the Eidolon module.
+Note that only one version may be required this way: attempting to `require` more than one version of the RGSS data structures will result in superclass mismatches. For this reason, if you potentially need to operate with more than one of the RGSS versions, you should use the core Eidolon module instead; essentially, the usage of this module allows you to dynamically create and destroy the needed RPG data structures whenever they are required. See the included documentation for more detailed information about the usage of the Eidolon module.
 
 ```ruby
 require 'eidolon'
 
+# Equivalent to the RGSSx +load_data+ method.
 def load_data(filename)
-  File.open(filename, 'rb') do |file|
-    return Marshal.load(file)
-  end
+  File.open(filename, 'rb') { |data| Marshal.load(data) }
 end
 
-@rgss_data  = []
-@rgss3_data = []
-
-Eidolon.build('RGSS')
-Dir.glob('**/*.rxdata') do |rxdata|
-  @rgss_data.push(load_data(rxdata))
+# Build the RGSS data structures and return RMXP project data.
+Eidolon.build('RGSS') do
+  data = []
+  Dir.glob('**/*.rxdata') { |rxdata| data << load_data(rxdata) }
+  data
 end
+```
 
-Eidolon.destroy!
+## Local Extensions
+Eidolon has been written in a way that allows developers to easily extend or modify the RGSSx data that it loads. This feature was primarily included to allow newer versions of RGSSx to be easily added to Eidolon in case of their release.
 
-Eidolon.build('RGSS3')
-Dir.glob('**/*.rvdata2') do |rvdata2|
-  @rgss3_data.push(load_data(rvdata2))
-end
+Essentially, Eidolon looks through a defined path for specific files to load RGSS data dependent on the RGSS version you request. For RGSS, it looks for `eidolon/rgss/loader.rb`, RGSS2 looks for `eidolon/rgss2/loader.rb`, and so on. In order to create RGSS4, for example, you simply need to recreate this structure locally -- and Eidolon will allow you to use it.
+
+```
+$ cat eidolon/rgss4/loader.rb
+# Load all of your needed modifications here.
+load 'eidolon/rgssx/loader.rb'
+load 'eidolon/rgss4/rpg/example.rb'
+
+$ cat rgss4_application.rb
+Eidolon.build(:RGSS4) { ... }
 ```
 
 ## Installation

data/lib/eidolon.rb

@@ -1,94 +1,99 @@
 require 'eidolon/version'
 
 # == Eidolon
-# This module provides methods for building the data structures used by the RPG
-# Maker series of game development programs so that the serialized data may be
-# loaded into an external Ruby implementation. The methods used are platform
-# and dependency agnostic.
+# This module provides methods for creating and destroying the data structures
+# used by the RPG Maker series of game development programs so that their data
+# may be loaded into an external Ruby implementation. The methods used are
+# platform and dependency agnostic.
 # 
 # == Usage
 # It is recommended that you explicitly declare which RGSS version Eidolon
 # should use before building the RGSSx data structures required; this is done
 # through the +Eidolon.rgss_version=+ method. This method accepts both integer
-# and representative string values -- for example, passing it an argument of
-# 1 or "RGSS" will both set the Eidolon RGSS version to the appropriate value.
-# Recognized RGSS versions are "RGSS" (XP), "RGSS2" (VX), and "RGSS3" (VX Ace).
+# and representative string or symbol values -- for example, passing it an
+# argument of 1, 'RGSS2', or :rgss3 will set the Eidolon RGSS version to the
+# appropriate value.
 # 
 # After explicitly requesting the desired RGSS version, you will want to build
 # the desired data structures with the +Eidolon.build+ method. This will create
 # the data structures for the specified RGSS version for use by the currently
 # running Ruby implementation. Note that the +Eidolon.build+ method will only
-# build data structures *once*.
+# build data structures *once*. You may also explicitly pass an RGSS version to
+# build as an argument to this method.
 # 
-# You will need to use the +Eidolon.destroy!+ method if you intend to use more
-# than one RGSS version in a single Ruby session. On their own, the RGSSx data
-# structures are inherently incompatible with one another -- as such, the
-# previous data structures must be destroyed, which is what +Eidolon.destroy!+
-# does for you.
+# Be aware that you will need to use the +Eidolon.destroy!+ method if you wish
+# to use more than one RGSS version in a single Ruby session. On their own, the
+# RGSSx data structures are inherently incompatible with one another (raising
+# superclass mismatch errors) -- as such, the previous data structures must be
+# destroyed, which the +Eidolon.destroy!+ method does for you.
 # 
-# == Example
+# In addition to this, you may pass a block to the +Eidolon.build+ method which
+# automatically creates and destroys the data structures for the passed RGSS
+# version. The specified RGSS version is available inside of the block and
+# destroyed immediately after the block returns. Using a block will also return
+# the value of the *block* rather than the usual +true+ or +false+ value.
+# 
+# == Examples
 #     require 'eidolon'
 #     
-#     # Building the RGSS3 (VX Ace) data structures.
+#     # Equivalent to the RGSSx method of the same name.
+#     def load_data(filename)
+#       File.open(filename, 'rb') { |data| Marshal.load(data) }
+#     end
+#     
+#     # Build the RGSS3 (VX Ace) data structures and obtain the project data of
+#     # an unencrypted RMVX Ace game.
 #     Eidolon.rgss_version = 'RGSS3'
-#     Eidolon.rgss_version # => "rgss3"
-#     Eidolon.build        # => true
-#     Eidolon.built?       # => true
+#     Eidolon.build  # => true
+#     Eidolon.built? # => true
 #     
-#     # Destroy the previously built RGSS3 data structures.
-#     Eidolon.destroy!
-#     Eidolon.built? # => false
+#     # Initialize an array for storing the data, then fill it.
+#     @rgss3_data = []
+#     Dir.glob('**/*.rvdata2') { |data| @rgss3_data << load_data(data) }
+#     @rgss3_data # => [[nil, #<RPG::Actor...> ... ] ... ]
 #     
-#     # Now we can build the RGSS (XP) data structures as well.
-#     Eidolon.build(1) # => true
+#     # Destroy the previously built RGSS3 data structures.
+#     Eidolon.destroy! # => true
+#     Eidolon.built?   # => false
 #     
-#     # Obtaining an array of the built RGSSx structures.
-#     Eidolon.built # => ["rgss", "rgss3"]
+#     # Now we can build the RGSS (XP) data structures with a block and return
+#     # the project data for an unencrypted RMXP game.
+#     Eidolon.build(1) do
+#       # Initialize an array for storing the data, fill it, then use it as the
+#       # block's return value.
+#       @xp_data = []
+#       Dir.glob('**/*.rxdata') { |data| @xp_data << load_data(data) }
+#       @xp_data
+#     end            # => [[nil, #<RPG::Actor...> ... ] ... ]
+#     Eidolon.built? # => false
 module Eidolon
   class << self
-    # The RGSSx version used by Eidolon. This determines which data structures
-    # to require in order to facilitate working with serialized RGSSx data.
-    attr_reader :rgss_version
-    
-    # An array of the RGSS versions which have had their data structures built
-    # by Eidolon.
-    attr_reader :built
-  end
-  
-  # Initialize the array of built RGSS versions.
-  @built = []
-  
-  # Set the RGSS version used by Eidolon to the passed value. May be set to an
-  # integer or representative string value for the desired RGSS version.
-  # 
-  # Examples:
-  #    Eidolon.rgss_version = "RGSS3" # Sets the version to "rgss3".
-  #    Eidolon.rgss_version = 1       # Sets the version to "rgss".
-  def self.rgss_version=(value)
-    return unless valid?(value)
-    @rgss_version = transform(value)
+    # The default RGSS version for Eidolon to build if no argument is given to
+    # the +Eidolon.build+ method. This is +nil+ by default.
+    attr_accessor :rgss_version
   end
   
   # Builds the data structures for the desired RGSS version. Returns +true+ if
   # the data structures were built, +false+ otherwise. This is a safe method,
   # ensuring that only the data structures from a single RGSS version will be
   # built.
+  # 
+  # If a block is given, the data structures are built before the block is
+  # executed and then automatically destroyed. This is particularly useful for
+  # temporarily accessing RGSSx data, and returns the return value of the given
+  # block.
   def self.build(version = @rgss_version)
-    return false if version.nil?
-    built? ? false : build!(version)
-  end
-  
-  # Forces building of the data structures for the desired RGSS version.
-  # Returns +true+ if the data structures were built, +false+ otherwise.
-  def self.build!(version = @rgss_version)
-    return false if version.nil?
-    self.rgss_version = version
-    @built.push(@rgss_version).compact.sort!.uniq!
-    load 'eidolon/rgssx/loader.rb'
-    load "eidolon/#{@rgss_version}/loader.rb"
-  rescue LoadError
+    return false if version.nil? || built?
+    begin
+      load "eidolon/#{transform(version)}/loader.rb"
+      return true unless block_given?
+    rescue ArgumentError, LoadError
+      destroy!
+      return false
+    end
+    return_value = yield
     destroy!
-    false
+    return_value
   end
   
   # Destroys the currently built RGSS data structures. Returns +true+ if the
@@ -108,22 +113,18 @@ module Eidolon
   class << self
     private
     # Transforms the given value into an applicable string used to find the
-    # appropriate RGSS version.
+    # appropriate RGSS version. Returns the transformed string. Raises an
+    # +ArgumentError+ if the string could not be transformed.
     def transform(version)
+      return version if version == (string = 'rgss')
       if version =~ /^rgss(\d?)/i
-        return 'rgss' if $1.empty?
-        'rgss' << $1
+        string << $1 unless $1.empty?
       else
-        return 'rgss' if version == 1
-        'rgss' << version.to_s
+        string << version.to_s unless version.between?(0, 1)
       end
-    end
-  
-    # Returns +true+ if a "loader.rb" file exists for the given RGSS version,
-    # +false+ otherwise.
-    def valid?(version)
-      fn = File.dirname(__FILE__) << "/eidolon/#{transform(version)}/loader.rb"
-      File.file?(fn)
+      string
+    rescue
+      raise ArgumentError.new("'#{version}' is an invalid RGSS version.")
     end
   end
 end

data/lib/eidolon/rgss/loader.rb

@@ -6,7 +6,8 @@
 # be loaded -- the actual order of loading them is unimportant (unlike the data
 # structures used by VX and VX Ace, which require some specific ordering).
 
-require 'eidolon/rgssx'
+# Load the generic RGSSx data structures.
+load 'eidolon/rgssx/loader.rb'
 
 load 'eidolon/rgss/rpg/actor.rb'
 load 'eidolon/rgss/rpg/armor.rb'

data/lib/eidolon/rgss2/loader.rb

@@ -2,7 +2,8 @@
 # Essentially, requiring this file will build a generic copy of the VX data
 # structures for use in a Ruby installation outside of VX itself.
 
-require 'eidolon/rgssx'
+# Load the generic RGSSx data structures.
+load 'eidolon/rgssx/loader.rb'
 
 # Audio data structures.
 load 'eidolon/rgss2/rpg/bgm.rb'

data/lib/eidolon/rgss3/loader.rb

@@ -2,7 +2,8 @@
 # Ace. Essentially, requiring this file will build a generic copy of the VX Ace
 # data structures for use in a Ruby installation outside of Ace itself.
 
-require 'eidolon/rgssx'
+# Load the generic RGSSx data structures.
+load 'eidolon/rgssx/loader.rb'
 
 # Audio data structures.
 load 'eidolon/rgss3/rpg/bgm.rb'

data/lib/eidolon/version.rb

@@ -6,5 +6,5 @@ module Eidolon
   }
   
   # Semantic version of the Eidolon RGSSx builder.
-  VERSION = '0.1.3'
+  VERSION = '0.2.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: eidolon
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.2.0
 platform: ruby
 authors:
 - Solistra
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-04-25 00:00:00.000000000 Z
+date: 2014-04-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: yard