blur 1.5.3 → 1.6

data/library/blur/script.rb

@@ -1,11 +1,30 @@
 # encoding: utf-8
 
 module Blur
+  # The +Script+ class is used for encapsulating dynamically loaded ruby scripts.
+  #
+  # The {Script#Script} method is then used to shape the DSL-language to make
+  # writing Blur scripts a breeze.
+  #
+  # @todo add examples in the documentation
+  # @see Script#Script
   class Script < Module
-    attr_accessor :__name, :__author, :__version, :__path, :__client
+    # @return the name of the script.
+    attr_accessor :__name
+    # @return the author of the script.
+    attr_accessor :__author
+    # @return the version of the script.
+    attr_accessor :__version
+    # @return the path in which the script remains.
+    attr_accessor :__path
+    # Can be used inside the script to act with the client itself.
+    # @return [Network::Client] the client delegate.
+    attr_accessor :__client
     
+    # Check to see if the script has been evaluated.
     def evaluated?; @__evaluated end
     
+    # Instantiates a script and evaluates the contents which remain in +path+.
     def initialize path
       @__path = path
       @__evaluated = false
@@ -17,6 +36,14 @@ module Blur
       end
     end
     
+    # Make it a DSL-way of writing a script.
+    #
+    # @example
+    #   Script :example do
+    #     def connection_ready network
+    #       # …
+    #     end
+    #   end
     def Script name, version = [1,0], author = nil, &block
       @__name    = name
       @__author  = author
@@ -27,6 +54,7 @@ module Blur
       true
     end
     
+    # Unload the script and save the cache, if present.
     def unload!
       cache.save if @__cache
       __send__ :unloaded if respond_to? :unloaded
@@ -34,20 +62,26 @@ module Blur
       @__cache = nil
     end
 
+    # Access another script with name +name+.
+    #
+    # @return [Script] the script with the name +name+, or nil.
     def script name
       @__client.scripts.find { |script| script.__name == name }
     end
     
+    # Get the cache, if none, instantiate a new cache.
     def cache
       @__cache ||= Cache.new self
     end
     
