Update documentation

.Rbuildignore

@@ -1,3 +1,5 @@
 ^.*\.Rproj$
 ^\.Rproj\.user$
 ^LICENSE\.md$
+^data-raw$
+^docs$

DESCRIPTION

@@ -5,13 +5,15 @@ Date: 2018-03-14
 Authors@R: c(
     person("Garrick", "Aden-Buie", email = "g.adenbuie@gmail.com", role = c("aut", "cre")),
     person("Winston", "Chang", role = c("ctb"), comment = "Author of textInput and textAreaInput fragments from shiny"),
+    person("Yihui", "Xie", role = c("ctb"), comment = "Author of escape_html fragment from highr"),
     person(family = "RStudio", role = "cph", comment = "Copyright holder of included shiny fragments")
     )
 Description: A set of RStudio Addins to help interactively test and build 
     regular expressions. Provides a Shiny gadget interface for interactively
-    constructing the regexp and viewing the results from common string-searching
-    functions. Also provides a helpful reference sheet as an RStudio addin.
-Depends: R (>= 3.4)
+    constructing the regular expression and viewing the results from common 
+    string-searching functions. The gadget interface includes a helpful 
+    regex syntax reference sheet and a library of common patterns.
+Depends: R (>= 3.2)
 License: GPL-3
 Encoding: UTF-8
 LazyData: true
@@ -26,7 +28,7 @@ Imports:
     utils,
     tidyr,
     rstudioapi,
-    shiny,
+    shiny (>= 0.13),
     miniUI,
     jsonlite,
     rematch2

NAMESPACE

@@ -2,7 +2,6 @@
 
 export(regex_gadget)
 export(regexplain_cheatsheet)
-export(run_regex)
 export(view_regex)
 import(miniUI)
 import(shiny)
@@ -14,5 +13,6 @@ importFrom(dplyr,select)
 importFrom(dplyr,summarize)
 importFrom(rlang,.data)
 importFrom(utils,getFromNamespace)
+importFrom(utils,globalVariables)
 importFrom(utils,installed.packages)
 importFrom(utils,packageVersion)

R/regex_gadget.R

@@ -1,13 +1,19 @@
 #' RegExplain gadget
 #'
+#' The function behind the RegExplain Selection and RegExplain File
+#' addins. Opens the RegExplain gadget interface in an RStudio viewer
+#' pane.
+#'
 #' @import miniUI
 #' @import shiny
 #' @param text Text to explore in gadget (editable using interface)
 #' @param start_page Open gadget to this tab, one of `"Text"`, `"RegEx"`,
 #'   `"Output"`, or `"Help"`
 #' @export
