perennial 0.2.2.2

data/lib/perennial/dispatchable.rb

@@ -0,0 +1,110 @@
+module Perennial
+  
+  # = Perennial::Dispatchable
+  # A Generic mixin which lets you define an object
+  # Which accepts handlers which can have arbitrary
+  # events dispatched.
+  # == Usage
+  #
+  #   class X
+  #     include Perennial::Dispatchable
+  #     self.handlers << SomeHandler.new
+  #   end
+  #   X.new.dispatch(:name, {:args => "Values"})
+  #
+  # Will first check if SomeHandler#handle_name exists,
+  # calling handle_name({:args => "Values"}) if it does,
+  # otherwise calling SomeHandler#handle(:name, {:args => "Values"})
+  module Dispatchable
+    
+    def self.handler_mapping
+      @@handler_mapping ||= Hash.new { |h,k| h[k] = [] }
+    end
+    
+    def self.included(parent)
+      parent.class_eval do
+        include InstanceMethods
+        extend  ClassMethods
+      end
+    end
+    
+    module InstanceMethods
+      
+      # Returns the handlers registered on this class,
+      # used inside +dispatch+.
+      def handlers
+        self.class.handlers
+      end
+      
+      # Dispatch an 'event' with a given name to the handlers
+      # registered on the current class. Used as a nicer way of defining
+      # behaviours that should occur under a given set of circumstances.
+      # == Params
+      # +name+: The name of the current event
+      # +opts+: an optional hash of options to pass
+      def dispatch(name, opts = {})
+        # The full handler name is the method we call given it exists.
+        full_handler_name = :"handle_#{name.to_s.underscore}"
+        # First, dispatch locally if the method is defined.
+        self.send(full_handler_name, opts) if self.respond_to?(full_handler_name)
+        # Iterate through all of the registered handlers,
+        # If there is a method named handle_<event_name>
+        # defined we sent that otherwise we call the handle
+        # method on the handler. Note that the handle method
+        # is the only required aspect of a handler. An improved
+        # version of this would likely cache the respond_to?
+        # call.
+        self.handlers.each do |handler|
+          if handler.respond_to?(full_handler_name)
+            handler.send(full_handler_name, opts)
+          else
+            handler.handle name, opts
+          end
+        end
+      # If we get the HaltHandlerProcessing exception, we
+      # catch it and continue on our way. In essence, we
+      # stop the dispatch of events to the next set of the
+      # handlers.
+      rescue HaltHandlerProcessing => e
+        Logger.info "Halting processing chain"
+      rescue Exception => e
+        Logger.log_exception(e)
+      end
+      
+    end
+    
+    module ClassMethods
+      
+      # Return an array of all registered handlers, ordered
+      # by their class and then the order of insertion. Please
+      # note that this will include ALL handlers up the inheritance
+      # chain unless false is passed as the only argument.
+      def handlers(recursive = true)
+        handlers = []
+        if recursive && superclass.respond_to?(:handlers)
+          handlers += superclass.handlers(recursive)
+        end
+        handlers += Dispatchable.handler_mapping[self]
+        return handlers
+      end
+      
+      # Assigns a new array of handlers and assigns each - Note that
+      # this will only set this classes handlers, it will not override
+      # those for others above / below it in the inheritance chain.
+      def handlers=(new_value)
+        Dispatchable.handler_mapping.delete self
+        [*new_value].each { |h| register_handler h }
+      end
+      
+      # Appends a handler to the list of handlers for this object.
+      # Handlers are called in the order they are registered.
+      def register_handler(handler)
+        unless handler.blank? || !handler.respond_to?(:handle)
+          Dispatchable.handler_mapping[self] << handler 
+        end
+      end
+      
+    end
+    
+  end
+end

data/lib/perennial/exceptions.rb

@@ -0,0 +1,6 @@
+module Perennial
+  # General Perennial exceptions.
+  class Error < StandardError;         end
+  # Called to halt handler processing.
+  class HaltHandlerProcessing < Error; end
+end

data/lib/perennial/generator.rb

