Route {routr} | R Documentation |
Create a route for dispatching on URL
Description
The Route
class is used to encapsulate a single URL dispatch, that is,
chose a single handler from a range based on a URL path. A handler will be
called with a request, response, and keys argument as well as any additional
arguments passed on to dispatch()
.
Details
The path will strip the query string prior to assignment of the handler, can
contain wildcards, and can be parameterised using the :
prefix. If there
are multiple matches of the request path the most specific will be chosen.
Specificity is based on number of elements (most), number of parameters
(least), and number of wildcards (least), in that order. Parameter
values will be available in the keys argument passed to the handler, e.g. a
path of /user/:user_id
will provide list(user_id = 123)
for a dispatch on
/user/123
in the keys
argument.
Handlers are only called for their side-effects and are expected to return
either TRUE
or FALSE
indicating whether additional routes in a
RouteStack
should be called, e.g. if a handler is returning FALSE
all
further processing of the request will be terminated and the response will be
passed along in its current state. Thus, the intend of the handlers is to
modify the request and response objects, in place. All calls to handlers will
be wrapped in try()
and if an exception is raised the response code will be
set to 500
with the body of the response being the error message. Further
processing of the request will be terminated. If a different error handling
scheme is wanted it must be implemented within the handler (the standard
approach is chosen to avoid handler errors resulting in a server crash).
A handler is referencing a specific HTTP method (get
, post
, etc.) but can
also reference all
to indicate that it should match all types of requests.
Handlers referencing all
have lower precedence than those referencing
specific methods, so will only be called if a match is not found within the
handlers of the specific method.
Initialization
A new 'Route'-object is initialized using the new()
method on the
generator:
Usage
route <- Route$new(...)
|
Arguments
... | Handlers to add up front. Must be in the form of named lists where the names corresponds to paths and the elements are the handlers. The name of the argument itself defines the method to listen on (see examples) |
Methods
The following methods are accessible in a Route
object:
add_handler(method, path, handler)
Add a handler to the specified method and path. The special method
'all'
will allow the handler to match all http request methods. The path is a URL path consisting of strings, parameters (strings prefixed with:
), and wildcards (*
), separated by/
. A wildcard will match anything and is thus not restricted to a single path element (i.e. it will span multiple/
if possible). The handler must be a function containing the argumentsrequest
,response
,keys
, and...
, and must return eitherTRUE
orFALSE
. Therequest
argument will be a reqres::Request object and theresponse
argument will be a reqres::Response object matching the current exchange. Thekeys
argument will be a named list with the value of all matched parameters from the path. Any additional argument passed on to thedispatch
method will be avaiable as well. This method will override an existing handler with the same method and path.remove_handler(method, path)
Removes the handler assigned to the specified method and path. If no handler have been assigned it will throw a warning.
get_handler(method, path)
Returns a handler already assigned to the specified method and path. If no handler have been assigned it will throw a warning.
remap_handlers(.f)
Allows you to loop through all added handlers and reassings them at will. A function with the parameters
method
,path
, andhandler
must be provided which is responsible for reassigning the handler given in the arguments. If the function does not reassign the handler, then the handler is removed.dispatch(request, ...)
Based on a reqres::Request object the route will find the correct handler and call it with the correct arguments. Anything passed in with
...
will be passed along to the handler.
Methods
Public methods
Method new()
Usage
Route$new(...)
Method print()
Usage
Route$print(...)
Method add_handler()
Usage
Route$add_handler(method, path, handler)
Method remove_handler()
Usage
Route$remove_handler(method, path)
Method get_handler()
Usage
Route$get_handler(method, path)
Method remap_handlers()
Usage
Route$remap_handlers(.f)
Method dispatch()
Usage
Route$dispatch(request, ...)
Method clone()
The objects of this class are cloneable with this method.
Usage
Route$clone(deep = FALSE)
Arguments
deep
Whether to make a deep clone.
See Also
RouteStack for binding multiple routes sequentially
Examples
# Initialise an empty route
route <- Route$new()
# Initialise a route with handlers assigned
route <- Route$new(
all = list(
'/*' = function(request, response, keys, ...) {
message('Request recieved')
TRUE
}
)
)
# Remove it again
route$remove_handler('all', '/*')