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

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)

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)

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]())
+#'   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
+#'   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
+#'       [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.
+#'       to work. You will need the `container` object from [start_splash()] for this to work.
 #' @export
 #' @examples \dontrun{
 #' install_splash()

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

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 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 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.

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) }
 

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) {
 

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

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,

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", ...) {

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

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}
+\name{as_response}
-\alias{as_request}
+\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)}

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{splash_obj}{Object created by a call to \code{\link[=splash]{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{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.

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}")}
 }

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

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

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{

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)}
 

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}

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)}
 

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.
+}

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{

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{

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{

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

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

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]())
+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
+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.}
 }

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
+      [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.
+      to work. You will need the `container` object from [start_splash()] for this to work.
 }
 \examples{
 \dontrun{