-regex_gadget <- function(text = NULL,
-                         start_page = if (is.null(text)) "Text" else "RegEx") {
+regex_gadget <- function(
+  text = NULL,
+  start_page = if (is.null(text)) "Text" else "RegEx"
+) {
   stopifnot(requireNamespace("miniUI"), requireNamespace("shiny"))
 
   update_available <- check_version()
@@ -164,13 +170,13 @@ regex_gadget <- function(text = NULL,
 
     observe({
       if (getOption('regexplain.debug.gadget.text', FALSE)) {
-        cat("\npattern: ", rtext())
+        cat("\ntext   :", rtext())
       }
       if (getOption('regexplain.debug.gadget.pattern', FALSE)) {
-        cat("\npattern: ", pattern())
+        cat("\npattern:", pattern())
       }
       if (getOption('regexplain.debug.gadget.replacement', FALSE)) {
-        cat("\npattern: ", replacement())
+        cat("\nreplace:", replacement())
       }
       cat("\n")
     })
@@ -374,6 +380,9 @@ regex_gadget <- function(text = NULL,
       "<p>An extra backslash is still needed to match a literal <code>\\</code> in standard regular expressions. This means that you will need to enter <code>\\\\</code> in the <strong>RegEx</strong> tab, and the output to R will be <code>&quot;\\\\\\\\&quot;</code>.</p>"
       )
 
+    # avoid CRAN check NOTES
+    help_text <- NULL          # in help_server.R
+    make_help_tab_text <- NULL # in help_server.R
     source(system.file("shiny", "help_server.R", package = "regexplain"), local = TRUE)
 
     observeEvent(input$help_resources, {

R/regex_help.R

@@ -1,5 +1,9 @@
 #' Regex Cheatsheet Quick Reference
 #'
+#' The function behind the RegExplain Cheatsheet addin. Opens a summary of
+#' regular expression syntax -- the RegExplain cheatsheet -- in an RStudio
+#' viewer pane.
+#'
 #' @import miniUI
 #' @import shiny
 #' @export

R/regexplain-package.R

@@ -1,5 +1,5 @@
 #' @importFrom dplyr "%>%" mutate filter group_by summarize select
-#' @importFrom utils getFromNamespace installed.packages packageVersion
+#' @importFrom utils getFromNamespace installed.packages packageVersion globalVariables
 #' @importFrom rlang .data
 #' @keywords internal
 "_PACKAGE"

R/run_regex.R

@@ -2,16 +2,14 @@
 #'
 #' @param text Text to search
 #' @param pattern regexp
-#' @inheritParams base::regexec
-#' @export
+#' @inheritDotParams base::regexec ignore.case perl fixed useBytes
 run_regex <- function(
   text,
   pattern,
   ignore.case = FALSE,
   perl = FALSE,
   fixed = FALSE,
-  useBytes = FALSE,
-  invert = FALSE
+  useBytes = FALSE
 ) {
   # Use regex to get matches by group, gives start index and length
   m <- regexec(pattern, text, ignore.case, perl, fixed, useBytes)
@@ -155,6 +153,14 @@ wrap_regex <- function(pattern, escape = TRUE, exact = TRUE) {
 
 #' View grouped regex results
 #'
+#' View the result of the regular expression when applied to the given text.
+#' The default behavior renders the result as HTML and opens the file in
+#' the RStudio viewer pane. If `render` is `FALSE`, the HTML itself is returned.
+#' If the output is destined for a [knitr] document, set `knitr` to `TRUE`.
+#'
+#' @examples
+#' view_regex("example", "amp", render=FALSE)
+#'
 #' @param text Text to search
 #' @param pattern Regex pattern to look for
 #' @param render Render results to an HTML doc and open in RStudio viewer?
@@ -166,7 +172,7 @@ wrap_regex <- function(pattern, escape = TRUE, exact = TRUE) {
 #'   the double `\\\\` required for escaping backslashes in R. When `FALSE`,
 #'   regex is displayed as interpreted by the regex engine (i.e. double `\\\\`
 #'   as a single `\\`).
-#' @param ... Passed to [run_regex()]
+#' @inheritDotParams base::regexec ignore.case perl fixed useBytes
 #' @export
 view_regex <- function(
   text,

R/shiny_modified_inputs.R

@@ -11,6 +11,7 @@
 #'
 #' @inheritParams shiny::textAreaInput
 #' @param is_code Should the text input be considered verbatim code input?
+#' @family modified shiny inputs
 textAreaInputAlt <- function(inputId, label, value = "", width = NULL, height = NULL,
                              cols = NULL, rows = NULL, placeholder = NULL, resize = NULL,
                              is_code = TRUE) {
@@ -65,6 +66,7 @@ textAreaInputAlt <- function(inputId, label, value = "", width = NULL, height =
 #'
 #' @inheritParams shiny::textInput
 #' @param width Width of `shiny-input-container` div.
+#' @family modified shiny inputs
 textInputCode <- function(inputId, label, value = "", width = NULL,
                           placeholder = NULL) {
   `%AND%` <- getFromNamespace("%AND%", "shiny")

R/utils.R

@@ -1,12 +1,17 @@
-escape_html <- function(x) {
-  x = gsub("&", "&amp;", x)
-  x = gsub("<", "&lt;", x)
-  x = gsub(">", "&gt;", x)
-  x = gsub("\"", "&quot;", x)
-  x = gsub(" ", "&nbsp;", x)
+# highr:::escape_html
+# by Yihui Xie, GPL license
+# https://github.com/yihui/highr/blob/4f54a5b8960d6246daadacea1020ebcdc458ce50/R/utils.R#L54-L61
+escape_html = function(x) {
+  x = gsub('&', '&amp;', x)
+  x = gsub('<', '&lt;', x)
+  x = gsub('>', '&gt;', x)
+  x = gsub('"', '&quot;', x)
   x
 }
 
 escape_backslash <- function(x) {
   gsub("\\\\", "\\\\\\\\", x)
 }
+
+# avoid CRAN note for tidyr::gather in wrap_results
+utils::globalVariables(c("end", "loc", "start", "type"))

man/regex_gadget.Rd

@@ -14,5 +14,7 @@ regex_gadget(text = NULL, start_page = if (is.null(text)) "Text" else
 \code{"Output"}, or \code{"Help"}}
 }
 \description{
-RegExplain gadget
+The function behind the RegExplain Selection and RegExplain File
+addins. Opens the RegExplain gadget interface in an RStudio viewer
+pane.
 }

man/regexplain-package.Rd

@@ -8,8 +8,9 @@
 \description{
 A set of RStudio Addins to help interactively test and build
 regular expressions. Provides a Shiny gadget interface for interactively
-constructing the regexp and viewing the results from common string-searching
-functions. Also provides a helpful reference sheet as an RStudio addin.
+constructing the regular expression and viewing the results from common
+string-searching functions. The gadget interface includes a helpful
+regex syntax reference sheet and a library of common patterns.
 }
 \seealso{
 Useful links:
@@ -25,6 +26,7 @@ Useful links:
 Other contributors:
 \itemize{
   \item Winston Chang (Author of textInput and textAreaInput fragments from shiny) [contributor]
+  \item Yihui Xie (Author of escape_html fragment from highr) [contributor]
   \item  RStudio (Copyright holder of included shiny fragments) [copyright holder]
 }
 

man/regexplain_cheatsheet.Rd

@@ -7,5 +7,7 @@
 regexplain_cheatsheet()
 }
 \description{
-Regex Cheatsheet Quick Reference
+The function behind the RegExplain Cheatsheet addin. Opens a summary of
+regular expression syntax -- the RegExplain cheatsheet -- in an RStudio
+viewer pane.
 }

man/run_regex.Rd

@@ -5,27 +5,24 @@
 \title{Extract matched groups from regexp}
 \usage{
 run_regex(text, pattern, ignore.case = FALSE, perl = FALSE, fixed = FALSE,
-  useBytes = FALSE, invert = FALSE)
+  useBytes = FALSE)
 }
 \arguments{
 \item{text}{Text to search}
 
 \item{pattern}{regexp}
 
-\item{ignore.case}{if \code{FALSE}, the pattern matching is \emph{case
+\item{...}{Arguments passed on to \code{base::regexec}
+\describe{
+  \item{ignore.case}{if \code{FALSE}, the pattern matching is \emph{case
       sensitive} and if \code{TRUE}, case is ignored during matching.}
-
-\item{perl}{logical.  Should Perl-compatible regexps be used?}
-
-\item{fixed}{logical.  If \code{TRUE}, \code{pattern} is a string to be
+  \item{perl}{logical.  Should Perl-compatible regexps be used?}
+  \item{fixed}{logical.  If \code{TRUE}, \code{pattern} is a string to be
     matched as is.  Overrides all conflicting arguments.}
-
-\item{useBytes}{logical.  If \code{TRUE} the matching is done
+  \item{useBytes}{logical.  If \code{TRUE} the matching is done
     byte-by-byte rather than character-by-character.  See
     \sQuote{Details}.}
-
-\item{invert}{logical.  If \code{TRUE} return indices or values for
-    elements that do \emph{not} match.}
+}}
 }
 \description{
 Extract matched groups from regexp

man/textAreaInputAlt.Rd

@@ -45,3 +45,6 @@ Standard \code{\link[shiny:textAreaInput]{shiny::textAreaInput()}} with addition
 code font style for the input text and with \code{autocomplete}, \code{autocorrect},
 \code{autocapitalize} and \code{spellcheck} set to \code{off} or \code{false}.
 }
+\seealso{
+Other modified shiny inputs: \code{\link{textInputCode}}
+}

man/textInputCode.Rd

@@ -25,3 +25,6 @@ Standard \code{\link[shiny:textInput]{shiny::textInput()}} with additional \code
 font style for the input text and with \code{autocomplete}, \code{autocorrect},
 \code{autocapitalize} and \code{spellcheck} set to \code{off} or \code{false}.
 }
+\seealso{
+Other modified shiny inputs: \code{\link{textAreaInputAlt}}
+}

man/view_regex.Rd

@@ -12,7 +12,17 @@ view_regex(text, pattern, ..., render = TRUE, escape = render,
 
 \item{pattern}{Regex pattern to look for}
 
-\item{...}{Passed to \code{\link[=run_regex]{run_regex()}}}
+\item{...}{Arguments passed on to \code{base::regexec}
+\describe{
+  \item{ignore.case}{if \code{FALSE}, the pattern matching is \emph{case
+      sensitive} and if \code{TRUE}, case is ignored during matching.}
+  \item{perl}{logical.  Should Perl-compatible regexps be used?}
+  \item{fixed}{logical.  If \code{TRUE}, \code{pattern} is a string to be
+    matched as is.  Overrides all conflicting arguments.}
+  \item{useBytes}{logical.  If \code{TRUE} the matching is done
+    byte-by-byte rather than character-by-character.  See
+    \sQuote{Details}.}
+}}
 
 \item{render}{Render results to an HTML doc and open in RStudio viewer?}
 
@@ -28,5 +38,12 @@ regex is displayed as interpreted by the regex engine (i.e. double \code{\\\\}
 as a single \code{\\}).}
 }
 \description{
-View grouped regex results
+View the result of the regular expression when applied to the given text.
+The default behavior renders the result as HTML and opens the file in
+the RStudio viewer pane. If \code{render} is \code{FALSE}, the HTML itself is returned.
+If the output is destined for a \link{knitr} document, set \code{knitr} to \code{TRUE}.
+}
+\examples{
+view_regex("example", "amp", render=FALSE)
+
 }