ustack 0.0.1 → 0.0.2

data/README.md

@@ -9,7 +9,7 @@ Micro middleware stack for general purpose.
 gem 'ustack'
 ```
 
-## Usage
+## Basic usage
 
 ```ruby
 class M1 < Struct.new(:app)
@@ -34,13 +34,15 @@ app = Ustack.new do
 end
 
 puts app.run
-  # => M1
-  # => M2
-  # => xxx
-  # => M1
-  # => zzz
+# => M1
+# => M2
+# => xxx
+# => M1
+# => zzz
 ```
 
+You can also `swap`, `insert_before` and `insert_after` middleware. See documentation for details.
+
 ## Contributing
 
 1. Fork it

data/lib/ustack.rb

@@ -1,19 +1,163 @@
 require 'ustack/version'
 
+# Micro middleware stack for general purpose.
+#
+# @example
+#   class M1 < Struct.new(:app)
+#     def call(env)
+#       puts self
+#       puts app.call(env)
+#       puts self
+#       'zzz'
+#     end
+#   end
+#
+#   class M2 < Struct.new(:app, :options)
+#     def call(env)
+#       puts self
+#       options[:return]
+#     end
+#   end
+#
+#   app = Ustack.new do
+#     use M1
+#     use M2, return: 'xxx'
+#   end
+#
+#   puts app.run
+#   # => M1
+#   # => M2
+#   # => xxx
+#   # => M1
+#   # => zzz
+#
+# @api public
 class Ustack
+  # Initializes new middleware stack.
+  #
+  # @example
+  #   app1 = Ustack.new
+  #   app2 = Ustack.new do
+  #     use M1
+  #     use M2, my_option: 'xxx'
+  #   end
+  #
+  # @return [Ustack] Initialized middleware stack.
+  # @api public
   def initialize(&block)
     instance_eval(&block) if block_given?
   end
 
+  # Tells the stack to use given middleware.
+  #
+  # @param [Class] klass Middleware class to be used.
+  # @param [Hash] options Hash of orbitrary options for new middlware.
+  #
+  # @example
+  #   app = Ustack.new do
+  #     use M1
+  #   end
+  #   app.use M2
+  #   app.use M2, my_option: 'xxx'
+  #
+  # @api public
   def use(klass, options=nil)
-    @stack ||= []
-    @stack << [klass, options]
+    @ustack ||= []
+    @ustack << [klass, options]
   end
 
+  # Swaps two middlewares.
+  #
+  # @param [Class] old_klass Middleware class to be replaced.
+  # @param [Class] new_klass New middleware class.
+  # @param [Hash] options Hash of orbitrary options for new middlware.
+  #
+  # @example
+  #   app = Ustack.new do
+  #     use M1
+  #   end
+  #   app.use M2
+  #   app.use M2, my_option: 'xxx'
+  #
+  # @api public
+  def swap(old_klass, new_klass, options=nil)
+    @ustack[index(old_klass)] = [new_klass, options]
+  end
+
+  # Insert a middleware before another middleware.
+  #
+  # @param [Class] klass Existing middleware.
+  # @param [Class] new_klass Middleware to be inserted.
+  # @param [Hash] options Hash of orbitrary options for new middlware.
+  #
+  # @example
+  #   app = Ustack.new do
+  #     use M1
+  #   end
+  #   app.insert_before M1, M0, my_option: 'xxx'
+  #
+  # @api public
+  def insert_before(klass, new_klass, options=nil)
+    @ustack.insert(index(klass), [new_klass, options])
+  end
+
+  # Insert a middleware after another middleware.
+  #
+  # @param [Class] klass Existing middleware.
+  # @param [Class] new_klass Middleware to be inserted.
+  # @param [Hash] options Hash of orbitrary options for new middlware.
+  #
+  # @example
+  #   app = Ustack.new do
+  #     use M1
+  #   end
+  #   app.insert_before M1, M2, my_option: 'xxx'
+  #
+  # @api public
+  def insert_after(klass, new_klass, options=nil)
+    @ustack.insert(index(klass) + 1, [new_klass, options])
+  end
+
+  # Runs the middlware stack.
+  #
+  # @param [Hash] env Initial environment.
+  #
+  # @example
+  #   class M1 < Struct.new(:app)
+  #     def call(env)
+  #       app.call(env)
+  #       'zzz'
+  #     end
+  #   end
+  #
+  #   class M2 < Struct.new(:app)
+  #     def call(env)
+  #       puts env[:my_env_key]
+  #     end
+  #   end
+  #
+  #   app = Ustack do
+  #     use M1
+  #     use m2
+  #   end
+  #
+  #   puts app.run(my_env_key: 'xxx')
+  #   # => 'xxx'
+  #   # => 'zzz'
+  #
+  # @return [Object] Value returned by the most outer middleware.
+  # @api public
   def run(env={})
-    @stack.reverse.each do |(klass, options)|
-      @app = options ? klass.new(@app, options) : klass.new(@app)
+    app = nil
+    @ustack.reverse.each do |(klass, options)|
+      app = options ? klass.new(app, options) : klass.new(app)
     end
-    @app.call(env)
+    app.call(env)
+  end
+
+  private
+
+  def index(klass, &block)
+    @ustack.each_with_index { |(k, _), i| return i if k == klass }
   end
 end

data/lib/ustack/version.rb

@@ -1,3 +1,3 @@
 class Ustack
-  VERSION = '0.0.1'
+  VERSION = '0.0.2'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ustack
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -11,6 +11,22 @@ bindir: bin
 cert_chain: []
 date: 2013-05-13 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -43,6 +59,22 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Micro middleware stack for general purpose
 email:
 - kostiantyn.kahanskyi@googlemail.com
@@ -68,7 +100,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -62502703547411652
+      hash: -2009942153785192305
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -77,7 +109,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -62502703547411652
+      hash: -2009942153785192305
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.25
@@ -85,3 +117,4 @@ signing_key:
 specification_version: 3
 summary: Micro middleware stack for general purpose
 test_files: []
+has_rdoc: