commute 0.1.2 → 0.2.0.rc.1

data/lib/commute/core/api.rb

@@ -0,0 +1,116 @@
+require 'commute/core/context'
+
+require 'commute/core/processors/hook'
+require 'commute/core/processors/request_builder'
+require 'commute/core/processors/sequencer'
+require 'commute/core/processors/code_status_processor'
+
+module Commute
+
+  # Public: An API is a context that already provides some standard
+  # context alternations. The collection of these alternations
+  # form a client driver for a remote API.
+  #
+  # The way that a context
+  # is built in an api is exactly the same as you would built it
+  # outside of an API class.
+  #
+  # An API also provides some basic primitives to execute the
+  # transformed request of a context. This can be done through
+  # the `run` method.
+  #
+  # To help you build default contexts (that is a context that
+  # every API instance starts building from), a API class itself
+  # is also a builder. When a API class is instantiated, the
+  # base context is built from the current base builder state, and
+  # is used as a base builder for the API instance (A builder itself).
+  #
+  # Examples
+  #
+  #   class PastieApi < Commute::Api
+  #
+  #     using(:response_body) do
+  #       append Downcaser.new
+  #     end
+  #
+  #     def get
+  #       transform(:id) { |request, id|
+  #         request.url = "http://pastie.org/pastes/#{id}/text"
+  #       }.get
+  #     end
+  #   end
+  #
+  #   gist = PastieApi.get(id: 5109586)
+  #
+  class Api < Builder
+    class << self
+      include Buildable
+
+      # The Builder methods should only be called in the Class itself.
+      # Otherwise, something like TestApi.with ... would modify
+      # the base builder, while we want it to create a new builder
+      # off the base one, with the provided parameters.
+      #
+      # Use TestApi.builder.with ... instead.
+      private *Builder::METHODS
+
+      # Internal: Memoized base builder.
+      def builder
+        @builder ||= Builder.new Context.new(Stack.new {})
+      end
+
+      # Internal: When an Api inherits another Api, it inherits its context.
+      def inherited klass
+        klass.instance_variable_set :@builder, Builder.new(builder.context)
+      end
+    end
+
+    # Internal: Forwards all methods on the class to the
+    # base context for this api.
+    #
+    # This is equivalent to calling TestApi.new.[method]
+    def self.method_missing method, *args, &block
+      self.new.send method, *args, &block
+    end
+
+    # Internal: A base stack that is used as a starting
+    # point for all apis. Includes a RequestBuilder
+    # and some convenient sequences for easy processor injection.
+    #
+    # Also provides basic on_request, on_response and
+    # on_complete hooks.
+    using do |stack, main|
+      main.append RequestBuilder.new
+      main.append Sequencer.new(:request), as: :request
+      main.append Sequencer.new(:execution), as: :execution
+      main.append Sequencer.new(:response), as: :response
+      main.append CodeStatusProcessor.new, as: :status
+      main.append Hook.new, as: :on_complete
+
+      stack.sequence(:execution) do
+        append Proc.new { |c|
+          Configuration.adapter.call c
+        }
+      end
+
+      # sequence(:request) do
+      #   append Scope.new(Sequencer.new(:request_body), :body), as: :body
+      # end
+
+      # sequence(:response) do
+      #   append Hook.new, as: :on_response
+      #   append Scope.new(Sequencer.new(:response_body), :body), as: :body
+      # end
+    end
+
+    # Public: Creates a new Api Builder, starting to build from
+    # the base context by default. Only when an Api has been
+    # turned into a context and then into a builder again, an
+    # argument will be given here.
+    #
+    # Returns a new Api instance.
+    def initialize context = self.class.builder.context
+      super
+    end
+  end
+end

data/lib/commute/core/builder.rb

