Description: This package contains the Rook specification and
convenience software for building and running Rook applications. To
get started, be sure and read the 'Rook' help file first.
Depends: R (>= 2.13.0)
Imports: utils, tools, methods, brew
License: GPL-2
LazyLoad: yes
Packaged: 2014-10-20 16:54:31 UTC; jeffrey
NeedsCompilation: yes
Repository: CRAN
Date/Publication: 2014-10-20 19:18:06
Rook/man/ 0000755 0001751 0000144 00000000000 12421227305 011753 5 ustar hornik users Rook/man/App-class.Rd 0000644 0001751 0000144 00000001312 12332170455 014066 0 ustar hornik users \name{App-class}
\Rdversion{1.1}
\docType{class}
\alias{App-class}
\alias{App}
\title{Class \code{App}}
\description{
Abstract class from which \code{Middleware} and \code{Builder} inherit. Provides the \code{app} field.
\code{App} can also be used to instantiate reference classed applications wrapped around a function. See \code{\link{Middleware}} for an example.
}
\section{Fields}{
\describe{
\item{\code{app}:}{A Rook application.}
}
}
\section{Methods}{
\describe{
\item{\code{new(app=NULL)}:}{ Creates a new \code{App} object. \code{app} is any \code{Rook} aware R object.}
}
}
\seealso{
\code{\link{is_rookable}}, \code{\link{Builder}}, and \code{\link{Middleware}}.
}
\keyword{classes}
Rook/man/Response-class.Rd 0000644 0001751 0000144 00000003174 12421227305 015150 0 ustar hornik users \name{Response-class}
\Rdversion{1.1}
\docType{class}
\alias{Response-class}
\alias{Response}
\title{Class \code{Response}}
\description{
A convenience class for creating \code{\link{Rook}} responses.
}
\seealso{
\code{\link{Rhttpd}} and \code{\link{Request}}.
}
\examples{
s <- Rhttpd$new()
\dontrun{
s$start(quiet=TRUE)
}
s$add(name="response",
app=function(env){
req <- Request$new(env)
res <- Response$new()
res$write('hello')
res$finish()
}
)
\dontrun{
s$browse('response') # Opens a browser window to the app.
}
s$remove(all=TRUE)
rm(s)
}
\keyword{classes}
\section{Methods}{
\describe{
\item{\code{header(key, value)}:}{ Sets an HTTP header for the
response. Both \code{key} and \code{value} must be character strings. If \code{value} is missing, then the \code{header} value is returned.}
\item{\code{redirect(target, status=302)}:}{ Sets up an HTTP redirect to the \code{target} url. }
\item{\code{write(str)}:}{ Takes a character vector and appends it to the response body. }
\item{\code{new(body='', status=200, headers=list())}:}{ Create a new Response object. \code{body} is a character vector, \code{status} is an HTTP status value. \code{headers} is a named list.}
\item{\code{set_cookie(key, value)}:}{ Sets an HTTP cookie for the response. Both \code{key} and \code{value} must be character strings.}
\item{\code{delete_cookie(key, value)}:}{ Sends appropriate HTTP header to delete the associated cookie on the client. \code{key} and \code{value} must be character strings.}
\item{\code{finish()}:}{ Returns the response according to the Rook specification.}
}
}
Rook/man/Static-class.Rd 0000644 0001751 0000144 00000001072 12332170455 014600 0 ustar hornik users \name{Static-class}
\Rdversion{1.1}
\docType{class}
\alias{Static-class}
\alias{Static}
\title{Class \code{Static}}
\description{
A \code{\link{Middleware}} class for serving static files from a root directory given a set of url paths.
}
\seealso{
See \code{\link{Builder}} for an example.
}
\keyword{classes}
\section{Methods}{
\describe{
\item{\code{new(urls, root)}:}{ Creates a new object. \code{urls} is a character vector whose elements must start with a \code{'/'}. \code{root} is a length 1 character vector whose value must be a valid directory. }
}
}
Rook/man/Request-class.Rd 0000644 0001751 0000144 00000015604 12421227305 015003 0 ustar hornik users \name{Request-class}
\Rdversion{1.1}
\docType{class}
\alias{Request-class}
\alias{Request}
\title{Class \code{Request}}
\description{
A convenience class for working with a \code{\link{Rook}} environment. Be sure to see the example at the end of this help file.
}
\examples{
#
# The following example prints out the result of each method.
#
ls_str <- function(s) paste(capture.output(str(s),file=NULL),collapse='\n')
s <- Rhttpd$new()
\dontrun{
s$start(quiet=TRUE)
}
s$add(name="request",
app=function(env){
req <- Request$new(env)
res <- Response$new()
res$set_cookie('imacookie','42')
action <- req$to_url('/foo',bar=1,baz='three')
res$write('
')
res$write(c('parseable_data: ',req$parseable_data(),'\n'))
res$write(c('url: ',req$url(),'\n'))
res$write(c('request_method: ',req$request_method(),'\n'))
res$write(c('GET: ',ls_str(req$GET()),'\n'))
res$write(c('post: ',req$post(),'\n'))
res$write(c('media_type: ',req$media_type(),'\n'))
res$write(c('query_string: ',req$query_string(),'\n'))
res$write(c('fullpath: ',req$fullpath(),'\n'))
res$write(c('referer: ',req$referer(),'\n'))
res$write(c('cookies: ',ls_str(req$cookies()),'\n'))
res$write(c('content_charset: ',req$content_charset(),'\n'))
res$write(c('head: ',req$head(),'\n'))
res$write(c('accept_encoding: ',req$accept_encoding(),'\n'))
res$write(c('content_length: ',req$content_length(),'\n'))
res$write(c('form_data: ',req$form_data(),'\n'))
res$write(c('xhr: ',req$xhr(),'\n'))
res$write(c('params: ',ls_str(req$params()),'\n'))
res$write(c('media_type_params:\n',ls_str(req$media_type_params()),'\n'))
res$write(c('user_agent: ',req$user_agent(),'\n'))
res$write(c('put: ',req$put(),'\n'))
res$write(c('get: ',req$get(),'\n'))
res$write(c('path: ',req$path(),'\n'))
res$write(c('body: ',ls_str(req$body()),'\n'))
res$write(c('port: ',req$port(),'\n'))
res$write(c('host_with_port: ',req$host_with_port(),'\n'))
res$write(c('scheme: ',req$scheme(),'\n'))
res$write(c('ip: ',req$ip(),'\n'))
res$write(c('options: ',req$options(),'\n'))
res$write(c('to_url: ',req$to_url('foo',bar=1,baz='two'),'\n'))
res$write(c('host: ',req$host(),'\n'))
res$write(c('POST: ',ls_str(req$POST()),'\n'))
res$write(c('trace: ',req$trace(),'\n'))
res$write(c('script_name: ',req$script_name(),'\n'))
res$write(c('content_type: ',req$content_type(),'\n'))
res$write(c('delete: ',req$delete(),'\n'))
res$write(c('path_info: ',req$path_info(),'\n'))
res$write(c('\nRac env: ',ls_str(as.list(env)),'\n'))
res$finish()
}
)
\dontrun{
s$browse('request') # Opens a browser window to the app.
}
s$remove(all=TRUE)
rm(s)
}
\section{Methods}{
\describe{
\item{\code{parseable_data()}:}{ Returns a boolean value determining if the POST payload is parseable. }
\item{\code{url()}:}{ Returns url as a character string containing the scheme, host, port, and possibly the GET query string if supplied.}
\item{\code{request_method()}:}{ Returns the HTTP method as a character string, e.g. 'GET', 'POST', etc. }
\item{\code{GET()}:}{ Returns a named list containing the variables parsed from the query string. }
\item{\code{post()}:}{ Returns TRUE if the current request method is 'POST', FALSE otherwise. }
\item{\code{new(env)}:}{ Instantiates a new \code{Request} object for the given \code{Rook} environment.}
\item{\code{media_type()}:}{ Returns the media type for the current request as a character string.}
\item{\code{query_string()}:}{ Returns the unparsed query string. }
\item{\code{fullpath()}:}{ Returns the same string as url() but without the scheme, host, and port. }
\item{\code{referer()} or \code{referrer()}:}{ Returns the referring url. }
\item{\code{cookies()}:}{ Returns any cookies in the request as a named list. }
\item{\code{content_charset()}:}{ Returns the content charset as a character string. }
\item{\code{head()}:}{ Returns TRUE if the HTTP method is 'HEAD', FALSE otherwise.}
\item{\code{accept_encoding()}:}{ Returns the accept encoding header as a character string.}
\item{\code{content_length()}:}{ Returns content length header value as a string. }
\item{\code{form_data()}:}{ Returns TRUE if there's form data, e.g. POST data with the request, FALSE otherwise.}
\item{\code{xhr()}:}{ Returns the x-requested-with header value as a character string.}
\item{\code{params()}:}{ Returns the combination of \code{POST()} and \code{GET()} in one named list.}
\item{\code{media_type_params()}:}{ Returns any media type parameters from the content type as a named list. }
\item{\code{user_agent()}:}{ Returns the user-agent header value as a character string. }
\item{\code{put()}:}{ Returns TRUE if the current request is a 'PUT'. }
\item{\code{get()}:}{ Returns TRUE if the current request is a 'GET'. }
\item{\code{path()}:}{ Returns a character string like \code{fullpath()} but without the query string. }
\item{\code{body()}:}{ Returns the 'rook.input' object from the environment. See \code{\link{RhttpdInputStream}} for more information.}
\item{\code{port()}:}{ Returns the server port as an integer.e}
\item{\code{host_with_port()}:}{ Returns the host and port as a character string separated by ':'. }
\item{\code{scheme()}:}{ Returns the scheme, e.g. 'http' or 'https', as a character string. }
\item{\code{ip()}:}{ Returns the remote IP address as a character string. }
\item{\code{options()}:}{ Returns TRUE if the current request is 'OPTIONS'. }
\item{\code{to_url(url, ...)}:}{ Concatenates the script name with the \code{url} argument along with any named parameters passed via \code{...} .}
\item{\code{host()}:}{ Returns the server host as a character string. }
\item{\code{POST()}:}{ Returns a named list containing the variables parsed from the POST payload.}
\item{\code{trace()}:}{ Returns TRUE if the current request is 'TRACE'. }
\item{\code{script_name(s=NULL)}:}{ Returns the script name of the application, e.g. '/custom/multi'. Also, if \code{s} is not NULL, sets the script name to \code{s}. }
\item{\code{content_type()}:}{ Returns the content-type header value as a character string. }
\item{\code{delete()}:}{ Returns TRUE if the current request is 'DELETE'. }
\item{\code{path_info(s=NULL)}:}{ Returns the portion of the url after the script name as a character string. If \code{s} is not NULL, sets the path info to \code{s}.}
}
}
\seealso{
\code{\link{Rhttpd}} and \code{\link{Response}}.
}
\keyword{classes}
Rook/man/Multipart-class.Rd 0000644 0001751 0000144 00000002345 12332170455 015336 0 ustar hornik users \name{Multipart-class}
\Rdversion{1.1}
\docType{class}
\alias{Multipart-class}
\alias{Multipart}
\title{Class \code{Multipart} and object \code{Multipart}}
\description{
A convenience object for parsing multipart/form-data POST payloads.
}
\examples{
s <- Rhttpd$new()
\dontrun{
s$start(quiet=TRUE)
}
s$add(name="multi",
app=function(env){
req <- Request$new(env)
res <- Response$new()
res$write('
')
post <- Multipart$parse(env)
if (length(post)){
poststr <- paste(capture.output(str(post),file=NULL),collapse='\n')
res$write(c('',poststr,'
'))
}
res$finish()
}
)
\dontrun{
s$browse('multi') # Opens a browser window to the app.
}
s$remove(all=TRUE)
rm(s)
}
\seealso{
\code{\link{Rhttpd}}, \code{\link{Request}}, and \code{\link{Response}}.
}
\section{Methods}{
\describe{
\item{\code{parse(env)}:}{ Returns parsed POST payload as a named list. \code{env} is an environment created by \code{Rhttpd} and conforms to the \code{\link{Rook}} specification.}
}
}
\keyword{classes}
Rook/man/Server.Rd 0000644 0001751 0000144 00000000505 12332170455 013514 0 ustar hornik users \name{Server}
\Rdversion{1.1}
\alias{Server}
\title{Rook Server Object}
\description{
\code{Server} is an object exported by Rook that has no value to the user. It is mainly used by web servers for their convenience. To see an example of how it may be used, see rApache.R in the inst/servers directory.
}
\keyword{classes}
Rook/man/Rhttpd-class.Rd 0000644 0001751 0000144 00000010030 12332170455 014610 0 ustar hornik users \name{Rhttpd-class}
\Rdversion{1.1}
\docType{class}
\alias{Rhttpd-class}
\alias{Rhttpd}
\title{Class \code{Rhttpd}}
\description{
\code{Rhttpd} is a convenience class for installing and running Rook
applications. It hides the details of starting and stopping the server
and adding and removing \code{Rook} applications from the server.
Users starts by creating one \code{Rhttpd} object, then adding
applications to it, and then starting the server (see the section
\dQuote{Examples} for a typical session). There are no restrictions on
creating more than one server object, but know that it only manages the
applications that are added to it and not others.
Applications can be added and removed regardless of whether or
not the server is running. Stopping the server does not remove
any applications. Adding an application with the same name as
one already installed simply overwrites the one installed. If
the server is started with no applications installed, it will
install the application named \code{RookTestApp} located in:
\code{system.file('exampleApps/RookTestApp.R',package='Rook')}.
Also, see \code{\link{browseURL}} to learn how to get R to
automatically launch your favorite web browser.
NOTE: This version of Rook can only listen on the loopback device.
}
\seealso{
\code{\link{RhttpdApp}}
}
\examples{
# Create an Rhttpd object and start the internal web server. Note that
# if there are no applications added, then the default RookTest app in
# system.file('exampleApps/RookTestApp.R',package='Rook') is automatically
# added.
s <- Rhttpd$new()
\dontrun{
s$start(quiet=TRUE)
s$browse(1)
}
s$print()
# Be sure to install the Hmisc package before installing and running
# this application. You will want to; it's a pretty good one.
# s$add(
# app=system.file('exampleApps/Hmisc/config.R',package='Rook'),
# name='hmisc')
s$add(
app=system.file('exampleApps/helloworld.R',package='Rook'),
name='hello'
)
s$add(
app=system.file('exampleApps/helloworldref.R',package='Rook'),
name='helloref'
)
s$add(
app=system.file('exampleApps/summary.R',package='Rook'),
name='summary'
)
s$print()
# Stops the server but doesn't uninstall the app
\dontrun{
s$stop()
}
s$remove(all=TRUE)
rm(s)
}
\keyword{classes}
\section{Methods}{
\describe{
\item{\code{open(x)} or \code{browse(x)}:}{ Calls \code{\link[utils]{browseURL}} on the installed Rook application designated by \code{x}. \code{x} is either an integer or a character string. See the output of \code{print()}.}
\item{\code{print()} or \code{show()}:}{ Lists the installed Rook applications.}
\item{\code{remove(app,all=FALSE)}:}{ Removes the application known to the server. \code{app} can be an \code{RhttpdApp} object previously added, the name of the application as a character string, or an index as a numeric or integer value. See the output of \code{print()}.}
\item{\code{full_url(i)}:}{ Returns the absolute url to the application for the given index.}
\item{\code{start(listen='127.0.0.1', port=getOption('help.ports'), quiet=FALSE)}:}{ Starts the server on the loopback device and \code{port}. \code{listen} is always character string. Note that if there are no applications added to the object prior to starting, then the RookTestApp located in \code{system.file('exampleApps/RookTestApp.R',package='Rook')} is automatically added.}
\item{\code{new()}:}{ Create a new \code{Rhttpd} object. }
\item{\code{launch(...)}:}{ Combines the steps of starting the server, creating an \code{RhttpdApp} object, adding it to the server, and opening the app in the browser. \code{...} argument is passed to \code{RhttpdApp$new()}.}
\item{\code{debug()}:}{ Returns the integer value provided by \code{getOption('Rhttpd_debug')} or 0 if the option is NULL. }
\item{\code{stop()}:}{ Stops the server. }
\item{\code{add(app=NULL,name=NULL)}:}{ Adds a new \code{Rook} application to the server. \code{app} can be an \code{\link{RhttpdApp}} object or any \code{Rook} application. \code{name} is a character string and is ignored if \code{app} is an \code{RhttpdApp} object.}
}
}
Rook/man/Middleware-class.Rd 0000644 0001751 0000144 00000003522 12332170455 015430 0 ustar hornik users \name{Middleware-class}
\Rdversion{1.1}
\docType{class}
\alias{Middleware-class}
\alias{Middleware}
\title{Class \code{Middleware}}
\description{
An abstract class for building Rook Middleware applications. \code{Middleware} applications either handle the incoming web request or hand off the request to the Rook app defined in the field of the same name.
}
\examples{
# Middleware applications are typically instantiated in the argument list of
# Builder$new(), but here is stand-alone example.
#
# Once your browser loads the app, you will see something like this in
# your location bar: http://127.0.0.1:28649/custom/middle. Add '/foo'
# onto the end of that and reload.
setRefClass(
'FooBar',
contains = 'Middleware',
methods = list(
initialize = function(...){
# app to defer to.
callSuper(app=App$new(function(env){
res <- Response$new()
res$write("I'm the deferred app.
")
res$finish()
}))
},
call = function(env){
req <- Request$new(env)
res <- Response$new()
if (length(grep('foo',req$path_info()))){
res$write("I'm the middleware app.
")
return(res$finish())
} else {
app$call(env)
}
}
)
)
s <- Rhttpd$new()
\dontrun{
s$start(quiet=TRUE)
}
s$add(name="middle",app=getRefClass('FooBar')$new())
\dontrun{
s$browse('middle') # Opens a browser window to the app.
}
s$remove(all=TRUE)
rm(s)
}
\seealso{
The following classes implement Middleware:
\code{\link{Brewery}} and \code{\link{Static}}.
}
\section{Methods}{
\describe{
\item{\code{set_app(app)}:}{ \code{app} is a \code{\link{Rook}} application that will handle the request if this Middleware app does not. }
}
}
\keyword{classes}
Rook/man/Mime-class.Rd 0000644 0001751 0000144 00000001237 12332170455 014243 0 ustar hornik users \name{Mime-class}
\Rdversion{1.1}
\docType{class}
\alias{Mime-class}
\alias{Mime}
\title{Class \code{Mime} and object \code{Mime}}
\description{
A convenience object for determining the MIME type of a file name.
}
\examples{
Mime$file_extname('foo.png')
Mime$mime_type('.png')
}
\keyword{classes}
\section{Methods}{
\describe{
\item{\code{file_extname(fname=NULL)}:}{ Returns the file extensions for the given file.}
\item{\code{mime_type(ext=NULL, fallback='application/octet-stream')}:}{ Returns the MIME type given the file extension. Be sure to include the dot character in \code{ext}. If no match is found, then the fallback MIME type is returned.}
}
}
Rook/man/URLMap-class.Rd 0000644 0001751 0000144 00000002442 12332170455 014453 0 ustar hornik users \name{URLMap-class}
\Rdversion{1.1}
\docType{class}
\alias{URLMap-class}
\alias{URLMap}
\title{Class \code{URLMap}}
\description{
A \code{\link{Rook}} application that maps url paths to other \code{Rook} applications.
}
\seealso{
\code{\link{Rhttpd}}.
}
\examples{
s <- Rhttpd$new()
s$add(
name="pingpong",
app=Rook::URLMap$new(
'/ping' = function(env){
req <- Rook::Request$new(env)
res <- Rook::Response$new()
res$write(sprintf('',req$to_url("/pong")))
res$finish()
},
'/pong' = function(env){
req <- Rook::Request$new(env)
res <- Rook::Response$new()
res$write(sprintf('',req$to_url("/ping")))
res$finish()
},
'/?' = function(env){
req <- Rook::Request$new(env)
res <- Rook::Response$new()
res$redirect(req$to_url('/pong'))
res$finish()
}
)
)
\dontrun{
s$start(quiet=TRUE)
s$browse('pingpong')
}
s$remove('pingpong')
\dontrun{
s$stop()
}
rm(s)
}
\keyword{classes}
\section{Methods}{
\describe{
\item{\code{new(...)}:}{ Creates a \code{Rook} application. All arguments must be \code{Rook} applications and named as in the example.}
}
}
Rook/man/RhttpdApp-class.Rd 0000644 0001751 0000144 00000003223 12332170455 015257 0 ustar hornik users \name{RhttpdApp-class}
\Rdversion{1.1}
\docType{class}
\alias{RhttpdApp-class}
\alias{RhttpdApp}
\title{Class \code{RhttpdApp}}
\description{
Creates a Rook application ready to add to an \code{\link{Rhttpd}} server.
}
\details{
The internal web server allows dispatching to user-defined closures
located in tools:::.httpd.handlers.env. For instance, if a handler named
'foo' is placed there, then the url path to that handler is /custom/foo.
\code{RhttpdApp} along with \code{\link{Rhttpd}} hide these details by
allowing a user to create application objects specifying only their name
and the application. There is currently a limit of 63 characters
or less for application names.
NOTE: When a file is given as the value of the \code{app} argument
to \code{new()}, it is monitored for timestamp changes. If a change
occurs in the modification time as returned by \code{\link[base]{file.info}},
then the file is sourced prior to handling subsequent requests.
}
\seealso{
\code{\link{Rhttpd}}.
}
\examples{
s <- Rhttpd$new()
s$add(RhttpdApp$new(
name='summary',
app=system.file('exampleApps/summary.R',package='Rook')
))
\dontrun{
s$start(quiet=TRUE)
s$browse(1)
}
s$remove(all=TRUE)
# Stops the server but doesn't uninstall the app
\dontrun{
s$stop()
}
s$remove(all=TRUE)
rm(s)
}
\keyword{classes}
\section{Methods}{
\describe{
\item{\code{new(app, name)}:}{ Creates an object of class \code{RhttpdApp}. Argument \code{app} can be any \code{\link{Rook}} aware object or it can be a location to a file whose source creates a Rook aware object. That object must be named either \code{'app'} or the value of \code{name}. \code{name} is a character vector.}
}
}
Rook/man/File-class.Rd 0000644 0001751 0000144 00000001614 12332170455 014232 0 ustar hornik users \name{File-class}
\Rdversion{1.1}
\docType{class}
\alias{File-class}
\alias{File}
\title{Class \code{File}}
\description{
A Rook application that serves static files from a root directory, according to the path info of the Rook request.
}
\examples{
# This example serves all your files in /etc (on UNIX and Mac only).
#
# Note that when you open the application, you will see the word
# 'Forbidden'. "File" doesn't serve directories, so you must amend the
# url in the location bar with the file you want to view. Try adding /passwd.
s <- Rhttpd$new()
\dontrun{
s$start(quiet=TRUE)
}
s$add(name="etc",app=File$new('/etc'))
\dontrun{
s$browse('etc') # Opens a browser window to the app.
}
s$remove(all=TRUE)
rm(s)
}
\section{Methods}{
\describe{
\item{\code{new(root):}}{
\code{root} is the name of the directory from where to serve files.
}
}}
\seealso{
\code{\link{Rhttpd}}.
}
\keyword{classes}
Rook/man/RhttpdErrorStream-class.Rd 0000644 0001751 0000144 00000000437 12332170455 017010 0 ustar hornik users \name{RhttpdErrorStream-class}
\Rdversion{1.1}
\docType{class}
\alias{RhttpdErrorStream-class}
\alias{RhttpdErrorStream}
\title{Class \code{RhttpdErrorStream}}
\description{
An internal class used by \code{\link{Rhttpd}}.
}
\examples{
showClass("RhttpdErrorStream")
}
\keyword{classes}
Rook/man/suspend_console.Rd 0000644 0001751 0000144 00000000453 12332170455 015453 0 ustar hornik users \name{suspend_console}
\alias{suspend_console}
\title{
Suspend the R console
}
\description{
Calls Sys.sleep in a never-ending while loop to mimic suspension of the R console.
}
\usage{
suspend_console()
}
\value{
No value is ever returned.
}
\seealso{
\code{\link{Rook}}.
}
\keyword{function}
Rook/man/RhttpdInputStream-class.Rd 0000644 0001751 0000144 00000000437 12332170455 017016 0 ustar hornik users \name{RhttpdInputStream-class}
\Rdversion{1.1}
\docType{class}
\alias{RhttpdInputStream-class}
\alias{RhttpdInputStream}
\title{Class \code{RhttpdInputStream}}
\description{
An internal class used by \code{\link{Rhttpd}}.
}
\examples{
showClass("RhttpdInputStream")
}
\keyword{classes}
Rook/man/Redirect-class.Rd 0000644 0001751 0000144 00000001013 12332170455 015105 0 ustar hornik users \name{Redirect-class}
\Rdversion{1.1}
\docType{class}
\alias{Redirect-class}
\alias{Redirect}
\title{Class \code{Redirect}}
\description{
A \code{\link{Rook}} application whose only role is to return an HTTP redirect header to the given url.
}
\seealso{
See \code{\link{Brewery}} for an example.
}
\keyword{classes}
\section{Methods}{
\describe{
\item{\code{new(url)}:}{ Returns a \code{Rook} object. \code{url} is a character string whose value is a full or relative url to which the browser is redirected.}
}
}
Rook/man/Builder-class.Rd 0000644 0001751 0000144 00000003001 12332170455 014731 0 ustar hornik users \name{Builder-class}
\Rdversion{1.1}
\docType{class}
\alias{Builder-class}
\alias{Builder}
\title{Class \code{Builder}}
\description{
A convenience object for combining various \code{Middleware} with a default application to create a more complex Rook application.
}
\examples{
# The following is the Hmisc example. Explore the folder
# system.file('exampleApps/Hmisc',package='Rook') for more information.
s <- Rhttpd$new()
\dontrun{
library(Hmisc)
dir.create(file.path(tempdir(),'plots'),showWarnings=FALSE)
s$add( name="Hmisc",
app=Builder$new(
Static$new(
urls = c('/css','/images','/javascript'),
root = system.file('exampleApps/Hmisc',package='Rook')
),
Static$new(urls='/plots',root=tempdir()),
Brewery$new(
url='/brew',
root= system.file('exampleApps/Hmisc',package='Rook'),
imagepath=file.path(tempdir(),'plots'),
imageurl='../plots/'
),
Redirect$new('/brew/useR2007.rhtml')
)
)
s$start(quiet=TRUE)
s$browse('Hmisc') # Opens a browser window to the application.
s$remove(all=TRUE)
s$stop()
}
}
\seealso{
\code{\link{Rhttpd}}, \code{\link{Static}}, \code{\link{Brewery}}, and \code{\link{Redirect}}.
}
\keyword{classes}
\section{Methods}{
\describe{
\item{\code{new(...)}:}{ Arguments can be any \code{Middleware} object while the last argument in the list must be a valid \code{Rook} application. That is, it will handle the incoming request without deferring to another application. }
}
}
Rook/man/is_rookable.Rd 0000644 0001751 0000144 00000000712 12332170455 014537 0 ustar hornik users \name{is_rookable}
\alias{is_rookable}
\title{
Test for Rookable applications
}
\description{
A convenience function for testing whether or not objects are either a function or reference class as defined by the Rook specification for applications.
}
\usage{
is_rookable(app)
}
\arguments{
\item{app}{ Any R object.}
}
\value{
Logical determining whether or not argument is Rookable. Not vectorized.
}
\seealso{
\code{\link{Rook}}.
}
\keyword{function}
Rook/man/Utils-class.Rd 0000644 0001751 0000144 00000005104 12332170455 014451 0 ustar hornik users \name{Utils-class}
\Rdversion{1.1}
\docType{class}
\alias{Utils-class}
\alias{Utils}
\title{Class \code{Utils}}
\description{
A convenience object for working with various aspects of web requests and responses.
}
\seealso{
\code{\link{Multipart}}.
}
\examples{
Utils$bytesize('foo')
Utils$escape('foo bar')
Utils$unescape('foo+bar')
Utils$escape_html('foo ')
Utils$escape('foo ')
Utils$escape('foo\n')
Utils$status_code('OK')
Utils$status_code('Found')
Utils$status_code('Not Found')
x <- Utils$parse_query('foo=1&bar=baz')
x
Utils$rfc2822(Sys.time())
Utils$timezero()
Utils$build_query(x)
rm(x)
}
\keyword{classes}
\section{Methods}{
\describe{
\item{\code{bytesize(string=NULL)}:}{ Returns size in bytes for \code{string}, a character vector. }
\item{\code{unescape(s=NULL)}:}{ returns the url decoded value of the character vector \code{s}. Also replaces the \code{'+'} character with a space. }
\item{\code{status_code(status=NULL)}:}{ returns integer value for the given HTTP \code{status}, which can either be numeric or or a character vector describing the status. Returns \code{as.integer(500)} if \code{status} is NULL.}
\item{\code{escape_html(string=NULL)}:}{ replaces \code{"&"}, \code{"<"}, \code{">"}, \code{"'"}, and \code{'"'} with entity equivalents. }
\item{\code{raw.match(needle=NULL, haystack=NULL, all=TRUE)}:}{ returns index position of \code{needle} in \code{haystack}. All matched indexes are returned by default. \code{needle} is either a raw vector or character string. \code{haystack} is a raw vector.}
\item{\code{parse_query(qs=NULL, d=DEFAULT_SEP)}:}{ Creates a named list from the the query string \code{qs}. \code{d} is the separator value and defaults to \code{'[&;] *'}.}
\item{\code{rfc2822(ts=NULL)}:}{ Formats \code{ts} in RFC2822 time. \code{ts} must be a \code{\link{POSIXt}} object.}
\item{\code{escape(s=NULL)}:}{ Transforms any non-printable characters found in \code{s} to their percent-encoded equivalents.}
\item{\code{build_query(params=NULL)}:}{ Creates a query string from the named list given in \code{params}. }
\item{\code{timezero()}:}{ Returns a \code{POSIXct} object set to UNIX epoch. }
\item{\code{set_cookie_header(header, key, value, expires, path, domain, secure, httpOnly)}:}{ Sets an HTTP cookie header in the environment \code{header}. All arguments except \code{expires} are length 1 character vectors, while \code{expires} must be a \code{POSIXct} object. }
\item{\code{delete_cookie_header(header, key, value, expires, path, domain, secure, httpOnly)}:}{ Deletes the HTTP cookie header. }
}
}
Rook/man/Rook-package.Rd 0000644 0001751 0000144 00000012021 12332170455 014545 0 ustar hornik users \name{Rook-package}
\alias{Rook-package}
\alias{Rook}
\docType{class}
\title{
Rook: A web server interface and package for R
}
\description{
This help page defines the Rook specification. It borrows heavily
from Ruby's Rack project: \url{http://rack.rubyforge.org/}.
After reading this document, read the \code{\link{Rhttpd}} help file
as it will get you familiar with installing and running \code{Rook}
applications. Then explore the example applications located in:
\code{system.file('exampleApps',package='Rook')}.
}
\section{Rook applications}{
A Rook application is an R reference class object that implements a 'call'
method or an R closure that takes exactly one argument, an environment,
and returns a list with three named elements: \code{'status'}, \code{'headers'},
and \code{'body'}.
}
\section{Hello World}{
Here is a basic Rook application as a closure that implements 'hello world':
\preformatted{
function(env){
body = paste('Hello World! This is Rook',env$rook.version,'.
')
list(
status = 200L,
headers = list(
'Content-Type' = 'text/html'
),
body = body
)
}
}
And the equivalent reference class example:
\preformatted{
setRefClass(
'HelloWorld',
methods = list(
call = function(env){
list(
status = 200L,
headers = list(
'Content-Type' = 'text/html'
),
body = paste('Hello World! This is Rook',env$rook.version,'.
')
)
}
)
)
}
}
\section{The Environment}{
The environment argument is a true R environment object which the
application is free to modify. It is required to contain the following
variables:
\describe{
\item{REQUEST_METHOD}{ The HTTP request method, such as "GET" or "POST". This
cannot ever be an empty string, and so is always required. }
\item{SCRIPT_NAME}{ The initial portion of the request URL's "path" that
corresponds to the application object, so that the application knows
its virtual "location". This may be an empty string, if the application
corresponds to the "root" of the server.}
\item{PATH_INFO}{ The remainder of the request URL's "path", designating the
virtual "location" of the request's target within the application. This
may be an empty string, if the request URL targets the application root
and does not have a trailing slash. This value may be percent-encoded
when I originating from a URL.}
\item{QUERY_STRING}{ The portion of the request URL that follows the ?,
if any. May be empty, but is always required!}
\item{SERVER_NAME, SERVER_PORT}{ When combined with SCRIPT_NAME and PATH_INFO,
these variables can be used to complete the URL. Note however that
HTTP_HOST, if present, should be used in preference to SERVER_NAME for
reconstructing the request URL. SERVER_NAME and SERVER_PORT can never
be empty strings, and so are always required.}
\item{HTTP_ Variables}{ Variables corresponding to the client-supplied
HTTP request headers (i.e., variables whose names begin with HTTP_). The
presence or absence of these variables should correspond with the presence
or absence of the appropriate HTTP header in the request.}
}
In addition, the environment must include the following Rook-specific variables:
\describe{
\item{rook.version}{ This version of Rook.}
\item{rook.url_scheme}{'http' or 'https', depending on the request URL.}
\item{rook.input}{See \dQuote{The Input Stream} section.}
\item{rook.errors}{See \dQuote{The Error Stream} section.}
}
}
\section{The Input Stream}{
The rook.input variable must contain an object created from a reference
class that implements \code{read_lines()}, \code{read()}, and \code{rewind()}:
\describe{
\item{\code{read_lines(l=-1L)}:}{takes one argument, the number of lines to read. Includes partial ending line.}
\item{\code{read(l=-1L)}:}{takes one argument, the number of bytes to read. Returns a raw vector.}
\item{\code{rewind()}:}{Rewinds the input stream back to the beginning.}
}
}
\section{The Error Stream}{
The rook.error variable must contain an object created from a reference
class that implements \code{flush()} and \code{cat()}:
\describe{
\item{\code{flush()}:}{called with no arguments and makes the error stream immediately appear.}
\item{\code{cat(...,sep=" ",fill=FALSE,labels=NULL)}:}{called with the same arguments as R's \code{"\link[base]{cat}"} without the \code{file} and append \code{argument}.}
}
}
\section{The Response}{
Rook applications return a list with three named elements: \code{'status'}, \code{'headers'},
and \code{'body'}.
\subsection{\code{'status'}}{
An HTTP status value as integer and must be greater than or equal to 100.
}
\subsection{\code{'headers'}}{
A named list that contains only character values corresponding to valid HTTP headers.
}
\subsection{\code{'body'}}{
Either a character or raw vector. If the character vector is named
with value \code{'file'} then value of the vector is interpreted as the
location of a file.
}}
\author{ Jeffrey Horner }
\keyword{package}
Rook/man/Brewery-class.Rd 0000644 0001751 0000144 00000002572 12332170455 014776 0 ustar hornik users \name{Brewery-class}
\Rdversion{1.1}
\docType{class}
\alias{Brewery-class}
\alias{Brewery}
\title{Class \code{Brewery}}
\description{
A \code{\link{Middleware}} class for mapping URLs to a directory of files that are subsequently passed to \code{\link[brew]{brew}}. When a file is brewed, the two variables \code{req} (an object of class \code{\link{Request}}) and \code{res} (an object of class \code{\link{Response}}) are available for use.
}
\section{Methods}{
\describe{
\item{\code{new(url,root,...):}}{
\code{url} is a character string or \code{\link{regexp}} on which to match, \code{root} is the name of the directory where brew files reside. Named arguments can be passed in via \code{...} and will be available within the scope of each brewed file.
}
}}
\examples{
#
# This application runs any file found in tempdir() through brew.
#
s <- Rhttpd$new()
\dontrun{
s$start(quiet=TRUE)
}
cat("Random Number: <\%=rnorm(1)\%>
",
file=file.path(tempdir(),"index.html"))
s$add(name="random",
app=Builder$new(
Brewery$new(url="/",root=tempdir()),
Redirect$new("/index.html")
)
)
\dontrun{
s$browse('random') # Opens a browser window to the app.
}
file.remove(file.path(tempdir(),"index.html"))
s$remove(all=TRUE)
rm(s)
}
\seealso{
\code{\link{Rhttpd}}, \code{\link{Builder}}, \code{\link{Redirect}}, and \code{\link[brew]{brew}}.
}
\keyword{classes}
',
',')
',sep=''))
}
res$finish()
},
'^/.*\\.png$' = function(env){
req <- Request$new(env)
res <- Response$new()
res$header('Content-type','image/png')
if (is.null(req$GET()$n)){
n <- 100
} else {
n <- as.integer(req$GET()$n)
}
t <- tempfile()
png(file=t)
png(t,type="cairo",width=200,height=200)
par(mar=rep(0,4))
plot(rnorm(n),col=rainbow(n,alpha=runif(n,0,1)),pch='.',cex=c(2,3,4,5,10,50))
dev.off()
res$body <- t
names(res$body) <- 'file'
res$finish()
},
'.*' = Redirect$new('/index.html')
)
)
Rook/inst/exampleApps/exampleData/ 0000755 0001751 0000144 00000000000 12332170455 016665 5 ustar hornik users Rook/inst/exampleApps/exampleData/index.html 0000644 0001751 0000144 00000001356 12332170455 020667 0 ustar hornik users
)%>){kind=link}