Merge pull request #37 from rstudio/feature/uri-encoding

Add URI encode/decode functions

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: httpuv
 Type: Package
 Title: HTTP and WebSocket server library
-Version: 1.3.1
+Version: 1.3.1.9000
 Date: 2014-07-11
 Author: RStudio, Inc.
 Copyright: RStudio, Inc.; Joyent, Inc.; Nginx Inc.; Igor Sysoev; Niels Provos;

NAMESPACE

@@ -1,3 +1,9 @@
+# Generated by roxygen2 (4.0.2): do not edit by hand
+
+export(decodeURI)
+export(decodeURIComponent)
+export(encodeURI)
+export(encodeURIComponent)
 export(interrupt)
 export(rawToBase64)
 export(runServer)
@@ -7,7 +13,7 @@ export(startPipeServer)
 export(startServer)
 export(stopDaemonizedServer)
 export(stopServer)
+exportClasses(WebSocket)
 import(methods)
 importFrom(Rcpp,evalCpp)
-export(WebSocket)
 useDynLib(httpuv)

NEWS

@@ -1,3 +1,10 @@
+httpuv 1.3.1.9000
+------------------------------------------------------------------------
+
+* Add encodeURI, encodeURIComponent, decodeURI, and decodeURIComponent
+  functions.
+
+
 httpuv 1.3.1
 ------------------------------------------------------------------------
 

R/RcppExports.R

@@ -41,3 +41,55 @@ destroyDaemonizedServer <- function(handle) {
     invisible(.Call('httpuv_destroyDaemonizedServer', PACKAGE = 'httpuv', handle))
 }
 
+#' URI encoding/decoding
+#' 
+#' Encodes/decodes strings using URI encoding/decoding in the same way that web
+#' browsers do. The precise behaviors of these functions can be found at
+#' developer.mozilla.org:
+#' \href{https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURI}{encodeURI},
+#' \href{https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent}{encodeURIComponent},
+#' \href{https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURI}{decodeURI},
+#' \href{https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURIComponent}{decodeURIComponent}
+#' 
+#' Intended as a faster replacement for \code{\link[utils]{URLencode}} and
+#' \code{\link[utils]{URLdecode}}.
+#' 
+#' encodeURI differs from encodeURIComponent in that the former will not encode
+#' reserved characters: \code{;,/?:@@&=+$}
+#' 
+#' decodeURI differs from decodeURIComponent in that it will refuse to decode
+#' encoded sequences that decode to a reserved character. (If in doubt, use
+#' decodeURIComponent.)
+#' 
+#' The only way these functions differ from web browsers is in the encoding of
+#' non-ASCII characters. All non-ASCII characters will be escaped byte-by-byte.
+#' If conformant non-ASCII behavior is important, ensure that your input vector
+#' is UTF-8 encoded before calling encodeURI or encodeURIComponent.
+#' 
+#' @param value Character vector to be encoded or decoded.
+#' @return Encoded or decoded character vector of the same length as the
+#'   input value.
+#'
+#' @export
+encodeURI <- function(value) {
+    .Call('httpuv_encodeURI', PACKAGE = 'httpuv', value)
+}
+
+#' @rdname encodeURI
+#' @export
+encodeURIComponent <- function(value) {
+    .Call('httpuv_encodeURIComponent', PACKAGE = 'httpuv', value)
+}
+
+#' @rdname encodeURI
+#' @export
+decodeURI <- function(value) {
+    .Call('httpuv_decodeURI', PACKAGE = 'httpuv', value)
+}
+
+#' @rdname encodeURI
+#' @export
+decodeURIComponent <- function(value) {
+    .Call('httpuv_decodeURIComponent', PACKAGE = 'httpuv', value)
+}
+

man/WebSocket-class.Rd

