Browse Source

fixed some dox, added generic lua add function to DSL; properly named as_response

master
boB Rudis 7 years ago
parent
commit
fbc8b84c35
  1. 3
      NAMESPACE
  2. 2
      R/as_request.r
  3. 10
      R/docker-splash.r
  4. 37
      R/dsl.r
  5. 4
      R/execute.r
  6. 2
      R/helpers.r
  7. 4
      R/render-har.r
  8. 6
      R/render-html.r
  9. 4
      R/render-json.r
  10. 4
      R/render_file.R
  11. 2
      man/as_har.Rd
  12. 6
      man/as_response.Rd
  13. 6
      man/execute_lua.Rd
  14. 2
      man/get_content_type.Rd
  15. 4
      man/render_file.Rd
  16. 4
      man/render_har.Rd
  17. 6
      man/render_html.Rd
  18. 2
      man/render_jpeg.Rd
  19. 6
      man/render_json.Rd
  20. 2
      man/render_png.Rd
  21. 28
      man/splash_add_lua.Rd
  22. 2
      man/splash_har.Rd
  23. 2
      man/splash_html.Rd
  24. 2
      man/splash_png.Rd
  25. 2
      man/splash_send_keys.Rd
  26. 2
      man/splash_send_text.Rd
  27. 4
      man/start_splash.Rd
  28. 6
      man/stop_splash.Rd

3
NAMESPACE

@ -7,7 +7,7 @@ export(HARviewer)
export(HARviewerOutput)
export(as_har)
export(as_req)
export(as_request)
export(as_response)
export(execute_lua)
export(get_body_size)
export(get_content_size)
@ -41,6 +41,7 @@ export(render_json)
export(render_png)
export(splash)
export(splash_active)
export(splash_add_lua)
export(splash_click)
export(splash_debug)
export(splash_focus)

2
R/as_request.r

