module Roda::RodaPlugins::Base::RequestMethods

  1. lib/roda.rb

Instance methods for RodaRequest, mostly related to handling routing for the request.

Constants

TERM = Object.new  

Attributes

captures [R]

The current captures for the request. This gets modified as routing occurs.

remaining_path [R]

The current path to match requests against.

scope [R]

The Roda instance related to this request object. Useful if routing methods need access to the scope of the Roda route block.

Public Class methods

new (scope, env)

Store the roda instance and environment.

[show source]
    # File lib/roda.rb
681 def initialize(scope, env)
682   @scope = scope
683   @captures = []
684   @remaining_path = _remaining_path(env)
685   @env = env
686 end

Public Instance methods

block_result (result)

Handle match block return values. By default, if a string is given and the response is empty, use the string as the response body.

[show source]
    # File lib/roda.rb
690 def block_result(result)
691   res = response
692   if res.empty? && (body = block_result_body(result))
693     res.write(body)
694   end
695 end
get (*args, &block)

Match GET requests. If no arguments are provided, matches all GET requests, otherwise, matches only GET requests where the arguments given fully consume the path.

[show source]
    # File lib/roda.rb
700 def get(*args, &block)
701   _verb(args, &block) if is_get?
702 end
halt (res=response.finish)

Immediately stop execution of the route block and return the given rack response array of status, headers, and body. If no argument is given, uses the current response.

r.halt [200, {'Content-Type'=>'text/html'}, ['Hello World!']]

response.status = 200
response['Content-Type'] = 'text/html'
response.write 'Hello World!'
r.halt
[show source]
    # File lib/roda.rb
714 def halt(res=response.finish)
715   throw :halt, res
716 end
inspect ()

Show information about current request, including request class, request method and full path.

r.inspect
# => '#<Roda::RodaRequest GET /foo/bar>'
[show source]
    # File lib/roda.rb
723 def inspect
724   "#<#{self.class.inspect} #{@env["REQUEST_METHOD"]} #{path}>"
725 end
is (*args, &block)

Does a terminal match on the current path, matching only if the arguments have fully matched the path. If it matches, the match block is executed, and when the match block returns, the rack response is returned.

r.remaining_path
# => "/foo/bar"

r.is 'foo' do
  # does not match, as path isn't fully matched (/bar remaining)
end

r.is 'foo/bar' do
  # matches as path is empty after matching
end

If no arguments are given, matches if the path is already fully matched.

r.on 'foo/bar' do
  r.is do
    # matches as path is already empty
  end
end

Note that this matches only if the path after matching the arguments is empty, not if it still contains a trailing slash:

r.remaining_path
# =>  "/foo/bar/"

r.is 'foo/bar' do
  # does not match, as path isn't fully matched (/ remaining)
end

r.is 'foo/bar/' do
  # matches as path is empty after matching
end

r.on 'foo/bar' do
  r.is "" do
    # matches as path is empty after matching
  end
end
[show source]
    # File lib/roda.rb
770 def is(*args, &block)
771   if args.empty?
772     if empty_path?
773       always(&block)
774     end
775   else
776     args << TERM
777     if_match(args, &block)
778   end
779 end
is_get? ()

Optimized method for whether this request is a GET request. Similar to the default Rack::Request get? method, but can be overridden without changing rack's behavior.

[show source]
    # File lib/roda.rb
784 def is_get?
785   @env["REQUEST_METHOD"] == 'GET'
786 end
matched_path ()

The already matched part of the path, including the original SCRIPT_NAME.

[show source]
    # File lib/roda.rb
824 def matched_path
825   e = @env
826   e["SCRIPT_NAME"] + e["PATH_INFO"].chomp(@remaining_path)
827 end
on (*args, &block)

Does a match on the path, matching only if the arguments have matched the path. Because this doesn't fully match the path, this is usually used to setup branches of the routing tree, not for final handling of the request.

r.remaining_path
# => "/foo/bar"

r.on 'foo' do
  # matches, path is /bar after matching
end

r.on 'bar' do
  # does not match
end

Like other routing methods, If it matches, the match block is executed, and when the match block returns, the rack response is returned. However, in general you will call another routing method inside the match block that fully matches the path and does the final handling for the request:

r.on 'foo' do
  r.is 'bar' do
    # handle /foo/bar request
  end