@@ -0,0 +1,89 @@
+require 'open-uri'
+require 'fileutils'
+require 'erb'
+
+module Perennial
+  class Generator
+    
+    class CommandEnv < Perennial::Application::CommandEnv
+      
+      def initialize
+        @generator = nil
+      end
+      
+      protected
+      
+      def setup_generator(*args)
+        @generator = Generator.new(*args)
+      end
+      
+      def method_missing(name, *args, &blk)
+        if @generator && @generator.respond_to?(name)
+          @generator.send(name, *args, &blk)
+        else
+          super
+        end
+      end
+      
+    end
+    
+    attr_accessor :template_path, :destination_path
+    
+    def initialize(destination, opts = {})
+      @destination_path = destination
+      @template_path    = opts[:template_path] || File.join(Settings.library_root, "templates")
+      puts "Starting generator for #{destination}"
+    end
+    
+    def download(from, to)
+      describe "Downloading #{from}"
+      file to, open(from).read
+    end
+    
+    def folders(*args)
+      args.each do |f|
+        describe "Creating folder #{f}"
+        FileUtils.mkdir_p(expand_destination_path(f))
+      end
+    end
+    
+    def file(name, contents)
+      dest_folder = File.dirname(name)
+      folders(dest_folder) unless File.directory?(expand_destination_path(dest_folder))
+      describe "Creating file #{name}"
+      File.open(expand_destination_path(name), "w+") do |f|
+        f.write(contents)
+      end
+    end
+    
+    def template(source, destination, environment = {})
+      describe "Processing template #{source}"
+      raw_template = File.read(expand_template_path(source))
+      processed_template = ERB.new(raw_template).result(binding_for(environment))
+      file destination, processed_template
+    end
+    
+    protected
+    
+    def binding_for(hash = {})
+      object = Object.new
+      hash.each_pair do |k, v|
+        object.instance_variable_set("@#{k}", v)
+      end
+      return object.send(:binding)
+    end
+    
+    def expand_template_path(p)
+      File.expand_path(p, @template_path)
+    end
+    
+    def expand_destination_path(p)
+      File.expand_path(p, @destination_path)
+    end
+    
+    def describe(action)
+      puts "- #{action}"
+    end
+    
+  end
+end

data/lib/perennial/hookable.rb