@ -18,7 +18,7 @@
#' map(as_request) %>%
#' map(httr::content, as="parsed")
#' }
as_request <- function(har_entry) {
as_response <- function(har_entry) {
if (length(har_entry$response$content$text) > 0) {
content_body <- openssl::base64_decode(har_entry$response$content$text)

10
R/docker-splash.r

@ -21,8 +21,8 @@ install_splash <- function(host = harbor::localhost) {
#' @param host Docker host; defaults to `localhost`
#' @param add_tempdir This is `FALSE` initially since you could try to run
#' the splash image on a remote system. It has to be a local one for this to work.
#' If `TRUE` then a local temporary directory (made with [tempdir]())
#' will be added to the mount configuration for use with [render_file](). You will need to
#' If `TRUE` then a local temporary directory (made with [tempdir()])
#' will be added to the mount configuration for use with [render_file()]. You will need to
#' ensure the necessary system temp dirs are accessible as a mounts. For
#' macOS this means adding `/private` to said Docker config.
#' @note you need Docker running on your system and have pulled the container with
@ -55,10 +55,10 @@ start_splash <- function(host = harbor::localhost, add_tempdir=FALSE) {
#' Stop a running a Splash server Docker container
#'
#' @param splash_container Docker `container` object created by [start_splash]
#' @param splash_container Docker `container` object created by [start_splash()]
#' @note you need Docker running on your system and have pulled the container with
#' [install_splash] and started the Splash container with [start_splash] for this
#' to work. You will need the `container` object from [start_splash] for this to work.
#' [install_splash()] and started the Splash container with [start_splash()] for this
#' to work. You will need the `container` object from [start_splash()] for this to work.
#' @export
#' @examples \dontrun{
#' install_splash()

37
R/dsl.r

@ -10,6 +10,33 @@ end
}
#' Add raw lua code into DSL call chain
#'
#' The `splashr` `lua` DSL (domain specific language) wrapper wraps what the package
#' author believes to be the most common/useful `lua` functions. Users of the package
#' may have need to insert some custom `lua` code within a DSL call chain they are
#' building. You can insert any Splash `lua` code you like with this function call.
#'
#' The code is inserted at the position the `splash_add_lua`() is called in the chain
#' which will be within the main "splash' function which is defined as:
#'
#' ```
#' function main(splash)
#' ...
#' end
#' ```
#'
#' If you need more flexibility, use the [execute_lua()] function.
#'
#' @md
#' @param splash_obj splashr object
#' @param lua_code length 1 character vector of raw `lua` code
#' @export
splash_add_lua <- function(splash_obj, lua_code) {
splash_obj$calls <- c(splash_obj$calls, lua_code, "\n")
splash_obj
}
#' Enable or disable response content tracking.
#'
#' By default Splash doesn’t keep bodies of each response in memory, for efficiency reasons.
@ -125,7 +152,7 @@ splash_focus <- function(splash_obj, selector) {
#' Send text as input to page context, literally, character by character.
#'
#' This is different from [splash_send_keys]
#' This is different from [splash_send_keys()]
#'
#' @md
#' @note This adds a call to `splash:wait` so you do not have to
@ -145,7 +172,7 @@ splash_send_text <- function(splash_obj, text) {
#' - whitespace is ignored and only used to separate the different keys
#' - characters are literally represented
#'
#' This is different from [splash_send_text]
#' This is different from [splash_send_text()]
#'
#' @md
#' @param splash_obj splashr object
@ -204,7 +231,7 @@ splash_wait <- function(splash_obj, time=2) {
#' Return information about Splash interaction with a website in HAR format.
#'
#' Similar to [render_har] but used in a script context. Should be the LAST element in
#' Similar to [render_har()] but used in a script context. Should be the LAST element in
#' a DSL script chain as this will execute the script and return the HAR content
#'
#' @md
@ -231,7 +258,7 @@ splash_har <- function(splash_obj) {
#' Return a HTML snapshot of a current page.
#'
#' Similar to [render_html] but used in a script context. Should be the LAST element in
#' Similar to [render_html()] but used in a script context. Should be the LAST element in
#' a DSL script chain as this will execute the script and return the HTML content
#'
#' @md
@ -262,7 +289,7 @@ splash_html <- function(splash_obj, raw_html=FALSE) {
#' Return a screenshot of a current page in PNG format.
#'
#' Similar to [render_png] but used in a script context. Should be the LAST element in
#' Similar to [render_png()] but used in a script context. Should be the LAST element in
#' a DSL script chain as this will execute the script and return the PNG content
#'
#' @md

4
R/execute.r

@ -1,8 +1,8 @@
#' Execute a custom rendering script and return a result.
#'
#' @md
#' @param splash_obj Object created by a call to [splash]
#' @param lua_source Browser automation script. See [Splash Script](http://splash.readthedocs.io/en/stable/scripting-tutorial.html#scripting-tutorial) Tutorial for more info.
#' @param splash_obj Object created by a call to [splash()]
#' @param lua_sourc Browser automation script. See [Splash Script](http://splash.readthedocs.io/en/stable/scripting-tutorial.html#scripting-tutorial) Tutorial for more info.
#' @param timeout A timeout (in seconds) for the render (defaults to 30).
#' @param allowed_domains Comma-separated list of allowed domain names. If present, Splash won’t load anything neither from domains not in this list nor from subdomains of domains not in this list.
#' @param proxy Proxy profile name or proxy URL.

2
R/helpers.r

@ -29,7 +29,7 @@ is_content_type <- function(har_resp_obj, type="application/json") {
}
#' @rdname get_content_type
#' @param har_resp_obj a reponse object from [render_har]() or [execute_lua]()
#' @param har_resp_obj a reponse object from [render_har()] or [execute_lua()]
#' @export
is_json <- function(har_resp_obj) { is_content_type(har_resp_obj) }

4
R/render-har.r

@ -6,7 +6,7 @@
#' @md
#' @param response_body When `TRUE`, response content is included in the HAR records
#' @inheritParams render_html
#' @return a `HARtools` `har` object
#' @return a [HARtools] `har` object
#' @references [Splash docs](http://splash.readthedocs.io/en/stable/index.html)
#' @export
render_har <- function(splash_obj = splash_local, url, base_url, response_body=FALSE, timeout=30, resource_timeout, wait=0,
@ -47,7 +47,7 @@ render_har <- function(splash_obj = splash_local, url, base_url, response_body=F
#' Turn a generic Splash HAR response into a HAR object
#'
#' @param splash_resp splash response object as returned by `splash::har()` lua script
#' @param splash_resp splash response object
#' @export
as_har <- function(splash_resp) {

6
R/render-html.r

@ -3,7 +3,7 @@
#' Similar to `rvest::read_html`.
#'
#' @md
#' @param splash_obj Object created by a call to [splash]
#' @param splash_obj Object created by a call to [splash()]
#' @param url The URL to render (required)
#' @param base_url The base url to render the page with.
#' @param timeout A timeout (in seconds) for the render (defaults to 30).
@ -24,9 +24,9 @@
#' @param save_args A list of argument names to put in cache.
#' @param load_args Parameter values to load from cache
#' @param raw_html if `TRUE` then return a character vector vs an XML document. Only valid for `render_html`
#' @return An XML document. Note that this is processed by [xml2::read_html] so it will not be
#' @return An XML document. Note that this is processed by [xml2::read_html()] so it will not be
#' the pristine, raw, rendered HTML from the site. Use `raw_html=TRUE` if you do not want it
#' to be processed first by `xml2`. If you choose `raw_html=TRUE` you'll get back a
#' to be processed first by [xml2]. If you choose `raw_html=TRUE` you'll get back a
#' character vector.
#' @references [Splash docs](http://splash.readthedocs.io/en/stable/index.html)
#' @export

4
R/render-json.r

@ -17,14 +17,14 @@
#' like images and AJAX queries is not returned). To get information about all
#' requests and responses use `har` parameter.
#' @param har Whether to include HAR in output. If `TRUE` the result will contain the same
#' data as [render_har] provides under `har` list entry. By default, response
#' data as [render_har()] provides under `har` list entry. By default, response
#' content is not included. To enable it use `response_body` parameter.
#' @param response_body Used with `har` parameter.
#' @return a huge `list`
#' @inheritParams render_jpeg
#' @note All "whether to include..." parameters are default `TRUE` except for `png` and
#' `jpeg` and a custom `print` method is defined to stop your console from being
#' overwhelmed with data. Use [str] to inspect various portions of the result.
#' overwhelmed with data. Use [str()] to inspect various portions of the result.
#' @references [Splash docs](http://splash.readthedocs.io/en/stable/index.html)
#' @export
render_json <- function(splash_obj = splash_local, url, base_url=NULL, quality=75, width=1024, height=768,

4
R/render_file.R

@ -6,12 +6,12 @@
#' TODO Enable passing in of an htmlwidget and use saveWidget
#'
#' @md
#' @param splash_obj Object created by a call to [splash]()
#' @param splash_obj Object created by a call to [splash()]
#' @param file_path Absolute path to a filename on the local host. **This only works with a locally running Splash instance started with [start_splash]().**
#' @param wait seconds to wait
#' @param output either `html` or `png` to get the page content or an image capture
#' @param viewport View width and height (in pixels) of the browser viewport to render the web page. Format is "`<width>x<height>`". e.g. 800x600. Default value is 1024x768.
#' @param ... other params to [render_html]() or [render_png]()
#' @param ... other params to [render_html()] or [render_png()]
#' @return An XML document or `magick` object
#' @export
render_file <- function(splash_obj = splash_local, file_path, output=c("html", "png"), wait=0, viewport="1024x768", ...) {

2
man/as_har.Rd

@ -7,7 +7,7 @@
as_har(splash_resp)
}
\arguments{
\item{splash_resp}{splash response object as returned by `splash::har()` lua script}
\item{splash_resp}{splash response object}
}
\description{
Turn a generic Splash HAR response into a HAR object

6
man/as_request.Rd → man/as_response.Rd

@ -1,10 +1,10 @@
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/as_request.r
\name{as_request}
\alias{as_request}
\name{as_response}
\alias{as_response}
\title{Return a HAR entry response as an httr::response object}
\usage{
as_request(har_entry)
as_response(har_entry)
}
\arguments{
\item{har_entry}{a HAR object (should contain a response body to be most useful)}

6
man/execute_lua.Rd

@ -8,9 +8,7 @@ execute_lua(splash_obj, lua_source, timeout = 30, allowed_domains, proxy,
filters, save_args, load_args)
}
\arguments{
\item{splash_obj}{Object created by a call to \link{splash}}
\item{lua_source}{Browser automation script. See \href{http://splash.readthedocs.io/en/stable/scripting-tutorial.html#scripting-tutorial}{Splash Script} Tutorial for more info.}
\item{splash_obj}{Object created by a call to \code{\link[=splash]{splash()}}}
\item{timeout}{A timeout (in seconds) for the render (defaults to 30).}
@ -23,6 +21,8 @@ execute_lua(splash_obj, lua_source, timeout = 30, allowed_domains, proxy,
\item{save_args}{A list of argument names to put in cache.}
\item{load_args}{Parameter values to load from cache}
\item{lua_sourc}{Browser automation script. See \href{http://splash.readthedocs.io/en/stable/scripting-tutorial.html#scripting-tutorial}{Splash Script} Tutorial for more info.}
}
\value{
\code{raw} content from the \code{httr} call. Given the vast diversity of possible return values, it's up to the caller to handle the return value.

2
man/get_content_type.Rd

@ -46,7 +46,7 @@ is_gif(har_resp_obj)
is_xhr(har_resp_obj)
}
\arguments{
\item{har_resp_obj}{a reponse object from [render_har]() or [execute_lua]()}
\item{har_resp_obj}{a reponse object from [render_har()] or [execute_lua()]}
\item{type}{content type to compare to (default: "\code{application/json}")}
}

4
man/render_file.Rd

@ -8,7 +8,7 @@ render_file(splash_obj = splash_local, file_path, output = c("html", "png"),
wait = 0, viewport = "1024x768", ...)
}
\arguments{
\item{splash_obj}{Object created by a call to \url{splash}}
\item{splash_obj}{Object created by a call to \code{\link[=splash]{splash()}}}
\item{file_path}{Absolute path to a filename on the local host. \strong{This only works with a locally running Splash instance started with \url{start_splash}.}}
@ -18,7 +18,7 @@ render_file(splash_obj = splash_local, file_path, output = c("html", "png"),
\item{viewport}{View width and height (in pixels) of the browser viewport to render the web page. Format is "\code{<width>x<height>}". e.g. 800x600. Default value is 1024x768.}
\item{...}{other params to \url{render_html} or \url{render_png}}
\item{...}{other params to \code{\link[=render_html]{render_html()}} or \code{\link[=render_png]{render_png()}}}
}
\value{
An XML document or \code{magick} object

4
man/render_har.Rd

@ -11,7 +11,7 @@ render_har(splash_obj = splash_local, url, base_url, response_body = FALSE,
load_args)
}
\arguments{
\item{splash_obj}{Object created by a call to \link{splash}}
\item{splash_obj}{Object created by a call to \code{\link[=splash]{splash()}}}
\item{url}{The URL to render (required)}
@ -54,7 +54,7 @@ render_har(splash_obj = splash_local, url, base_url, response_body = FALSE,
\item{load_args}{Parameter values to load from cache}
}
\value{
a \code{HARtools} \code{har} object
a \link{HARtools} \code{har} object
}
\description{
It includes information about requests made, responses received, timings, headers, etc and

6
man/render_html.Rd

@ -10,7 +10,7 @@ render_html(splash_obj = splash_local, url, base_url, timeout = 30,
images, headers, body, http_method, save_args, load_args, raw_html = FALSE)
}
\arguments{
\item{splash_obj}{Object created by a call to \link{splash}}
\item{splash_obj}{Object created by a call to \code{\link[=splash]{splash()}}}
\item{url}{The URL to render (required)}
@ -53,9 +53,9 @@ render_html(splash_obj = splash_local, url, base_url, timeout = 30,
\item{raw_html}{if \code{TRUE} then return a character vector vs an XML document. Only valid for \code{render_html}}
}
\value{
An XML document. Note that this is processed by \link[xml2:read_html]{xml2::read_html} so it will not be
An XML document. Note that this is processed by \code{\link[xml2:read_html]{xml2::read_html()}} so it will not be
the pristine, raw, rendered HTML from the site. Use \code{raw_html=TRUE} if you do not want it
to be processed first by \code{xml2}. If you choose \code{raw_html=TRUE} you'll get back a
to be processed first by \link{xml2}. If you choose \code{raw_html=TRUE} you'll get back a
character vector.
}
\description{

2
man/render_jpeg.Rd

@ -11,7 +11,7 @@ render_jpeg(splash_obj = splash_local, url, base_url = NULL, quality = 75,
images, headers, body, http_method, save_args, load_args)
}
\arguments{
\item{splash_obj}{Object created by a call to \link{splash}}
\item{splash_obj}{Object created by a call to \code{\link[=splash]{splash()}}}
\item{url}{The URL to render (required)}

6
man/render_json.Rd

@ -13,7 +13,7 @@ render_json(splash_obj = splash_local, url, base_url = NULL, quality = 75,
console = TRUE, history = TRUE, har = TRUE, response_body = FALSE)
}
\arguments{
\item{splash_obj}{Object created by a call to \link{splash}}
\item{splash_obj}{Object created by a call to \code{\link[=splash]{splash()}}}
\item{url}{The URL to render (required)}
@ -81,7 +81,7 @@ like images and AJAX queries is not returned). To get information about all
requests and responses use \code{har} parameter.}
\item{har}{Whether to include HAR in output. If \code{TRUE} the result will contain the same
data as \link{render_har} provides under \code{har} list entry. By default, response
data as \code{\link[=render_har]{render_har()}} provides under \code{har} list entry. By default, response
content is not included. To enable it use \code{response_body} parameter.}
\item{response_body}{Used with \code{har} parameter.}
@ -95,7 +95,7 @@ It can include HTML, PNG and other information, based on arguments passed.
\note{
All "whether to include..." parameters are default \code{TRUE} except for \code{png} and
\code{jpeg} and a custom \code{print} method is defined to stop your console from being
overwhelmed with data. Use \link{str} to inspect various portions of the result.
overwhelmed with data. Use \code{\link[=str]{str()}} to inspect various portions of the result.
}
\references{
\href{http://splash.readthedocs.io/en/stable/index.html}{Splash docs}

2
man/render_png.Rd

@ -11,7 +11,7 @@ render_png(splash_obj = splash_local, url, base_url = NULL, width = 1024,
images, headers, body, http_method, save_args, load_args)
}
\arguments{
\item{splash_obj}{Object created by a call to \link{splash}}
\item{splash_obj}{Object created by a call to \code{\link[=splash]{splash()}}}
\item{url}{The URL to render (required)}

28
man/splash_add_lua.Rd

@ -0,0 +1,28 @@
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/dsl.r
\name{splash_add_lua}
\alias{splash_add_lua}
\title{Add raw lua code into DSL call chain}
\usage{
splash_add_lua(splash_obj, lua_code)
}
\arguments{
\item{splash_obj}{splashr object}
\item{lua_code}{length 1 character vector of raw \code{lua} code}
}
\description{
The \code{splashr} \code{lua} DSL (domain specific language) wrapper wraps what the package
author believes to be the most common/useful \code{lua} functions. Users of the package
may have need to insert some custom \code{lua} code within a DSL call chain they are
building. You can insert any Splash \code{lua} code you like with this function call.
}
\details{
The code is inserted at the position the \code{splash_add_lua}() is called in the chain
which will be within the main "splash' function which is defined as:\preformatted{function main(splash)
...
end
}
If you need more flexibility, use the \code{\link[=execute_lua]{execute_lua()}} function.
}

2
man/splash_har.Rd

@ -10,7 +10,7 @@ splash_har(splash_obj)
\item{splash_obj}{splashr object}
}
\description{
Similar to \link{render_har} but used in a script context. Should be the LAST element in
Similar to \code{\link[=render_har]{render_har()}} but used in a script context. Should be the LAST element in
a DSL script chain as this will execute the script and return the HAR content
}
\examples{

2
man/splash_html.Rd

@ -12,7 +12,7 @@ splash_html(splash_obj, raw_html = FALSE)
\item{raw_html}{if \code{TRUE} then return a character vector vs an XML document.}
}
\description{
Similar to \link{render_html} but used in a script context. Should be the LAST element in
Similar to \code{\link[=render_html]{render_html()}} but used in a script context. Should be the LAST element in
a DSL script chain as this will execute the script and return the HTML content
}
\examples{

2
man/splash_png.Rd

@ -13,7 +13,7 @@ splash_png(splash_obj)
a \link{magick} image object
}
\description{
Similar to \link{render_png} but used in a script context. Should be the LAST element in
Similar to \code{\link[=render_png]{render_png()}} but used in a script context. Should be the LAST element in
a DSL script chain as this will execute the script and return the PNG content
}
\examples{

2
man/splash_send_keys.Rd

@ -18,7 +18,7 @@ splash_send_keys(splash_obj, keys)
}
}
\details{
This is different from \link{splash_send_text}
This is different from \code{\link[=splash_send_text]{splash_send_text()}}
}
\references{
See \href{https://splash.readthedocs.io/en/stable/scripting-ref.html#splash-send-keys}{the docs} for more info

2
man/splash_send_text.Rd

@ -12,7 +12,7 @@ splash_send_text(splash_obj, text)
\item{text}{string to send}
}
\description{
This is different from \link{splash_send_keys}
This is different from \code{\link[=splash_send_keys]{splash_send_keys()}}
}
\note{
This adds a call to \code{splash:wait} so you do not have to

4
man/start_splash.Rd

@ -11,8 +11,8 @@ start_splash(host = harbor::localhost, add_tempdir = FALSE)
\item{add_tempdir}{This is `FALSE` initially since you could try to run
the splash image on a remote system. It has to be a local one for this to work.
If `TRUE` then a local temporary directory (made with [tempdir]())
will be added to the mount configuration for use with [render_file](). You will need to
If `TRUE` then a local temporary directory (made with [tempdir()])
will be added to the mount configuration for use with [render_file()]. You will need to
ensure the necessary system temp dirs are accessible as a mounts. For
macOS this means adding `/private` to said Docker config.}
}

6
man/stop_splash.Rd

@ -7,15 +7,15 @@
stop_splash(splash_container)
}
\arguments{
\item{splash_container}{Docker `container` object created by [start_splash]}
\item{splash_container}{Docker `container` object created by [start_splash()]}
}
\description{
Stop a running a Splash server Docker container
}
\note{
you need Docker running on your system and have pulled the container with
[install_splash] and started the Splash container with [start_splash] for this
to work. You will need the `container` object from [start_splash] for this to work.
[install_splash()] and started the Splash container with [start_splash()] for this
to work. You will need the `container` object from [start_splash()] for this to work.
}
\examples{
\dontrun{

Loading…
Cancel
Save