From c511d8ac05e5990481e2421f03d5308f3fc84227 Mon Sep 17 00:00:00 2001
From: John Mount <jmount@win-vector.com>
Date: Sat, 28 Sep 2019 08:17:37 -0700
Subject: [PATCH] move locum to package

---
 NAMESPACE                 |   6 ++
 R/locum.R                 | 159 ++++++++++++++++++++++++++++++++++++++
 man/apply_left.locum.Rd   |  28 +++++++
 man/apply_right.locum.Rd  |  29 +++++++
 man/as.character.locum.Rd |  25 ++++++
 man/format.locum.Rd       |  25 ++++++
 man/locum.Rd              |  21 +++++
 man/print.locum.Rd        |  25 ++++++
 8 files changed, 318 insertions(+)
 create mode 100644 R/locum.R
 create mode 100644 man/apply_left.locum.Rd
 create mode 100644 man/apply_right.locum.Rd
 create mode 100644 man/as.character.locum.Rd
 create mode 100644 man/format.locum.Rd
 create mode 100644 man/locum.Rd
 create mode 100644 man/print.locum.Rd

diff --git a/NAMESPACE b/NAMESPACE
index f6ee0523..78155643 100644
--- a/NAMESPACE
+++ b/NAMESPACE
@@ -9,8 +9,11 @@ S3method(":=",numeric)
 S3method(apply_left,Collector)
 S3method(apply_left,UnaryFn)
 S3method(apply_left,default)
+S3method(apply_left,locum)
 S3method(apply_right,UnaryFn)
 S3method(apply_right,default)
+S3method(apply_right,locum)
+S3method(as.character,locum)
 S3method(as.list,UnaryFn)
 S3method(as.list,UnaryFnList)
 S3method(c,UnaryFn)
@@ -18,8 +21,10 @@ S3method(format,PartialFunction)
 S3method(format,PartialNamedFn)
 S3method(format,SrcFunction)
 S3method(format,UnaryFnList)
+S3method(format,locum)
 S3method(format,wrapr_as_dot_fn)
 S3method(format,wrapr_as_fn)
+S3method(print,locum)
 S3method(print,wrapr_as_dot_fn)
 S3method(print,wrapr_as_fn)
 S3method(view,data.frame)
@@ -80,6 +85,7 @@ export(invert_perm)
 export(lambda)
 export(lapplym)
 export(let)
+export(locum)
 export(makeFunction_se)
 export(map_to_char)
 export(map_upper)
