Deprecrate chain. Closes #201

NEWS.md

@@ -1,5 +1,7 @@
 # dplyr 0.1.3.0.99
 
+* `chain()` is now deprecated. Please use `%.%` instead.
+
 * dplyr is more careful when setting the keys of data tables, so it never
   accidentally modifies an object that it doesn't own. It also avoids
   unnecessary key setting which negatively affected performance.

R/chain.r

@@ -6,13 +6,19 @@
 #' functions providing an alternative way of calling dplyr (and other data
 #' manipulation) functions that you read can from left to right.
 #'
-#' The functions work via simple substitution so that \code{chain(x, f(y))} or
+#' The functions work via simple substitution so that
 #' \code{x \%.\% f(y)} is translated into \code{f(x, y)}.
 #'
+#' @section Deprecation:
+#'
+#' \code{chain} was deprecated in version 0.2, and will be removed in
+#' 0.3. It was removed in the interest of making dplyr code more
+#' standardised and \code{\%.\%} is much more popular.
+#'
 #' @param x,y A dataset and function to apply to it
 #' @param ...,calls A sequence of data transformations, starting with a dataset.
 #'   The first argument of each call should be omitted - the value of the
-#'   previous step will be substituted in automatically.  Use \code{chain} and
+#'   previous step will be substituted in automatically. Use \code{chain} and
 #'   \code{...} when working interactive; use \code{chain_q} and \code{calls}
 #'   when calling from another function.
 #' @param env Environment in which to evaluation expressions. In ordinary
@@ -56,18 +62,10 @@
 #'   ) %.%
 #'   filter(arr > 30 | dep > 30)
 #'
-#' chain(
-#'   hflights,
-#'   group_by(Year, Month, DayofMonth),
-#'   select(Year:DayofMonth, ArrDelay, DepDelay),
-#'   summarise(
-#'     arr = mean(ArrDelay, na.rm = TRUE),
-#'     dep = mean(DepDelay, na.rm = TRUE)
-#'   ),
-#'   filter(arr > 30 | dep > 30)
-#' )
 #' }
 chain <- function(..., env = parent.frame()) {
+  # Deprecated 0.2. Remove in 0.3
+  warning("Chain is deprecated. Please use %.%", call. = FALSE)
   chain_q(dots(...), env = env)
 }
 

man/chain.Rd

@@ -16,7 +16,7 @@ x \%.\% y
 
 \item{...,calls}{A sequence of data transformations, starting with a dataset.
 The first argument of each call should be omitted - the value of the
-previous step will be substituted in automatically.  Use \code{chain} and
+previous step will be substituted in automatically. Use \code{chain} and
 \code{...} when working interactive; use \code{chain_q} and \code{calls}
 when calling from another function.}
 
@@ -31,9 +31,16 @@ functions providing an alternative way of calling dplyr (and other data
 manipulation) functions that you read can from left to right.
 }
 \details{
-The functions work via simple substitution so that \code{chain(x, f(y))} or
+The functions work via simple substitution so that
 \code{x \%.\% f(y)} is translated into \code{f(x, y)}.
 }
+\section{Deprecation}{
+
+
+\code{chain} was deprecated in version 0.2, and will be removed in
+0.3. It was removed in the interest of making dplyr code more
+standardised and \code{\%.\%} is much more popular.
+}
 \examples{
 if (require("hflights")) {
 # If you're performing many operations you can either do step by step
@@ -72,16 +79,6 @@ hflights \%.\%
   ) \%.\%
   filter(arr > 30 | dep > 30)
 
-chain(
-  hflights,
-  group_by(Year, Month, DayofMonth),
-  select(Year:DayofMonth, ArrDelay, DepDelay),
-  summarise(
-    arr = mean(ArrDelay, na.rm = TRUE),
-    dep = mean(DepDelay, na.rm = TRUE)
-  ),
-  filter(arr > 30 | dep > 30)
-)
 }
 }