+    # Convert it to a debug-friendly format.
     def inspect
       %{#<#{self.class.name} @name=#{@__name.inspect} @version=#{@__version.inspect} @author=#{@__author.inspect}>}
     end
     
   private
   
+    # Attempt to evaluate the contents of the script.
     def evaluate
       module_eval File.read(@__path), File.basename(@__path), 0
       @__evaluated = true

data/library/blur/script/cache.rb

@@ -2,24 +2,42 @@
 
 module Blur
   class Script < Module
+    # The +Cache+ class enables data storing inside Blur and it scripts.
+    #
+    # What it does is simply store a hash, and act like it is that hash.
+    #
+    # When the client closes, it sends a message to all available scripts
+    # and then those scripts tells the cache to save, in order to remember
+    # that data and reload it at the next run.
+    #
+    # Cache can then save the contents of the hash to a yaml file that persists
+    # in the ./cache/ directory.
+    #
+    # That same file is then loaded once needed again.
     class Cache
-      
+      # Get the path to the cache directory (./cache/)
       def self.path
         %{#{File.dirname File.expand_path $0}/cache}
       end
       
+      # Check if there exists a cache file for the script with name +name+.
       def self.exists? name
         File.exists? "#{path}/#{name}.yml"
       end
       
+      # Get a cache value by key.
       def [] key; @hash[key] end
+
+      # Set a cache value by key.
       def []= key, value; @hash[key] = value end
       
+      # Instantiate a cache with a script reference.
       def initialize script
         @hash   = {}
         @script = script
       end
       
+      # Save all internal data to a yaml file in the cache directory.
       def save
         directory = File.dirname path
         
@@ -32,6 +50,9 @@ module Blur
         end
       end
       
+      # Load a yaml file as internal data from the cache directory.
+      #
+      # @return [Hash] the loaded data.
       def load
         if yaml = YAML.load_file(path)
           @hash = yaml
@@ -40,10 +61,14 @@ module Blur
         File.unlink path
       end
       
+      # Let Hash#to_s do the job.
       def to_s; @hash end
       
     private
     
+      # The current caches file path.
+      #
+      # @return [String] the file path.
       def path
         %{#{Cache.path}/#{@script.__name}.yml}
       end

data/library/blur/script/messageparsing.rb

@@ -2,9 +2,39 @@
 
 module Blur
   class Script < Module
+    # The +MessageParsing+ module is a module that gives the ability to turn a
+    # script into a DSL-like framework.
+    #
+    # What it does is automatically test to see if a message starts with a
+    # trigger, and then, if so, it sends the command-part of the message to
+    # the script object itself.
+    #
+    # This way, the plugin-writer doesn't need to have repetetive code like
+    # that in every script.
+    #
+    # @example
+    #   Script :example do
+    #     extend MessageParsing
+    #
+    #     def command_test user, channel, message
+    #       channel.say "I hear you."
+    #     end
+    #   end
+    #
+    #   # And if a user were to send the message ".test my method", it would
+    #   # trigger the #command_test method with the following arguments
+    #   #
+    #   # user    => #<Blur::Network::User … >
+    #   # channel => #<Blur::Network::Channel … >
+    #   # message => ".test my method"
     module MessageParsing
+      # The prefix that turns it into a possible command.
       MessageTrigger = "."
       
+      # Handle all calls to the scripts +message+ method, check to see if
+      # the message containts a valid command, serialize it and pass it to
+      # the script as command_name with the parameters +user+, +channel+
+      # and +message+.
       def message user, channel, line
         return unless line.start_with? MessageTrigger
         
@@ -17,7 +47,8 @@ module Blur
       end
       
     protected
-    
+      
+      # Strip all non-word characters from the input command.
       def serialize name
         name.gsub /\W/, '' if name
       end

metadata

@@ -1,20 +1,63 @@
 --- !ruby/object:Gem::Specification 
 name: blur
 version: !ruby/object:Gem::Version 
-  prerelease: 
-  version: 1.5.3
+  prerelease: false
+  segments: 
+  - 1
+  - 6
+  version: "1.6"
 platform: ruby
 authors: 
 - Mikkel Kroman
 autorequire: 
-bindir: executables
+bindir: bin
 cert_chain: []
 
-date: 2011-02-14 00:00:00 +01:00
+date: 2011-09-30 00:00:00 +02:00
 default_executable: 
-dependencies: []
-
-description: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: majic
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        - 1
+        version: "0.1"
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: crypt19
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: eventmachine
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">"
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        - 12
+        version: "0.12"
+  type: :runtime
+  version_requirements: *id003
+description: "    An event-driven IRC-framework in and for Ruby. Is extensible and supports script with (re)loading functionality during runtime.\n"
 email: mk@maero.dk
 executables: []
 
@@ -26,6 +69,7 @@ files:
 - library/blur.rb
 - library/blur/client.rb
 - library/blur/enhancements.rb
+- library/blur/handling.rb
 - library/blur/network.rb
 - library/blur/network/channel.rb
 - library/blur/network/command.rb
@@ -34,11 +78,13 @@ files:
 - library/blur/script.rb
 - library/blur/script/cache.rb
 - library/blur/script/messageparsing.rb
-- library/blur/handling.rb
+- library/blur/encryption/fish.rb
+- library/blur/encryption/base64.rb
+- library/blur/encryption.rb
 has_rdoc: true
-homepage: 
-licenses: []
-
+homepage: https://github.com/mkroman/blur
+licenses: 
+- ISC
 post_install_message: 
 rdoc_options: []
 
@@ -49,19 +95,23 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      version: 1.9.1
+      segments: 
+      - 0
+      version: "0"
 required_rubygems_version: !ruby/object:Gem::Requirement 
   none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      segments: 
+      - 0
       version: "0"
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.5.0
+rubygems_version: 1.3.7
 signing_key: 
 specification_version: 3
-summary: Extensible IRC library
+summary: An event-driven IRC-framework for Ruby.
 test_files: []