diff --git a/R/locum.R b/R/locum.R
new file mode 100644
index 00000000..feed80ca
--- /dev/null
+++ b/R/locum.R
@@ -0,0 +1,159 @@
+
+#' Build a stand in for a future value to be placed in a pipe.
+#'
+#' The locum stands in for a value to be specified later in a pipeline.
+#' This is similar to a lambda or function abstraction.
+#'
+#' @return a locum stand-in
+#'
+#' @examples
+#'
+#' p <- locum() %.>% sin(.)
+#' 5 %.>% p
+#'
+#' @export
+#'
+#'
+locum <- function() {
+  locum <- list(stages = list())
+  class(locum) <- 'locum'
+  return(locum)
+}
+
+
+#' Format a locum for presentation.
+#'
+#' @param x locum to be formatted
+#' @param ... additional arguments, use "start" to replace initial step presentation
+#' @return formatted string
+#'
+#' @examples
+#'
+#' p <- locum() %.>% sin(.)
+#' format(p, start = 5)
+#'
+#' @export
+#'
+format.locum <- function(x, ...) {
+  args <- list(...)
+  locum <- x
+  start_name <- 'locum()'
+  if('start' %in% names(args)) {
+    start_name <- format(args[['start']])
+  }
+  stage_strs <- vapply(
+    locum$stages,
+    function(si) {
+      format(si$pipe_right_arg)
+    }, character(1))
+  stage_strs <- c(list(start_name),
+                  stage_strs)
+  return(paste(stage_strs,
+               collapse = " %.>%\n   "))
+}
+
+
+#' Format a locum for presentation.
+#'
+#' @param x locum to be formatted
+#' @param ... additional arguments, use "start" to replace initial step presentation
+#' @return formatted string
+#'
+#' @examples
+#'
+#' p <- locum() %.>% sin(.)
+#' as.character(p, start = 5)
+#'
+#' @export
+#'
+as.character.locum <- function(x, ...) {
+  return(format(x, ...))
+}
+
+
+#' Print a locum presentation.
+#'
+#' @param x locum to be formatted
+#' @param ... additional arguments, use "start" to replace initial step presentation
+#' @return formatted string
+#'
+#' @examples
+#'
+#' p <- locum() %.>% sin(.)
+#' print(p, start = 5)
+#'
+#' @export
+#'
+print.locum <- function(x, ...) {
+  cat(format(x, ...))
+}
+
+
+#' S3 dispatch on class of pipe_left_arg for a locum.
+#'
+#' For formal documentation please see \url{https://github.com/WinVector/wrapr/blob/master/extras/wrapr_pipe.pdf}.
+#'
+#' @param pipe_left_arg left argument.
+#' @param pipe_right_arg substitute(pipe_right_arg) argument.
+#' @param pipe_environment environment to evaluate in.
+#' @param left_arg_name name, if not NULL name of left argument.
+#' @param pipe_string character, name of pipe operator.
+#' @param right_arg_name name, if not NULL name of right argument.
+#' @return result
+#'
+#' @export
+#'
+apply_left.locum <- function(
+  pipe_left_arg,
+  pipe_right_arg,
+  pipe_environment,
+  left_arg_name,
+  pipe_string,
+  right_arg_name) {
+  locum <- pipe_left_arg
+  capture <- list(
+    pipe_right_arg = force(pipe_right_arg),
+    pipe_environment = force(pipe_environment),
+    left_arg_name = force(left_arg_name),
+    pipe_string = force(pipe_string),
+    right_arg_name = force(right_arg_name))
+  locum$stages <- c(locum$stages, list(capture))
+  return(locum)
+}
+
+
+#' S3 dispatch on class of pipe_right_argument for a locum.
+#'
+#' Triggered if right hand side of pipe stage was a name that does not resolve to a function.
+#' For formal documentation please see \url{https://github.com/WinVector/wrapr/blob/master/extras/wrapr_pipe.pdf}.
+#'
+#' @param pipe_left_arg left argument
+#' @param pipe_right_arg right argument
+#' @param pipe_environment environment to evaluate in
+#' @param left_arg_name name, if not NULL name of left argument.
+#' @param pipe_string character, name of pipe operator.
+#' @param right_arg_name name, if not NULL name of right argument.
+#' @return result
+#'
+#' @export
+#'
+apply_right.locum <- function(
+  pipe_left_arg,
+  pipe_right_arg,
+  pipe_environment,
+  left_arg_name,
+  pipe_string,
+  right_arg_name) {
+  force(pipe_left_arg)
+  locum <- pipe_right_arg
+  for(s in locum$stages) {
+    pipe_left_arg <- pipe_impl(
+      pipe_left_arg,
+      s$pipe_right_arg,
+      s$pipe_environment,
+      pipe_string = s$pipe_string)
+  }
+  return(pipe_left_arg)
+}
+
+
diff --git a/man/apply_left.locum.Rd b/man/apply_left.locum.Rd
new file mode 100644
index 00000000..39cb3957
--- /dev/null
+++ b/man/apply_left.locum.Rd
@@ -0,0 +1,28 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/locum.R
+\name{apply_left.locum}
+\alias{apply_left.locum}
+\title{S3 dispatch on class of pipe_left_arg for a locum.}
+\usage{
+\method{apply_left}{locum}(pipe_left_arg, pipe_right_arg, pipe_environment,
+  left_arg_name, pipe_string, right_arg_name)
+}
+\arguments{
+\item{pipe_left_arg}{left argument.}
+
+\item{pipe_right_arg}{substitute(pipe_right_arg) argument.}
+
+\item{pipe_environment}{environment to evaluate in.}
+
+\item{left_arg_name}{name, if not NULL name of left argument.}
+
+\item{pipe_string}{character, name of pipe operator.}
+
+\item{right_arg_name}{name, if not NULL name of right argument.}
+}
+\value{
+result
+}
+\description{
+For formal documentation please see \url{https://github.com/WinVector/wrapr/blob/master/extras/wrapr_pipe.pdf}.
+}
diff --git a/man/apply_right.locum.Rd b/man/apply_right.locum.Rd
new file mode 100644
index 00000000..a71078db
--- /dev/null
+++ b/man/apply_right.locum.Rd
@@ -0,0 +1,29 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/locum.R
+\name{apply_right.locum}
+\alias{apply_right.locum}
+\title{S3 dispatch on class of pipe_right_argument for a locum.}
+\usage{
+\method{apply_right}{locum}(pipe_left_arg, pipe_right_arg,
+  pipe_environment, left_arg_name, pipe_string, right_arg_name)
+}
+\arguments{
+\item{pipe_left_arg}{left argument}
+
+\item{pipe_right_arg}{right argument}
+
+\item{pipe_environment}{environment to evaluate in}
+
+\item{left_arg_name}{name, if not NULL name of left argument.}
+
+\item{pipe_string}{character, name of pipe operator.}
+
+\item{right_arg_name}{name, if not NULL name of right argument.}
+}
+\value{
+result
+}
+\description{
+Triggered if right hand side of pipe stage was a name that does not resolve to a function.
+For formal documentation please see \url{https://github.com/WinVector/wrapr/blob/master/extras/wrapr_pipe.pdf}.
+}
diff --git a/man/as.character.locum.Rd b/man/as.character.locum.Rd
new file mode 100644
index 00000000..9e94a810
--- /dev/null
+++ b/man/as.character.locum.Rd
@@ -0,0 +1,25 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/locum.R
+\name{as.character.locum}
+\alias{as.character.locum}
+\title{Format a locum for presentation.}
+\usage{
+\method{as.character}{locum}(x, ...)
+}
+\arguments{
+\item{x}{locum to be formatted}
+
+\item{...}{additional arguments, use "start" to replace initial step presentation}
+}
+\value{
+formatted string
+}
+\description{
+Format a locum for presentation.
+}
+\examples{
+
+p <- locum() \%.>\% sin(.)
+as.character(p, start = 5)
+
+}
diff --git a/man/format.locum.Rd b/man/format.locum.Rd
new file mode 100644
index 00000000..c85030d6
--- /dev/null
+++ b/man/format.locum.Rd
@@ -0,0 +1,25 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/locum.R
+\name{format.locum}
+\alias{format.locum}
+\title{Format a locum for presentation.}
+\usage{
+\method{format}{locum}(x, ...)
+}
+\arguments{
+\item{x}{locum to be formatted}
+
+\item{...}{additional arguments, use "start" to replace initial step presentation}
+}
+\value{
+formatted string
+}
+\description{
+Format a locum for presentation.
+}
+\examples{
+
+p <- locum() \%.>\% sin(.)
+format(p, start = 5)
+
+}
diff --git a/man/locum.Rd b/man/locum.Rd
new file mode 100644
index 00000000..ba76ceed
--- /dev/null
+++ b/man/locum.Rd
@@ -0,0 +1,21 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/locum.R
+\name{locum}
+\alias{locum}
+\title{Build a stand in for a future value to be placed in a pipe.}
+\usage{
+locum()
+}
+\value{
+a locum stand-in
+}
+\description{
+The locum stands in for a value to be specified later in a pipeline.
+This is similar to a lambda or function abstraction.
+}
+\examples{
+
+p <- locum() \%.>\% sin(.)
+5 \%.>\% p
+
+}
diff --git a/man/print.locum.Rd b/man/print.locum.Rd
new file mode 100644
index 00000000..064dee79
--- /dev/null
+++ b/man/print.locum.Rd
@@ -0,0 +1,25 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/locum.R
+\name{print.locum}
+\alias{print.locum}
+\title{Print a locum presentation.}
+\usage{
+\method{print}{locum}(x, ...)
+}
+\arguments{
+\item{x}{locum to be formatted}
+
+\item{...}{additional arguments, use "start" to replace initial step presentation}
+}
+\value{
+formatted string
+}
+\description{
+Print a locum presentation.
+}
+\examples{
+
+p <- locum() \%.>\% sin(.)
+print(p, start = 5)
+
+}