@@ -0,0 +1,63 @@
+module Perennial
+  # = Perennial::Hookable
+  # 
+  # Perennial::Hookable provides a generic set of functionality
+  # for implementing simple block-based hooks / callbacks. On
+  # a class level, this makes it easy for you to do event driven
+  # programming in that code can be registered to be run
+  # when something happens.
+  #
+  # Hookable differs from Perennial::Dispatchable in that it is
+  # designed to be lightweight / used for things like setting things
+  # up without all of the overhead of defining handlers / dispatching
+  # messages.
+  module Hookable
+    
+    def self.included(parent)
+      parent.class_eval do
+        extend ClassMethods
+        cattr_accessor :hooks
+        self.hooks = Hash.new { |h,k| h[k] = [] }
+      end
+    end
+    
+    module ClassMethods
+      
+      # Append a hook for a given type of hook in order
+      # to be called later on via invoke_hooks!
+      def append_hook(type, &blk)
+        self.hooks_for(type) << blk unless blk.blank?
+      end
+
+      # Return all of the existing hooks or an empty
+      # for a given hook type.
+      def hooks_for(type)
+        self.hooks[type.to_sym]
+      end
+
+      # Invoke (call) all of the hooks for a given
+      # type.
+      def invoke_hooks!(type)
+        hooks_for(type).each { |hook| hook.call }
+      end
+      
+      # Defines a set of handy methods to make it
+      # easy to define simplistic block based hooks
+      # on an arbitrary class.
+      def define_hook(*args)
+        klass = self.metaclass
+        args.map { |a| a.to_sym }.each do |name|
+          
+          klass.class_eval(<<-RUBY, __FILE__, __LINE__ + 1)
+            def #{name}(&blk)               # def before_run(&blk)
+              append_hook(:#{name}, &blk)   #   append_hook(:before_run, &blk)
+            end                             # end
+          RUBY
+          
+        end
+      end
+      
+    end
+    
+  end
+end

data/lib/perennial/loader.rb

@@ -0,0 +1,103 @@
+require 'singleton'
+
+module Perennial
+  class Loader
+    include Singleton
+    include Perennial::Hookable
+    
+    cattr_accessor :controllers, :current_type, :default_type
+    @@controllers = {}
+    
+    define_hook :before_run, :after_stop
+    
+    def self.register_controller(name, controller)
+      return if name.blank? || controller.blank?
+      name = name.to_sym
+      @@controllers[name] = controller
+      metaclass.class_eval(<<-RUBY, __FILE__, __LINE__ + 1)
+        def #{name}?                 # def client?
+          @@current_type == :#{name} #   @@current_type == :client
+        end                          # end
+      RUBY
+    end
+    
+    def self.run!(type = self.default_type, options = {})
+      @@current_type = type.to_sym
+      self.instance.run!(options)
+    end
+    
+    def self.stop!(force = false)
+      self.instance.stop!(force)
+    end
+    
+    def run!(options = {})
+      self.register_signals
+      self.class.invoke_hooks! :before_setup
+      Daemon.daemonize! if Settings.daemon?
+      Logger.log_name = "#{@@current_type.to_s}.log"
+      Logger.setup
+      Settings.setup
+      self.load_custom_code
+      self.class.invoke_hooks!        :before_run
+      self.attempt_controller_action! :run, options
+    end
+    
+    def stop!(force = false)
+      if force || !@attempted_stop
+        self.class.invoke_hooks!        :before_stop
+        self.attempt_controller_action! :stop
+        self.class.invoke_hooks!        :after_stop
+        @attempted_stop = true
+      end
+      Daemon.cleanup! if Settings.daemon?
+    end
+    
+    def current_controller
+      @current_controller ||= @@controllers[@@current_type.to_sym]
+    end
+    
+    protected
+    
+    def load_custom_code
+      # Attempt to load a setup file given it exists.
+      begin
+        config_dir = Settings.root / "config"
+        setup_file = config_dir / "setup.rb"
+        require(setup_file) if File.directory?(config_dir) && File.exist?(setup_file)
+      rescue LoadError
+      end
+      # Load any existing handlers assuming we can find the folder
+      handler_directory = Settings.root / "handlers"
+      if File.directory?(handler_directory)
+        Dir[handler_directory / "**" / "*.rb"].each do |handler|
+          require handler
+        end
+      end
+    end
+    
+    def register_signals
+      loader = self.class
+      %w(INT TERM).each do |signal|
+        trap(signal) do
+          loader.stop!
+          exit
+        end
+      end
+    end
+    
+    def attempt_controller_action!(action, *args)
+      action = action.to_sym
+      unless current_controller.blank? || !current_controller.respond_to?(action)
+        method = current_controller.method(action)
+        if method.arity == 0
+          method.call
+        elsif method.arity < 0 || method.arity == args.size
+          method.call(*args)
+        else
+          raise ArgumentError, "controller action #{action} requires #{method.arity} arguments, provided #{args.size}"
+        end
+      end
+    end
+    
+  end
+end

data/lib/perennial/loggable.rb

@@ -0,0 +1,15 @@
+module Perennial
+  # A mixin that provides logger instance and
+  # class methods
+  module Loggable
+   
+    def self.included(parent)
+      parent.extend self
+    end
+    
+    def logger
+      Logger
+    end
+    
+  end
+end

data/lib/perennial/logger.rb

@@ -0,0 +1,109 @@
+require 'fileutils'
+
+module Perennial
+  class Logger
+    
+    cattr_accessor :logger, :log_name
+    
+    @@log_name = "perennial.log"
+    @@setup    = false
+    
+    class << self
+      
+      def setup?
+        !!@@setup
+      end
+      
+      def setup
+        return if setup?
+        setup!
+      end
+      
+      def setup!
+        log_path = Settings.root / "log" / @@log_name.to_str
+        @@logger = new(log_path, Settings.log_level, Settings.verbose?)
+        @@setup = true
+      end
+      
+      def method_missing(name, *args, &blk)
+       self.setup # Ensure the logger is setup
+       @@logger.send(name, *args, &blk)
+      end
+      
+      def respond_to?(symbol, include_private = false)
+        self.setup
+        super(symbol, include_private) || @@logger.respond_to?(symbol, include_private)
+      end
+    
+    end
+    
+    LEVELS = {
+      :fatal => 7,
+      :error => 6,
+      :warn  => 4,
+      :info  => 3,
+      :debug => 0
+    }
+  
+    PREFIXES = {}
+  
+    LEVELS.each { |k,v| PREFIXES[k] = "[#{k.to_s.upcase}]".ljust 7 }
+
+    COLOURS = {
+      :fatal => 31, # red
+      :error => 33, # yellow
+      :warn  => 35, # magenta
+      :info  => 32, # green
+      :debug => 34  # white
+    }
+  
+    attr_accessor :level, :file, :verbose
+  
+    def initialize(path, level = :info, verbose = Settings.verbose?)
+      @level   = level.to_sym
+      @verbose = verbose
+      FileUtils.mkdir_p(File.dirname(path))
+      @file    = File.open(path, "a+")
+    end
+  
+    def close!
+      @file.close
+    end
+  
+    LEVELS.each do |name, value|
+      define_method(name) do |message|
+        write("#{PREFIXES[name]} #{message}", name) if LEVELS[@level] <= value
+      end
+    
+      define_method(:"#{name}?") do
+        LEVELS[@level] <= value
+      end
+      
+    end
+  
+    def log_exception(exception)
+      error "Exception: #{exception}"
+      exception.backtrace.each do |l|
+        error ">> #{l}"
+      end
+    end
+    
+    def verbose?
+      !!@verbose
+    end
+  
+    private
+  
+    def write(message, level = self.level)
+      @file.puts message
+      @file.flush
+      $stdout.puts colourize(message, level) if verbose?
+    end
+  
+    def colourize(message, level)
+      "\033[1;#{COLOURS[level]}m#{message}\033[0m"
+    end
+ 
+    
+  end
+end

data/lib/perennial/manifest.rb

@@ -0,0 +1,34 @@
+module Perennial
+  class Manifest
+    
+    class_inheritable_accessor :app_name, :namespace
+    self.app_name  = :perennial
+    self.namespace =  Perennial
+    
+    def self.inspect
+      "#<#{self.name} app_name: #{self.app_name.inspect}, namespace: #{self.namespace.inspect}>"
+    end
+    
+    module Mixin
+      # Called in your application to set the default
+      # namespace and app_name. Also, if a block is
+      # provided it yields first with Manifest and then
+      # with the Loader class, making it simpler to setup.
+      def manifest(&blk)
+        Manifest.namespace = self
+        Manifest.app_name  = self.name.to_s.underscore
+        parent_folder = File.expand_path(File.dirname(__DIR__(0)))
+        Settings.library_root = parent_folder
+        libary_folder = parent_folder / 'lib'/ Manifest.app_name
+        attempt_require((libary_folder / 'core_ext'), (libary_folder / 'exceptions'))
+        unless blk.nil?
+          args = []
+          args << Manifest if blk.arity != 0
+          args << Loader   if blk.arity > 1 || blk.arity < 0
+          blk.call(*args)
+        end
+      end
+    end
+    
+  end
+end

data/lib/perennial/option_parser.rb

@@ -0,0 +1,105 @@
+module Perennial
+  class OptionParser
+    
+    attr_reader :arguments
+    
+    def initialize
+      @parsed_values = {}
+      @arguments     = []
+      @callbacks     = {}
+      @descriptions  = {}
+      @shortcuts     = {}
+    end
+    
+    def add(name, description, opts = {}, &blk)
+      name = name.to_sym
+      @callbacks[name] = blk
+      @descriptions[name] = description
+      shortcut = opts.has_key?(:shortcut) ? opts[:shortcut] : generate_default_shortcut(name)
+      @shortcuts[shortcut] = name unless shortcut.blank?
+    end
+    
+    def summary
+      output = []
+      max_length = 0
+      @callbacks.each_key do |name|
+        shortcuts = []
+        @shortcuts.each_pair { |k,v| shortcuts << k if v == name }
+        text = "--#{name.to_s.gsub("_", "-")}"
+        text << ", #{shortcuts.map { |sc| "-#{sc}" }.join(", ")}" unless shortcuts.empty?
+        max_length = [text.size, max_length].max
+        output << [text, @descriptions[name]]
+      end
+      output.map { |text, description| "#{text.ljust(max_length)} - #{description}" }.join("\n")
+    end
+    
+    def parse(arguments = ARGV)
+      arguments, options = ArgumentParser.parse(arguments)
+      @arguments = arguments
+      options.each_pair do |name, value|
+        name = name.gsub("-", "_")
+        expanded_name = @shortcuts[name] || name.to_sym
+        callback = @callbacks[expanded_name]
+        callback.call(value) if callback.present?
+      end
+      return nil
+    end
+    
+    # Over ride with your apps custom banner
+    def self.print_banner
+    end
+    
+    def add_defaults!
+      return if defined?(@defaults_added) && @defaults_added
+      logger_levels = Logger::LEVELS.keys.map { |k| k.to_s }
+      add(:daemon, 'Runs this application as a daemon') { Settings.daemon = true }
+      add(:verbose, 'Runs this application verbosely, writing to STDOUT') { Settings.verbose = true }
+      add(:log_level, "Sets this applications log level, one of: #{logger_levels.join(", ")}") do |level|
+        if logger_levels.include?(level)
+          Settings.log_level = level.to_sym
+        else
+          puts "The provided log level must be one of #{logger_levels.join(", ")} (Given #{level})"
+          exit!
+        end
+      end
+      add(:help, "Shows this help message") do
+        self.print_banner
+        $stdout.puts "Usage: #{$0} [options]"
+        $stdout.puts "\nOptions:"
+        $stdout.puts self.summary
+        exit!
+      end
+      @defaults_added = true
+    end
+    
+    def self.default
+      return @default if defined?(@default) && @default.present?
+      @default = setup_default!
+    end
+    
+    def self.parse_argv(with = default)
+      with.parse
+      ARGV.replace with.arguments
+    end
+    
+    def self.setup_default!
+      opts = self.new
+      opts.add_defaults!
+      return opts
+    end
+    
+    protected
+    
+    def generate_default_shortcut(name)
+      raw = name.to_s[0, 1]
+      if !@shortcuts.has_key?(raw)
+        return raw
+      elsif !@shortcuts.has_key?(raw.upcase)
+        return raw.upcase
+      else
+        raise "No shortcut option could generate for '#{name}' - Please specify :short (possibly as nil) to override"
+      end
+    end
+    
+  end
+end