Class: Vagrant::Action::Builder

Inherits:
Object
  • Object
show all
Defined in:
lib/vagrant/action/builder.rb

Overview

Action builder which provides a nice DSL for building up a middleware sequence for Vagrant actions. This code is based heavily off of Rack::Builder and ActionDispatch::MiddlewareStack in Rack and Rails, respectively.

Usage

Building an action sequence is very easy:

app = Vagrant::Action::Builder.new do
  use MiddlewareA
  use MiddlewareB
end

Vagrant::Action.run(app)

Instance Method Summary collapse

Constructor Details

#initialize(&block) ⇒ Builder

Initializes the builder. An optional block can be passed which will be evaluated in the context of the instance.



22
23
24
 
# File 'lib/vagrant/action/builder.rb', line 22

def initialize(&block)
  instance_eval(&block) if block_given?
end

Instance Method Details

#call(env) ⇒ Object

Runs the builder stack with the given environment.



119
120
121
 
# File 'lib/vagrant/action/builder.rb', line 119

def call(env)
  to_app(env).call(env)
end

#delete(index) ⇒ Object

Deletes the given middleware object or index



91
92
93
94
 
# File 'lib/vagrant/action/builder.rb', line 91

def delete(index)
  index = self.index(index) unless index.is_a?(Integer)
  stack.delete_at(index)
end

#flatten ⇒ Object

Returns a mergeable version of the builder. If use is called with the return value of this method, then the stack will merge, instead of being treated as a separate single middleware.



37
38
39
40
41
 
# File 'lib/vagrant/action/builder.rb', line 37

def flatten
  lambda do |env|
    self.call(env)
  end
end

#index(object) ⇒ Integer

Returns the numeric index for the given middleware object.

Parameters:

  • object (Object) —

    The item to find the index for

Returns:

  • (Integer) 


100
101
102
103
104
105
106
 
# File 'lib/vagrant/action/builder.rb', line 100

def index(object)
  stack.each_with_index do |item, i|
    return i if item[0] == object
  end

  nil
end

#insert(index, middleware, *args, &block) ⇒ Object Also known as: insert_before

Inserts a middleware at the given index or directly before the given middleware object.



64
65
66
67
 
# File 'lib/vagrant/action/builder.rb', line 64

def insert(index, middleware, *args, &block)
  index = self.index(index) unless index.is_a?(Integer)
  stack.insert(index, [middleware, args, block])
end

#insert_after(index, middleware, *args, &block) ⇒ Object

Inserts a middleware after the given index or middleware object.



72
73
74
75
76
 
# File 'lib/vagrant/action/builder.rb', line 72

def insert_after(index, middleware, *args, &block)
  index = self.index(index) unless index.is_a?(Integer)
  raise "no such middleware to insert after: #{index.inspect}" unless index
  insert(index + 1, middleware, *args, &block)
end

#stack ⇒ Array

Returns the current stack of middlewares. You probably won't need to use this directly, and it's recommended that you don't.

Returns:

  • (Array) 


30
31
32
 
# File 'lib/vagrant/action/builder.rb', line 30

def stack
  @stack ||= []
end

#swap(index, middleware, *args, &block) ⇒ Object

Swaps out the given middlware object or index with the new middleware.



80
81
82
83
84
85
86
87
88
 
# File 'lib/vagrant/action/builder.rb', line 80

def swap(index, middleware, *args, &block)
  if index.is_a?(Integer)
    delete(index)
    insert(index, middleware, *args, &block)
  else
    insert_before(index, middleware, *args, &block)
    delete(index)
  end
end

#to_app(env) ⇒ Object

Converts the builder stack to a runnable action sequence.

Parameters:

Returns:

  • (Object) —

    A callable object



112
113
114
115
116
 
# File 'lib/vagrant/action/builder.rb', line 112

def to_app(env)
  # Wrap the middleware stack with the Warden to provide a consistent
  # and predictable behavior upon exceptions.
  Warden.new(stack.dup, env)
end

#use(middleware, *args, &block) ⇒ Object

Adds a middleware class to the middleware stack. Any additional args and a block, if given, are saved and passed to the initializer of the middleware.

Parameters:

  • middleware (Class) —

    The middleware class



48
49
50
51
52
53
54
55
56
57
58
59
60
 
# File 'lib/vagrant/action/builder.rb', line 48

def use(middleware, *args, &block)
  if middleware.kind_of?(Builder)
    # Prepend with a environment setter if args are given
    self.use(Env::Set, *args, &block) if !args.empty? && args.first.is_a?(Hash)

    # Merge in the other builder's stack into our own
    self.stack.concat(middleware.stack)
  else
    self.stack << [middleware, args, block]
  end

  self
end