saper 0.5.0

data/lib/saper/core/error.rb

@@ -0,0 +1,47 @@
+module Saper
+  
+  # Generic exception acting as a parent class for all exceptions in Saper library.
+  class Error < Exception; end
+  
+  # FileUnreadable is raised whenever a recipe file cannot be read.
+  class FileUnreadable < Error; end
+  
+  # NoAction is raised whenever an implementation of Saper::Action is not found.
+  class ActionNotFound < Error; end
+  
+  # NamespaceMissing is raised whenever Saper::Runtime requires a missing namespace.
+  class NamespaceMissing < Error; end
+  
+  # NoAction is raised whenever an unsupported object is added to Saper::Recipe.
+  class ActionExpected < Error; end
+  
+  # InvalidAction is raised whenever serialized representation of Saper::Action is invalid.
+  class InvalidAction < Error; end
+  
+  # InvalidAction is raised whenever serialized representation of Saper::Recipe is invalid.
+  class InvalidRecipe < Error; end
+
+  # InvalidNamespace is raised whenever serialized representation of Saper::Namespace is invalid.
+  class InvalidNamespace < Error; end
+  
+  # InvalidType is raised whenever argument type is not recognized.
+  class InvalidType < Error; end
+  
+  # InvalidArgument is raised whenever an argument has incorrect type or value.
+  class InvalidArgument < Error; end
+  
+  # InvalidInput is raised whenever Saper::Action does not support this type of input.
+  class InvalidInput < Error; end
+  
+  # RecipeNotFound is raised whenever action calls a recipe that cannot be found.
+  class RecipeNotFound < Error; end
+  
+  # UnreachableURL is raised whenever a connection error occurs.
+  class UnreachableURL < Error; end
+  
+  # InvalidItem is raised whenever Saper::Item is initialized with an invalid underlying.
+  class InvalidItem < Error; end
+  
+  # @todo
+  class RuntimeMissing < Error; end
+end

data/lib/saper/core/item.rb

@@ -0,0 +1,70 @@
+module Saper
+  class Item
+    
+    # Tracks subclasses of Saper::Argument.
+    # @return [Class]
+    def self.inherited(base)
+      subclasses[base.type] = base
+    end
+    
+    # Returns a hash of subclasses.
+    # @return [Hash]
+    def self.subclasses
+      @subclasses ||= {}
+    end
+    
+    # Returns class name as an underscored string.
+    # @return [String]
+    def self.type
+      name.split("::").last.gsub(/([a-z])([A-Z])/,'\1_\2').downcase
+    end
+    
+    # Returns a subclass with specified type.
+    # @param type [Symbol] action type
+    # @return [Saper::Argument]
+    def self.[](type)
+      subclasses[type.to_s] || raise(InvalidItem, "Invalid action argument: %s" % type)
+    end
+    
+    # Returns `true` if there is a subclass with specified type.
+    # @param type [Symbol] action type
+    # @return [Boolean]
+    def self.exists?(type)
+      subclasses.keys.include?(type.to_s)
+    end
+    
+    # Returns a new instance of Saper::Argument. Returns nil and fails
+    # silently if there is an error during initialization.
+    # @return [Saper::Argument]
+    def self.try(*args, &block)
+      begin
+        new(*args, &block)
+      rescue InvalidItem, ArgumentError
+        nil
+      end
+    end
+    
+    # Returns a new instance of Saper::Argument.
+    # @return [Saper::Argument]
+    def self.new(*args, &block)
+      if self == Item
+        self[args.shift].new(*args, &block)
+      else
+        super(*args, &block)
+      end
+    end
+    
+    # Returns `true` if other item contains the same data.
+    # @return [Boolean]
+    def ==(other)
+      to_s == other.to_s
+    end
+    
+    # Returns class name as a Symbol.
+    # @return [Symbol]
+    def type
+      self.class.type.to_sym
+    end
+    
+  end
+end

data/lib/saper/core/keychain.rb

@@ -0,0 +1,18 @@
+module Saper
+  class Keychain
+  
+    # Returns a new keychain instance
+    # @return [Saper::Keychain]
+    def initialize
+      # TODO: not yet implemented
+    end
+    
+    # Returns access credentials for the specified service.
+    # @param service [String, Symbol] service name
+    # @return [Hash, nil]
+    def [](service)
+      # TODO: not yet implemented
+    end
+    
+  end
+end

data/lib/saper/core/logger.rb

@@ -0,0 +1,74 @@
+module Saper
+  class Logger
+    
+    # TODO: requires serious overhaul
+    
+    attr_reader :io
+    
+    def initialize(io = nil)
+      @io = io || StringIO.new
+    end
+    
+    def download(url)
+      io.write "%s %s\r\n" % [bold("Downloading"), url]
+    end
+    
+    def runtime(instance, indent = 0)
+      io.write bold("Recipe tree\r\n") if indent == 0
+      io.write "%s%s\r\n" % [" " * indent, action(instance)]
+      instance.children.each do |child|
+        runtime(child, indent + 1)
+      end
+    end
+    
+    def bold(string)
+      "\033[1m%s\033[0m" % string
+    end
+    
+    def red(string)
+      "\033[31m%s\033[0m" % string
+    end
+    
+    def green(string)
+      "\033[32m%s\033[0m" % string
+    end
+    
+    def action(instance)
+      "%s %s > %s" % [action_name(instance), action_input(instance), action_output(instance)]
+    end
+    
+    def action_input(instance)
+      item(instance.input)
+    end
+    
+    def action_output(instance)
+      item(instance.action.multiple? ? instance.output : instance.output.first)
+    end
+    
+    def action_name(instance)
+      instance.error? ? red(instance.action.name) : green(instance.action.name)
+    end
+    
+    def item(instance)
+      case instance
+      when Array
+        "[%s]" % instance.map { |i| item(i) }.join(",")
+      when nil
+        'nil'
+      when Items::Document
+        'Document'
+      when Items::HTML
+        'HTML'
+      when String
+        '%s' % instance
+      when Items::Text
+        '%s' % instance.to_s
+      when Items::Atom
+        '%s' % instance.to_hash
+      else
+        instance.class
+      end
+    end
+    
+  end
+end

data/lib/saper/core/namespace.rb

@@ -0,0 +1,139 @@
+module Saper
+  
+  def run(file, recipe, input = nil)
+    load(file).run(recipe, input)
+  end
+  
+  def load(file)
+    parse File.read(path)
+  end
+  
+  # Namespace is a parsing / storage utility for recipes
+  # that were meant to work as a group. It must be initiated
+  # for some actions to work properly (e.g. `run_chain`).
+  class Namespace
+    
+    # Parses namespace specified as a string or a block.
+    # @param string [String] list of recipes
+    # @return [Saper::Namespace]
+    def self.parse(string = nil, &block)
+      instance = DSL.new
+      if string.is_a?(String)
+        instance.instance_eval(string)
+      end
+      if block_given?
+        instance.instance_eval(&block)
+      end
+      instance.namespace
+    end
+    
+    # Returns a new instance of Saper::Namespace
+    # @param data [Hash]
+    # @return [Saper::Namespace]
+    def self.unserialize(data, &block)
+      unless data.is_a?(Hash)
+        raise(InvalidNamespace, data)
+      end
+      unless data[:recipes].is_a?(Array)
+        raise(InvalidNamespace, data)
+      end
+      new do |namespace|
+        data[:recipes].each do |recipe|
+          namespace << Recipe.unserialize(recipe, namespace)
+        end
+        if block_given?
+          yield namespace
+        end
+      end
+    end
+    
+    # Returns a new Namespace instance
+    # @return [Saper::Namespace]
+    def initialize
+      @recipes = {}
+      if block_given?
+        yield self
+      end
+    end
+    
+    # @todo
+    def run_by_default(symbol = nil)
+      @default ||= symbol
+    end
+    
+    # Runs an recipe and returns resulting Saper:Runtime.
+    # @param input [Object]
+    # @param name [String, Symbol] action name
+    # @param options [Hash] options for Runtime instance
+    # @return [Saper::Runtime]
+    def run(name = nil, input = nil, options ={})
+      self[name].run(input, options.merge(:namespace => self))
+    end
+    
+    # Returns recipe with specified ID or fails silently if not found.
+    # @param id [String, Symbol] recipe ID
+    # @return [Saper::Recipe, nil]
+    def try(id)
+      begin
+        self[id]
+      rescue
+        nil
+      end
+    end
+    
+    # Returns recipe with specified ID.
+    # @param id [String, Symbol] recipe ID
+    # @return [Saper::Recipe]
+    def [](id)
+      if @recipes.key?(id.to_s)
+        value = @recipes[id.to_s]
+        if value.is_a?(Recipe)
+          return value
+        end
+        if value.respond_to?(:to_recipe)
+          return @recipes[id.to_s] = value.to_recipe
+        end
+      else
+        find(id)
+      end
+    end
+    
+    # Caches recipe instance.
+    # @param id [String, Symbol] recipe ID
+    # @param recipe [Saper::Recipe]
+    # @return [Saper::Recipe]
+    def []=(id, recipe)
+      unless recipe.is_a?(Saper::Recipe)
+        unless recipe.respond_to?(:to_recipe)
+          raise ActionExpected
+        end
+      end
+      @recipes[id.to_s] = recipe
+    end
+    
+    # Searches for and returns a recipe.
+    # @return [Saper::Recipe]
+    def find(id)
+      raise RecipeNotFound, id
+    end
+    
+    # Returns the number of recipes within this namespace.
+    # @return [Integer]
+    def size
+      @recipes.size
+    end
+    
+    # Returns a serialized representation of this Namespace.
+    # @return [Hash]
+    def serialize
+      { :recipes => @recipes.values.map(&:serialize) }
+    end
+    
+    # Returns a JSON representation of this recipe.
+    # @return [String]
+    def to_json(*args)
+      serialize.to_json(*args)
+    end
+    
+  end
+end