@@ -0,0 +1,55 @@
+% Generated by roxygen2 (4.0.2): do not edit by hand
+\docType{class}
+\name{WebSocket-class}
+\alias{WebSocket}
+\alias{WebSocket-class}
+\title{WebSocket object}
+\arguments{
+\item{...}{For internal use only.}
+}
+\description{
+An object that represents a single WebSocket connection. The object can be
+used to send messages and close the connection, and to receive notifications
+when messages are received or the connection is closed.
+}
+\details{
+WebSocket objects should never be created directly. They are obtained by
+passing an \code{onWSOpen} function to \code{\link{startServer}}.
+}
+\section{Fields}{
+
+
+  \describe{
+    \item{\code{request}}{
+      The Rook request environment that opened the connection. This can be
+      used to inspect HTTP headers, for example.
+    }
+  }
+}
+
+\section{Methods}{
+
+
+  \describe{
+    \item{\code{onMessage(func)}}{
+      Registers a callback function that will be invoked whenever a message
+      is received on this connection. The callback function will be invoked
+      with two arguments. The first argument is \code{TRUE} if the message
+      is binary and \code{FALSE} if it is text. The second argument is either
+      a raw vector (if the message is binary) or a character vector.
+    }
+    \item{\code{onClose(func)}}{
+      Registers a callback function that will be invoked when the connection
+      is closed.
+    }
+    \item{\code{send(message)}}{
+      Begins sending the given message over the websocket. The message must
+      be either a raw vector, or a single-element character vector that is
+      encoded in UTF-8.
+    }
+    \item{\code{close()}}{
+      Closes the websocket connection.
+    }
+  }
+}
+

man/encodeURI.Rd

@@ -0,0 +1,49 @@
+% Generated by roxygen2 (4.0.2): do not edit by hand
+\name{encodeURI}
+\alias{decodeURI}
+\alias{decodeURIComponent}
+\alias{encodeURI}
+\alias{encodeURIComponent}
+\title{URI encoding/decoding}
+\usage{
+encodeURI(value)
+
+encodeURIComponent(value)
+
+decodeURI(value)
+
+decodeURIComponent(value)
+}
+\arguments{
+\item{value}{Character vector to be encoded or decoded.}
+}
+\value{
+Encoded or decoded character vector of the same length as the
+  input value.
+}
+\description{
+Encodes/decodes strings using URI encoding/decoding in the same way that web
+browsers do. The precise behaviors of these functions can be found at
+developer.mozilla.org:
+\href{https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURI}{encodeURI},
+\href{https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent}{encodeURIComponent},
+\href{https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURI}{decodeURI},
+\href{https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURIComponent}{decodeURIComponent}
+}
+\details{
+Intended as a faster replacement for \code{\link[utils]{URLencode}} and
+\code{\link[utils]{URLdecode}}.
+
+encodeURI differs from encodeURIComponent in that the former will not encode
+reserved characters: \code{;,/?:@&=+$}
+
+decodeURI differs from decodeURIComponent in that it will refuse to decode
+encoded sequences that decode to a reserved character. (If in doubt, use
+decodeURIComponent.)
+
+The only way these functions differ from web browsers is in the encoding of
+non-ASCII characters. All non-ASCII characters will be escaped byte-by-byte.
+If conformant non-ASCII behavior is important, ensure that your input vector
+is UTF-8 encoded before calling encodeURI or encodeURIComponent.
+}
+

man/httpuv-package.Rd

@@ -1,34 +1,32 @@
+% Generated by roxygen2 (4.0.2): do not edit by hand
 \docType{package}
 \name{httpuv-package}
 \alias{httpuv}
 \alias{httpuv-package}
 \title{HTTP and WebSocket server}
 \description{
-  HTTP and WebSocket server
+HTTP and WebSocket server
 }
 \details{
-  Allows R code to listen for and interact with HTTP and
-  WebSocket clients, so you can serve web traffic directly
-  out of your R process. Implementation is based on
-  \href{https://github.com/joyent/libuv}{libuv} and
-  \href{https://github.com/joyent/http-parser}{http-parser}.
+Allows R code to listen for and interact with HTTP and WebSocket clients, so
+you can serve web traffic directly out of your R process. Implementation is
+based on \href{https://github.com/joyent/libuv}{libuv} and
+\href{https://github.com/joyent/http-parser}{http-parser}.
 
-  This is a low-level library that provides little more
-  than network I/O and implementations of the HTTP and
-  WebSocket protocols. For an easy way to create web
-  applications, try \href{http://rstudio.com/shiny/}{Shiny}
-  instead.
+This is a low-level library that provides little more than network I/O and
+implementations of the HTTP and WebSocket protocols. For an easy way to
+create web applications, try \href{http://rstudio.com/shiny/}{Shiny} instead.
 }
 \examples{
 \dontrun{
 demo("echo", package="httpuv")
 }
 }
 \author{
-  Joe Cheng \email{joe@rstudio.com}
+Joe Cheng \email{joe@rstudio.com}
 }
 \seealso{
-  startServer
+startServer
 }
 \keyword{package}
 

man/interrupt.Rd

@@ -1,15 +1,15 @@
+% Generated by roxygen2 (4.0.2): do not edit by hand
 \name{interrupt}
 \alias{interrupt}
 \title{Interrupt httpuv runloop}
 \usage{
-  interrupt()
+interrupt()
 }
 \description{
-  Interrupts the currently running httpuv runloop, meaning
-  \code{\link{runServer}} or \code{\link{service}} will
-  return control back to the caller and no further tasks
-  will be processed until those methods are called again.
-  Note that this may cause in-process uploads or downloads
-  to be interrupted in mid-request.
+Interrupts the currently running httpuv runloop, meaning
+\code{\link{runServer}} or \code{\link{service}} will return control back to
+the caller and no further tasks will be processed until those methods are
+called again. Note that this may cause in-process uploads or downloads to be
+interrupted in mid-request.
 }
 

man/rawToBase64.Rd

@@ -1,15 +1,16 @@
+% Generated by roxygen2 (4.0.2): do not edit by hand
 \name{rawToBase64}
 \alias{rawToBase64}
 \title{Convert raw vector to Base64-encoded string}
 \usage{
-  rawToBase64(x)
+rawToBase64(x)
 }
 \arguments{
-  \item{x}{A raw vector.}
+\item{x}{A raw vector.}
 }
 \description{
-  Converts a raw vector to its Base64 encoding as a
-  single-element character vector.
+Converts a raw vector to its Base64 encoding as a single-element character
+vector.
 }
 \examples{
 set.seed(100)

man/runServer.Rd

@@ -1,40 +1,37 @@
+% Generated by roxygen2 (4.0.2): do not edit by hand
 \name{runServer}
 \alias{runServer}
 \title{Run a server}
 \usage{
-  runServer(host, port, app,
-    interruptIntervalMs = ifelse(interactive(), 100, 1000))
+runServer(host, port, app, interruptIntervalMs = ifelse(interactive(), 100,
+  1000))
 }
 \arguments{
-  \item{host}{A string that is a valid IPv4 address that is
-  owned by this server, or \code{"0.0.0.0"} to listen on
-  all IP addresses.}
+\item{host}{A string that is a valid IPv4 address that is owned by this
+server, or \code{"0.0.0.0"} to listen on all IP addresses.}
 
-  \item{port}{A number or integer that indicates the server
-  port that should be listened on. Note that on most
-  Unix-like systems including Linux and Mac OS X, port
-  numbers smaller than 1025 require root privileges.}
+\item{port}{A number or integer that indicates the server port that should be
+listened on. Note that on most Unix-like systems including Linux and Mac OS
+X, port numbers smaller than 1025 require root privileges.}
 
-  \item{app}{A collection of functions that define your
-  application. See Details.}
+\item{app}{A collection of functions that define your application. See
+Details.}
 
-  \item{interruptIntervalMs}{How often to check for
-  interrupt. The default should be appropriate for most
-  situations.}
+\item{interruptIntervalMs}{How often to check for interrupt. The default
+  should be appropriate for most situations.}
 }
 \description{
-  This is a convenience function that provides a simple way
-  to call \code{\link{startServer}}, \code{\link{service}},
-  and \code{\link{stopServer}} in the correct sequence. It
-  does not return unless interrupted or an error occurs.
+This is a convenience function that provides a simple way to call
+\code{\link{startServer}}, \code{\link{service}}, and
+\code{\link{stopServer}} in the correct sequence. It does not return unless
+interrupted or an error occurs.
 }
 \details{
-  If you have multiple hosts and/or ports to listen on,
-  call the individual functions instead of
-  \code{runServer}.
+If you have multiple hosts and/or ports to listen on, call the individual
+functions instead of \code{runServer}.
 }
 \seealso{
-  \code{\link{startServer}}, \code{\link{service}},
+\code{\link{startServer}}, \code{\link{service}},
   \code{\link{stopServer}}
 }