% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/router.R
\name{Router}
\alias{Router}
\title{Router}
\description{
A port of the \href{https://github.com/pillarjs/router}{pillarjs/router} package
for R. Maintains an ordered stack of layers; each layer pairs a path pattern
with a middleware function, a nested \code{Router}, or a \code{Route} object. Middleware
and nested routers are added via \verb{$use()}; routes are added via \verb{$route()} or
the HTTP-verb shortcuts. When a request arrives, the stack is walked in order
and each matching layer is invoked until the request is handled or the stack
is exhausted.
\subsection{Important details}{
\itemize{
\item \strong{\code{forward()} instead of \code{next()}} -- \code{next} is a reserved word in R.
\code{forward("route")} and \code{forward("router")} work identically to their
Express counterparts.
\item \strong{\code{forward} is implicit} -- handlers do not need to declare \code{forward} as
an argument to call it; it is automatically injected into the handler's
formals if absent. \code{function(req, res) { forward() }} works just as well
as \code{function(req, res, forward) { forward() }}.
\item \strong{\code{forward} is auto-called} -- if a handler returns without calling
\code{forward()} or sending a response, \code{forward()} is called automatically.
\item \strong{Error handlers take three arguments} -- write error handlers as
\verb{(err, req, res)}; \code{forward} is injected automatically as the fourth
argument.
}
}

\subsection{HTTP verb shortcuts}{

\verb{$get()}, \verb{$post()}, \verb{$put()}, \verb{$delete()}, etc. (one per HTTP verb) and
\verb{$all()} are convenience wrappers with signature \verb{(path, ...)} equivalent to
\verb{router$route(path)$<verb>(...)}. They return \code{self} invisibly for chaining.
}
}
\examples{
router <- Router$new()

router$get(
  "/get",
  function(req, res) {
    res$send("Hello there!")
  }
)$post(
  "/post",
  function(req, res) {
    res$send("Goodbye!")
  }
)

router$get(
  "/hello",
  function(req, res) {
    forward()
  },
  function(req, res) {
    res$send("Hello!")
  }
)

router$post("/bye", function(req, res) {
  res$send("Bye!")
})

router$route("/hi")$get(function(req, res) {
  res$send("handling a GET request!")
})$post(function(req, res) {
  res$send("handling a POST request!")
})

router$get(
  c("/path", "/another-path"),
  function(req, res) {
    res$send("Hola!")
  }
)

## ------------------------------------------------
## Method `Router$param`
## ------------------------------------------------

router <- Router$new()

router$param("id", function(req, res, value, name) {
  user <- findUser(value)
  req$user <- list(id = value, name = user$name)
  forward()
})

router$get("/user/:id", function(req, res) {
  res$send(paste("user:", req$user$name))
})
}
\section{Methods}{
\subsection{Public methods}{
\itemize{
\item \href{#method-Router-new}{\code{Router$new()}}
\item \href{#method-Router-handle}{\code{Router$handle()}}
\item \href{#method-Router-use}{\code{Router$use()}}
\item \href{#method-Router-route}{\code{Router$route()}}
\item \href{#method-Router-param}{\code{Router$param()}}
\item \href{#method-Router-static}{\code{Router$static()}}
\item \href{#method-Router-getStack}{\code{Router$getStack()}}
\item \href{#method-Router-clone}{\code{Router$clone()}}
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-Router-new"></a>}}
\if{latex}{\out{\hypertarget{method-Router-new}{}}}
\subsection{Method \code{new()}}{
Creates a new \code{Router}.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{Router$new(caseSensitive = FALSE, mergeParams = FALSE, strict = FALSE)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{caseSensitive}}{(\code{logical(1)})\cr
When \code{TRUE}, path matching is case-sensitive (\verb{/Foo} does not match \verb{/foo}).
Default \code{FALSE}.}

\item{\code{mergeParams}}{(\code{logical(1)})\cr
When \code{TRUE}, \code{req$params} from a parent router are merged with those of
this router instead of being replaced. Default \code{FALSE}.}

\item{\code{strict}}{(\code{logical(1)})\cr
When \code{TRUE}, trailing slashes are significant (\verb{/foo/} does not match \verb{/foo}).
Default \code{FALSE}.}
}
\if{html}{\out{</div>}}
}
\subsection{Returns}{
A new \code{Router} object.
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-Router-handle"></a>}}
\if{latex}{\out{\hypertarget{method-Router-handle}{}}}
\subsection{Method \code{handle()}}{
Dispatches a request through the router's layer stack. Normally called
by a server or a parent router rather than directly.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{Router$handle(req, res = NULL, callback = NULL)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{req}}{(\code{environment})\cr Rook request environment.}

\item{\code{res}}{(\code{Response})\cr Response object.}

\item{\code{callback}}{(\code{function})\cr
Called when no layer matched or an unhandled error occurred.}
}
\if{html}{\out{</div>}}
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-Router-use"></a>}}
\if{latex}{\out{\hypertarget{method-Router-use}{}}}
\subsection{Method \code{use()}}{
Mounts one or more middleware handlers, optionally scoped to a path prefix.
A \link{Router} may be passed and will be wrapped automatically. Functions whose
first parameter is named \code{err} are treated as error handlers.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{Router$use(...)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{...}}{(\verb{function | list})\cr
An optional leading \code{character(1)} path prefix, followed by one or more
handler functions, nested lists of functions, or another \link{Router}.}
}
\if{html}{\out{</div>}}
}
\subsection{Returns}{
\code{self} invisibly.
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-Router-route"></a>}}
\if{latex}{\out{\hypertarget{method-Router-route}{}}}
\subsection{Method \code{route()}}{
Creates a new \code{Route} for \code{path} and appends it to the stack.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{Router$route(path)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{path}}{(\code{character(1)})\cr Path pattern.}
}
\if{html}{\out{</div>}}
}
\subsection{Returns}{
The new \code{Route} invisibly.
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-Router-param"></a>}}
\if{latex}{\out{\hypertarget{method-Router-param}{}}}
\subsection{Method \code{param()}}{
Registers a callback triggered whenever a named route parameter is
present in a matched route. The callback runs before the route handler.

The callback signature is \verb{function(req, res, value, name)}:
\itemize{
\item \code{value} -- the captured value of the parameter.
\item \code{name}  -- the parameter name (character).
}
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{Router$param(name, fn)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{name}}{(\code{character(1)})\cr Name of the route parameter to watch.}

\item{\code{fn}}{(\code{function})\cr
Callback with signature \verb{function(req, res, value, name)}.}
}
\if{html}{\out{</div>}}
}
\subsection{Returns}{
\code{self} invisibly.
}
\subsection{Examples}{
\if{html}{\out{<div class="r example copy">}}
\preformatted{router <- Router$new()

router$param("id", function(req, res, value, name) {
  user <- findUser(value)
  req$user <- list(id = value, name = user$name)
  forward()
})

router$get("/user/:id", function(req, res) {
  res$send(paste("user:", req$user$name))
})
}
\if{html}{\out{</div>}}

}

}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-Router-static"></a>}}
\if{latex}{\out{\hypertarget{method-Router-static}{}}}
\subsection{Method \code{static()}}{
Registers a directory of static files to be served at a given URL prefix.
Static files are served directly by httpuv's background I/O thread without
invoking R.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{Router$static(root, url, ...)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{root}}{(\code{character(1)})\cr
Local filesystem path to the directory containing the files to serve.}

\item{\code{url}}{(\code{character(1)})\cr
URL prefix at which the files will be available (e.g. \code{"/static"}).}

\item{\code{...}}{Additional arguments passed to \code{\link[httpuv:staticPath]{httpuv::staticPath()}}.}
}
\if{html}{\out{</div>}}
}
\subsection{Returns}{
\code{self} invisibly.
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-Router-getStack"></a>}}
\if{latex}{\out{\hypertarget{method-Router-getStack}{}}}
\subsection{Method \code{getStack()}}{
Returns the internal layer stack.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{Router$getStack()}\if{html}{\out{</div>}}
}

\subsection{Returns}{
\code{list} of \code{Layer} objects.
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-Router-clone"></a>}}
\if{latex}{\out{\hypertarget{method-Router-clone}{}}}
\subsection{Method \code{clone()}}{
The objects of this class are cloneable with this method.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{Router$clone(deep = FALSE)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{deep}}{Whether to make a deep clone.}
}
\if{html}{\out{</div>}}
}
}
}
