Class: Newman::Application

Inherits:
Object
  • Object
show all
Includes:
Filters
Defined in:
lib/newman/application.rb

Instance Method Summary collapse

Methods included from Filters

#subject, #to

Constructor Details

#initialize(&block) ⇒ Application

A ‘Newman::Application` object is a blank slate upon creation, with fields set to hold `callbacks`, `matchers`, and `extensions`. A block may optionally be provided, which then gets executed within the context of the newly created `Newman::Application` instance. This is the common way of building applications, and is demonstrated by the example below:

ping_pong = Newman::Application.new do
  subject("ping") do
    respond(:subject => "pong")
  end
end

Any method that can be called on a ‘Newman::Application` instance can be called within the provided block, including those methods mixed in by `Newman::Filters`.



32
33
34
35
36
37
38
 
# File 'lib/newman/application.rb', line 32

def initialize(&block)
  self.callbacks  = []
  self.matchers   = {}
  self.extensions = []

  instance_eval(&block) if block_given?
end

Instance Method Details

#call(params) ⇒ Object

‘Newman::Application#call` accepts a hash of parameters which gets used to create a new `Newman::Controller` object. The controller is then extended by all of the modules stored in the `extensions` field on the application object, and is finally passed along to `Newman::Application#trigger_callbacks`, which does the magical work of figuring out which callbacks to run, if any.

This method is meant to be run by a ‘Newman::Server` object, and isn’t especially useful on its own.



52
53
54
55
56
 
# File 'lib/newman/application.rb', line 52

def call(params)
  controller = Controller.new(params)      
  extensions.each { |mod| controller.extend(mod) }
  trigger_callbacks(controller)
end

#callback(action, filter) ⇒ Object

‘Newman::Application#callback` is a low level feature for defining custom callbacks. For ideas on how to roll your own filters with it, see the implementation of the `Newman::Filters` module.



193
194
195
196
 
# File 'lib/newman/application.rb', line 193

def callback(action, filter)
  callbacks << { :filter   => filter, 
                 :action   => action }
end

#compile_regex(pattern) ⇒ Object

‘Newman::Application#compile_regex` is used for converting pattern strings into a regular expression string suitable for use in filters. This method is a low-level feature, and is not meant for use by application developers. See the `Newman::Filters` module for how to use it to build your own callback filters.



206
207
208
209
 
# File 'lib/newman/application.rb', line 206

def compile_regex(pattern)
  Regexp.escape(pattern)
        .gsub(/\\{(.*?)\\}/) { |m| "(?<#{$1}>#{matchers[$1]})" } 
end

#default(&callback) ⇒ Object

‘Newman::Application#default` is used to define a default callback which will run when no other callbacks match the incoming request. For example, you can define a callback such as the one below:

default do
  respond(:subject => "REQUEST NOT UNDERSTOOD")
end

Unless you are building an application that will never fail to match at least one of its filters, you MUST set up a default callback if you want to avoid a possible application error. We know this is not exactly the most desireable behavior, and will try to fix this in a future version of Newman.



74
75
76
 
# File 'lib/newman/application.rb', line 74

def default(&callback)
  self.default_callback = callback
end

#helpers(&block) ⇒ Object

‘Newman::Application#helpers` is used to build simple controller extensions, and is mostly just syntactic sugar. For example, rather than using an explicit module, the example shown in the `Newman::Application#use` documentation can be rewritten as follows:

list_app = Newman::Application.new do
  helpers do
    def load_list(name)
      store = Newman::Store.new(settings.application.list_db)
      Newman::MailingList.new(name, store)
    end
  end

  match :list_id, "[^.]+"

  to(:tag, "{list_id}.subscribe") do
    list = load_list(params[:list_id])

    if list.subscriber?(sender)
      # send a failure message
    else
      # susbcribe the user and send a welcome message
    end
  end
end

It’s important to note that for any controller extensions that might be reusable, or for more complicated logic, ‘Newman::Application#use` is probably a better tool to use.



151
152
153
 
# File 'lib/newman/application.rb', line 151

def helpers(&block)
  use Module.new(&block)
end

#match(name, pattern) ⇒ Object

‘Newman::Application#match` is used to define patterns which are used for extracting callback parameters. An example is shown below:

jester = Newman::Application.new do
  match :genre, '\S+'
  match :title, '.*'

  subject(:match, "a {genre} story '{title}'") do
    story_library.add_story(:genre => params[:genre],
                            :title => params[:title],
                            :body => request.body.to_s)

    respond :subject => "Jester saved '#{params[:title]}'"
  end
end

Because Newman’s built in filters are designed to escape regular expression syntax by default, ‘Newman::Application#match` provides the only high-level mechanism for dynamic filter matches. Low level matching is possible via `Newman::Application#callback`, but would be an exercise in tedium for most application developers.

NOTE: ‘Newman::Application#match` converts the provided `name` to a string using `to_s` to make life easier for the internals. Because `Newman::Application#matchers` is an implementation detail, you probably don’t need to worry about this unless you’re hacking on Newman itself.



183
184
185
 
# File 'lib/newman/application.rb', line 183

def match(name, pattern)
  matchers[name.to_s] = pattern
end

#use(extension) ⇒ Object

‘Newman:::Application#use` is used to register the extension modules that get mixed in to the controller objects created by `Newman::Application#call`. This allows an application object to provide extensions for use within its callbacks, as in the example shown below.

module ListLoader
  def load_list(name)
    store = Newman::Store.new(settings.application.list_db)
    Newman::MailingList.new(name, store)
  end
end

list_app = Newman::Application.new do
  use ListLoader

  match :list_id, "[^.]+"

  to(:tag, "{list_id}.subscribe") do
    list = load_list(params[:list_id])

    if list.subscriber?(sender)
      # send a failure message
    else
      # susbcribe the user and send a welcome message
    end
  end
end

This method is mainly meant to be used with pre-packaged extensions or more complicated forms of callback helpers. This example was just shown for the sake of its simplicity, but for similar use cases it would actually be better to use ‘Newman::Application#helpers`



114
115
116
 
# File 'lib/newman/application.rb', line 114

def use(extension)
  extensions << extension
end