@@ -0,0 +1,261 @@
+module Commute
+
+  # TODO comments
+  module Buildable
+
+    def self.included klass
+      klass.extend Forwardable
+      klass.def_delegators :builder, *Builder::METHODS
+    end
+
+    private
+
+    def builder
+      Builder.new self
+    end
+  end
+
+  # TODO comments
+  class Builder
+
+    METHODS = [:with, :without, :enable, :disable,
+      :hook, :transform, :using, :get, :put, :post, :patch, :delete].freeze
+
+    # Public: Initializes a new Builder from a context that
+    # starts to build a new context on top of it.
+    #
+    # Use 'context' to get the built context.
+    def initialize context
+      @stack = context.stack
+      @parameters = context.parameters
+      @transformations = context.transformations
+      @disables = context.disables
+      @cloned = []
+    end
+
+    # Internal: Get the context built with this builder.
+    #
+    # Returns a new Context.
+    def context
+      # Make new clones now.
+      @cloned = []
+      # Return the context.
+      Context.new @stack, @parameters, @transformations, @disables, self.class
+    end
+
+    # Internal: When a method is called on the builder that
+    # does not exist, we assume that the developer wanted to
+    # call a method on the already built context. So we return
+    # that built context and forward the method to it.
+    #
+    # Returns the return value from the method invoked on the built context.
+    def method_missing name, *args, &block
+      context.send name, *args, &block
+    end
+
+    # Public: Adds logical parameters to the context.
+    # Logocal parameters whose names match the id of a
+    # layer, get passed to that layer as options.
+    #
+    # When a parameter is set to nil, it is excluded
+    # from the update, use `without` instead.
+    #
+    # Examples
+    #
+    #   people.all.with(max: 100)
+    #   people.all.enable(:auth).with(auth: 'secret')
+    #
+    def with parameters
+      cloned(:@parameters)
+      parameters.delete_if { |k,v| v.nil? }
+      @parameters.merge!(parameters) do |key, o, n|
+        if o.kind_of? Array
+          o + n
+        elsif o.kind_of? Hash
+          o.merge! n
+        else
+          n
+        end
+      end
+      self
+    end
+    alias :for :with
+    alias :where :with
+
+    def with! parameters
+      cloned(:@parameters)
+      parameters.delete_if { |k,v| v.nil? }
+      # Do not check for collisions.
+      @parameters.merge!(parameters)
+      self
+    end
+
+    # Public: Removes logical parameters from the context.
+    #
+    # Examples
+    #
+    #   people.all.without(:index, :max)
+    #
+    def without *parameters
+      cloned(:@parameters)
+      parameters.each { |parameter| @parameters.delete parameter }
+      self
+    end
+
+    # Public: Enables processors in the stack. Causes the request
+    # to be processed by these processors before executing it.
+    #
+    # Only needed if the processor was disabled before. Adding
+    # a processor to a sequence will auto-enable it.
+    #
+    # Examples
+    #
+    #   api = people.all.disable(:format)
+    #   # later
+    #   api.enable(:format)
+    #
+    def enable *processors
+      cloned(:@disables)
+      processors.each { |processor| @disables.delete processor }
+      self
+    end
+
+    # Public: Disable layers in the stack. Causes the request
+    # not to be processed by these layers.
+    #
+    # Equivalent for context.without(:auth)
+    #
+    # Examples
+    #
+    #   people.all.disable(:auth)
+    #
+    def disable *processors
+      cloned(:@disables)
+      @disables = @disables | processors
+      self
+    end
+
+    # Public: Adds a hook to the context, this hook will be
+    # triggered for all requests made based on this context.
+    #
+    # Block form equivalent for context.with(event: handler)
+    #
+    # The logic behind this is that the id of the hook processor
+    # is the name of the event. The parameter (handler) will
+    # be passed as options to the processor.
+    #
+    # event   - The event to register the handler for.
+    # handler - The handler to be triggered when an event comes up.
+    #
+    def hook event, &handler
+      with(event => handler)
+    end
+
+    # Public: Adds a transformation to the context that instructs
+    # the context transformer how a request must be built from this context.
+    #
+    # Mostly used in API classes.
+    #
+    # dependencies   - Logical parameters this transformation is based on (optional).
+    # transformation - The transformation logic.
+    #
+    # Yields
+    #   No dependencies: the request and the context (if the arity permits it).
+    #   Dependencies: The request and the dependency values (unless all dependency values are nil).
+    #
+    # Examples
+    #
+    #   context.transform(:since) { |request, since| request.query[:since] = since }
+    #   context.transform(:id) { |request, id| request.url = "http://pastie.com/#{id}"}
+    #
+    #   context.transform { |request| request.url = 'http://example.com' }
+    #
+    #   context.transform { |request, context|
+    #     context[:user] ? "/users/#{self[:user]}/gists" : '/gists'
+    #   }
+    #
+    def transform *dependencies, &transformation
+      cloned(:@transformations)
+      if dependencies.empty?
+        @transformations << transformation
+      else
+        @transformations << Proc.new do |request, context|
+          dependency_values = dependencies.map { |dep| context[dep] }
+          transformation.call request, *dependency_values unless dependency_values.all?(&:nil?)
+        end
+      end
+      self
+    end
+
+    # Same as `transform` but removes all existing transformations for these dependencies.
+    def transform! *dependencies, &transformation
+    end
+
+    # Public: Used to alter the stack or one of its sequences.
+    #
+    # When no name is given, the stack is altered.
+    #
+    # name - The name of the sequence that needs altering.
+    #
+    # Yields the stack or one of its sequences.
+    # When the block has no arguments, the block is evalled
+    # on the stack or its sequence.
+    #
+    # Examples
+    #
+    #   using(:response_body) do
+    #     append(Commute::Common::Json::Parse.new)
+    #   end
+    #
+    #   # Is actually the equivalent for
+    #   using do
+    #     sequence(:response_body) do
+    #       append(Commute::Common::Json::Parse.new)
+    #     end
+    #   end
+    #
+    def using name = nil, &alter
+      cloned(:@stack)
+      if name
+        sequence = @stack.sequence(name)
+        sequence.alter &alter if alter
+      else
+        @stack.alter &alter
+      end
+      self
+    end
+
+    # Public: Configure the HTTP request method.
+    # Adds a request transformation configuring the request http method.
+    [:get, :put, :post, :patch, :delete].each do |http_method|
+      define_method http_method do
+        transform { |request| request.method = http_method }
+      end
+    end
+
+    # TODO
+    def limit max
+      with limit: max
+    end
+
+    # TODO
+    def offset index
+      with offset: index
+    end
+
+    # TODO
+    def order field, direction = :asc
+      with order: { field: field, direction: direction }
+    end
+
+    private
+
+    # Makes sure the given instance variable is cloned.
+    def cloned variable
+      if !@cloned.include? variable
+        @cloned << variable
+        instance_variable_set variable, instance_variable_get(variable).dup
+      end
+    end
+  end
+end

data/lib/commute/core/commuter.rb

@@ -0,0 +1,116 @@
+require 'commute/core/context'
+
+module Commute
+
+  # Public: A Commuter is a package that holds a value
+  # associated to a context.
+  #
+  # A commuter can be tagged to make conditional
+  # processing possible.
+  #
+  class Commuter
+    attr_reader :context
+
+    # Public: Creates a new commuter
+    def initialize context, value = nil
+      @context = context
+      @value = value
+      @tags = []
+    end
+
+    # Public: Returns the inner value of the commuter.
+    def get
+      @value
+    end
+
+    # Public: Sets the inner value of the commuter.
+    #
+    # value - The new value.
+    def set value
+      @value = value
+    end
+
+    # Public: Changes the value of a commuter using a block.
+    # ONLY calls the block if the commuter value is not nil.
+    #
+    # Yields the value of the commuter.
+    #
+    # Returns nothing
+    def change
+      @value = yield @value unless @value.nil?
+      return nil
+    end
+
+    # Public: Get some parameters on how the commuter
+    # should be processed within a certain processor.
+    #
+    # processor_id - The id of the processor
+    #
+    # Returns whatever set in the context for this processor.
+    def parameters processor_id
+      self.context[processor_id]
+    end
+
+    # TODO
+    def disabled? processor_id
+      false
+    end
+
+    # TODO
+    def enabled? processor_id
+      !disabled?(processor_id)
+    end
+
+    # Public: Tags the commuter.
+    #
+    # tag - The tag to tag with (can be any object).
+    #
+    # Returns nothing.
+    def tag tag
+      @tags << tag
+      return nil
+    end
+
+    # Public: Checks if a commuter has a certain tag.
+    #
+    # tag - The tag to check presence of (can be any object).
+    #
+    # Returns true if the commuter is tagged with the given tag.
+    def tagged? tag
+      @tags.include? tag
+    end
+
+    # Public: Delays a commuter by giving it a block that
+    # must definitely be executed before the commute can continue.
+    #
+    # delay - The delay that must be executed.
+    #
+    # Returns nothing.
+    def delay &delay
+      @delay = delay
+      nil
+    end
+
+    def return
+      delay {}
+    end
+
+    # Public: check if a commuter is delayed.
+    def delayed?
+      !!@delay
+    end
+
+    # Public: Wait for a delay to be executed.
+    # And the do something when done.
+    #
+    # Yields when the delay has been executed.
+    #
+    # Returns nothing.
+    def wait &done
+      delay = @delay
+      @delay = nil
+      delay.call &done
+      return nil
+    end
+  end
+end

data/lib/commute/core/context.rb