data/lib/saper/core/recipe.rb

@@ -0,0 +1,134 @@
+module Saper
+  class Recipe
+    
+    # Returns a new instance of Saper::Recipe
+    # @param data [Hash]
+    # @return [Saper::Recipe]
+    def self.unserialize(data, namespace = nil, &block)
+      if data.is_a?(Array)
+        return data.map { |item| unserialize(item, namespace) }
+      end
+      unless data.is_a?(Hash)
+        raise(InvalidRecipe, data)
+      end
+      new(data[:id], :name => data[:name], :namespace => namespace) do |recipe|
+        unless data[:actions].nil?
+          recipe.push *Action.unserialize(data[:actions], namespace)
+        end
+        if block_given?
+          yield recipe
+        end
+      end
+    end
+    
+    # Parses block and returns a Recipe instance.
+    # @param id [Symbol] recipe ID
+    # @return [Saper::Recipe]
+    def self.parse(id = nil, name = nil, &block)
+      DSL::Recipe.parse(id, name, &block)
+    end
+    
+    # Returns unique ID of the recipe.
+    attr_reader :id
+
+    # Returns list of recipe actions.
+    attr_reader :actions
+    
+    # Returns a new instance of Saper::Recipe
+    # @param id [String]
+    # @return [Saper::Recipe]
+    def initialize(id = nil, options = {})
+      @id      = id || SecureRandom.hex
+      @actions = []
+      @options = options
+      if block_given?
+        yield self
+      end
+    end
+    
+    # Returns recipe name.
+    # @return [String, nil]
+    def name
+      @options[:name].nil? ? nil : @options[:name].to_s
+    end
+    
+    # Returns Saper::Namespace instance.
+    # @return [Namespace]
+    def namespace
+      @options[:namespace].is_a?(Namespace) ? @options[:namespace] : nil
+    end
+    
+    # Returns a list of data types required as input.
+    # @return [Array<Symbol>]
+    def input_required
+      empty? ? [] : actions.first.requires
+    end
+    
+    # Returns `true` if recipe requires some input.
+    # @return [Boolean]
+    def input_required?
+      !input_required.empty?
+    end
+    
+    # Adds a new action to the end of the recipe and returns self.
+    # @param action [Saper::Action]
+    # @return [self]
+    def <<(action)
+      if action.is_a?(Action)
+        @actions.push(action)
+      else
+        raise ActionExpected, action
+      end
+      self
+    end
+    
+    # Adds new actions to the end of the recipe and returns self.
+    # @param actions [Array<Saper::Action>]
+    # @return [self]
+    def push(*actions)
+      actions.compact.each do |action|
+        self << action
+      end
+      self
+    end
+    
+    # Runs recipe and returns Runtime instance.
+    # @param input [object] input for the first action
+    # @param options [Hash] options for Runtime object
+    # @return [Saper::Runtime]
+    def run(input = nil, options = {})
+      Runtime.new(actions, input, { :namespace => namespace }.merge(options))
+    end
+    
+    # Returns `true` if recipe contains no actions.
+    # @return [Boolean]
+    def empty?
+      actions.empty?
+    end
+    
+    # Returns `true` if recipe produces multiple results.
+    # @return [Boolean]
+    def multiple?
+      empty? ? false : actions.any?(&:multiple?)
+    end
+    
+    # Returns a serialized representation of this Recipe.
+    # @return [Hash]
+    def serialize
+      { :id => id, :name => name, :actions => @actions.map(&:serialize) }
+    end
+    
+    # Returns a string representation of this recipe.
+    # @return [String]
+    def to_string
+      "recipe %s do\n%s\nend" % [id.inspect, actions.map(&:to_string).join("\n")]
+    end
+    
+    # Returns a JSON representation of this recipe.
+    # @return [String]
+    def to_json(*args)
+      serialize.to_json(*args)
+    end
+    
+  end
+end