end
[show source]
    # File lib/roda.rb
815 def on(*args, &block)
816   if args.empty?
817     always(&block)
818   else
819     if_match(args, &block)
820   end
821 end
path ()

This an an optimized version of Rack::Request#path.

r.env['SCRIPT_NAME'] = '/foo'
r.env['PATH_INFO'] = '/bar'
r.path
# => '/foo/bar'
[show source]
    # File lib/roda.rb
835 def path
836   e = @env
837   "#{e["SCRIPT_NAME"]}#{e["PATH_INFO"]}"
838 end
post (*args, &block)

Match POST requests. If no arguments are provided, matches all POST requests, otherwise, matches only POST requests where the arguments given fully consume the path.

[show source]
    # File lib/roda.rb
852 def post(*args, &block)
853   _verb(args, &block) if post?
854 end
real_remaining_path ()

An alias of remaining_path. If a plugin changes remaining_path then it should override this method to return the untouched original.

[show source]
    # File lib/roda.rb
845 def real_remaining_path
846   remaining_path
847 end
redirect (path=default_redirect_path, status=default_redirect_status)

Immediately redirect to the path using the status code. This ends the processing of the request:

r.redirect '/page1', 301 if r['param'] == 'value1'
r.redirect '/page2' # uses 302 status code
response.status = 404 # not reached

If you do not provide a path, by default it will redirect to the same path if the request is not a GET request. This is designed to make it easy to use where a POST request to a URL changes state, GET returns the current state, and you want to show the current state after changing:

r.is "foo" do
  r.get do
    # show state
  end

  r.post do
    # change state
    r.redirect
  end
end
[show source]
    # File lib/roda.rb
879 def redirect(path=default_redirect_path, status=default_redirect_status)
880   response.redirect(path, status)
881   throw :halt, response.finish
882 end
response ()

The response related to the current request. See ResponseMethods for instance methods for the response, but in general the most common usage is to override the response status and headers:

response.status = 200
response['Header-Name'] = 'Header value'
[show source]
    # File lib/roda.rb
890 def response
891   @scope.response
892 end
roda_class ()

Return the Roda class related to this request.

[show source]
    # File lib/roda.rb
895 def roda_class
896   self.class.roda_class
897 end
root (&block)

Match method that only matches GET requests where the current path is /. If it matches, the match block is executed, and when the match block returns, the rack response is returned.

[r.request_method, r.remaining_path]
# => ['GET', '/']

r.root do
  # matches
end

This is usuable inside other match blocks:

[r.request_method, r.remaining_path]
# => ['GET', '/foo/']

r.on 'foo' do
  r.root do
    # matches
  end
end

Note that this does not match non-GET requests:

[r.request_method, r.remaining_path]
# => ['POST', '/']

r.root do
  # does not match
end

Use r.post "" for POST requests where the current path is /.

Nor does it match empty paths:

[r.request_method, r.remaining_path]
# => ['GET', '/foo']

r.on 'foo' do
  r.root do
    # does not match
  end
end

Use r.get true to handle GET requests where the current path is empty.

[show source]
    # File lib/roda.rb
946 def root(&block)
947   if remaining_path == "/" && is_get?
948     always(&block)
949   end
950 end
run (app)

Call the given rack app with the environment and return the response from the rack app as the response for this request. This ends the processing of the request:

r.run(proc{[403, {}, []]}) unless r['letmein'] == '1'
r.run(proc{[404, {}, []]})
response.status = 404 # not reached

This updates SCRIPT_NAME/PATH_INFO based on the current remaining_path before dispatching to another rack app, so the app still works as a URL mapper.

[show source]
    # File lib/roda.rb
963 def run(app)
964   e = @env
965   path = real_remaining_path
966   sn = "SCRIPT_NAME"
967   pi = "PATH_INFO"
968   script_name = e[sn]
969   path_info = e[pi]
970   begin
971     e[sn] += path_info.chomp(path)
972     e[pi] = path
973     throw :halt, app.call(e)
974   ensure
975     e[sn] = script_name
976     e[pi] = path_info
977   end
978 end
session ()

The session for the current request. Raises a RodaError if a session handler has not been loaded.

[show source]
    # File lib/roda.rb
982 def session
983   @env['rack.session'] || raise(RodaError, "You're missing a session handler, try using the sessions plugin.")
984 end