@@ -0,0 +1,63 @@
+require 'forwardable'
+
+require 'commute/core/builder'
+require 'commute/core/stack'
+require 'commute/core/builder'
+
+module Commute
+  class Context
+    include Buildable
+
+    attr_reader :stack, :parameters, :transformations, :disables
+
+    def initialize stack = nil, parameters = {}, transformations = [], \
+       disables = [], builder_class = Builder
+      @stack = stack.freeze
+      @parameters = parameters.freeze || {}
+      @transformations = transformations.freeze || []
+      @disables = disables.freeze || {}
+      @builder_class = builder_class
+    end
+
+    def [] key
+      @parameters[key]
+    end
+
+    # Public: Creates a new context, resetting all transformations.
+    #
+    def reset
+    end
+
+    # Returns the
+    def run &on_complete
+      context = on_complete ? with(on_complete: on_complete) : self
+      commuter = Commuter.new context
+      @stack.call commuter
+      commuter.get
+    end
+
+    def run! *args, &block
+      result = self.run(*args, &block)
+      if result.kind_of?(Array)
+        result.first
+      else
+        result
+      end
+    end
+
+    def method_missing method, *args, &block
+      b = builder
+      if b.respond_to?(method)
+        b.send method, *args, &block
+      else
+        super
+      end
+    end
+
+    private
+
+    def builder
+      @builder_class.new self
+    end
+  end
+end

data/lib/commute/core/processors/code_status_processor.rb

@@ -0,0 +1,40 @@
+require 'commute/core/commuter'
+
+module Commute
+
+  # Internal: Looks at a response and decides if it was
+  # successful or not. This is the most basic one of
+  # those checkers. It simply checks if the response
+  # code is a 2xx code, when it is, the request was
+  # a success.
+  #
+  # This processor replaces the commuter's Response
+  #
+  class CodeStatusProcessor
+
+    class CodeStatus
+      @id = :status
+
+      attr_reader :code
+
+      def initialize code
+        @code = code
+        @success = (200..299).include? code
+      end
+
+      def success?
+        @success
+      end
+
+      def fail?
+        !@success
+      end
+    end
+
+    def call commuter
+      commuter.change do |response|
+        [response.body, CodeStatus.new(response.code)]
+      end
+    end
+  end
+end

data/lib/commute/core/processors/hook.rb

@@ -0,0 +1,14 @@
+require 'commute/core/commuter'
+
+module Commute
+
+  # Public: A Hook is a processor that yields the commuter value to a handler.
+  # The handler is given via the options for the processor (via its name).
+  #
+  class Hook
+
+    def call commuter, handler = nil
+      handler.call *commuter.get if handler
+    end
+  end
+end

data/lib/commute/core/processors/request_builder.rb

@@ -0,0 +1,26 @@
+require 'commute/core/commuter'
+require 'commute/core/request'
+
+module Commute
+
+  # Internal: A RequestBuilder builds a request given a context.
+  #
+  # It basically call all transformations defined on the context,
+  # resulting in a request. The request is then passed as the new
+  # value of the commuter (still with a reference to the context).
+  #
+  class RequestBuilder
+    @id = :builder
+
+    def call commuter
+      # Create a new request.
+      request = Request.new
+      # Build the request using context transformations.
+      commuter.context.transformations.each do |t|
+        t.call request, commuter.context
+      end
+      # Set the request on the commuter.
+      commuter.set request
+    end
+  end
+end

data/lib/commute/core/processors/sequencer.rb

@@ -0,0 +1,46 @@
+require 'commute/core/commuter'
+
+module Commute
+
+  # Public: A sequencer is a processor that lazily fetches a sequence
+  # from the stack and executes it with the given commuter.
+  #
+  # This has the advantage that an either not ye existent sequence or
+  # a sequence that could be modified later, can be referenced from
+  # another sequence.
+  #
+  # Examples:
+  #
+  #   Stack.new do |stack, main|
+  #     # Defining a new sequence.
+  #     response = stack.sequence(:response) do
+  #       ...
+  #     end
+  #
+  #     # This would work but if we alter the response
+  #     # sequence later on, it would still use this one.
+  #     main.append response
+  #
+  #     # Instead we do
+  #     main.append Sequencer.new(:response)
+  #   end
+  #
+  class Sequencer
+
+    # Public: Creates a new sequencer.
+    #
+    # name - The name of the sequence that needs to be called (lazily).
+    def initialize name
+      @name = name
+    end
+
+    def call commuter
+      # Get the stack from the processing context.
+      stack = commuter.context.stack
+      # Get the sequence we need to call.
+      sequence =  stack.get(@name)
+      # Call the sequence if one was found.
+      sequence.call commuter if sequence
+    end
+  end
+end