[med-svn] [r-cran-proto] 01/11: New upstream version 1.0.0
Andreas Tille
tille at debian.org
Tue Dec 6 17:56:48 UTC 2016
This is an automated email from the git hooks/post-receive script.
tille pushed a commit to branch master
in repository r-cran-proto.
commit dae2e7e4252a8e0b23f74986520e659b6ca6ee58
Author: Andreas Tille <tille at debian.org>
Date: Tue Dec 6 18:23:06 2016 +0100
New upstream version 1.0.0
---
COPYING | 0
COPYRIGHTS | 10 -
DESCRIPTION | 33 +-
MD5 | 62 +-
NAMESPACE | 14 +-
NEWS.md | 141 ++++
R/graph.proto.R | 76 +--
R/proto.R | 467 ++++++++++---
README.debian | 10 -
README.md | 82 +++
build/vignette.rds | Bin 0 -> 280 bytes
demo/00Index | 4 +-
demo/proto-gWidgets.R | 149 +++++
demo/proto-vignette.R | 396 ++++++-----
demo/proto.R | 118 ----
inst/FAQ | 0
inst/NEWS | 143 ----
inst/README | 100 ---
inst/ReleaseNotes.txt | 178 +++++
inst/THANKS | 2 +-
inst/WISHLIST | 0
inst/doc/proto.Rnw | 1380 ++++++++++++++++++++++++++++++++++++++-
inst/doc/proto.pdf | Bin 372236 -> 369428 bytes
inst/doc/protoref.Rnw | 53 +-
inst/doc/protoref.pdf | Bin 63397 -> 58772 bytes
man/graph.proto.Rd | 68 --
man/proto-package.Rd | 88 +--
man/proto.Rd | 542 +++++++--------
tests/testthat.R | 4 +
tests/testthat/test-getting.R | 33 +
tests/testthat/test-printing.R | 13 +
vignettes/README | 5 -
vignettes/Z.cls | 173 -----
vignettes/cloning3.dot | 8 -
vignettes/cloning3.pdf | Bin
vignettes/proto-concordance.tex | 2 +
vignettes/proto-dot.pdf | Bin 5138 -> 5644 bytes
vignettes/proto-dot.tex | 0
vignettes/proto-raw | 1276 ------------------------------------
vignettes/proto-raw.tex | 1359 --------------------------------------
vignettes/proto-smoothing03.pdf | Bin 7335 -> 4548 bytes
vignettes/proto-smoothing03.tex | 0
vignettes/proto-smoothing04.pdf | Bin 6276 -> 13222 bytes
vignettes/proto-smoothing04.tex | 0
vignettes/proto-smoothing06.pdf | Bin 8557 -> 5750 bytes
vignettes/proto-smoothing06.tex | 0
vignettes/proto-smoothing10.pdf | Bin 28157 -> 25258 bytes
vignettes/proto-smoothing10.tex | 0
vignettes/proto.Rnw | 1380 ++++++++++++++++++++++++++++++++++++++-
vignettes/proto.bib | 0
vignettes/proto.tex | 1380 ++++++++++++++++++++++++++++++++++++++-
vignettes/protoref-raw.tex | 0
vignettes/protoref.Rnw | 53 +-
53 files changed, 5696 insertions(+), 4106 deletions(-)
diff --git a/COPYING b/COPYING
old mode 100755
new mode 100644
diff --git a/COPYRIGHTS b/COPYRIGHTS
deleted file mode 100755
index 777a8b5..0000000
--- a/COPYRIGHTS
+++ /dev/null
@@ -1,10 +0,0 @@
-COPYRIGHT STATUS
-----------------
-
-This bulk of this code is
-
- Copyright (C) 2004 Louis Kates, Thomas Petzoldt
-
-All code is subject to the GNU General Public License, Version 2. See
-the file COPYING for the exact conditions under which you may
-redistribute it.
diff --git a/DESCRIPTION b/DESCRIPTION
old mode 100755
new mode 100644
index 414259f..db05b28
--- a/DESCRIPTION
+++ b/DESCRIPTION
@@ -1,14 +1,25 @@
Package: proto
-Version: 0.3-10
-Date: 2012-12-21
-Title: Prototype object-based programming
-Author: Louis Kates, Thomas Petzoldt
-Maintainer: Gabor Grothendieck <ggrothendieck at gmail.com>
-Description: An object oriented system using object-based, also called
- prototype-based, rather than class-based object oriented ideas.
-Suggests: graph, Rgraphviz
+Version: 1.0.0
+Title: Prototype Object-Based Programming
+Description: An object oriented system using object-based, also
+ called prototype-based, rather than class-based object oriented ideas.
+Authors at R: c(
+ person("Hadley", "Wickham", , "hadley at rstudio.com", "cre"),
+ person("Gabor", "Grothendieck", , "ggrothendieck at gmail.com", "aut"),
+ person("Louis", "Kates", role = "aut"),
+ person("Thomas", "Petzoldt", role = "aut")
+ )
License: GPL-2
-URL: http://r-proto.googlecode.com
-Packaged: 2012-12-22 16:03:20 UTC; Louis
+URL: https://github.com/hadley/proto
+BugReports: https://github.com/hadley/proto/issues
+Suggests: testthat, covr
+RoxygenNote: 5.0.1.9000
+NeedsCompilation: no
+Packaged: 2016-10-28 22:08:08 UTC; hadley
+Author: Hadley Wickham [cre],
+ Gabor Grothendieck [aut],
+ Louis Kates [aut],
+ Thomas Petzoldt [aut]
+Maintainer: Hadley Wickham <hadley at rstudio.com>
Repository: CRAN
-Date/Publication: 2012-12-22 21:51:44
+Date/Publication: 2016-10-29 00:23:07
diff --git a/MD5 b/MD5
index 24f3849..b256e16 100644
--- a/MD5
+++ b/MD5
@@ -1,43 +1,41 @@
46aaf69a91703493b666f212a04f2d8d *COPYING
-f1b835a71d977b89a230f0e4f99dd90d *COPYRIGHTS
-cb34824dbd8ef8d6dd5d2f4bdc3fcd1a *DESCRIPTION
-09754c9bb5e1c4827329a9e0ba97b396 *NAMESPACE
-42c1cfc8132441d8265761c8043556ff *R/graph.proto.R
-c1123ff65baf22a8a7ff44e5d6801a00 *R/proto.R
-6037abe3a5b93273e226787815fef835 *README.debian
-54b1b6fd87c468388e490fec90867b1c *demo/00Index
-ceeaf4410099f287e2270fc78818cecf *demo/proto-vignette.R
-753a9fadec704a3bbbdf33acb55b74cc *demo/proto.R
+d13d6e897e600782decc062154405515 *DESCRIPTION
+79185c6178ca17f2333a13e1c04364f5 *NAMESPACE
+b82d79a3b0808d0727b3ed1dd1dca232 *NEWS.md
+5fdb9a168d79e51eb75682fb80d7ab38 *R/graph.proto.R
+32feac1144591dc1544ba145143e171f *R/proto.R
+172a2f42e29eff6d5d4b8b0f4ea22d8c *README.md
+07d42b7a2aef34560965f9cc44e2f6d4 *build/vignette.rds
+e7d0d22a9bf06821743815ed52398ec9 *demo/00Index
+f7c8dfe577867e2bb17740e6d1e90d0c *demo/proto-gWidgets.R
+483dcf4797b0e433519c54852273b2d4 *demo/proto-vignette.R
389be8e7c57d3814674707a35c692459 *inst/FAQ
-5955a48859befe932beb3b7785404f21 *inst/NEWS
-6cfcfccaa048fc8ee56ea2643b8db12e *inst/README
-24576b9372c63525afb6e103f7380a7c *inst/THANKS
+10ae2772e93fc9e20d6c04cac4c28b0a *inst/ReleaseNotes.txt
+d9d380a3002a53780a3f2e295f72d964 *inst/THANKS
7ecc08fce7089dad44f647b8bfb1434a *inst/WISHLIST
-bca490c5de076ff9b93c69255f317f4a *inst/doc/proto.Rnw
-7b2b24726d56bbc93494e400bf7d030f *inst/doc/proto.pdf
-4273f3c74b47222ea69a1b08438a821f *inst/doc/protoref.Rnw
-1b706daf7d2b28e24331627a8a68a53c *inst/doc/protoref.pdf
-a78c61ae7a81202d3a8ac767c0b57a42 *man/graph.proto.Rd
-e1efd10e8444a7473c04328576a7a5ea *man/proto-package.Rd
-00d697562783af865d8c4558aef8852c *man/proto.Rd
-681237a1b1290f1e6fc93667591a7865 *vignettes/README
-954ced282c02125db098edbb5bf7d147 *vignettes/Z.cls
-ec6063dd71e4a60916a310e810b72686 *vignettes/cloning3.dot
+4c02116aa0d3f18588e6eac75245d477 *inst/doc/proto.Rnw
+5c03a6e10e561838a2dc6e78b8d82dc4 *inst/doc/proto.pdf
+7fa93ee9be6446b7a58ca3f03f83a920 *inst/doc/protoref.Rnw
+94c06ffe4baa25c966cf8d1f87c95433 *inst/doc/protoref.pdf
+6d0a2ee1cef9d7e3e35e57ec5f783e56 *man/proto-package.Rd
+107f52b7c76137a872c40b16d1b62d3b *man/proto.Rd
+13edf6e57a045e63a721fd0465f719d4 *tests/testthat.R
+cbda723db33f74ef3d17ca4db97f5b01 *tests/testthat/test-getting.R
+224a9f6df86f731c79dfae8a6c0f6cf8 *tests/testthat/test-printing.R
d64eff73ca94aa8d8e23eb2bfa69fd86 *vignettes/cloning3.pdf
-186a0c34001100a81c27bf519c81edb2 *vignettes/proto-dot.pdf
+014b4c7791b70438f0073a264aa18f4b *vignettes/proto-concordance.tex
+cfa8f120382d437ef100e932c11a4c32 *vignettes/proto-dot.pdf
bfce81e7eaa5cf3d01dae6f9964aeab5 *vignettes/proto-dot.tex
-3fbe78134c2dd817cb585b9218574c61 *vignettes/proto-raw
-2ee13f271faa022648600c5f3736cb83 *vignettes/proto-raw.tex
-e8904de6669701e6c252964f8ef7ad0b *vignettes/proto-smoothing03.pdf
+5acb4a84c924cf82234ead21f9885a62 *vignettes/proto-smoothing03.pdf
1320f930222ba5b29e84f9321891b280 *vignettes/proto-smoothing03.tex
-ef781a3c343efd0e19283aea096a4e55 *vignettes/proto-smoothing04.pdf
+3428268a6c07e7dc06413ee7a9ac3a86 *vignettes/proto-smoothing04.pdf
fdc0cf82a3583a4debfebcf2f66531c3 *vignettes/proto-smoothing04.tex
-5819b82ae7b1fac31abac5014ad8cafb *vignettes/proto-smoothing06.pdf
+a7328df62707e20a7ab4e00e00ba9050 *vignettes/proto-smoothing06.pdf
3b65082f7e4b40eda30d384124125fde *vignettes/proto-smoothing06.tex
-b1e193bbfee964291660ff1cdd26c284 *vignettes/proto-smoothing10.pdf
+691c6188ecfadf96684e1ec8349f6181 *vignettes/proto-smoothing10.pdf
383ef6322b693e859795cecaa29390c4 *vignettes/proto-smoothing10.tex
-bca490c5de076ff9b93c69255f317f4a *vignettes/proto.Rnw
+4c02116aa0d3f18588e6eac75245d477 *vignettes/proto.Rnw
7ad5d41f758d4792ef9c3a4bcfbe32da *vignettes/proto.bib
-1cc3d874f03f7073b3935825054775bf *vignettes/proto.tex
+a05a09f2df0c4e8743011ae343ccf8d4 *vignettes/proto.tex
a3ca93bf6e5afe69e729381c44c14a4c *vignettes/protoref-raw.tex
-4273f3c74b47222ea69a1b08438a821f *vignettes/protoref.Rnw
+7fa93ee9be6446b7a58ca3f03f83a920 *vignettes/protoref.Rnw
diff --git a/NAMESPACE b/NAMESPACE
old mode 100755
new mode 100644
index a77f192..41e0cce
--- a/NAMESPACE
+++ b/NAMESPACE
@@ -1 +1,13 @@
-exportPattern(".")
+# Generated by roxygen2: do not edit by hand
+
+S3method("$",proto)
+S3method("$<-",proto)
+S3method(as.proto,environment)
+S3method(as.proto,list)
+S3method(as.proto,proto)
+S3method(print,proto)
+S3method(print,protoMethod)
+S3method(str,proto)
+export(as.proto)
+export(is.proto)
+export(proto)
diff --git a/NEWS.md b/NEWS.md
new file mode 100644
index 0000000..dc98ec0
--- /dev/null
+++ b/NEWS.md
@@ -0,0 +1,141 @@
+# VERSION 1.0.0
+
+* You can override the default printing method by providing a `proto_print`
+ method in your object.
+
+* `graph.proto()` has been removed since it relies on packages that are
+ no longer on CRAN. `name.proto()` is no longer exported since it was
+ used primarily by `graph.proto()`.
+
+* Hadley Wickham has taken over maintenance.
+
+* All outstanding R CMD check problems have been fixed.
+
+* New NAMESPACE file that ensures that proto works when not attached.
+
+# VERSION 0.3-9
+
+* minor changes to satisfy subtitute/eval changes in R 2.13.0 (thanks to
+ Luke Tierney)
+
+* x could previously not be the name of a proto object. Now fixed.
+
+* proto print methods could break str.proto. Now fixed.
+
+# VERSION 0.3-8
+
+* minor changes to satisfy R 2.6.0
+
+# VERSION 0.3-7
+
+* FAQ added as Appendix A of vignette
+
+* str.proto added (modified code of Tom Short)
+
+* the class of p$fun is now "instantiatedProtoMethod" and
+ print.instantiatedProtoMethod provided (modified code of Tom Short)
+
+* "$.proto" now has a third argument which, if present, is a list of
+ arguments at which to evaluate the instantiated method. Intended for
+ use within sapply/lapply/etc. See examples in ?proto .
+
+* modified DESCRIPTION to point to new home page
+
+# VERSION 0.3-6
+
+* order of arguments in proto and as.proto.list changed to
+ address a bug
+
+# VERSION 0.3-5
+
+* new arg funEnvir= on proto and as.proto.list [experimental]
+
+* new arg SELECT= on as.proto [experimental]
+
+# VERSION 0.3-4
+
+* new function graph.proto using Rgraphviz replaces dot.proto
+
+* updated vignettes
+
+* added proto-package.Rd (viewable via package?proto)
+
+# VERSION 0.3-3
+
+* updated NEWS, README, WISHLIST and moved to to inst directory
+
+# VERSION 0.3-2
+
+* bug fix (recursion bug)
+
+* documentation improvements (vignette, .Rd files, README)
+
+# VERSION 0.3-1
+
+* .Rd file improvements
+
+# VERSION 0.3-0
+
+* that/super changed to .that/.super.
+
+* .Name changed to ..Name in dot.proto
+
+* improvements to .Rd files and vignette
+
+# VERSION 0.2-6
+
+* demo index file fixed and demo renamed and enhanced
+
+* proto.bib updated
+
+* consistent use of obj$with(meth) in examples and demo where method
+ not used in the context of a call
+
+# VERSION 0.2-5
+
+* vignette and reference card now pass R CMD check/build/install
+
+* CHANGES renamed to NEWS
+
+# VERSION 0.2-4
+
+* added control argument to dot.proto
+
+# VERSION 0.2-3
+
+* added reference card
+
+* modified demo, .Rd files and vignette to correspond to new interface
+
+* changed argument list for proto and eliminated delegate
+
+* created as.proto.list and eliminated copy.proto
+
+* fixed bug in proto. Parent was not always set correctly.
+
+* added ... argument to copy.proto
+
+* added the isnot.function support function for use with copy.proto
+
+* cleaned up $.proto code for handling .. names.
+
+* the on-the-fly wrapper function generated by obj$meth now has the
+ current environment as its environment.
+
+* proto no longer coerces its parent to a proto object. See note
+ at end of proto.Rd.
+
+* added .. name processing and updated .Rd file
+
+* dot.proto now accepts names with dots in them
+
+* added delegate and copy.proto commands and updated .Rd file
+
+# VERSION 0.2-2
+
+* added .. name processing and updated .Rd file
+
+* dot.proto now accepts names with dots in them
+
+* added delegate and copy.proto commands and updated .Rd file
+
diff --git a/R/graph.proto.R b/R/graph.proto.R
old mode 100755
new mode 100644
index 384ea97..fcd1af9
--- a/R/graph.proto.R
+++ b/R/graph.proto.R
@@ -1,55 +1,21 @@
-
-name.proto <- function(., envir = parent.frame()) {
- stopifnot(is.environment(.) ||
- (is.character(.) && is.environment(get(., envir))))
- if (is.environment(.)) {
- if (exists("..Name", ., inherits = FALSE)) .$..Name
- else {
- L <- unlist(eapply(envir, identical, .))
- if (any(L)) names(L[L])[1]
- else gsub("^.* |>$", "", capture.output(print.default(.))[[1]])
- }
- } else {
- e <- get(., envir)
- if (exists("..Name", e, inherits = FALSE)) e$..Name
- else .
- }
-}
-
-graph.proto <- function(e,
- g = new("graphNEL", edgemode = "directed"), child.to.parent = TRUE) {
- if (missing(e)) e <-
- if (exists(".that")) get(".that") else parent.frame()
- if ( suppressWarnings(! require(graph) || ! require(Rgraphviz)) )
- stop("Error: packages graph and Rgraphviz must be available for loading")
- # add node if its not already in g
- addNode. <- function(x, g) if (x %in% nodes(g)) g else addNode(x, g)
- # add edge between nodes adding nodes too if not already in g
- addEdge. <- function(x, y, g) {
- g <- addNode.(x,g); g <- addNode.(y, g)
- addEdge(x, y, g, 1)
- }
- nn <- unlist(eapply(e, is.proto))
- for(x in names(nn[nn]))
- g <- if (child.to.parent)
- addEdge.(name.proto(x,e), name.proto(get(x,e)$parent.env(), e), g)
- else
- addEdge.(name.proto(get(x,e)$parent.env(), e), name.proto(x, e), g)
- g
-}
-
-### test
-# a <- proto()
-# b <- a$proto()
-# g <- graph.proto()
-# plot(g)
-# g <- graph.proto(child.to.parent = FALSE) # change arrow heads
-# plot(g)
-# g <- graph.proto(new("graphNEL")) # undirected
-# plot(g)
-# g <- graph.proto()
-# attrs <- list(node = list(fillcolor = "lightgreen"),
-# edge = list(color = "cyan"),
-# graph = list(rankdir = "BT"))
-# plot(graph.proto(), attrs) # specify plot attributes
-
+name.proto <- function(., envir = parent.frame()) {
+ stopifnot(is.environment(.) ||
+ (is.character(.) && is.environment(get(., envir))))
+ if (is.environment(.)) {
+ if (exists("..Name", ., inherits = FALSE))
+ .$..Name
+ else {
+ L <- unlist(eapply(envir, identical, .))
+ if (any(L))
+ names(L[L])[1]
+ else
+ gsub("^.* |>$", "", utils::capture.output(print.default(.))[[1]])
+ }
+ } else {
+ e <- get(., envir)
+ if (exists("..Name", e, inherits = FALSE))
+ e$..Name
+ else
+ .
+ }
+}
diff --git a/R/proto.R b/R/proto.R
old mode 100755
new mode 100644
index 7947044..774d1ef
--- a/R/proto.R
+++ b/R/proto.R
@@ -1,92 +1,375 @@
-proto <- function (. = parent.env(envir), expr = {}, envir =
- new.env(parent = parent.frame()), ..., funEnvir = envir) {
- parent.env(envir) <- .
- as.proto.environment(envir) # must do this before eval(...)
- # moved eval after for so that ... always done first
- # eval(substitute(eval(quote({ expr }))), envir)
- dots <- list(...); names <- names(dots)
- for (i in seq(length = length(dots))) {
- assign(names[i], dots[[i]], envir = envir)
- if (!identical(funEnvir, FALSE) && is.function(dots[[i]]))
- environment(envir[[names[i]]]) <- funEnvir
- }
- eval(substitute(eval(quote({ expr }))), envir)
- if (length(dots)) as.proto.environment(envir) else envir
-}
-
-as.proto <- function(x, ...) UseMethod("as.proto")
-as.proto.environment <- function(x, ...) {
- assign(".that", x, envir = x)
- assign(".super", parent.env(x), envir = x)
- structure(x, class = c("proto", "environment"))
-}
-as.proto.proto <- function(x, ...) x
-as.proto.list <- function(x, envir, parent, all.names = FALSE, ...,
- funEnvir = envir, SELECT = function(x) TRUE) {
- if (missing(envir)) {
- if (missing(parent)) parent <- parent.frame()
- envir <- if (is.proto(parent))
- parent$proto(...)
- else
- proto(parent, ...)
- }
- for(s in names(x))
- if (SELECT(x[[s]])) {
- assign(s, x[[s]], envir = envir)
- if (is.function(x[[s]]) && !identical(funEnvir, FALSE))
- environment(envir[[s]]) <- funEnvir
- }
- if (!missing(parent)) parent.env(envir) <- parent
- as.proto.environment(envir) # force refresh of .that and .super
-}
-
-"$<-.proto" <- function(this,s,value) {
- if (s == ".super") parent.env(this) <- value
- if (is.function(value)) environment(value) <- this
- this[[as.character(substitute(s))]] <- value
- this
-}
-
-is.proto <- function(x) inherits(x, "proto")
-isnot.function <- function(x) ! is.function(x)
-
-"$.proto" <-
-function (this, x, args) {
- inh <- substr(x, 1, 2) != ".."
- p <- parent.frame()
- res <- get(x, envir = this, inherits = inh)
- is.function <- is.function(res)
- is.that <- match(deparse(substitute(this)), c(".that", ".super"),
- nomatch = 0)
- if (is.function && !is.that) {
- res <- function(...) get(x, envir = this, inherits = inh)(this, ...)
- class(res) <- c("instantiatedProtoMethod", "function")
- attr(res, "this") <- this
- if (!missing(args)) res <- do.call(res, args, envir = p)
- }
- res
-}
-
-
-# modified from Tom Short's original
-print.instantiatedProtoMethod <- function(x, ...) {
- # cat("proto method call: ")
- # print(unclass(x))
- cat("proto method (instantiated with ", name.proto(attr(x, "this")),
- "): ", sep = "")
- print(eval(body(x)[[1]], envir = environment(x)))
-}
-
-# modified from Tom Short's original
-str.proto <- function(object, max.level = 1, nest.lev = 0, indent.str =
- paste(rep.int(" ", max(0, nest.lev + 1)), collapse = ".."), ...) {
- cat("proto", name.proto(object), "\n")
- Lines <- capture.output(str(as.list(object), max.level = max.level,
- nest.lev = nest.lev, ...))[-1]
- for(s in Lines) cat(s, "\n")
- if (is.proto(parent.env(object))) {
- cat(indent.str, "parent: ", sep = "")
- str(parent.env(object), nest.lev = nest.lev + 1, ...)
- }
-}
-
+#' Object-Oriented Programming with the Prototype Model
+#'
+#' Object-oriented programming with the prototype model. \code{"proto"}
+#' facilitates object-oriented programming using an approach that emphasizes
+#' objects rather than classes (although it is powerful enough to readily
+#' represent classes too).
+#'
+#' @name proto-package
+#' @docType package
+#' @keywords programming
+#' @examples
+#'
+#' cat("parent\n")
+#' oop <- proto(x = 10, view = function(.) paste("this is a:", .$x))
+#' oop$ls()
+#' oop$view()
+#'
+#' cat("override view in parent\n")
+#' ooc1 <- oop$proto(view = function(.) paste("this is a: ***", .$x, "***"))
+#' ooc1$view()
+#'
+#' cat("override x in parent\n")
+#' ooc2 <- oop$proto(x = 20)
+#' ooc2$view()
+NULL
+
+#' Prototype object-based programming
+#'
+#' \code{proto} creates or modifies objects of the proto object oriented
+#' system.
+#'
+#' The \code{proto} class is an \code{S3} subclass of the R \code{environment}
+#' class. In particular this implies that \code{proto} objects have single
+#' inheritance and mutable state as all environments do. The \code{proto}
+#' function creates and modifies objects of the \code{proto} class. It (1)
+#' sets the parent of codeenvir to \code{parent}, (2) evaluates \code{expr} in
+#' the \code{envir} environment and (3) lazily evaluates the arguments in
+#' \code{\dots{}} in the parent environment resetting the environment of any
+#' functions (where the resetting is also done lazily). All such functions are
+#' known as methods and should have the receiver object as their first
+#' argument. Conventionally this is \code{.} (i.e. a dot). Also \code{.that}
+#' and \code{.super} variables are added to the environment \code{envir}.
+#' These point to the object itself and its parent, respectively. Note that
+#' \code{proto} can be used as a method and overridden like any other method.
+#' This allows objects to have object-specific versions of \code{proto}. There
+#' also exist \code{that()} and \code{super()} functions which have the same
+#' purpose as \code{.that} and \code{.super} but do not rely on the
+#' \code{.that} and \code{.super}. \code{.that}, \code{.super}, \code{that()}
+#' and \code{super()} can only be used within methods that have their object as
+#' their environment. In addition \code{that()} and \code{super()} may only be
+#' used within the top level of such methods ( and not within functions within
+#' such methods).
+#'
+#' \code{as.proto} is a generic with methods for environments, proto objects
+#' and lists.
+#'
+#' \code{as.proto.list} copies each component, \code{el}, of the list \code{x}
+#' into the the environment or proto object \code{envir} for which
+#' \code{FUN(el)} is \code{TRUE}. Components whose name begins with a dot,
+#' \code{.}, are not copied unless \code{all.names} is \code{TRUE} (and
+#' \code{FUN(el)} is \code{TRUE}). The result is a proto object whose parent is
+#' \code{parent}. If \code{envir} is omitted a new object is created through a
+#' call to \code{proto} with \code{parent} and \code{\dots{}} as arguments. If
+#' \code{parent} is also omitted then the current environment is the parent.
+#' Note that if \code{parent} is a proto object with its own \code{proto}
+#' method then the \code{proto} method of the parent will override the one
+#' described here in which case the functionality may differ.
+#'
+#' \code{$} can be used to access or set variables and methods in an object.
+#'
+#' When \code{$} is used for getting variables and methods, calls of the form
+#' \code{obj$v} search for v in \code{obj} and if not found search upwards
+#' through the ancestors of \code{obj} until found unless the name \code{v}
+#' begins with two dots \code{..}. In that case no upward search is done.
+#'
+#' If \code{meth} is a function then \code{obj$meth} is an object of class
+#' \code{c("instantiatedProtoMethod", "function")} which is a \code{proto}
+#' method with the first, i.e. proto slot, already filled in. It is normally
+#' used in the context of a call to a method, e.g. \code{obj$meth(x,y)}. There
+#' also exists \code{print.instantiatedProtoMethod} for printing such objects.
+#' Be aware that an instantiated proto method is not the same as a proto
+#' method. An instantiated proto method has its first argument filled (with
+#' the receiver object) whereas the first argument of a proto method does not.
+#' If it is desired to actually return the method as a value not in the context
+#' of a call then use the form \code{obj$with(meth)} or \code{obj[[meth]]}
+#' which are similar to \code{with(obj, meth)} except that the variation using
+#' \code{with} will search through ancestors while \code{[[} will not search
+#' through ancestors). The difference between \code{obj$meth} and
+#' \code{obj$with(meth)} is that in the first case \code{obj} implicitly
+#' provides the first argument to the call so that \code{obj$meth(x,y)} and
+#' \code{obj$with(meth)(obj,x,y)} are equivalent while in the case of
+#' \code{obj$with(meth)} the first argument is not automatically inserted.
+#'
+#' \code{$.proto} also has a multiple argument form. If three or more
+#' arguments are present then they specify the arguments at which the
+#' instantiated method is to be evaluated. In this form the receiver object
+#' must be specified explicitly. This form can be used in situations where the
+#' highest speed is required such as in the inner loops of computations.
+#'
+#' The forms \code{.that$meth} and \code{.super$meth} are special and should
+#' only be used within methods. \code{.that} refers to the object in which the
+#' current method is located and \code{.super} refers to the parent of
+#' \code{.that}. In both cases the receiver object must be specified as the
+#' first argument -- the receiver is not automatically inserted as with other
+#' usages of \code{$}.
+#'
+#' \code{$} can be used to set variables and methods in an object. No ancestors
+#' are searched for the set form of \code{$}. If the variable is the special
+#' variable \code{.super} then not only is the variable set but the object's
+#' parent is set to \code{.super}.
+#'
+#' A \code{with} method is available for \code{proto} objects.
+#'
+#' \code{is.proto(p)} returns TRUE if p is a prototype object.
+#'
+#' \code{str.proto} is provided for inspecting \code{proto} objects.
+#'
+#' @aliases proto as.proto as.proto.environment as.proto.list
+#' as.proto.data.frame as.proto.proto isnot.function is.proto $.proto $<-.proto
+#' with.proto str.proto . this .that that .super super
+#' print.instantiatedProtoMethod
+#' @param . the parent object of the new object. May be a proto object or an
+#' environment.
+#' @param expr a series of statements enclosed in braces that define the
+#' variables and methods of the object. Empty braces, the default, may be used
+#' if there are no variables or methods to add at this time.
+#' @param envir an existing prototype object or environment into which the
+#' variables and methods defined in \code{expr} are placed. If omitted a new
+#' object is created.
+#' @param funEnvir the environment of methods passed via \dots{} are
+#' automatically set to this environment. Normally this argument is omitted,
+#' defaulting to \code{envir}; however, one can specify \code{FALSE} to cause
+#' their environment to not be set or one can specify some other environment or
+#' proto object to which their environment is to be set.
+#' @param x a list.
+#' @param parent a prototype object or environment which is to be used as the
+#' parent of the object. If \code{envir} is specified then its parent is
+#' coerced to \code{parent}.
+#' @param \dots for \code{proto} these are components to be embedded in the new
+#' object. For \code{as.proto.list} these are arguments to pass to
+#' \code{proto} in the case that a new object is created. for \code{$.proto}
+#' the method is evaluated at these arguments.
+#' @return \code{proto} and \code{as.proto} all return proto objects.
+#' @note proto methods can be used with environments but some care must be
+#' taken. Problems can be avoided by always using proto objects in these
+#' cases. This note discusses the pitfalls of using environments for those
+#' cases where such interfacing is needed.
+#'
+#' If \code{e} is an environment then \code{e$x} will only search for \code{x}
+#' in \code{e} and no further whereas if \code{e} were a proto object its
+#' ancestors will be searched as well. For example, if the parent of a
+#' \code{proto} object is an \code{environment} but not itself a \code{proto}
+#' object then \code{.super$x} references in the methods of that object will
+#' only look as far as the parent.
+#'
+#' Also note that the form \code{e$meth(...)} when used with an environment
+#' will not automatically insert \code{e} as the first argument and so
+#' environments can only be used with methods by using the more verbose
+#' \code{e$meth(e, ...)}. Even then it is not exactly equivalent since
+#' \code{meth} will only be looked up in \code{e} but not its ancestors. To get
+#' precise equivalence write the even more verbose \code{with(e, meth)(e,
+#' ...)}.
+#'
+#' If the user has a proto object \code{obj} which is a child of the global
+#' environment and whose methods use \code{.super} then \code{.super} will
+#' refer to an environment, not a proto object (unless the global environment
+#' is coerced to a proto object) and therefore be faced with the search
+#' situation discussed above. One solution is to create an empty root object
+#' between the global environment and \code{obj} as in this diagram \code{Root
+#' <- obj$.super <- proto(.GlobalEnv)} where \code{Root} is the root object.
+#' Now \code{.super} references will reference \code{Root}, which is a proto
+#' object so search will occur as expected. \code{proto} does not provide such
+#' a root object automatically but the user can create one easily, if desired.
+#'
+#' Although not recommended, it possible to coerce the global environment to a
+#' proto object by issuing the command \code{as.proto(.GlobalEnv)}. This will
+#' effectively make the global environment a proto root object but has the
+#' potential to break other software, although the authors have not actually
+#' found any software that it breaks.
+#' @seealso \code{\link{as.list}}, \code{\link{names}},
+#' \code{\link{environment}}
+#' @keywords programming
+#' @examples
+#' oo <- proto(expr = {
+#' x = c(10, 20, 15, 19, 17)
+#' location = function(.) mean(.$x) # 1st arg is object
+#' rms = function(.) sqrt(mean((.$x - .$location())^2))
+#' bias = function(., b) .$x <- .$x + b
+#' })
+#'
+#' debug(oo$with(rms)) # cannot use oo$rms to pass method as a value
+#' undebug(oo$with(rms)) # cannot use oo$rms to pass method as a value
+#'
+#' oo2 <- oo$proto( location = function(.) median(.$x) )
+#' oo2$rms() # note that first argument is omitted.
+#' oo2$ls() # list components of oo2
+#' oo2$as.list() # contents of oo2 as a list
+#' oo2 # oo2 itself
+#' oo2$parent.env() # same
+#' oo2$parent.env()$as.list() # contents of parent of oo2
+#' oo2$print()
+#' oo2$ls()
+#' oo2$str()
+#' oo3 <- oo2
+#' oo2$identical(oo3)
+#' oo2$identical(oo)
+#'
+#' # start off with Root to avoid problem cited in Note
+#' Root <- proto()
+#' oop <- Root$proto(a = 1, incr = function(.) .$a <- .$a+1)
+#' ooc <- oop$proto(a = 3) # ooc is child of oop but with a=3
+#' ooc$incr()
+#' ooc$a # 4
+#'
+#' # same but proto overridden to force a to be specified
+#' oop$proto <- function(., a) { .super$proto(., a=a) }
+#' \dontrun{
+#' ooc2 <- oop$proto() # Error. Argument "a" is missing, with no default.
+#' }
+#' ooc2 <- oop$proto(a = 10)
+#' ooc2$incr()
+#' ooc2$a # 11
+#'
+#' # use of with to eliminate having to write .$a
+#' o2 <- proto(a = 1, incr = function(.) with(., a <- a+1))
+#' o2c <- as.proto(o2$as.list()) # o2c is a clone of o2
+#' o2d <- o2$proto() # o2d is a child of o2
+#' o2$a <- 2
+#' o2c$a # a not changed by assignment in line above
+#' o2d$a # a is changed since a not found in o2d so found in o2
+#'
+#' p <- proto(a = 0, incr = function(., x) .$a <- .$a + x)
+#' pc <- p$proto(a = 100)
+#'
+#' p$incr(7)
+#' p$incr(x=7)
+#' p$a
+#'
+#' @export
+proto <- function(. = parent.env(envir), expr = {},
+ envir = new.env(parent = parent.frame()), ...,
+ funEnvir = envir) {
+ parent.env(envir) <- .
+ envir <- as.proto.environment(envir) # must do this before eval(...)
+ # moved eval after for so that ... always done first
+ # eval(substitute(eval(quote({ expr }))), envir)
+ dots <- list(...); names <- names(dots)
+ for (i in seq_along(dots)) {
+ assign(names[i], dots[[i]], envir = envir)
+ if (!identical(funEnvir, FALSE) && is.function(dots[[i]]))
+ environment(envir[[names[i]]]) <- funEnvir
+ }
+ eval(substitute(eval(quote({
+ expr
+ }))), envir)
+ if (length(dots))
+ as.proto.environment(envir)
+ else
+ envir
+}
+
+#' @export
+#' @rdname proto
+as.proto <- function(x, ...) {
+ UseMethod("as.proto")
+}
+
+#' @export
+#' @rdname proto
+as.proto.environment <- function(x, ...) {
+ assign(".that", x, envir = x)
+ assign(".super", parent.env(x), envir = x)
+ structure(x, class = c("proto", "environment"))
+}
+
+#' @export
+#' @rdname proto
+as.proto.proto <- function(x, ...) {
+ x
+}
+
+#' @param all.names only names not starting with a dot are copied unless
+#' all.names is TRUE.
+#' @param list list whose components are an alternate way to specifying
+#' arguments in place of \code{\dots{}}
+#' @param SELECT a function which given an object returns \code{TRUE} or
+#' \code{FALSE} such that only those for which \code{SELECT} returns
+#' \code{TRUE} are kept in the returned \code{proto} object.
+#' @rdname proto
+#' @export
+as.proto.list <- function(x, envir, parent, all.names = FALSE, ...,
+ funEnvir = envir, SELECT = function(x) TRUE) {
+ if (missing(envir)) {
+ if (missing(parent))
+ parent <- parent.frame()
+ envir <- if (is.proto(parent))
+ parent$proto(...)
+ else
+ proto(parent, ...)
+ }
+ for (s in names(x))
+ if (SELECT(x[[s]])) {
+ assign(s, x[[s]], envir = envir)
+ if (is.function(x[[s]]) && !identical(funEnvir, FALSE))
+ environment(envir[[s]]) <- funEnvir
+ }
+ if (!missing(parent))
+ parent.env(envir) <- parent
+ as.proto.environment(envir) # force refresh of .that and .super
+}
+
+#' @export
+"$<-.proto" <- function(this,s,value) {
+ if (s == ".super")
+ parent.env(this) <- value
+ if (is.function(value))
+ environment(value) <- this
+ this[[as.character(substitute(s))]] <- value
+ this
+}
+
+#' @export
+#' @rdname proto
+is.proto <- function(x) inherits(x, "proto")
+
+#' @export
+"$.proto" <- function(x, name) {
+ inherits <- substr(name, 1, 2) != ".."
+
+ res <- get(name, envir = x, inherits = inherits)
+ if (!is.function(res))
+ return(res)
+
+ if (deparse(substitute(x)) %in% c(".that", ".super"))
+ return(res)
+
+ structure(
+ function(...) res(x, ...),
+ class = "protoMethod",
+ method = res
+ )
+}
+
+#' @export
+print.protoMethod <- function(x, ...) {
+ cat("<ProtoMethod>\n")
+ print(attr(x, "method"), ...)
+}
+
+# modified from Tom Short's original
+#' @export
+str.proto <- function(object, max.level = 1, nest.lev = 0,
+ indent.str = paste(rep.int(" ", max(0, nest.lev + 1)), collapse = ".."),
+ ...) {
+ cat("proto", name.proto(object), "\n")
+ Lines <- utils::capture.output(utils::str(
+ as.list(object), max.level = max.level,
+ nest.lev = nest.lev, ...
+ ))[-1]
+ for (s in Lines)
+ cat(s, "\n")
+ if (is.proto(parent.env(object))) {
+ cat(indent.str, "parent: ", sep = "")
+ utils::str(parent.env(object), nest.lev = nest.lev + 1, ...)
+ }
+}
+
+#' @export
+print.proto <- function(x, ...) {
+ if (!exists("proto_print", envir = x, inherits = TRUE))
+ return(NextMethod())
+
+ x$proto_print(...)
+}
+
diff --git a/README.debian b/README.debian
deleted file mode 100755
index 7589830..0000000
--- a/README.debian
+++ /dev/null
@@ -1,10 +0,0 @@
-The optional graphics features of proto
-require an installed version of Rgraphviz.
-
-To pass R CMD CHECK, the following Debian
-packages are required:
-
-graphviz_dev
-libglib1.2-dev
-
-2005-09-27
\ No newline at end of file
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..e9b0455
--- /dev/null
+++ b/README.md
@@ -0,0 +1,82 @@
+# Proto
+
+[](https://travis-ci.org/hadley/proto)
+[](https://CRAN.R-project.org/package=proto)
+[](https://codecov.io/github/hadley/proto?branch=master)
+
+Proto is an R package that facilitates prototype
+programming, a type of object-oriented programming that
+does not use classes as an atomic concept (but is powerful
+enough to encompass them).
+
+The package is lightweight providing a thin layer on top of
+R environments. Unlike other packages which grow over time
+proto has become smaller over time as it was successively
+polished to reduce it to its essentials. Despite its small
+size prototype-based systems can be more powerful than more
+complex class-based systems.
+
+## Ease of use
+
+The proto package is easy to use because:
+
+1. few names. There is only one new function name to learn
+among the core functions. The 'proto' function constructs
+new proto objects. Remaining core functions include various
+as.proto methods, assignment and retrieval via $ and
+is.proto.
+
+2. documentation. A 15 page report, a reference card, a demo
+and help files are provided.
+
+3. consistency. Proto objects form an subclass of the
+environment class. They are and work like environments.
+One can leverage everything one knows about environments
+to use proto. The package is highly consistent with R and
+works the way R works.
+
+4. concise implementation. The source code, excluding
+dot.proto, is about one page of code making it possible to
+rapidly understand it in its entirety not only from the
+documentation but also by reading its source. (This should
+not be necessary but its there for those who wish.)
+
+5. tested. The package has been independently tested by
+multiple people and has no known bugs. (If you find any
+please let the developers know!)
+
+## Example
+
+The proto package is used like this:
+
+```R
+library(proto)
+
+# new object with variable a and method addtwice
+oo <- proto(a = 1, addtwice = function(., x) .$a <- .$a + 2*x)
+
+oo$addtwice(3) # add twice 3 to 1
+oo$ls() # "a" "addtwice"
+oo$a # 7
+
+# create child object overriding a
+ooc <- oo$proto(a = 10)
+
+ooc$addtwice(1) # inherit addtwice from parent oo
+ooc$ls() # "a"
+ooc$a # 12 - addtwice from oo used "a" in ooc!
+```
+
+### Documentation
+
+More information is available via:
+
+```R
+demo(proto) # a self running demo
+
+vignette("proto") # 15 page report
+vignette("protoref") # reference card
+
+?proto # constructs proto objects
+?dot.proto # visualize a proto project
+```
diff --git a/build/vignette.rds b/build/vignette.rds
new file mode 100644
index 0000000..be28909
Binary files /dev/null and b/build/vignette.rds differ
diff --git a/demo/00Index b/demo/00Index
old mode 100755
new mode 100644
index 54b77ef..f8adb09
--- a/demo/00Index
+++ b/demo/00Index
@@ -1,2 +1,2 @@
-proto Using prototype objects with a differential equations analysis.
-proto-vignette code from proto vignette
+proto-gWidgets gWidget example - John Verzani
+proto-vignette code from proto vignette
diff --git a/demo/proto-gWidgets.R b/demo/proto-gWidgets.R
new file mode 100644
index 0000000..9208c3a
--- /dev/null
+++ b/demo/proto-gWidgets.R
@@ -0,0 +1,149 @@
+# John Verzani's gWidgets example found here:
+# http://wiener.math.csi.cuny.edu/pmg/gWidgets/Examples/ProtoExample-II-ex.html
+
+options("guiToolkit" = "RGtk2")
+library(proto)
+library(gWidgets)
+
+BasicGUI = proto(
+ new = function(., message = "Basic GUI", ...) {
+ ## pre proto-0.4-0
+ # .$proto(message=message,
+ # props=list(),widgetList=list(), widgets = list(),...)
+ .$proto(message = message,...)
+ },
+ Show = function(.) {
+ if (is.null(.$window))
+ .$window <- gwindow(.$message)
+ g = ggroup(horizontal = FALSE, cont = .$window)
+ .$makeBody(container = g)
+ .$makeButtons(container = g)
+ },
+ makeBody = function(., container) {
+ glabel(.$message, cont = container)
+ if (length(.$widgetList) > 0) {
+ tbl <- glayout(cont = container)
+ ctr = 1;
+ for (i in names(.$widgetList)) {
+ tmp = .$widgetList[[i]]
+ FUN = tmp[[1]]
+ tmp[[1]] <- NULL
+ tbl[ctr,1] = i
+ tbl[ctr,2] <-
+ (.$widgets[[i]] <- do.call(FUN, c(tmp, container = tbl)))
+ ctr = ctr + 1
+ }
+ visible(tbl) <- TRUE
+ }
+ },
+ makeButtons = function(., container) {
+ gseparator(cont = container)
+ bg = ggroup(cont = container)
+ addSpring(bg)
+ ## for these we take advantage of the fact that when we call
+ ## the handlers this way the "." gets passed in via the first argument
+ cancelButton = gbutton(
+ "cancel", cont = bg,
+ action = list(self = ., super = super()),
+ handler = .$cancelButtonHandler
+ )
+ okButton = gbutton(
+ "ok", cont = bg,
+ action = list(self = ., super = super()),
+ handler = .$okButtonHandler
+ )
+ },
+ ## Notice, the signature includes the initial "."
+ okButtonHandler = function(.,h,...) {
+ for (i in names(.$widgetList)) {
+ ## store vals in props of super
+ # .$.super$props[[i]] <- svalue(.$widgets[[i]]) # pre 0.4-0
+ h$action$super$props[[i]] <- svalue(.$widgets[[i]])
+ }
+ dispose(.$window)
+ },
+ cancelButtonHandler = function(.,h,...) {
+ dispose(.$window)
+ ## others?
+ },
+ window = NULL, # top-level gwindow
+ message = "Basic widget",
+ props = list(), # for storing properties of widgets
+ widgetList = list(),
+ widgets = list()
+)
+
+
+BGTest = BasicGUI$new(
+ message = "Basic Widget Test",
+ widgetList = list(
+ edit = list(type = "gedit",text = "starting text"),
+ droplist = list(type = "gdroplist", items = letters),
+ slider = list(type = "gslider", value = 10),
+ radio = list(
+ type = "gradio", items = 1:3, horizontal = FALSE
+ )
+ )
+)
+## override handler so we don't set values in parent
+BGTest$okButtonHandler = function(.,handler,...) {
+ print(sapply(.$widgets,svalue)) ## or whatever else
+ dispose(.$window)
+}
+BGTest$Show() ## show the widget
+
+Parent = BasicGUI$new(message = "Just a parent, not shown")
+MainChild = Parent$new(
+ message = "Plot a histogram",
+ makeBody = function(., container) {
+ glabel("Plot a histogram of a variable", cont = container)
+ g1 = ggroup(cont = container)
+ tbl = glayout(cont = g1)
+ tbl[1,1] = "numeric vector:"
+ tbl[1,2] <- (.$widgets[[1]] = gedit("", cont = tbl))
+ ## others
+ visible(tbl) <- TRUE # RGtk2
+ ## more button to create child
+ moreButton = gbutton(
+ "Labels",cont = g1,
+ # action = .$.super, # pass in super
+ action = list(self = .,super = parent.env(.)), # pass in super
+ handler = function(h,...) {
+ ## make a child of the Parent. This uses
+ ## the plain BasicGUI style where we specify a
+ ## widget list to produce the GUI.
+ child <-
+ h$action$super$proto(
+ window = gwindow("Adjust plot labels"),
+ message = "Plot labels",
+ widgetList = list(
+ "main" = list(type = "gedit",
+ text = "main title"),
+ "xlab" = list(type = "gedit",
+ text = "xlab")
+ )
+ )
+ child$Show()
+ ## Could add other buttons here for other variables.
+ }
+ )
+ },
+ ## Override the default ok button handler. In this case to
+ ## gather arguments and then plot the histogram.
+ okButtonHandler = function(.,h,...) {
+ lst = list(x = svalue(svalue(.$widgets[[1]]))) ## get values from var name
+ # lst = c(lst, .$.super$props)
+ lst = c(lst, h$action$super$props)
+ do.call("hist",lst)
+ dispose(.$window)
+ }
+
+)
+
+## add defaults
+Parent$props$main = "Main title"
+Parent$props$xlab = "xlab"
+
+
+## Now show the parent
+MainChild$Show()
diff --git a/demo/proto-vignette.R b/demo/proto-vignette.R
old mode 100755
new mode 100644
index 93165c8..2e7803e
--- a/demo/proto-vignette.R
+++ b/demo/proto-vignette.R
@@ -1,200 +1,196 @@
-
-# code from proto vignette
-
-library(proto)
-
-addProto <- proto( x = rnorm(5), add = function(.) sum(.$x) )
-addProto$add()
-addProto2 <- addProto$proto( x = 1:5 )
-addProto2$add()
-
-addProto2$y <- seq(2,10,2)
-addProto2$x <- 1:10
-addProto2$add3 <- function(., z) sum(.$x) + sum(.$y) + sum(z)
-addProto2$add()
-addProto2$add3(c(2,3,5))
-addProto2$y
-
-# addProto2$add <- function(.) .super$add(.) + sum(.$y)
-addProto2$add <- function(.) parent.env(addProto2)$add(.) + sum(.$y)
-
-addProto2a <- addProto$proto(x = 1:5)
-addProto2a$add()
-
-Add <- proto(
- add = function(.) sum(.$x),
- new = function(., x) .$proto(x=x)
-)
-add1 <- Add$new(x = 1:5)
-add1$add()
-add2 <- Add$new(x = 1:10)
-add2$add()
-
-Logadd <- Add$proto( logadd = function(.) log( .$add() ) )
-logadd1 <- Logadd$new(1:5)
-logadd1$logadd()
-
-addProto$ls()
-
-addProto$str()
-addProto$print()
-addProto$as.list()
-addProto2a$parent.env()
-
-addProto$eapply(length) # show length of each component
-
-addProto$identical(addProto2)
-
-library(Rgraphviz)
-g <- graph.proto()
-plot(g)
-
-oo <- proto(expr = {
- x <- rnorm(251, 0, 0.15)
- x <- filter(x, c(1.2, -0.05, -0.18), method = "recursive")
- x <- unclass(x[-seq(100)]) * 2 + 20
- tt <- seq(12200, length = length(x))
- ..x.smooth <- NA
- xlab <- "Time (days)"
- ylab <- "Temp (deg C)"
- pch <- "."
- col <- rep("black",2)
- smooth <- function(., ...) {
- .$..x.smooth <- supsmu(.$tt, .$x, ...)$y
- }
- plot <- function(.) with(., {
- graphics::plot(tt, x, pch = pch, xlab = xlab,
- ylab = ylab, col = col[1])
- if (!is.na(..x.smooth[1]))
- lines(tt, ..x.smooth, col=col[2])
- })
- residuals <- function(.) with(., {
- data.frame(t = tt, y = x - ..x.smooth)
- })
- })
-
-## inspect the object
-oo
-oo$ls(all.names = TRUE)
-oo$pch
-
-par(mfrow=c(1,2))
-# oo$plot()
-## set a slot
-oo$pch <- 20
-## smooth curve and plot
-oo$smooth()
-oo$plot()
-## plot and analyse residuals, stored in the object
-plot(oo$residuals(), type="l")
-# hist(oo$residuals()$y)
-# acf(oo$residuals()$y)
-oo.res <- oo$proto( pch = "-", x = oo$residuals()$y,
- ylab = "Residuals deg K" )
-
-par(mfrow=c(1,1))
-oo.res$smooth()
-oo.res$plot()
-
-## change date format of the parent
-oo$tt <- oo$tt + as.Date("1970-01-01")
-oo$xlab <- format(oo.res$tt[1], "%Y")
-## change colors
-oo$col <- c("blue", "red")
-
-oo$splot <- function(., ...) {
- .$smooth(...)
- .$plot()
-}
-
-## the new function is now available to all children of oo
-par(mfrow=c(1,2))
-oo$splot(bass=2)
-oo.res$splot()
-
-
-## and at last we change the data and repeat the analysis
-oos <- oo$proto( expr = {
- tt <- seq(0,4*pi, length=1000)
- x <- sin(tt) + rnorm(tt, 0, .2)
-})
-oos$splot()
-#plot(oos$residuals())
-
-oos.res <- as.proto( oo.res$as.list(), parent = oos )
-oos.res$x <- oos$residuals()$y
-oos.res$splot()
-
-par(mfrow=c(1,2))
-oos$splot()
-oos.res$splot()
-
-
-longley.ci <- proto( expr = {
- data(longley)
- x <- longley[,c("GNP", "Unemployed")]
- n <- nrow(x)
- pp <- c(.025, .975)
-
- corx <- cor(x)[1,2]
- ci <- function(.)
- (.$CI <- tanh( atanh(.$corx) + qnorm(.$pp)/sqrt(.$n-3) ))
-})
-
-
-longley.ci.boot <- longley.ci$proto({
- N <- 1000
- ci <- function(.) {
- corx <- function(idx) cor(.$x[idx,])[1,2]
- samp <- replicate(.$N, corx(sample(.$n, replace = TRUE)))
- (.$CI <- quantile(samp, .$pp))
- }
-})
-
-longley.ci$ci()
-longley.ci.boot$ci()
-longley.ci.boot$proto(N=4000)$ci()
-
-# do not need left <- right <- NULL anymore in leaf
-# also eliminated right <- NULL in parent
-tree <- proto(expr = {
- incr <- function(., val) .$value <- .$value + val
- ..Name <- "root"
- value <- 3
- ..left <- proto( expr = { ..Name = "leaf" })
-})
-
-cat("root:", tree$value, "leaf:", tree$..left$value, "\n")
-
-# incrementing root increments leaf too
-tree$incr(1)
-cat("root:", tree$value, "leaf:", tree$..left$value, "\n")
-
-
-# incrementing leaf gives it its own value field
-# so now incrementing root does not increment leaf
-tree$..left$incr(10)
-cat("root:", tree$value, "leaf:", tree$..left$value, "\n")
-tree$incr(5)
-cat("root:", tree$value, "leaf:", tree$..left$value, "\n")
-
-lineq <- proto(eq = "6*x + 12 - 10*x/4 = 2*x",
- solve = function(.) {
- e <- eval(parse(text=paste(sub("=", "-(", .$eq), ")")), list(x = 1i))
- -Re(e)/Im(e)
- },
- print = function(.) cat("Equation:", .$eq, "Solution:", .$solve(), "\n")
-)
-lineq$print()
-
-lineq2 <- lineq$proto(eq = "2*x = 7*x-12+x")
-lineq2$print()
-
-Lineq <- lineq
-rm(eq, envir = Lineq)
-Lineq$new <- function(., eq) proto(., eq = eq)
-
-lineq3 <- Lineq$new("3*x=6")
-lineq3$print()
-
-
+
+# code from proto vignette
+
+library(proto)
+
+addProto <- proto( x = rnorm(5), add = function(.) sum(.$x) )
+addProto$add()
+addProto2 <- addProto$proto( x = 1:5 )
+addProto2$add()
+
+addProto2$y <- seq(2,10,2)
+addProto2$x <- 1:10
+addProto2$add3 <- function(., z) sum(.$x) + sum(.$y) + sum(z)
+addProto2$add()
+addProto2$add3(c(2,3,5))
+addProto2$y
+
+# addProto2$add <- function(.) .super$add(.) + sum(.$y)
+addProto2$add <- function(.) parent.env(addProto2)$add(.) + sum(.$y)
+
+addProto2a <- addProto$proto(x = 1:5)
+addProto2a$add()
+
+Add <- proto(
+ add = function(.) sum(.$x),
+ new = function(., x) .$proto(x=x)
+)
+add1 <- Add$new(x = 1:5)
+add1$add()
+add2 <- Add$new(x = 1:10)
+add2$add()
+
+Logadd <- Add$proto( logadd = function(.) log( .$add() ) )
+logadd1 <- Logadd$new(1:5)
+logadd1$logadd()
+
+addProto$ls()
+
+addProto$str()
+addProto$print()
+addProto$as.list()
+addProto2a$parent.env()
+
+addProto$eapply(length) # show length of each component
+
+addProto$identical(addProto2)
+
+oo <- proto(expr = {
+ x <- rnorm(251, 0, 0.15)
+ x <- filter(x, c(1.2, -0.05, -0.18), method = "recursive")
+ x <- unclass(x[-seq(100)]) * 2 + 20
+ tt <- seq(12200, length = length(x))
+ ..x.smooth <- NA
+ xlab <- "Time (days)"
+ ylab <- "Temp (deg C)"
+ pch <- "."
+ col <- rep("black",2)
+ smooth <- function(., ...) {
+ .$..x.smooth <- supsmu(.$tt, .$x, ...)$y
+ }
+ plot <- function(.) with(., {
+ graphics::plot(tt, x, pch = pch, xlab = xlab,
+ ylab = ylab, col = col[1])
+ if (!is.na(..x.smooth[1]))
+ lines(tt, ..x.smooth, col=col[2])
+ })
+ residuals <- function(.) with(., {
+ data.frame(t = tt, y = x - ..x.smooth)
+ })
+ })
+
+## inspect the object
+oo
+oo$ls(all.names = TRUE)
+oo$pch
+
+par(mfrow=c(1,2))
+# oo$plot()
+## set a slot
+oo$pch <- 20
+## smooth curve and plot
+oo$smooth()
+oo$plot()
+## plot and analyse residuals, stored in the object
+plot(oo$residuals(), type="l")
+# hist(oo$residuals()$y)
+# acf(oo$residuals()$y)
+oo.res <- oo$proto( pch = "-", x = oo$residuals()$y,
+ ylab = "Residuals deg K" )
+
+par(mfrow=c(1,1))
+oo.res$smooth()
+oo.res$plot()
+
+## change date format of the parent
+oo$tt <- oo$tt + as.Date("1970-01-01")
+oo$xlab <- format(oo.res$tt[1], "%Y")
+## change colors
+oo$col <- c("blue", "red")
+
+oo$splot <- function(., ...) {
+ .$smooth(...)
+ .$plot()
+}
+
+## the new function is now available to all children of oo
+par(mfrow=c(1,2))
+oo$splot(bass=2)
+oo.res$splot()
+
+
+## and at last we change the data and repeat the analysis
+oos <- oo$proto( expr = {
+ tt <- seq(0,4*pi, length=1000)
+ x <- sin(tt) + rnorm(tt, 0, .2)
+})
+oos$splot()
+#plot(oos$residuals())
+
+oos.res <- as.proto( oo.res$as.list(), parent = oos )
+oos.res$x <- oos$residuals()$y
+oos.res$splot()
+
+par(mfrow=c(1,2))
+oos$splot()
+oos.res$splot()
+
+
+longley.ci <- proto( expr = {
+ data(longley)
+ x <- longley[,c("GNP", "Unemployed")]
+ n <- nrow(x)
+ pp <- c(.025, .975)
+
+ corx <- cor(x)[1,2]
+ ci <- function(.)
+ (.$CI <- tanh( atanh(.$corx) + qnorm(.$pp)/sqrt(.$n-3) ))
+})
+
+
+longley.ci.boot <- longley.ci$proto({
+ N <- 1000
+ ci <- function(.) {
+ corx <- function(idx) cor(.$x[idx,])[1,2]
+ samp <- replicate(.$N, corx(sample(.$n, replace = TRUE)))
+ (.$CI <- quantile(samp, .$pp))
+ }
+})
+
+longley.ci$ci()
+longley.ci.boot$ci()
+longley.ci.boot$proto(N=4000)$ci()
+
+# do not need left <- right <- NULL anymore in leaf
+# also eliminated right <- NULL in parent
+tree <- proto(expr = {
+ incr <- function(., val) .$value <- .$value + val
+ ..Name <- "root"
+ value <- 3
+ ..left <- proto( expr = { ..Name = "leaf" })
+})
+
+cat("root:", tree$value, "leaf:", tree$..left$value, "\n")
+
+# incrementing root increments leaf too
+tree$incr(1)
+cat("root:", tree$value, "leaf:", tree$..left$value, "\n")
+
+
+# incrementing leaf gives it its own value field
+# so now incrementing root does not increment leaf
+tree$..left$incr(10)
+cat("root:", tree$value, "leaf:", tree$..left$value, "\n")
+tree$incr(5)
+cat("root:", tree$value, "leaf:", tree$..left$value, "\n")
+
+lineq <- proto(eq = "6*x + 12 - 10*x/4 = 2*x",
+ solve = function(.) {
+ e <- eval(parse(text=paste(sub("=", "-(", .$eq), ")")), list(x = 1i))
+ -Re(e)/Im(e)
+ },
+ print = function(.) cat("Equation:", .$eq, "Solution:", .$solve(), "\n")
+)
+lineq$print()
+
+lineq2 <- lineq$proto(eq = "2*x = 7*x-12+x")
+lineq2$print()
+
+Lineq <- lineq
+rm(eq, envir = Lineq)
+Lineq$new <- function(., eq) proto(., eq = eq)
+
+lineq3 <- Lineq$new("3*x=6")
+lineq3$print()
+
+
diff --git a/demo/proto.R b/demo/proto.R
deleted file mode 100755
index 8028998..0000000
--- a/demo/proto.R
+++ /dev/null
@@ -1,118 +0,0 @@
-########################################################################
-## DEMO: ecological model applications have common properties,
-## that belong together:
-## - equations
-## - constant parameters
-## - initial values of the state variables
-## - time steps
-## - an adequate solver, and
-## - utility functions
-########################################################################
-
-# if (dev.cur() <= 1) get(getOption("device"))()
-
-opar <- par(ask = interactive() &&
- (.Device %in% c("X11", "GTK", "gnome", "windows","quartz")))
-
-if (require(odesolve)) {
-
- library(odesolve)
- library(proto)
-
- ## object creation from scratch (ex-nihilo)
- lv <- proto(expr = {
- equations <- function(t, x, p) {
- dx1.dt <- p["k1"] * x[1] - p["k2"] * x[1] * x[2]
- dx2.dt <- - p["k3"] * x[2] + p["k2"] * x[1] * x[2]
- list(c(dx1.dt, dx2.dt))
- }
- # vectors of parameters, timesteps and initial values
- parms <- c(k1=0.2, k2=0.2, k3=0.2)
- times <- 1:100
- init <- c(prey=0.5, predator=1)
- # two methods
- solve <- function(.) {
- # must use .$with(equations) instead of .$equations
- # as latter can only be used in a call
- equations <- .$with(equations)
- res <- as.data.frame(rk4(.$init, .$times, equations, .$parms))
- }
- plot <- function(.) {
- res <- .$solve()
-
- graphics::plot(res$time, res$predator, col = "red",
- type = "b", pch = 20)
- graphics::plot(res$time, res$prey, col = "green",
- type = "b", pch = 20)
- }
- })
-
- ## the created object is fully functional
- par(mfrow=c(2,1))
- res <- lv$solve()
- plot(res)
- lv$plot()
-
- ## derive a child object with a different ODE solver
- lv.lsoda <- lv$proto(
- solve <- function(.) {
- equations <- .$with(equations)
- res <- lsoda(.$init, .$times, equations, .$parms)
- as.data.frame(res)
- }
- )
-
- ## test this child object
- lv.lsoda$plot()
-
- ### derive two scenarios
-
- ## scenario 1 with initial values, that are in equilibrium
- sc1 <- lv.lsoda$proto(init <- c(prey=1, predator=1))
-
- ## scenario 2, similar to scenario 1, but with different parameters
- sc2 <- sc1$proto(parms <- c(k1=0.3, k2=0.2, k3=0.2))
-
- ## solve, plot, compare these scenarios
- par(mfrow=c(2,2))
- sc1$plot()
- sc2$plot()
-
- ## and as a last example, we modify parameters of the parent
- lv$times <- seq(0, 100, 0.1)
-
- sc1$main <- "Scenario 1"
- sc2$main <- "Scenario 2"
- lv$plot <- function(.) {
- res <- .$solve()
-
- graphics::plot(res$time, res$predator, col = "red",
- type = "l", pch = 20, main=.$main)
- graphics::plot(res$time, res$prey, col = "green",
- type = "l", pch = 20, main=.$main)
- }
-
- par(mfrow=c(2,2))
-
- sc1$plot()
- sc2$plot()
-
- ## fragile base object: the folowing would give an error
- # lv$plot()
-
- ## but it works if we add the required main title
- lv$main <- "Reference"
- lv$plot()
-
- ## show the object relationships
- g <- graph.proto()
- plot(g)
-
- ## Conclusion:
- ## - the responsibility is due to the user, but
- ## - prototypes allow oop without overhead
-
-}
-
-par(opar)
-
diff --git a/inst/FAQ b/inst/FAQ
old mode 100755
new mode 100644
diff --git a/inst/NEWS b/inst/NEWS
deleted file mode 100755
index d6ac92b..0000000
--- a/inst/NEWS
+++ /dev/null
@@ -1,143 +0,0 @@
-
-VERSION 0.3-10
-
-o added NAMESPACE file
-
-o removed junk files
-
-VERSION 0.3-9.2
-
-o fixed bug in print.instantiatedProtoMethod
-
-VERSION 0.3-9.1
-
-o minor change to pass R CMD CHECK
-
-o removed one file that was not relevant to this version of proto
-
-VERSION 0.3-9
-
-o minor changes to satisfy subtitute/eval changes in R 2.13.0 (thanks to
- Luke Tierney)
-
-o x could previously not be the name of a proto object. Now fixed.
-
-o proto print methods could break str.proto. Now fixed.
-
-VERSION 0.3-8
-
-o minor changes to satisfy R 2.6.0
-
-VERSION 0.3-7
-
-o FAQ added as Appendix A of vignette
-
-o str.proto added (modified code of Tom Short)
-
-o the class of p$fun is now "instantiatedProtoMethod" and
- print.instantiatedProtoMethod provided (modified code of Tom Short)
-
-o "$.proto" now has a third argument which, if present, is a list of
- arguments at which to evaluate the instantiated method. Intended for
- use within sapply/lapply/etc. See examples in ?proto .
-
-o modified DESCRIPTION to point to new home page
-
-VERSION 0.3-6
-
-o order of arguments in proto and as.proto.list changed to
- address a bug
-
-VERSION 0.3-5
-
-o new arg funEnvir= on proto and as.proto.list [experimental]
-
-o new arg SELECT= on as.proto [experimental]
-
-VERSION 0.3-4
-
-o new function graph.proto using Rgraphviz replaces dot.proto
-
-o updated vignettes
-
-o added proto-package.Rd (viewable via package?proto)
-
-VERSION 0.3-3
-
-o updated NEWS, README, WISHLIST and moved to to inst directory
-
-VERSION 0.3-2
-
-o bug fix (recursion bug)
-
-o documentation improvements (vignette, .Rd files, README)
-
-VERSION 0.3-1
-
-o .Rd file improvements
-
-VERSION 0.3-0
-
-o that/super changed to .that/.super.
-
-o .Name changed to ..Name in dot.proto
-
-o improvements to .Rd files and vignette
-
-VERSION 0.2-6
-
-o demo index file fixed and demo renamed and enhanced
-
-o proto.bib updated
-
-o consistent use of obj$with(meth) in examples and demo where method
- not used in the context of a call
-
-VERSION 0.2-5
-
-o vignette and reference card now pass R CMD check/build/install
-
-o CHANGES renamed to NEWS
-
-VERSION 0.2-4
-
-o added control argument to dot.proto
-
-VERSION 0.2-3
-
-o added reference card
-
-o modified demo, .Rd files and vignette to correspond to new interface
-
-o changed argument list for proto and eliminated delegate
-
-o created as.proto.list and eliminated copy.proto
-
-o fixed bug in proto. Parent was not always set correctly.
-
-o added ... argument to copy.proto
-
-o added the isnot.function support function for use with copy.proto
-
-o cleaned up $.proto code for handling .. names.
-
-o the on-the-fly wrapper function generated by obj$meth now has the
- current environment as its environment.
-
-o proto no longer coerces its parent to a proto object. See note
- at end of proto.Rd.
-
-o added .. name processing and updated .Rd file
-
-o dot.proto now accepts names with dots in them
-
-o added delegate and copy.proto commands and updated .Rd file
-
-VERSION 0.2-2
-
-o added .. name processing and updated .Rd file
-
-o dot.proto now accepts names with dots in them
-
-o added delegate and copy.proto commands and updated .Rd file
-
diff --git a/inst/README b/inst/README
deleted file mode 100755
index b0f5543..0000000
--- a/inst/README
+++ /dev/null
@@ -1,100 +0,0 @@
-
-Proto is an R package that facilitates prototype
-programming, a type of object-oriented programming that
-does not use classes as an atomic concept (but is powerful
-enough to encompass them).
-
-The package has been in development for over a year and on
-CRAN since the beginning of 2005.
-
-The package is lightweight providing a thin layer on top of
-R environments. Unlike other packages which grow over time
-proto has become smaller over time as it was successively
-polished to reduce it to its essentials. Despite its small
-size prototype-based systems can be more powerful than more
-complex class-based systems.
-
-EASE OF USE
-
-The proto package is easy to use because:
-
-1. few names. There is only one new function name to learn
-among the core functions. The 'proto' function constructs
-new proto objects. Remaining core functions include various
-as.proto methods, assignment and retrieval via $ and
-is.proto.
-
-2. documentation. A 15 page report, a reference card, a demo
-and help files are provided.
-
-3. consistency. Proto objects form an subclass of the
-environment class. They are and work like environments.
-One can leverage everything one knows about environments
-to use proto. The package is highly consistent with R and
-works the way R works.
-
-4. concise implementation. The source code, excluding
-dot.proto, is about one page of code making it possible to
-rapidly understand it in its entirety not only from the
-documentation but also by reading its source. (This should
-not be necessary but its there for those who wish.)
-
-5. tested. The package has been independently tested by
-multiple people and has no known bugs. (If you find any
-please let the developers know!)
-
-6. visualization. It includes a graphical support function,
-graph.proto, which produces inheritance graphs of projects
-that can be rendered using the Rgraphviz plot function,
-allowing one to visualize projects.
-
-EXAMPLE
-
-The proto package is used like this:
-
- library(proto)
-
- # new object with variable a and method addtwice
- oo <- proto(a = 1, addtwice = function(., x) .$a <- .$a + 2*x)
-
- oo$addtwice(3) # add twice 3 to 1
- oo$ls() # "a" "addtwice"
- oo$a # 7
-
- # create child object overriding a
- ooc <- oo$proto(a = 10)
-
- ooc$addtwice(1) # inherit addtwice from parent oo
- ooc$ls() # "a"
- ooc$a # 12 - addtwice from oo used "a" in ooc!
-
-DOCUMENTATION
-
-More information is available via:
-
- install.packages("proto") # needs R 2.1.0 or later
- library(proto)
-
- demo(proto) # a self running demo
-
- vignette("proto") # 15 page report
- vignette("protoref") # reference card
-
- ?proto # constructs proto objects
- ?dot.proto # visualize a proto project
-
- # other information
- file.show(system.file("NEWS", package = "proto"))
- file.show(system.file("README", package = "proto")) # this file
- file.show(system.file("WISHLIST", package = "proto"))
-
-proto is available on CRAN now for R 2.1.0 and later.
-
-Comments are welcome.
-
-Louis Kates <lkates at alumni.princeton.edu>
-Thomas Petzoldt <thomas.petzoldt at tu-dresden.de>
-
-September 9, 2005 (updated)
-May 12, 2005
-
diff --git a/inst/ReleaseNotes.txt b/inst/ReleaseNotes.txt
new file mode 100644
index 0000000..efa4c2d
--- /dev/null
+++ b/inst/ReleaseNotes.txt
@@ -0,0 +1,178 @@
+
+Guide to version 0.4-0 of proto
+
+1. Lazy Evaluation
+
+The proto function now evaluates its ... argument lazily.
+This together with a lazy cloning routine, clone, allows the
+user to use a proto object as a template for other objects.
+
+For example, in the code below
+- gwindow is the gWidgets function to create a new window and
+- gbutton is the function to create a button in indicated container.
+
+We create a proto object p which defines
+- a container, container, embodying a new window and
+- a method, go, which places a button in it.
+
+We clone p to create q before we run p$go() so that q
+gets its own promise and that will result in p$go()
+and q$go() creating different windows.
+
+ library(proto)
+ library(gWidgets)
+
+ p <- proto(go = function(.) gbutton(.$msg, cont = .$container),
+ msg = "Hello", container = gwindow()) # now its lazy
+ q <- p$clone() # promises copied, not forced
+ p$go()
+ q$go()
+
+Had the statements been run in the following order, i.e. q
+is defined after p$go is run, then clone would have copied
+the actual container and not a promise to it so q would try
+to place its button in the same container as p giving an
+error.
+
+ p <- proto(go = function(.) gbutton(.$msg, cont = .$container),
+ msg = "Hello", container = gwindow()) # now its lazy
+ p$go()
+ q <- p$clone() # promises copied, not forced
+ q$go() # ERROR !!!
+
+Here is an example that does not make use of any additional
+R packages. It also appears in example(proto) . Note the
+difference between the following two code snippets which
+differ only in the order of the statements:
+
+ # q is cloned before promises in p are forced
+ p <- proto(append = function(., x) .$L[[x]] <- x, L = proto())
+ q <- p$clone()
+ p$append("A")
+ as.list(p$L)
+ q$append("B")
+ as.list(q$L)
+
+ # promises in p are forced before q is cloned
+ p <- proto(append = function(., x) .$L[[x]] <- x, L = proto())
+ p$append("C")
+ as.list(p$L)
+ q <- p$clone()
+ q$append("D")
+ as.list(q$L)
+
+2. as.list.environment
+
+This is a workaround to handle the a bug in R's version of
+this command. R will not evaluate promises when converting
+an environment to a list and this can cause subsequent
+problems. The implementation in proto works around this
+problem in R.
+
+3. $.proto
+
+If p is a proto object and meth is a method in it then
+p$meth(myArg) first runs p$meth creating an instantiated
+proto object. Previously this was a call to meth with p
+inserted as its first argument. This has been changed so
+that the keyword receiver is inserted as its first argument
+and reciever is given a default value of p so that by
+default it works the same as before; however, it is possible
+to specify a different value for receiver like this:
+
+ p$meth(receiver = q, myArg)
+
+in which case the meth found in p (or an ancestor) is run
+using q as the receiver object and myArg as an argument.
+Note that
+
+ p$meth(myArg)
+ p$meth(receiver = p, myArg)
+
+are the same.
+
+4. super() and that()
+
+Previously .that and .super were built in variables that
+could be used in methods to refer to the object the method
+is defined in and its parent respectively. These variables
+were stored in every proto object and if a method had that
+object as its environment then it could access them to find
+out what object it belongs to and to easily refer to its
+object's parent.
+
+Unfortunately this polluted every proto object with .that and
+.super variables. To clean this up we have defined that()
+and super() functions which simply return the environment of
+the method they are defined in and its parent respectively
+so that .that and .super are no longer needed.
+
+Also there were special rules in $.proto so .that$meth would
+not automatically insert .that into the resulting function
+and similarly for .super. For compatibility .that and
+.super continue to exist and the special rule continues to
+be supported; however, for that() and super() no special
+processing is done. Given the existence of receiver its not
+needed. Thus:
+
+ .that$meth(p, myArgs)
+ that()$meth(receiver = p, myArgs)
+
+are the same. Both .that/.super and that()/super()
+currently exist but in an upcoming version of proto
+.that/.super will be eliminated so users should take the
+time to switch over.
+
+Note that .that and .super would continue to work within a
+function within a method but that() and super() do not. On
+the other hand its quite easy to work around it:
+
+ p <- function(.) {
+ f <- function() .that
+ x <- f()
+ }
+
+is the same as (we just added the first line and changed
+.that to that):
+
+ p <- function(.) {
+ that <- that()
+ f <- function() that
+ x <- f()
+ }
+
+Looking over a large amount of proto code we found very
+little of it uses .that or .super so the elimination of
+these variables in every proto object seems like a
+worthwhile benefit compared to the minor change in syntax
+required in a small number of routines.
+
+5. There are several new demos. To see them try this:
+
+ demo(package = proto)
+
+One of these demos is from John Verzani who developed the
+gWidgets package. For more proto examples with gWidgets see
+the links on the proto home page to his other examples.
+
+6. instantiatedProtoMethod
+
+This feature has been in proto for a while. It was
+developed based on the original by Tom Short. p$meth
+creates an object of class "instantiatedProtoMethod" which
+has its own print method.
+
+7. Examples
+
+There are some gWidget examples from John Verzani that specifically take
+advantage of proto 0.4-0 features here:
+http://wiener.math.csi.cuny.edu/pmg/gWidgets/Examples/ProtoExample-II-ex.pdf
+
+8. DESCRIPTION
+
+Packages that have proto objects at the top level should use
+"LazyLoad: false" in their DESCRIPTION file. (Alternately
+"SaveImage: true" works although it has been deprecated in R. Also
+note that omitting the LazyLoad: line means that R will choose
+a default action and so is NOT equivalent to "LazyLoad: false".)
+
diff --git a/inst/THANKS b/inst/THANKS
old mode 100755
new mode 100644
index 53b85b0..ab7e451
--- a/inst/THANKS
+++ b/inst/THANKS
@@ -6,6 +6,6 @@ Thanks to John Verzani for helpful conversations regarding lazy
evaluation.
Thanks to Luke Tierney for helpful conversations regarding
-lazy evaluation and promises in R and fixes for R 2.13.
+lazy evaluation and promises in R.
Thanks to Matthias Burger for providing full argument patch.
diff --git a/inst/WISHLIST b/inst/WISHLIST
old mode 100755
new mode 100644
diff --git a/inst/doc/proto.Rnw b/inst/doc/proto.Rnw
old mode 100755
new mode 100644
index 47316a9..f5ba084
--- a/inst/doc/proto.Rnw
+++ b/inst/doc/proto.Rnw
@@ -1,22 +1,1358 @@
-% To build the vignette:
-% 1. run Sweave("proto-raw") to create proto-raw.tex
-% 2. build as usual using Rcmd build proto
-%
-% To build vignette manually:
-% 1. Sweave("proto-raw") to create proto-raw.tex
-% 2. Sweave("proto.Rnw")
-% 3. pdflatex proto.tex
-%
-% To build manually using sweave.bat using batchfiles on Windows:
-% 1. sweave proto-raw --tex
-% 2. sweave proto
-
-\SweaveOpts{engine=R,eps=FALSE}
-
-%\VignetteIndexEntry{proto: An R Package for Prototype Programming}
-%\VignetteDepends{}
-%\VignetteKeywords{object oriented, prototype programming, S3, R}
-%\VignettePackage{proto}
-
-\input{proto-raw}
-
+%\VignetteIndexEntry{proto: An R Package for Prototype Programming}
+%\VignetteDepends{}
+%\VignetteKeywords{object oriented, prototype programming, S3, R}
+%\VignettePackage{proto}
+
+\documentclass[nojss]{jss}
+\usepackage{Sweave}
+\DeclareGraphicsExtensions{.pdf, .eps, .png}
+
+\newlength{\half}
+\setlength{\half}{70mm}
+
+\author{Louis Kates\\GKX Associates Inc. \And
+ Thomas Petzoldt\\Technische Universit\"at Dresden}
+\Plainauthor{Louis Kates, Thomas Petzoldt}
+
+\title{\pkg{proto}: An \proglang{R} Package for Prototype Programming}
+%% \Shorttitle{\pkg{proto}: An \proglang{R} Package for Prototype Programming}
+
+\Plaintitle{proto: An R Package for Prototype Programming}
+
+\Keywords{prototype programming, delegation, inheritance, clone,
+ object orientated, \proglang{S3}, \proglang{R}}
+\Plainkeywords{object oriented, prototype programming, S3, R}
+
+\Abstract{
+
+ \pkg{proto} is an \proglang{R} package which facilitates a style
+ of programming known as prototype
+ programming. Prototype programming is a type of object
+ oriented programming in which there are no classes.
+ \pkg{proto} is simple yet retains the object oriented features of
+ delegation (the prototype counterpart to inheritance)
+ and object oriented dispatch. \code{proto} can be used
+ to organize the concrete data and procedures in statistical studies
+ and other applications
+ without the necessity of defining classes while still providing convenient
+ access to an object oriented style of programming. Furthermore, it
+ can be used in a class-based style as well so that incremental design can
+ begin with defining the concrete objects and later transition to abstract
+ classes, once the general case is understood, without having to change to
+ object-oriented frameworks.
+ The key goals of the package are to integrate into \proglang{R}
+ while providing nothing more than a thin layer on top of it.
+}
+
+\hyphenation{ma-ni-pu-lating}
+
+\begin{document}
+\SweaveOpts{concordance=TRUE}
+
+
+
+
+\section{Introduction} \label{sec:intro}
+
+\subsection[Object Oriented Programming in R]{Object Oriented Programming in \proglang{R}}
+\label{sec:oo}
+
+The \proglang{R} system for statistical computing
+\citep[\url{http://www.R-project.org/}]{Rcore2005} ships with two
+systems for object oriented programming referred to as \proglang{S3}
+and \proglang{S4}. With the increased interest in object oriented
+programming within \proglang{R} over the last years additional object
+oriented programming packages emerged. These include the \pkg{R.oo}
+package \citep{Bengtsson2003} and the \pkg{OOP} package
+\citep[\url{http://www.omegahat.net/OOP/}]{Rnews:Chambers+Lang:2001a}.
+All these packages have the common thread that they use
+classes as the basis of inheritance. When a message is sent to an
+object the class of the object is examined and that class determines the
+specific function to be executed. In prototype programming there
+are no classes making it simple yet it retains much of the power of
+class-based programming. In the fact, \pkg{proto} is so simple that
+there is only one significant new routine name, \code{proto}. The
+other routines are just the expected support routines such as
+\code{as.proto} to coerce objects to proto objects, \code{\$} to
+access and set proto object components and \code{is.proto} to check
+whether an object is a proto object. In addition, \code{graph.proto}
+will generate a graphical ancestor tree showing the parent-child
+relationships among generated \code{proto} objects.
+
+The aim of the package is to provide a lightweight layer for prototype
+programming in \proglang{R} written only in \proglang{R} leveraging the
+existing facilities of the language rather than adding its own.
+
+\subsection{History}
+\label{sec:history}
+
+The concept of
+prototype programming
+\citep{Lieberman1986, Taivalsaari1996a, Noble1999}
+has developed over a number of years with the \proglang{Self}
+language \citep{Agesen1992}
+being the key evolved programming language to demonstrate
+the concept. In statistics, the \proglang{Lisp}-based
+\proglang{LispStat} programming language \citep{Tierney1990} was
+the first and possibly only statistical system to feature prototype
+programming.
+
+Despite having been developed over 20 years ago, and some attempts to
+enter the mainstream (e.g. \proglang{Newtonscript}
+on the Newton computer, which
+is no longer available, and \proglang{Javascript} where
+it is available but whose
+domain of application largely precluses use of prototype programming)
+prototype programming is not well known due to lack of language
+support in popular programming languages such as \proglang{C} and
+\proglang{Java}. It tends
+to be the domain of research languages or \proglang{Lisp}.
+
+Thus the
+the availability of a popular language,
+\proglang{R} \footnote{Some indications of the popularity of R are
+the high volume mailing lists, international development team, the
+existence of over 500 addon packages, conferences and numerous books
+and papers devoted to R.},
+that finally does provide the key infrastructure
+is an important development.
+
+This work grew out of the need to organize multiple scenarios of model
+simulations in ecological modelling \citep{Rnews:Petzoldt:2003} and
+was subsequently generalized to the present package. A number of
+iterations of the code, some motivated by the ever increasing feature
+set in \proglang{R}, resulted in a series of utilities and ultimately
+successive versions of an \proglang{R} package developed over the last
+year. An initial version used \proglang{R} lists as the basis of the
+package. Subsequently the package was changed to use \proglang{R}
+environments. The first version to use environments stored the
+receiver object variable in a proxy parent environment which was
+created on-the-fly at each method call. The present version of
+the \pkg{proto} package passes the receiver object through the argument list,
+while hiding this from the caller. It defines the \code{proto} class
+as a subclass of the \code{environment} class so that
+functionality built into \proglang{R} for the environment class is
+automatically inherited by the \code{proto} class.
+
+\subsection{Overview}
+\label{sec:overview}
+
+It is assumed that the reader has some general
+familiarity with object oriented programming concepts and with
+\proglang{R}.
+
+The paper will proceed primarily by example focusing on illustrating
+the package \code{proto} through such demonstration. The remainder of
+the paper is organized as follows: Section~\ref{sec:proto-class}
+explains how \code{"proto"} objects are created and illustrates the
+corresponding methods for setting and getting components. It further
+discusses how object oriented delegation (the prototype programming
+analogue of inheritance) is handled and finally discusses the
+internals of the package. This section uses small examples chosen for
+their simplicity in illustrating the concepts. In
+Section~\ref{sec:examples} we provide additional examples of prototype
+programming in action. Four examples are shown. The first involves
+smoothing of data. Secondly we demonstrate the calculation of
+correlation confidence intervals using classical (Fisher Transform)
+and modern (bootstrapping) methods. Thirdly we demonstrate the
+development of a binary tree as would be required for a dendrogram.
+Fourthly, we use the solution of linear equations to illustrate
+program evolution from object-based to class-based, all
+within the \pkg{proto} framework.
+Section~\ref{sec:summary} gives a few summarizing remarks. Finally,
+an appendix provides a reference card that summarizes the
+functionality contained in \pkg{proto} in terms of its constituent
+commands.
+
+%% \pagebreak[4]
+
+\section[The class "proto" and its methods]{The class \code{"proto"} and its methods}
+\label{sec:proto-class}
+
+\subsection[Creation of "proto" objects]{Creation of \code{"proto"} objects}
+\label{sec:proto}
+
+In this section we shall show, by example, the creation of two
+prototype objects and related operations. The simple idea is that
+each \code{"proto"} object is a set of components: functions (methods)
+and variables, which are tightly related in some way.
+
+A prototype object is an environment holding the variables and
+methods of the object. \footnote{In particular this implies that
+\code{"proto"} objects have single inheritance, follow ordinary
+environment scoping rules and have mutable state as environments
+do.}
+
+A prototype object is created using the constructor function
+\code{proto} (see Appendix~\ref{sec:ref} at the end of this paper or
+\pkg{proto} package help for complete syntax of commands).
+
+\begin{Scode}
+addProto <- proto( x = rnorm(5), add = function(.) sum(.$x) )
+\end{Scode}
+
+In this simple example, the \code{proto} function defines two
+components: a variable \code{x} and a method \code{add}. The variable
+\code{x} is a vector of 5 numbers and the method sums those numbers.
+The \code{proto} object \code{addProto} contains the variable and the
+method. Thus the \code{addProto} \code{proto} object can be used to compute
+the sum of the values stored in it.
+As shown with the \code{add} method in this example, formal argument
+lists of methods must always have a first argument of dot
+(i.e. \code{.}) which signifies the object on which the method is
+operating. The dot refers to the current object in the same way that
+a dot refers to the current directory in UNIX. Within the method one
+must refer to other variables and methods in the object by prefacing
+each with \code{.\$}. For example, in the above we write
+\code{sum(.\$x)}. Finally, note that the data and the method are very
+closely related. Such close coupling is important in order to create
+an easily maintained system.
+
+To illustrate the usage of \code{proto}, we first load the package and
+set the random seed to make the examples in this paper exactly
+reproducible.
+
+\begin{Schunk}
+\begin{Sinput}
+> library(proto)
+> set.seed(123)
+\end{Sinput}
+\end{Schunk}
+
+Then, we create the \code{proto} object from above
+and call its \code{add} method.
+\begin{Schunk}
+\begin{Sinput}
+> addProto <- proto(x = rnorm(5), add = function(.) sum(.$x))
+> addProto$add()
+\end{Sinput}
+\begin{Soutput}
+[1] 0.9678513
+\end{Soutput}
+\end{Schunk}
+We also create another object, \code{addProto2}
+with a different \code{x} vector and
+invoke its \code{add} method too.
+\begin{Schunk}
+\begin{Sinput}
+> addProto2 <- addProto$proto(x = 1:5)
+> addProto2$add()
+\end{Sinput}
+\begin{Soutput}
+[1] 15
+\end{Soutput}
+\end{Schunk}
+In the examples above, we created a prototype object \code{addProto}
+and then called its \code{add} method as just explained.
+The notation \code{addProto\$add}
+tells the system to look for the \code{add} method
+in the \code{addProto} object. In the expression \code{addProto\$add},
+the \code{proto} object to the left
+of the dollar sign, \code{addProto} here, is referred to as the
+\emph{receiver} object. This expression
+also has a second purpose which is to
+pass the receiver object implicitly as the first argument of \code{add}.
+Note that we called \code{add} as if it had zero arguments but, in fact,
+it has one argument because the receiver is automatically and implicitly
+supplied as the first argument. In general,
+the notation \code{object\$method(arguments)} is
+used to invoke the indicated method of the receiver object using the
+object as the implicit first argument along with the indicated
+arguments as the subsequent arguments.
+As with the \code{addProto} example, the receiver
+object not only determines where to find the
+method but also is implicitly passed to the method through
+the first argument. The motivation for this notation
+is to relieve the user of
+specifying the receiver object twice:
+once to locate the method in the object and a second
+time to pass the object itself to the method.
+The \code{\$} is overloaded by the \code{proto}
+class to automatically do both with one reference to the receiver object.
+Even though, as with the \code{addProto} example, the first
+argument is not listed in the call
+it still must be listed among the formal arguments
+in the definition of the method. It
+is conventional to use
+a dot \code{.} as the first formal argument in the method/function
+definition. That is, we call \code{add} using \code{addProto\$add()}
+displaying zero arguments
+but we define \code{add} in \code{addProto} displaying
+one argument \code{add <- function(.)}, the dot.
+
+In this example,
+we also created a second object, \code{addProto2},
+which has the first object, \code{addProto} as its parent.
+Any reference to a
+component in the second object that is unsuccessful will cause
+search to continue in the parent. Thus the call \code{addProto2\$add()}
+looks for \code{add} in \code{addProto2} and not finding it there
+searches its parent, \code{addProto}, where it is, indeed, found.
+\code{add} is invoked with the receiver object, \code{addProto2}, as
+the value of dot.
+The call \code{addProto2\$add()} actually causes the \code{add}
+in \code{addProto} to run but it still uses the \code{x} from
+\code{addProto2} since dot (\code{.}) is \code{addProto2} here
+and \code{add} references \code{.\$x}.
+Note that the reference to \code{.\$x} in the
+\code{add} found in \code{addProto}
+does not refer to the \code{x} in \code{addProto} itself.
+The \code{x} in \code{addProto2} has overridden the \code{x} in its parent.
+This point is important so the reader should take care to absorb this
+point.
+
+This simple example already shows the key elements of the system
+and how \emph{delegation} (the prototype programming term for inheritance)
+works without classes.
+
+We can add new components or replace components in an object and
+invoke various methods like this:
+\begin{Schunk}
+\begin{Sinput}
+> addProto2$y <- seq(2, 10, 2)
+> addProto2$x <- 1:10
+> addProto2$add3 <- function(., z) sum(.$x) + sum(.$y) + sum(z)
+> addProto2$add()
+\end{Sinput}
+\begin{Soutput}
+[1] 55
+\end{Soutput}
+\begin{Sinput}
+> addProto2$add3(c(2, 3, 5))
+\end{Sinput}
+\begin{Soutput}
+[1] 95
+\end{Soutput}
+\begin{Sinput}
+> addProto2$y
+\end{Sinput}
+\begin{Soutput}
+[1] 2 4 6 8 10
+\end{Soutput}
+\end{Schunk}
+
+In this example, we insert variable \code{y} into the object \code{addProto2}
+with a value of \code{seq(2,10,2)},
+reset variable \code{x} to a new value and insert a new method,
+\code{add3}. Then we invoke
+our two methods and display \code{y}. Again, note that in the case of
+\code{protoAdd2\$add} the \code{add} method is not present in
+\code{protoAdd2} and so search continues to the parent \code{addProto}
+where it is found.
+
+\subsection{Internals}
+\label{sec:internals}
+
+So far, we have used simple examples to illustrate the basic manipulation
+of objects: construction, getting and setting components and method
+invocation. We now discuss the internals of the package and how it relates
+to \proglang{R} constructs.
+\code{proto} is actually an \proglang{S3} class which is a subclass
+of the \code{environment} class. Every \code{proto} object is an
+environment and its class is \code{c("proto", "environment")}. The \code{\$}
+accessor is similar to the same accessor in environments except it will
+use the \proglang{R} \code{get} function to
+search up parent links if it cannot otherwise find the object (unlike
+environments). When accessing a method, \code{\$}
+automatically supplies the
+first argument to the method
+unless the object is \code{.that} or \code{.super}. \code{.that}
+is a special variable which \code{proto} adds to every \code{proto} object
+denoting the object itself. \code{.super} is also added to every
+proto object and is the parent of \code{.that}. \code{.that}
+and \code{.super} are normally used
+within methods of an object to refer to other components of the same
+or parent object, respectively,
+as opposed to the receiver (\code{.}). For example,
+suppose we want \code{add} in \code{addProto2} to add the elements
+of \code{x} together and the elements of
+\code{y} together and then add these two sums. We could redefine add like this:
+
+\begin{Schunk}
+\begin{Sinput}
+> addProto2$add <- function(.) .super$add(.) + sum(.$y)
+\end{Sinput}
+\end{Schunk}
+
+making use of the \code{add} already defined in the parent.
+One exception should be noted here. When one uses \code{.super},
+as above, or \code{.that} to specify a method then the receiver
+object must be explicitly specified
+in argument one (since in those cases the receiver
+is possibly different than
+\code{.super} or \code{.that} so the system cannot automatically supply it
+to the call.)
+
+Setting a value is similar to the corresponding operation for
+environments except that any function, i.e method, which is
+inserted has its environment set to the environment of the object
+into which it is being inserted. This is necessary so that such
+methods can reference \code{.that} and \code{.super} using
+lexical scoping.
+
+In closing this section a few points should be re-emphasized and
+expanded upon. A
+\code{proto} object is an environment whose parent object is the
+parent environment of the \code{proto} object. The methods in the \code{proto}
+objects are ordinary functions that have the containing object as their
+environment.
+
+The \proglang{R} \code{with} function can be used with environments and
+therefore can be used with \code{proto} objects since \code{proto}
+objects are environments too. Thus \code{with(addProto, x)} refers
+to the variable \code{x} in \code{proto} object \code{addProto}
+and \code{with(addProto, add)} refers to the method \code{add}
+in the same way. \code{with(addProto, add)(addProto)} can be used
+to call \code{add}. These constructs all follow from their corresponding
+use in environments from which they are inherited.
+
+Because the \code{with} expressions are somewhat verbose, two common
+cases can be shortened using the \code{\$} operator. \code{addProto\$x}
+can be used to refer to variable \code{x} in \code{proto} object
+\code{addProto} and has the same meaning as \code{with(addProto, x)}.
+In particular like \code{with} but
+unlike the the behavior of the \code{\$} operator on
+environments, when used with \code{proto} objects, \code{\$} will
+search not only the object itself but also its ancestors.
+Similarly \code{addProto\$add()} can be used to call
+method \code{add} in \code{addProto} also searching through ancestors
+if not found in \code{addProto}. Note that \code{addProto\$add}
+returns an object of class
+
+\code{c("instantiatedProtoMethod", "function")}
+which is derived from \code{add} such that the first argument,
+the \code{proto} object,
+is already inserted. Note that there is a \code{print} method for
+class \code{"instantiatedProtoMethod"} so printing such objects will
+display the underlying function but returning such objects
+is not the same as returning the function without slot one inserted.
+Thus, if one wants exactly the original \code{add}
+as a value one should use \code{with(addProto, add)} or
+\code{addProto\$with(add)}.
+
+Within a method, if a variable is referred to without
+qualification simply as \code{x}, say, then its meaning is
+unchanged from how it is otherwise used in \proglang{R} and
+follows the same scope rules as any variable to resolve its name. If it is
+desired that the variable have object scope, i.e. looked up
+in the receiver object and its ancestors, then \code{.\$x}
+or similar \code{with} notation, i.e. \code{with(., x)}, should be used.
+Similarly \code{.\$f(x)} calls
+method \code{f} automatically inserting the receiver object
+into argument one and using \code{x} for argument two. It
+looks for \code{f} first in the receiver object and then its
+ancestors.
+
+\subsection{Traits}
+\label{sec:traits}
+
+Let us look at the definition of a child object once again.
+In the code below,
+\code{addProto} is the previously defined parent object
+and the expression \code{addProto\$proto(x = 1:5)} defines
+a child object of \code{addProto} and assigns it to variable
+\code{addProto2a}.
+
+\begin{Schunk}
+\begin{Sinput}
+> addProto2a <- addProto$proto(x = 1:5)
+> addProto2a$add()
+\end{Sinput}
+\begin{Soutput}
+[1] 15
+\end{Soutput}
+\end{Schunk}
+
+That is, \code{proto} can be used to create a new child of
+an existing object by writing the
+parent object on the left of the \code{\$} and
+\code{proto} on its right. Any contents to
+be added to the new child are listed in arguments of \code{proto}
+as shown.
+
+For example, first let us create a class-like structure. In the
+following \code{Add} is an object that behaves very much like a class
+with an \code{add} method and a method \code{new} which constructs
+new objects. In the line creating object \code{add1} the expression
+\code{Add\$new(x = 1:5)} invokes the \code{new} constructor of the
+receiver object \code{Add}. The method \code{new} has an argument of
+\code{x = 1:5} which defines an \code{x} variable in the \code{add1}
+object being instantiated. We similarly create another object
+\code{add2}.
+
+\begin{Schunk}
+\begin{Sinput}
+> Add <- proto(add = function(.) sum(.$x), new = function(., x) .$proto(x = x))
+> add1 <- Add$new(x = 1:5)
+> add1$add()
+\end{Sinput}
+\begin{Soutput}
+[1] 15
+\end{Soutput}
+\begin{Sinput}
+> add2 <- Add$new(x = 1:10)
+> add2$add()
+\end{Sinput}
+\begin{Soutput}
+[1] 55
+\end{Soutput}
+\end{Schunk}
+
+An object which contains only methods and variables that are
+intended to be shared by all its children (as opposed to an
+object whose purpose is to have its own methods and variables)
+is known as a \emph{trait} \citep{Agesen1992}. It
+is similar to a class in class-based
+object oriented programming.
+Note that the objects \code{add1} and \code{add2} have the trait
+\code{Add} as their parent. We could implement subclass-like and
+superclass-like objects by simply defining similar trait objects to
+be the parent or child of \code{Add}. For example, suppose we
+want a class which calculates the sum of the logarithms of the data. We
+could define:
+
+\begin{Schunk}
+\begin{Sinput}
+> Logadd <- Add$proto(logadd = function(.) log(.$add()))
+> logadd1 <- Logadd$new(1:5)
+> logadd1$logadd()
+\end{Sinput}
+\begin{Soutput}
+[1] 2.70805
+\end{Soutput}
+\end{Schunk}
+
+Here the capitalized objects are traits.
+\code{Logadd} is a trait. It is a child of \code{Add}
+which is also a trait. \code{logadd1} is an ordinary object,
+not a trait.
+One possible design is to create a tree of traits and other objects
+in which the leaves are ordinary objects and the remaining nodes
+are traits. This would closely correspond to class-based
+object oriented programming.
+
+Note that the delegation of methods from
+one trait to another as in
+\code{new} which is inherited by \code{Logadd} from \code{Add}
+is nothing more than the same mechanism by which traits delegate
+methods to
+objects since, of course, traits are just objects no different
+from any other object other than by the conventions we impose on them.
+This unification of subclassing and instantiation beautifully
+shows the simplification that prototype programming represents.
+
+\subsection{Utilities}
+\label{sec:utilities}
+The fact that method calls automatically insert the first argument
+can be used to good effect in leveraging existing \proglang{R}
+functions while allowing an object-oriented syntax.
+
+For example, \code{ls()} can be used to list the components of
+\code{proto} objects:
+
+\begin{Schunk}
+\begin{Sinput}
+> addProto$ls()
+\end{Sinput}
+\begin{Soutput}
+[1] "add" "x"
+\end{Soutput}
+\end{Schunk}
+
+Functions like:
+
+\begin{Schunk}
+\begin{Sinput}
+> addProto$str()
+> addProto$print()
+> addProto$as.list()
+> addProto2a$parent.env()
+\end{Sinput}
+\end{Schunk}
+
+show additional information about the elements. \code{eapply}
+can be used to explore more properties such as the
+the length of each component of an object:
+
+\begin{Schunk}
+\begin{Sinput}
+> addProto$eapply(length)
+\end{Sinput}
+\end{Schunk}
+
+Another example of some interest in any object oriented system
+which allows multiple references to one single object is that
+object identity
+can be tested using the respective base function:
+
+\begin{Schunk}
+\begin{Sinput}
+> addProto$identical(addProto2)
+\end{Sinput}
+\begin{Soutput}
+[1] FALSE
+\end{Soutput}
+\end{Schunk}
+
+\code{proto} does contain a special purpose \code{str.proto} function
+but in the main it
+is important to notice here, that
+\code{proto} has no code that is specific to \code{ls} or
+any of the other ordinary \proglang{R}
+functions listed. We are simply making use of the
+fact that \code{obj\$fun(...)} is transformed into \code{get("fun",
+obj)(obj, ...)} by the proto \code{\$} operator. For example, in the
+case of \code{addProto\$ls()} the system looks for \code{ls} in object
+\code{addProto}. It cannot find it there so it looks to its parent,
+which is the global environment. It does not find it there so it
+searches the remainder of the search path, i.e. the path shown by
+running the \proglang{R} command \code{search()}, and finally finds it
+in the base package, invoking it with an argument of \code{addProto}.
+Since all \code{proto} objects are also environments
+\code{ls(addProto)} interprets \code{addProto} as an environment and
+runs the \code{ls} command with it. In the \code{ls} example there
+were no arguments other than \code{addProto}, and even that one was
+implicit, but if there were
+additional arguments then they would be passed as shown in the
+\code{eapply} and \code{identical} examples above.
+
+\subsection{Plotting}
+\label{sec:plot}
+
+The \code{graph.proto} function can be used to create
+graphs that can be rendered by the \code{Rgraphviz} package
+creating visual representations of ancestor trees (figure
+\ref{fig:proto-dot}).
+That package provides an interface to the
+\proglang{GraphViz} \code{dot} program \citep{Ganser+North:1999}.
+
+\code{graph.proto} takes three arguments, all of which are
+usually omitted. The first argument is a \code{proto} object
+(or an environment) out of which all contained \code{proto} objects
+and their parents (but not higher order ancestors) are graphed.
+If it is omitted, the current environment is assumed.
+The second argument is a graph (in the sense of the \code{graph}
+package) to which the nodes and edges are added. If it is omitted
+an empty graph is assumed. The last argument is a logical variable
+that specifies the orientation of arrows. If omitted arrows are
+drawn from children to their parents.
+
+
+\input{proto-dot}
+
+\begin{figure}[htbp]
+\begin{center}
+\includegraphics{proto-dot}
+\caption{\label{fig:proto-dot} Ancestor tree generated using graph.proto. Edges
+point from child to parent.}
+\end{center}
+\end{figure}
+
+\pagebreak[4]
+
+\section{Examples}
+\label{sec:examples}
+
+\subsection{Smoothing}
+\label{sec:smooth}
+
+In the following we create a \code{proto} object named \code{oo}
+containing a vector of data \code{x} (generated from a simulated
+autoregressive model) and time points
+\code{tt}, an intermediate result
+\code{x.smooth}, some plotting parameters \code{xlab}, \code{ylab},
+\code{pch}, \code{col} and three methods \code{smooth}, \code{plot}
+and \code{residuals} which smooth the data, plot the data and
+calculate residuals, respectively. We also define \code{..x.smooth}
+which holds intermediate results. Names beginning with two dots
+prevent them from being delegated to children. If we override
+\code{x} in a child we would not want an out-of-sync \code{x.smooth}.
+Note that the components of an object can be specified using a code
+block in place of the argument notation we used previously in the
+\code{proto} command.
+
+\begin{Schunk}
+\begin{Sinput}
+> oo <- proto(expr = {
++ x <- rnorm(251, 0, 0.15)
++ x <- filter(x, c(1.2, -0.05, -0.18), method = "recursive")
++ x <- unclass(x[-seq(100)]) * 2 + 20
++ tt <- seq(12200, length = length(x))
++ ..x.smooth <- NA
++ xlab <- "Time (days)"
++ ylab <- "Temp (deg C)"
++ pch <- "."
++ col <- rep("black", 2)
++ smooth <- function(., ...) {
++ .$..x.smooth <- supsmu(.$tt, .$x, ...)$y
++ }
++ plot <- function(.) with(., {
++ graphics::plot(tt, x, pch = pch, xlab = xlab, ylab = ylab,
++ col = col[1])
++ if (!is.na(..x.smooth[1]))
++ lines(tt, ..x.smooth, col = col[2])
++ })
++ residuals <- function(.) with(., {
++ data.frame(t = tt, y = x - ..x.smooth)
++ })
++ })
+\end{Sinput}
+\end{Schunk}
+
+Having defined our \code{proto} object we can inspect it, as shown
+below, using
+\code{print} which is automatically invoked if the
+name of the object, \code{oo}, is entered on a line by itself.
+In this case, there is no proto print method so we inherit the
+environment print method which displays the environment hash code.
+Although it produces too much output to show here,
+we could have displayed a
+list of the entire contents of the object \code{oo}
+via \code{oo\$as.list(all.names = TRUE)}.
+We can get a list of the names of the
+components of the object using \code{oo\$ls(all.names = TRUE)} and will look
+at the contents of one component, \code{oo\$pch}.
+
+\begin{Schunk}
+\begin{Sinput}
+> oo
+\end{Sinput}
+\begin{Soutput}
+<environment: 0x01fbd8c8>
+attr(,"class")
+[1] "proto" "environment"
+\end{Soutput}
+\begin{Sinput}
+> oo$ls(all.names = TRUE)
+\end{Sinput}
+\begin{Soutput}
+ [1] "..x.smooth" ".super" ".that" "col" "pch"
+ [6] "plot" "residuals" "smooth" "tt" "x"
+[11] "xlab" "ylab"
+\end{Soutput}
+\begin{Sinput}
+> oo$pch
+\end{Sinput}
+\begin{Soutput}
+[1] "."
+\end{Soutput}
+\end{Schunk}
+
+Let us illustrate a variety of manipulations. We will set up the
+output to plot 2 plots per screen using \code{mfrow}. We change the
+plotting symbol, smooth the data, invoke the \code{plot} method to
+display a plot of the data and the smooth and then plot the residuals
+in the second plot (figure \ref{fig:proto-smooting03}).
+
+
+\input{proto-smoothing03}
+
+\begin{figure}[h!]
+\begin{center}
+\includegraphics[width=\textwidth]{proto-smoothing03}
+\end{center}
+\caption{Data and smooth from \code{oo\$plot()} (left) and plot of
+\code{oo\$residuals()} (right).}
+\label{fig:proto-smooting03}
+\end{figure}
+
+
+Now let us illustrate the creation of a child object and delegation.
+We create a new child object of \code{oo} called \code{oo.res}. We
+will override the \code{x} value in its parent by setting \code{x} in
+the child to the value of the residuals in the parent. We will also
+override the \code{pch} and \code{ylab} plotting parameters. We will
+return to 1 plot per screen and run \code{plot} using the
+\code{oo.res} object as the receiver invoking the \code{smooth} and
+\code{plot} methods (which are delegated from the parent \code{oo})
+with the data in the child (figure \ref{fig:smoothing04}).
+
+\input{proto-smoothing04}
+% \begin{figure}[tp]
+\begin{figure}[h!]
+\begin{center}
+\includegraphics[width=\half]{proto-smoothing04}
+\end{center}
+\caption{Output of \code{oo.res\$plot()}.
+\code{oo.res\$x} contains the residuals from \code{oo}.}
+\label{fig:smoothing04}
+\end{figure}
+Now we make use of delegation to change the parent
+and child in a consistent way with respect to certain plot characteristics.
+We have been using a numeric time axis.
+Let us interpret these numbers as the number of days since the Epoch,
+January 1, 1970, and let us also change the plot colors.
+
+\begin{Schunk}
+\begin{Sinput}
+> oo$tt <- oo$tt + as.Date("1970-01-01")
+> oo$xlab <- format(oo.res$tt[1], "%Y")
+> oo$col <- c("blue", "red")
+\end{Sinput}
+\end{Schunk}
+
+
+We can introduce a new method, \code{splot}, into
+the parent \code{oo} and have it automatically
+inherited by its children. In this example
+it smooths and then plots and we use it with
+both \code{oo} and \code{oo.res} (figure \ref{fig:smoothing06}).
+
+
+\input{proto-smoothing06}
+
+\begin{figure}[tbp]
+\begin{center}
+\includegraphics[width=\textwidth]{proto-smoothing06}
+\caption{Plotting options and \code{splot} function applied
+to both parent (left) and child (right) object}
+\label{fig:smoothing06}
+\end{center}
+\end{figure}
+
+Numerous possibilities exist to make use of the
+mechanisms shown, so one may create different child objects, apply
+different smoothing parameters, overwrite the smoothing function with
+a lowess smoother and finally compare fits and residuals.
+
+Now lets change the data and repeat the analysis. Rather than
+overwrite the data we will preserve it in \code{oo} and create a child
+\code{oos} to hold an analysis with sinusoidal data.
+
+\begin{Schunk}
+\begin{Sinput}
+> oos <- oo$proto(expr = {
++ tt <- seq(0, 4 * pi, length = 1000)
++ x <- sin(tt) + rnorm(tt, 0, 0.2)
++ })
+> oos$splot()
+\end{Sinput}
+\end{Schunk}
+
+Lets perform the residual analysis with \code{oos}.
+We will make a deep copy of \code{oo.res}, i.e. duplicate its
+contents and not merely delegate it, by copying \code{oo.res}
+to a list from which we create the duplicate, or cloned,
+\code{proto} object (figure \ref{fig:smoothing10} and \ref{fig:cloning}):
+
+\begin{Schunk}
+\begin{Sinput}
+> oos.res <- as.proto(oo.res$as.list(), parent = oos)
+> oos.res$x <- oos$residuals()$y
+> oos.res$splot()
+\end{Sinput}
+\end{Schunk}
+
+
+\begin{figure}[tbp]
+\begin{center}
+\includegraphics[width=\textwidth]{proto-smoothing10}
+\caption{Smoothing of sinusoidal data (left)
+and of their residuals (right)}\label{fig:smoothing10}
+\end{center}
+\end{figure}
+
+\begin{figure}[h!]
+\begin{center}
+\includegraphics[width=50mm]{cloning3.pdf}
+\caption{Cloning (dashed line) and delegation (solid line). Edges point
+from child to parent.}\label{fig:cloning}
+\end{center}
+\end{figure}
+
+We have delegated variables
+and methods and overridden both.
+Thus, even with such a simple analysis, object orientation
+and delegation came into play.
+The reader can plainly see that smoothing and residual
+analysis were not crucial to the example and this example
+could be replaced with any statistical analysis including
+likelihood or other estimation techniques, time series, survival
+analysis, stochastic processes and so on. The key aspect is
+just that we are performing one-of analyses and do not want to
+set up an elaborate class infrastructure but just want to
+directly create objects to organize our calculations while
+relying on delegation and dispatch to eliminate redundancy.
+
+\subsection{Correlation, Fisher's Transform and Bootstrapping}
+\label{sec:corr}
+
+The common approach to
+confidence intervals for the correlation coefficient is to
+assume normality of the underlying data and then use Fisher's transform
+to transform the correlation coefficient to an approximately normal
+random variable.
+Fisher showed that with the above normality assumption, transforming
+the correlation coefficient using
+the hyperbolic arc tangent function
+yields a random variable
+approximately distributed with an
+$\frac{N(p, 1)}{\sqrt(n-3)}$ distribution. The transformed random
+variable can be used to create normal distribution confidence intervals
+and the procedure can be back transformed to get confidence intervals
+for the original correlation coefficient.
+
+A more recent approach to confidence intervals for the correlation
+coefficient is to use bootstrapping. This does not require the
+assumption of normality of the underlying distribution and requires
+no special purpose theory devoted solely to the correlation coefficient,
+
+Let us calculate the 95\%
+confidence intervals using Fisher's transform
+first. We use \code{GNP} and \code{Unemployed} from the Longley data
+set. First we retrieve the data set and extract the required columns
+into \code{x}. Then we set \code{n} to the number of cases
+and \code{pp} to the percentiles
+of interest. Finally we calculate the sample correlation and
+create a function to calculate the confidence interval using
+Fisher's Transform. This function not only returns the confidence
+interval but also stores it in \code{CI} in the receiver object.
+
+\begin{Schunk}
+\begin{Sinput}
+> longley.ci <- proto(expr = {
++ data(longley)
++ x <- longley[, c("GNP", "Unemployed")]
++ n <- nrow(x)
++ pp <- c(0.025, 0.975)
++ corx <- cor(x)[1, 2]
++ ci <- function(.) (.$CI <- tanh(atanh(.$corx) + qnorm(.$pp)/sqrt(.$n -
++ 3)))
++ })
+\end{Sinput}
+\end{Schunk}
+
+Now let us repeat this analysis using the bootstrapping approach. We
+derive a new object \code{longley.ci.boot} as child of
+\code{longley.ci}, setting the number of replications, \code{N}, and
+defining the procedure, \code{ci} which does the actual bootstrap
+calculation.
+
+\begin{Schunk}
+\begin{Sinput}
+> longley.ci.boot <- longley.ci$proto({
++ N <- 1000
++ ci <- function(.) {
++ corx <- function(idx) cor(.$x[idx, ])[1, 2]
++ samp <- replicate(.$N, corx(sample(.$n, replace = TRUE)))
++ (.$CI <- quantile(samp, .$pp))
++ }
++ })
+\end{Sinput}
+\end{Schunk}
+
+In the example code below the first line runs the Fisher Transform
+procedure and the second runs the bootstrap procedure. Just to check
+that we have performed sufficient bootstrap iterations we rerun it in
+the third line, creating a delegated object on-the-fly running its
+\code{ci} method and then immediately throwing the object away.
+The fact that 4,000
+replications give roughly the same result as 1,000 replications
+satisfies us that we have used a sufficient number of replications.
+
+\begin{Schunk}
+\begin{Sinput}
+> longley.ci$ci()
+\end{Sinput}
+\begin{Soutput}
+[1] 0.1549766 0.8464304
+\end{Soutput}
+\begin{Sinput}
+> longley.ci.boot$ci()
+\end{Sinput}
+\begin{Soutput}
+ 2.5% 97.5%
+0.2299395 0.8211854
+\end{Soutput}
+\begin{Sinput}
+> longley.ci.boot$proto(N = 4000)$ci()
+\end{Sinput}
+\begin{Soutput}
+ 2.5% 97.5%
+0.2480999 0.8259276
+\end{Soutput}
+\end{Schunk}
+
+We now have the results stored in two objects nicely organized for the
+future. Note, again, that despite the simplicity of the example we
+have used the features of object oriented programming, coupling the
+data and methods that go together, while relying on delegation and
+dispatch to avoid duplication.
+
+\subsection{Dendrograms}
+\label{sec:tree}
+
+In \cite{Gentleman2002} there is an \proglang{S4}
+example of creating a binary tree
+for use as a dendrogram. Here we directly define a binary tree with no
+setup at all. To keep it short we will create a binary tree of only
+two nodes having a root whose left branch points to a leaf. The leaf
+inherits the \code{value} and \code{incr} components from the root.
+The attractive feature is that the leaf be defined as a child of the
+parent using \code{proto} before the parent is even finished
+being defined. Compared to the cited \proglang{S4} example where it
+was necessary to create an extra class to introduce the required level of
+indirection there is no need to take any similar action.
+
+\code{tree} is the root node of the tree. It has four components. A
+method \code{incr} which increments the \code{value} component, a
+\code{..Name}, the \code{value} component itself and the left branch
+\code{..left}. \code{..left} is itself a proto object which is a
+child of \code{tree}. The leaf inherits the \code{value} component
+from its parent, the root. As mentioned, at the time we define
+\code{..left} we have not even finished defining \code{tree} yet we
+are able to implicitly reference the yet to be defined parent.
+
+\begin{Schunk}
+\begin{Sinput}
+> tree <- proto(expr = {
++ incr <- function(., val) .$value <- .$value + val
++ ..Name <- "root"
++ value <- 3
++ ..left <- proto(expr = {
++ ..Name = "leaf"
++ })
++ })
+\end{Sinput}
+\end{Schunk}
+
+Although this is a simple structure we could have embedded additional
+children into \code{root} and \code{leaf} and so on recursively making
+the tree or dendrogram arbitrarily complex.
+
+Let us do some computation with this structure. We display the
+\code{value} fields in the two nodes, increment the value field in the
+root and then display the two nodes again to show .that the leaf
+changed too.
+
+\begin{Schunk}
+\begin{Sinput}
+> cat("root:", tree$value, "leaf:", tree$..left$value, "\n")
+\end{Sinput}
+\begin{Soutput}
+root: 3 leaf: 3
+\end{Soutput}
+\begin{Sinput}
+> tree$incr(1)
+> cat("root:", tree$value, "leaf:", tree$..left$value, "\n")
+\end{Sinput}
+\begin{Soutput}
+root: 4 leaf: 4
+\end{Soutput}
+\end{Schunk}
+
+If we increment \code{value} in \code{leaf} directly (see the example
+below where we increment it by 10) then it receives its own copy of
+\code{value} so from that point on \code{leaf} no longer inherits
+\code{value} from \code{root}. Thus incrementing the root by 5 no
+longer increments the \code{value} field in the leaf.
+
+\begin{Schunk}
+\begin{Sinput}
+> tree$..left$incr(10)
+> cat("root:", tree$value, "leaf:", tree$..left$value, "\n")
+\end{Sinput}
+\begin{Soutput}
+root: 4 leaf: 14
+\end{Soutput}
+\begin{Sinput}
+> tree$incr(5)
+> cat("root:", tree$value, "leaf:", tree$..left$value, "\n")
+\end{Sinput}
+\begin{Soutput}
+root: 9 leaf: 14
+\end{Soutput}
+\end{Schunk}
+
+\subsection{From Prototypes to Classes}
+\label{sec:increment}
+
+In many cases we will use \pkg{proto} for a design that uses prototypes
+during the full development cycle. In other cases we may use it in an
+incremental way starting with prototypes but ultimately transitioning
+to classes.
+As shown in Section~\ref{sec:traits} the \pkg{proto} package is
+powerful enough to handle class-based as well as class-free programming.
+Here we illustrate this process of incremental design
+starting with
+concrete objects and then over time classifing them into classes,
+evolving a class-based program. \pkg{proto} provides a smooth
+transition path since it can handle both the class-free and the class-based
+phases -- there is no need to switch object systems part way through.
+In this example, we define an object which holds a linear equation, \code{eq},
+represented as a character string in terms of the unknown variable \code{x}
+and a \code{print} and a \code{solve} method. We execute the
+\code{print} method
+to solve it. We also create child object \code{lineq2}
+which overrides \code{eq} and execute its \code{print} method.
+
+\begin{Schunk}
+\begin{Sinput}
+> lineq <- proto(eq = "6*x + 12 - 10*x/4 = 2*x", solve = function(.) {
++ e <- eval(parse(text = paste(sub("=", "-(", .$eq), ")")),
++ list(x = 0+1i))
++ -Re(e)/Im(e)
++ }, print = function(.) cat("Equation:", .$eq, "Solution:", .$solve(),
++ "\n"))
+> lineq$print()
+\end{Sinput}
+\begin{Soutput}
+Equation: 6*x + 12 - 10*x/4 = 2*x Solution: -8
+\end{Soutput}
+\begin{Sinput}
+> lineq2 <- lineq$proto(eq = "2*x = 7*x-12+x")
+> lineq2$print()
+\end{Sinput}
+\begin{Soutput}
+Equation: 2*x = 7*x-12+x Solution: 2
+\end{Soutput}
+\end{Schunk}
+
+We could continue with enhancements but at this point we decide that we
+have a general case and so wish
+to abstract \code{lineq} into a class. Thus we define a trait,
+\code{Lineq}, which is just \code{lineq} minus \code{eq} plus
+a constructor \code{new}. The key difference between \code{new}
+and the usual \code{proto} function
+is that with \code{new} the initialization of \code{eq} is mandatory.
+Having completed this definition
+we instantiate an object of
+class/trait \code{Lineq} and execute it.
+
+\begin{Schunk}
+\begin{Sinput}
+> Lineq <- lineq
+> rm(eq, envir = Lineq)
+> Lineq$new <- function(., eq) proto(., eq = eq)
+> lineq3 <- Lineq$new("3*x=6")
+> lineq3$print()
+\end{Sinput}
+\begin{Soutput}
+Equation: 3*x=6 Solution: 2
+\end{Soutput}
+\end{Schunk}
+
+Note how we have transitioned from a prototype style of programming
+to a class-based style of programming all the while staying within
+the \pkg{proto} framework.
+
+\section{Summary} \label{sec:summary}
+
+\subsection{Benefits}
+\label{sec:benefits}
+
+The key benefit of the \pkg{proto} package is to provide
+access to a style of programming that has not been conveniently
+accessible within \proglang{R} or any other mainstream language today.
+
+\pkg{proto} can be used in two key ways: class-free object oriented programming
+and class-based object oriented programming.
+
+A key application for \pkg{proto} in class-free programming is to wrap the code
+and data for each run of a particular statistical study into an object for
+purposes of organization and reproducibility. It provides such organization
+directly and without the need and overhead of class definitions
+yet still provides the
+inheritance and dispatch advantages of object oriented programming.
+We provide examples of this style of programming in
+Section~\ref{sec:smooth}
+and
+Section~\ref{sec:corr}.
+A third example in
+Section~\ref{sec:tree} illustrates a beneficial use of \pkg{proto} with
+recursive data structures.
+
+Another situation where prototype programming is of interest is in the initial
+development stages of a program. In this case, the design may not be fully
+clear so it is more convenient to create concrete objects individually rather
+than premature abstractions through classes. The \code{graph.proto}
+function can be used to generate visual representations of the object
+tree suggesting classifications of objects so that
+as the program evolves the general case becomes clearer and
+in a bottom up fashion the objects are incrementally abstracted into
+classes. In this case,
+\pkg{proto} provides a smooth transition path since it not only supports
+class-free programming but, as explained in the Section~\ref{sec:traits}, is
+sufficiently powerful to support class-based programming, as well.
+
+
+\subsection{Conclusion}
+\label{sec:conclusion}
+
+The package \pkg{proto} provides an \proglang{S3} subclass of the
+\code{environment} class for constructing and manipulating object
+oriented systems without classes. It can also emulate classes even
+though classes are not a primitive structure. Its key design goals
+are to provide as simple and as thin a layer as practically possible
+while giving the user convenient access to this alternate object
+oriented paradigm. This paper describes, by example, how prototype
+programming can be carried out in \proglang{R} using \pkg{proto} and
+illustrates such usage. Delegation, cloning traits and general
+manipulation and incremental development are all reviewed by example.
+
+\section*{Computational details}
+\label{sec:compute}
+
+The results in this paper were obtained using \proglang{R} 2.1.0 with
+the package \pkg{proto} 0.3--2. \proglang{R} itself and the
+\pkg{proto} package are available from CRAN at
+\url{http://CRAN.R-project.org/}. The GraphViz software is available
+from \url{http://www.graphviz.org}.
+
+\phantomsection
+\addcontentsline{toc}{section}{References}
+\bibliography{proto}
+%\input{proto.bbl}
+
+\newpage\mbox{}
+\begin{appendix}
+\section{Frequently Asked Questions}
+\label{sec:faq}
+\begin{enumerate}
+\item{What scope do unqualified object references within methods use?
+
+A \pkg{proto} object is an environment and that environment
+is the environment
+of the methods in it (by default).
+That is, unqualified object references
+within a \pkg{proto} method look first in the method itself and secondly in the
+\pkg{proto} object containing the method.
+This is referred to as object
+scope as opposed to lexical scope or dynamic scope. It allows simple
+situations, where delegation is not used, to use unqualified names. Thus
+simple situations remain simple.
+\citep{Kates2004}
+discusses the fragile base class problem which
+relates to this question. Also note that if a \pkg{proto} object is created
+via the \code{proto} function using an argument of \code{funEnvir = FALSE}
+then the environment of the function/method will not be set as just
+described (but rather it will retain its original environment) so the
+above does not apply. This can be used for instances when non-default
+processing is desirable.}
+\item{Why does \code{obj\$meth} not return the method, \code{meth}?
+
+Conceptually \code{obj\$meth} returns \code{meth} but with
+\code{obj} already inserted into its first argument.
+This is termed an instantiated
+\pkg{proto}
+method and is of \proglang{S3} class \code{"instantiatedProtoMethod"}.
+
+In contrast, the method itself (i.e. the uninstantited method)
+would not have the first argument already
+inserted. To return the method itself use \code{with(obj, meth}.
+
+The main advantage of a design that makes the distinction between instantiated
+and uninstantiated methods is that uninstantiated methods are never
+changed so
+debugging can be more readily carried out (as discussed in the next
+question and answer).
+}
+\item{How does one debug a method?
+
+\pkg{proto} does not dynamically redefine methods. This has the advantage
+that the ordinary \proglang{R} \code{debug} and \code{undebug} commands can be
+used. When using these be sure that to use them with the uninstantiated method
+itself and not the instantiated method derived from it. That is,
+use:
+\begin{verbatim}
+ with(obj, debug(meth))
+\end{verbatim}
+
+and not
+\begin{verbatim}
+ debug(obj$meth) # wrong
+\end{verbatim}
+}
+\item{Is multiple inheritance supported?
+
+No. \pkg{proto} is just a thin layer on top of \proglang{R}
+environments and \proglang{R} environments
+provide single inheritance only. \citep{Kates2004}
+discusses some ways of handling situations which would otherwise require
+multiple inheritance.}
+\item{Does \pkg{proto} support lazy evaluation?
+
+Since \code{proto} methods are just \proglang{R} functions they do support
+lazy evaluation; however, the \code{proto} function itself
+does evaluate its arguments. To get the
+effect of lazy evaluation when using the \code{proto}
+function replace any properties with a function.
+
+If the caller is the parent of the \code{proto} object then its
+particularly simple. Note how we got the equivalent of lazy evaluation
+in the second example where f is a function:
+
+\begin{verbatim}
+# eager evaluation
+x <- 0
+p <- proto(f = x, g = function(.) $x)
+x <- 1
+p$f # 0
+
+# versus making f a function
+
+# simulates lazy evaluation
+x <- 0
+p <- proto(f = function(.) x, g = function(.) .$x)
+x <- 1
+p$f() # 1
+\end{verbatim}
+
+If we cannot guarantee that the proto object has the caller
+as its parent then ensure that the environment of the function
+has not been reset. If no method needs to reference \code{.that}
+or \code{.super} then we can arrange for that using
+\code{funEnvir=FALSE} as seen here in the second example:
+\begin{verbatim}
+
+# does not work as intended
+x <- 0
+p <- proto(x = 99)
+q <- p$proto(f = function(.) x, g = function(.) .$x)
+x <- 1
+q$f() # 99
+
+# does work
+x <- 0
+p <- proto(x = 99)
+q <- p$proto(f = function(.) x, g = function(.) .$x, funEnvir = FALSE)
+x <- 1
+q$f() # 1
+\end{verbatim}
+
+If we wish only to not reset the function used to simulate
+lazy evaluation then we can do it using either of the
+two equivalent alternatives below. \code{g}
+is an ordinary method whose environment is reset to \code{q}
+whereas \code{f} is a function whose environment is not reset and
+serves to provide lazy evaluation for \code{x} found in the caller.
+
+\begin{verbatim}
+x <- 0
+p <- proto(x = 99)
+# g will use q's y in children of q even if those children
+# override y
+q <- p$proto(y = 25, g = function(.) .that$y + .$x)
+q[["f"]] <- function(.) x
+x <- 1
+q$f() # 1
+
+# equivalent alternative
+
+x <- 0
+p <- proto(x = 99)
+q <- proto(f = function(.) x, funEnvir = FALSE,
+ envir = p$proto(y = 25, g = function(.) .that$y + .$x))
+x <- 1
+q$f() # 1
+\end{verbatim}
+}
+\end{enumerate}
+\newpage{}
+\section{Reference Card}
+\label{sec:ref}
+\input{protoref-raw}
+\end{appendix}
+
+\end{document}
+
diff --git a/inst/doc/proto.pdf b/inst/doc/proto.pdf
index b48b69e..a554816 100644
Binary files a/inst/doc/proto.pdf and b/inst/doc/proto.pdf differ
diff --git a/inst/doc/protoref.Rnw b/inst/doc/protoref.Rnw
old mode 100755
new mode 100644
index f46c9c8..00d00d3
--- a/inst/doc/protoref.Rnw
+++ b/inst/doc/protoref.Rnw
@@ -1,26 +1,27 @@
-\SweaveOpts{engine=R,eps=FALSE}
-
-%\VignetteIndexEntry{protoref: proto Reference Card}
-%\VignetteDepends{}
-%\VignetteKeywords{object oriented, prototype programming, S3, R}
-%\VignettePackage{proto}
-
-\documentclass[a4]{article}
-\usepackage{Rd}
-
-%\newlength{\refcardwidth}
-%\setlength{\refcardwidth}{20cm}
-
-% \usepackage{c:/PROGRA~1/R/RW2010~1/share/texmf/Sweave}
-\begin{document}
-\pagestyle{empty}
-
-%\begin{landscape}
-\centerline{\Large \bf \pkg{proto} reference card}
-\vspace{0.8cm}
-\begin{small}
-\input{protoref-raw}
-\end{small}
-%\end{landscape}
-
-\end{document}
+\SweaveOpts{engine=R,eps=FALSE}
+
+%\VignetteIndexEntry{protoref: proto Reference Card}
+%\VignetteDepends{}
+%\VignetteKeywords{object oriented, prototype programming, S3, R}
+%\VignettePackage{proto}
+
+\documentclass[a4]{article}
+\usepackage{Rd}
+\usepackage{Sweave}
+
+%\newlength{\refcardwidth}
+%\setlength{\refcardwidth}{20cm}
+
+\begin{document}
+\SweaveOpts{concordance=TRUE}
+\pagestyle{empty}
+
+%\begin{landscape}
+\centerline{\Large \bf \pkg{proto} reference card}
+\vspace{0.8cm}
+\begin{small}
+\input{protoref-raw}
+\end{small}
+%\end{landscape}
+
+\end{document}
diff --git a/inst/doc/protoref.pdf b/inst/doc/protoref.pdf
old mode 100755
new mode 100644
index 20d9eae..8e82aea
Binary files a/inst/doc/protoref.pdf and b/inst/doc/protoref.pdf differ
diff --git a/man/graph.proto.Rd b/man/graph.proto.Rd
deleted file mode 100755
index 0cabf3c..0000000
--- a/man/graph.proto.Rd
+++ /dev/null
@@ -1,68 +0,0 @@
-\name{graph.proto}
-\alias{graph.proto}
-\alias{name.proto}
-\title{ Create a graph of proto objects }
-\description{
- Creates a graph of the parent/child relationships among a set of
- proto objects.
-}
-\usage{
-graph.proto(e, g = new("graphNEL", edgemode = "directed"), child.to.parent = TRUE)
-}
-%- maybe also 'usage' for other objects documented here.
-\arguments{
- \item{e}{ A proto object or an environment whose proto objects will
- be graphed. }
- \item{g}{ A graph to add the edges and nodes to. Defaults to an
- empty graph. }
- \item{child.to.parent}{ If TRUE then arrows are drawn from child to
- parent; otherwise, from parent to child. }
-}
-\details{
- This function is used to create a graph in the sense of the
- \code{"graph"} package out of the parent child relationships
- of proto objects. All \code{"proto"} objects in \code{"e"}
- and their immediate parents are placed in the graph.
-
- The objects are labelled using their \code{"..Name"} component.
- If there is no \code{"..Name"} component then their
- variable name in \code{"e"} is used. In the case
- of a parent that is not in \code{"e"}, an internally generated
- name will be used if the parent has no \code{"..Name"} component.
- If two \code{"proto"} objects to be graphed have the same name
- the result is undefined.
-}
-\value{
- Produces an object of class \code{"graph"} that can subsequently
- be plotted.
-}
-
-\note{
- \code{graph.proto} makes use of the \code{Rgraphviz}
- package in the \code{BioConductor} repository and so
- \code{Rgraphviz} must be installed and loaded. On Linux one gotcha
- is that you may need to add the
- \code{graphviz} shared library, e.g. to add the directory containing
- the \code{.so} files,
- to your linker path via:
- \code{export LD_LIBRARY_PATH=/path/to/graphviz/libs}.
-}
-
-\examples{
-\dontrun{
-a <- proto()
-b <- a$proto()
-g <- graph.proto()
-plot(g)
-g <- graph.proto(child.to.parent = FALSE) # change arrow heads
-plot(g)
-g <- graph.proto(g = new("graphNEL")) # undirected
-plot(g)
-g <- graph.proto()
-attrs <- list(node = list(fillcolor = "lightgreen"),
- edge = list(color = "cyan"),
- graph = list(rankdir = "BT"))
-plot(graph.proto(), attrs = attrs) # specify plot attributes
-}
-}
-\keyword{programming}
diff --git a/man/proto-package.Rd b/man/proto-package.Rd
old mode 100755
new mode 100644
index b9d416e..966e48c
--- a/man/proto-package.Rd
+++ b/man/proto-package.Rd
@@ -1,59 +1,29 @@
-\name{proto-package}
-\alias{proto-package}
-\docType{package}
-\title{
-Object-Oriented Programming with the Prototype Model
-}
-\description{
-Object-oriented programming with the prototype model. \code{"proto"}
-facilitates object-oriented programming using an approach
-that emphasizes objects rather than classes (although it
-is powerful enough to readily represent classes too).
-}
-\details{
-\code{"proto"} allows one to write object-oriented programs using
-the prototype model. It is a simple system that
-uses objects rather than classes yet is powerful enough to readily
-encompass classes too.
-The following are sources of information on \code{"proto"}:
-\tabular{ll}{
-Home page\tab \code{u <- "http://r-proto.googlecode.com"; browseURL(u)}\cr
-Overview\tab \code{README <- system.file("README", package = "proto"); file.show(README)}\cr
-Invoking a demo file\tab \code{demo("proto")}\cr
-Referance Card\tab \code{vignette("protoref")}\cr
-Tutorial \tab \code{vignette("proto")}\cr
-Prototype OO concepts document\tab \code{u <- "http://r-proto.googlecode.com/files/prototype_approaches.pdf"; browseURL(u)}\cr
-News\tab \code{RShowDoc("NEWS", package = "proto")}\cr
-Wish List\tab \code{RShowDoc("WISHLIST", package = "proto")}\cr
-Thanks\tab \code{RShowDoc("THANKS", package = "proto")}\cr
-License\tab \code{RShowDoc("COPYING", package = "proto")}\cr
-Citation\tab \code{citation(package = "proto")}\cr
-This File\tab \code{package?proto}\cr
-Help file\tab \code{?proto}\cr
-graph.proto Help File\tab \code{?graph.proto}\cr
-}
-}
-
-\note{See \code{?graph.proto} for the solution to a common
-Linux installation problem with \code{Rgraphviz} that \code{proto}
-depends on.}
-
-\keyword{programming}
-\examples{
-cat("parent\n")
-oop <- proto(x = 10, view = function(.) paste("this is a:", .$x))
-oop$ls()
-oop$view()
-
-cat("override view in parent\n")
-ooc1 <- oop$proto(view = function(.) paste("this is a: ***", .$x, "***"))
-ooc1$view()
-
-cat("override x in parent\n")
-ooc2 <- oop$proto(x = 20)
-ooc2$view()
-\dontrun{
-g <- graph.proto()
-plot(g)
-}
-}
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/proto.R
+\docType{package}
+\name{proto-package}
+\alias{proto-package}
+\title{Object-Oriented Programming with the Prototype Model}
+\description{
+Object-oriented programming with the prototype model. \code{"proto"}
+facilitates object-oriented programming using an approach that emphasizes
+objects rather than classes (although it is powerful enough to readily
+represent classes too).
+}
+\examples{
+
+cat("parent\\n")
+oop <- proto(x = 10, view = function(.) paste("this is a:", .$x))
+oop$ls()
+oop$view()
+
+cat("override view in parent\\n")
+ooc1 <- oop$proto(view = function(.) paste("this is a: ***", .$x, "***"))
+ooc1$view()
+
+cat("override x in parent\\n")
+ooc2 <- oop$proto(x = 20)
+ooc2$view()
+}
+\keyword{programming}
+
diff --git a/man/proto.Rd b/man/proto.Rd
old mode 100755
new mode 100644
index 60f3c1d..60c0dda
--- a/man/proto.Rd
+++ b/man/proto.Rd
@@ -1,265 +1,277 @@
-\name{proto}
-\alias{proto}
-\alias{as.proto}
-\alias{as.proto.environment}
-\alias{as.proto.list}
-\alias{as.proto.proto}
-\alias{isnot.function}
-\alias{is.proto}
-\alias{$.proto}
-\alias{$<-.proto}
-\alias{with.proto}
-\alias{str.proto}
-\alias{.}
-\alias{this}
-\alias{.that}
-\alias{that}
-\alias{.super}
-\alias{super}
-\alias{print.instantiatedProtoMethod}
-\title{Prototype object-based programming}
-\description{
-\code{proto} creates or modifies objects of the proto object
-oriented system.
-}
-\usage{
-proto(. = parent.env(envir), expr = {}, envir =
- new.env(parent = parent.frame()), ..., funEnvir )
-\method{as.proto}{list}(x, envir, parent, all.names = FALSE, ...,
- funEnvir = envir, SELECT = function(x) TRUE)
-isnot.function(x)
-}
-
-\arguments{
- \item{.}{the parent object of the new object. May be a proto object
- or an environment.}
- \item{expr}{a series of statements enclosed in braces that define
- the variables and methods of the object. Empty braces, the default,
- may be used
- if there are no variables or methods to add at this time.}
- \item{envir}{an existing prototype object or environment into which
- the variables and methods defined in \code{expr} are placed.
- If omitted a new object is created.}
- \item{funEnvir}{the environment of methods passed via \dots are automatically
- set to this environment. Normally this argument is omitted, defaulting
- to \code{envir}; however, one can specify \code{FALSE}
- to cause their environment to not be set or one can specify some
- other environment or proto object to which their environment is to be set.}
- \item{x}{a list.}
- \item{parent}{a prototype object or environment which is to be used
- as the parent of the object. If \code{envir} is specified then
- its parent is coerced to \code{parent}.}
- \item{\dots}{for \code{proto} these are components to be embedded in
- the new object. For \code{as.proto.list} these are arguments to
- pass to \code{proto} in the case that a new object is created.}
- \item{SELECT}{a function which given an object returns \code{TRUE} or
- \code{FALSE} such that only those for which \code{SELECT} returns
- \code{TRUE} are kept in the returned \code{proto} object.}
- \item{all.names}{only names not starting with a dot are copied unless
- all.names is TRUE.}
-}
-
-\details{
-The \code{proto} class
-is defined to be a subclass of the R \code{environment} class.
-In particular this implies that \code{proto} objects have
-single inheritance and mutable state as all environments do.
-\code{proto} creates or modifies objects of this class. It inserts
-all variables and functions in \code{expr} and then in \code{\dots}
-into \code{envir} setting the parent to \code{.}. The environment of
-all functions inserted into the environment are set to that environment.
-All such functions should
-have the receiver object as their first argument.
-Conventionally this is \code{.} (i.e. a dot).
-Also \code{.that} and \code{.super}
-variables are added to the environment. These
-point to the object itself and its parent.
-Note that \code{proto} can be used as a method and overridden
-like any other method. This allows objects to have object-specific
-versions of \code{proto}.
-
-\code{as.proto} is a generic with methods for environments, proto objects
-and lists.
-
-\code{as.proto.list} copies inserts a copy of each component, \code{el},
-of the list \code{x} into the the environment or proto object
-\code{envir} for which \code{FUN(el)} is \code{TRUE}. Also, components
-whose name begins with a dot, \code{.}, are not copied unless
-\code{all.names} is \code{TRUE} (and \code{FUN(el)} is \code{TRUE}).
-The result is a proto object whose parent is \code{parent}.
-If \code{envir} is omitted a new object is created through a call to
-\code{proto} with \code{parent} and \code{\dots} as arguments.
-If \code{parent} is also omitted then the current environment is used.
-Note that if \code{parent} is a proto object with its own \code{proto}
-method then this call to \code{proto} will be overridden by that method.
-
-The utility function \code{isnot.function} is provided for use with
-\code{as.proto.list} to facilitate the copying of variables only.
-
-\code{$} can be used to access or set variables and methods in an
-object.
-
-When \code{$} is used for getting variables and methods, calls of
-the form \code{obj$v} search for v in \code{obj} and if not found
-search upwards through the ancestors of \code{obj} until found
-unless the name \code{v} begins with two dots \code{..}. In that case no
-upward search is done.
-
-If \code{meth} is a function then \code{obj$meth} is an object
-of class \code{c("instantiatedProtoMethod", "function")}
-which is a \code{proto}
-method with the first, i.e. proto slot, already filled in.
-It is normally used in the
-context of a call to a method, e.g. \code{obj$meth(x,y)}.
-There also exists \code{print.instantiatedProtoMethod}
-for printing such objects. Note that an instantiated proto method
-is not the same as a proto method. The first has its first slot
-filled in whereas the second does not.
-If it is desired to actually return the method as a value not
-in the context of a call then use the form
-\code{obj$with(meth)} or \code{obj[[meth]]}
-which are similar to \code{with(obj, meth)} except that
-the variation using \code{with} will search through ancestors while
-\code{[[} will not search through ancestors).
-The difference between \code{obj$meth} and \code{obj$with(meth)}
-is that in the first case
-\code{obj} implicitly provides the first argument to the
-call so that \code{obj$meth(x,y)} and \code{obj$with(meth)(obj,x,y)}
-are equivalent while in the case of \code{obj$with(meth)} the first
-argument is not automatically inserted.
-\code{$.proto} also has a three argument form. If the third argument
-is present then it should be a list specifying the arguments at which
-the instantiated method is to be evaluated.
-
-
-
-The forms \code{.that$meth} and
-\code{.super$meth}
-are special and should only be used within methods. \code{.that}
-refers to the object in which the current method is located
-and \code{.super} refers to the parent of \code{.that}. In both
-cases the receiver object must be
-specified as the first argument --- the receiver
-is not automatically inserted
-as with other usages of \code{$}.
-
-\code{$} can be used to set variables and methods in an object.
-No ancestors are searched for the set form of \code{$}.
-If the variable is the special variable \code{.super} then not only
-is the variable set but the object's parent is set to \code{.super}.
-
-A \code{with} method is available for \code{proto} objects.
-
-\code{is.proto(p)} returns TRUE if p is a prototype object.
-
-\code{str.proto} is provided for inspecting \code{proto} objects.
-
-}
-
-\value{
-\code{proto} and \code{as.proto} all
-return proto objects. \code{isnot.function} returns a logical value.
-}
-
-\note{
-proto methods can be used with environments but some care must be
-taken. These can be avoided by always using proto objects in these
-cases. This note discusses the pitfalls of using environments for
-those cases where such interfacing is needed.
-
-Note that if \code{e} is an environment then \code{e$x} will only
-search for \code{x} in \code{e} and no further whereas if \code{e}
-were a proto object its ancestors will be searched as well.
-For example,
-if the parent of a \code{proto} object is an \code{environment}
-but not itself a \code{proto} object then \code{.super$x} references
-in the methods of that object will only look as far as the parent.
-
-Also note that the form \code{e$meth(...)} when used with an environment
-will not automatically insert \code{e} as the first argument and
-so environments can only be used with methods by using the more verbose
-\code{e$meth(e, ...)}. Even then it is not exactly equivalent since
-\code{meth} will only be looked up in \code{e} but not its ancestors.
-To get precise equivalence write the even more verbose
-\code{with(e, meth)(e, ...)}.
-
-If the user has a proto object \code{obj}
-which is a child of the global environment and whose methods
-use \code{.super} then \code{.super} will refer to an environment,
-not a proto object (unless the global environment is coerced to
-a proto object) and therefore be faced with the search situation
-discussed above. One solution is to
-create an empty root object between the global environment
-and \code{obj} like this \code{Root <- obj$.super <- proto(.GlobalEnv)}
-where \code{Root} is the root object.
-Now \code{.super} references will reference \code{Root}, which is
-a proto object so search will occur as expected. \code{proto}
-does not provide such a root object automatically
-but the user can create one easily as shown, if desired.
-
-Although not recommended, it possible to coerce the global environment
-to a proto object by issuing the command
-\code{as.proto(.GlobalEnv)}. This will effectively make the global
-environment a proto root object
-but has the potential to break other software, although the
-authors have not actually found any software that it breaks.
-}
-
-\seealso{\code{\link{as.list}}, \code{\link{names}}, \code{\link{environment}}}
-
-\examples{
-oo <- proto(expr = {x = c(10, 20, 15, 19, 17)
- location <- function(.) mean(.$x) # 1st arg is object
- rms <- function(.)
- sqrt(mean((.$x - .$location())^2))
- bias <- function(., b) .$x <- .$x + b
-})
-
-debug(oo$with(rms)) # cannot use oo$rms to pass method as a value
-undebug(oo$with(rms)) # cannot use oo$rms to pass method as a value
-
-oo2 <- oo$proto( location = function(.) median(.$x) )
-oo2$rms() # note that first argument is omitted.
-oo2$ls() # list components of oo2
-oo2$as.list() # contents of oo2 as a list
-oo2 # oo2 itself
-oo2$parent.env() # same
-oo2$parent.env()$as.list() # contents of parent of oo2
-oo2$print()
-oo2$ls()
-oo2$str()
-oo3 <- oo2
-oo2$identical(oo3)
-oo2$identical(oo)
-
-# start off with Root to avoid problem cited in Note
-Root <- proto()
-oop <- Root$proto(a = 1, incr = function(.) .$a <- .$a+1)
-ooc <- oop$proto(a = 3) # ooc is child of oop but with a=3
-ooc$incr()
-ooc$a # 4
-
-# same but proto overridden to force a to be specified
-oop$proto <- function(., a) { .super$proto(., a=a) }
-\dontrun{
-ooc2 <- oop$proto() # Error. Argument "a" is missing, with no default.
-}
-ooc2 <- oop$proto(a = 10)
-ooc2$incr()
-ooc2$a # 11
-
-# use of with to eliminate having to write .$a
-o2 <- proto(a = 1, incr = function(.) with(., a <- a+1))
-o2c <- as.proto(o2$as.list()) # o2c is a clone of o2
-o2d <- o2$proto() # o2d is a child of o2
-o2$a <- 2
-o2c$a # a not changed by assignment in line above
-o2d$a # a is changed since a not found in o2d so found in o2
-
-p <- proto(a = 0, incr = function(., x) .$a <- .$a + x)
-pc <- p$proto(a = 100)
-sapply(list(p, pc), "$.proto", "incr", list(x = 7))
-
-}
-\keyword{programming}
-
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/proto.R
+\name{proto}
+\alias{proto}
+\alias{as.proto}
+\alias{as.proto.environment}
+\alias{as.proto.list}
+\alias{as.proto.data.frame}
+\alias{as.proto.proto}
+\alias{isnot.function}
+\alias{is.proto}
+\alias{$.proto}
+\alias{$<-.proto}
+\alias{with.proto}
+\alias{str.proto}
+\alias{.}
+\alias{this}
+\alias{.that}
+\alias{that}
+\alias{.super}
+\alias{super}
+\alias{print.instantiatedProtoMethod}
+\alias{as.proto}
+\alias{as.proto.environment}
+\alias{as.proto.proto}
+\alias{as.proto.list}
+\alias{is.proto}
+\title{Prototype object-based programming}
+\usage{
+proto(. = parent.env(envir), expr = { }, envir = new.env(parent =
+ parent.frame()), ..., funEnvir = envir)
+
+as.proto(x, ...)
+
+\method{as.proto}{environment}(x, ...)
+
+\method{as.proto}{proto}(x, ...)
+
+\method{as.proto}{list}(x, envir, parent, all.names = FALSE, ...,
+ funEnvir = envir, SELECT = function(x) TRUE)
+
+is.proto(x)
+}
+\arguments{
+\item{.}{the parent object of the new object. May be a proto object or an
+environment.}
+
+\item{expr}{a series of statements enclosed in braces that define the
+variables and methods of the object. Empty braces, the default, may be used
+if there are no variables or methods to add at this time.}
+
+\item{envir}{an existing prototype object or environment into which the
+variables and methods defined in \code{expr} are placed. If omitted a new
+object is created.}
+
+\item{\dots}{for \code{proto} these are components to be embedded in the new
+object. For \code{as.proto.list} these are arguments to pass to
+\code{proto} in the case that a new object is created. for \code{$.proto}
+the method is evaluated at these arguments.}
+
+\item{funEnvir}{the environment of methods passed via \dots{} are
+automatically set to this environment. Normally this argument is omitted,
+defaulting to \code{envir}; however, one can specify \code{FALSE} to cause
+their environment to not be set or one can specify some other environment or
+proto object to which their environment is to be set.}
+
+\item{x}{a list.}
+
+\item{parent}{a prototype object or environment which is to be used as the
+parent of the object. If \code{envir} is specified then its parent is
+coerced to \code{parent}.}
+
+\item{all.names}{only names not starting with a dot are copied unless
+all.names is TRUE.}
+
+\item{SELECT}{a function which given an object returns \code{TRUE} or
+\code{FALSE} such that only those for which \code{SELECT} returns
+\code{TRUE} are kept in the returned \code{proto} object.}
+
+\item{list}{list whose components are an alternate way to specifying
+arguments in place of \code{\dots{}}}
+}
+\value{
+\code{proto} and \code{as.proto} all return proto objects.
+}
+\description{
+\code{proto} creates or modifies objects of the proto object oriented
+system.
+}
+\details{
+The \code{proto} class is an \code{S3} subclass of the R \code{environment}
+class. In particular this implies that \code{proto} objects have single
+inheritance and mutable state as all environments do. The \code{proto}
+function creates and modifies objects of the \code{proto} class. It (1)
+sets the parent of codeenvir to \code{parent}, (2) evaluates \code{expr} in
+the \code{envir} environment and (3) lazily evaluates the arguments in
+\code{\dots{}} in the parent environment resetting the environment of any
+functions (where the resetting is also done lazily). All such functions are
+known as methods and should have the receiver object as their first
+argument. Conventionally this is \code{.} (i.e. a dot). Also \code{.that}
+and \code{.super} variables are added to the environment \code{envir}.
+These point to the object itself and its parent, respectively. Note that
+\code{proto} can be used as a method and overridden like any other method.
+This allows objects to have object-specific versions of \code{proto}. There
+also exist \code{that()} and \code{super()} functions which have the same
+purpose as \code{.that} and \code{.super} but do not rely on the
+\code{.that} and \code{.super}. \code{.that}, \code{.super}, \code{that()}
+and \code{super()} can only be used within methods that have their object as
+their environment. In addition \code{that()} and \code{super()} may only be
+used within the top level of such methods ( and not within functions within
+such methods).
+
+\code{as.proto} is a generic with methods for environments, proto objects
+and lists.
+
+\code{as.proto.list} copies each component, \code{el}, of the list \code{x}
+into the the environment or proto object \code{envir} for which
+\code{FUN(el)} is \code{TRUE}. Components whose name begins with a dot,
+\code{.}, are not copied unless \code{all.names} is \code{TRUE} (and
+\code{FUN(el)} is \code{TRUE}). The result is a proto object whose parent is
+\code{parent}. If \code{envir} is omitted a new object is created through a
+call to \code{proto} with \code{parent} and \code{\dots{}} as arguments. If
+\code{parent} is also omitted then the current environment is the parent.
+Note that if \code{parent} is a proto object with its own \code{proto}
+method then the \code{proto} method of the parent will override the one
+described here in which case the functionality may differ.
+
+\code{$} can be used to access or set variables and methods in an object.
+
+When \code{$} is used for getting variables and methods, calls of the form
+\code{obj$v} search for v in \code{obj} and if not found search upwards
+through the ancestors of \code{obj} until found unless the name \code{v}
+begins with two dots \code{..}. In that case no upward search is done.
+
+If \code{meth} is a function then \code{obj$meth} is an object of class
+\code{c("instantiatedProtoMethod", "function")} which is a \code{proto}
+method with the first, i.e. proto slot, already filled in. It is normally
+used in the context of a call to a method, e.g. \code{obj$meth(x,y)}. There
+also exists \code{print.instantiatedProtoMethod} for printing such objects.
+Be aware that an instantiated proto method is not the same as a proto
+method. An instantiated proto method has its first argument filled (with
+the receiver object) whereas the first argument of a proto method does not.
+If it is desired to actually return the method as a value not in the context
+of a call then use the form \code{obj$with(meth)} or \code{obj[[meth]]}
+which are similar to \code{with(obj, meth)} except that the variation using
+\code{with} will search through ancestors while \code{[[} will not search
+through ancestors). The difference between \code{obj$meth} and
+\code{obj$with(meth)} is that in the first case \code{obj} implicitly
+provides the first argument to the call so that \code{obj$meth(x,y)} and
+\code{obj$with(meth)(obj,x,y)} are equivalent while in the case of
+\code{obj$with(meth)} the first argument is not automatically inserted.
+
+\code{$.proto} also has a multiple argument form. If three or more
+arguments are present then they specify the arguments at which the
+instantiated method is to be evaluated. In this form the receiver object
+must be specified explicitly. This form can be used in situations where the
+highest speed is required such as in the inner loops of computations.
+
+The forms \code{.that$meth} and \code{.super$meth} are special and should
+only be used within methods. \code{.that} refers to the object in which the
+current method is located and \code{.super} refers to the parent of
+\code{.that}. In both cases the receiver object must be specified as the
+first argument -- the receiver is not automatically inserted as with other
+usages of \code{$}.
+
+\code{$} can be used to set variables and methods in an object. No ancestors
+are searched for the set form of \code{$}. If the variable is the special
+variable \code{.super} then not only is the variable set but the object's
+parent is set to \code{.super}.
+
+A \code{with} method is available for \code{proto} objects.
+
+\code{is.proto(p)} returns TRUE if p is a prototype object.
+
+\code{str.proto} is provided for inspecting \code{proto} objects.
+}
+\note{
+proto methods can be used with environments but some care must be
+taken. Problems can be avoided by always using proto objects in these
+cases. This note discusses the pitfalls of using environments for those
+cases where such interfacing is needed.
+
+If \code{e} is an environment then \code{e$x} will only search for \code{x}
+in \code{e} and no further whereas if \code{e} were a proto object its
+ancestors will be searched as well. For example, if the parent of a
+\code{proto} object is an \code{environment} but not itself a \code{proto}
+object then \code{.super$x} references in the methods of that object will
+only look as far as the parent.
+
+Also note that the form \code{e$meth(...)} when used with an environment
+will not automatically insert \code{e} as the first argument and so
+environments can only be used with methods by using the more verbose
+\code{e$meth(e, ...)}. Even then it is not exactly equivalent since
+\code{meth} will only be looked up in \code{e} but not its ancestors. To get
+precise equivalence write the even more verbose \code{with(e, meth)(e,
+...)}.
+
+If the user has a proto object \code{obj} which is a child of the global
+environment and whose methods use \code{.super} then \code{.super} will
+refer to an environment, not a proto object (unless the global environment
+is coerced to a proto object) and therefore be faced with the search
+situation discussed above. One solution is to create an empty root object
+between the global environment and \code{obj} as in this diagram \code{Root
+<- obj$.super <- proto(.GlobalEnv)} where \code{Root} is the root object.
+Now \code{.super} references will reference \code{Root}, which is a proto
+object so search will occur as expected. \code{proto} does not provide such
+a root object automatically but the user can create one easily, if desired.
+
+Although not recommended, it possible to coerce the global environment to a
+proto object by issuing the command \code{as.proto(.GlobalEnv)}. This will
+effectively make the global environment a proto root object but has the
+potential to break other software, although the authors have not actually
+found any software that it breaks.
+}
+\examples{
+oo <- proto(expr = {
+ x = c(10, 20, 15, 19, 17)
+ location = function(.) mean(.$x) # 1st arg is object
+ rms = function(.) sqrt(mean((.$x - .$location())^2))
+ bias = function(., b) .$x <- .$x + b
+})
+
+debug(oo$with(rms)) # cannot use oo$rms to pass method as a value
+undebug(oo$with(rms)) # cannot use oo$rms to pass method as a value
+
+oo2 <- oo$proto( location = function(.) median(.$x) )
+oo2$rms() # note that first argument is omitted.
+oo2$ls() # list components of oo2
+oo2$as.list() # contents of oo2 as a list
+oo2 # oo2 itself
+oo2$parent.env() # same
+oo2$parent.env()$as.list() # contents of parent of oo2
+oo2$print()
+oo2$ls()
+oo2$str()
+oo3 <- oo2
+oo2$identical(oo3)
+oo2$identical(oo)
+
+# start off with Root to avoid problem cited in Note
+Root <- proto()
+oop <- Root$proto(a = 1, incr = function(.) .$a <- .$a+1)
+ooc <- oop$proto(a = 3) # ooc is child of oop but with a=3
+ooc$incr()
+ooc$a # 4
+
+# same but proto overridden to force a to be specified
+oop$proto <- function(., a) { .super$proto(., a=a) }
+\dontrun{
+ooc2 <- oop$proto() # Error. Argument "a" is missing, with no default.
+}
+ooc2 <- oop$proto(a = 10)
+ooc2$incr()
+ooc2$a # 11
+
+# use of with to eliminate having to write .$a
+o2 <- proto(a = 1, incr = function(.) with(., a <- a+1))
+o2c <- as.proto(o2$as.list()) # o2c is a clone of o2
+o2d <- o2$proto() # o2d is a child of o2
+o2$a <- 2
+o2c$a # a not changed by assignment in line above
+o2d$a # a is changed since a not found in o2d so found in o2
+
+p <- proto(a = 0, incr = function(., x) .$a <- .$a + x)
+pc <- p$proto(a = 100)
+
+p$incr(7)
+p$incr(x=7)
+p$a
+
+}
+\seealso{
+\code{\link{as.list}}, \code{\link{names}},
+\code{\link{environment}}
+}
+\keyword{programming}
+
diff --git a/tests/testthat.R b/tests/testthat.R
new file mode 100644
index 0000000..bcbab1f
--- /dev/null
+++ b/tests/testthat.R
@@ -0,0 +1,4 @@
+library(testthat)
+library(proto)
+
+test_check("proto")
diff --git a/tests/testthat/test-getting.R b/tests/testthat/test-getting.R
new file mode 100644
index 0000000..e409415
--- /dev/null
+++ b/tests/testthat/test-getting.R
@@ -0,0 +1,33 @@
+context("Getting")
+
+test_that("$ returns values as is", {
+ x <- proto(x = 1)
+
+ expect_equal(x$x, 1)
+})
+
+test_that("$ inherits from parent", {
+ x <- proto(x = 1)
+ y <- proto(x, y = 2)
+
+ expect_equal(y$x, 1)
+})
+
+test_that("$ doesn't inherit if name starts with ..", {
+ x <- proto(..x = 1)
+ y <- proto(x, ..y = 2)
+
+ expect_error(y$..x, "not found")
+})
+
+test_that("methods are given class protoMethod", {
+ x <- proto(f = function(.) 1 + 2)
+
+ expect_is(x$f, "protoMethod")
+})
+
+test_that("first argument passed to method is object itself", {
+ x <- proto(x = 1, y = 2)
+
+ expect_equal(x$ls(), c("x", "y"))
+})
diff --git a/tests/testthat/test-printing.R b/tests/testthat/test-printing.R
new file mode 100644
index 0000000..c432911
--- /dev/null
+++ b/tests/testthat/test-printing.R
@@ -0,0 +1,13 @@
+context("printing")
+
+test_that("can override printing with proto_print", {
+ x <- proto(proto_print = function(.) 10)
+ out <- capture.output(print(x))[[1]]
+ expect_match(out, "10")
+})
+
+test_that("default object prints as environment", {
+ x <- proto()
+ out <- capture.output(print(x))[[1]]
+ expect_match(out, "environment")
+})
diff --git a/vignettes/README b/vignettes/README
deleted file mode 100755
index 190065d..0000000
--- a/vignettes/README
+++ /dev/null
@@ -1,5 +0,0 @@
-To build the vignette:
-
-* vignette building is now straightforward using R CMD build
-
-
diff --git a/vignettes/Z.cls b/vignettes/Z.cls
deleted file mode 100755
index 1be2e59..0000000
--- a/vignettes/Z.cls
+++ /dev/null
@@ -1,173 +0,0 @@
-\def\fileversion{1.0}
-\def\filename{Z}
-\def\filedate{2004/10/08}
-%%
-%% Package `Z' to use with LaTeX2e for Z reports
-%% Copyright (C) 2004 Achim Zeileis
-%%
-\NeedsTeXFormat{LaTeX2e}
-\ProvidesClass{Z}[\filedate\space\fileversion\space Z class by Achim Zeileis]
-
-%% options
-\LoadClass[10pt,a4paper,twoside]{article}
-
-%% required packages
-\RequirePackage{graphicx,a4wide,color,hyperref,ae,fancyvrb,thumbpdf}
-\RequirePackage[T1]{fontenc}
-\usepackage[authoryear,round,longnamesfirst]{natbib}
-\bibpunct{(}{)}{;}{a}{}{,}
-\bibliographystyle{jss}
-
-%% paragraphs
-\setlength{\parskip}{0.7ex plus0.1ex minus0.1ex}
-\setlength{\parindent}{0em}
-
-%% commands
-\let\code=\texttt
-\let\proglang=\textsf
-\newcommand{\pkg}[1]{{\normalfont\fontseries{b}\selectfont #1}}
-\newcommand{\email}[1]{\href{mailto:#1}{\normalfont\texttt{#1}}}
-\newcommand{\E}{\mathsf{E}}
-\newcommand{\VAR}{\mathsf{VAR}}
-\newcommand{\COV}{\mathsf{COV}}
-\newcommand{\Prob}{\mathsf{P}}
-
-%% for all publications
-\newcommand{\Plaintitle}[1]{\def\@Plaintitle{#1}}
-\newcommand{\Shorttitle}[1]{\def\@Shorttitle{#1}}
-\newcommand{\Plainauthor}[1]{\def\@Plainauthor{#1}}
-\newcommand{\Keywords}[1]{\def\@Keywords{#1}}
-\newcommand{\Plainkeywords}[1]{\def\@Plainkeywords{#1}}
-\newcommand{\Abstract}[1]{\def\@Abstract{#1}}
-
-%% defaults
-\author{Firstname Lastname\\Affiliation}
-\title{Title}
-\Abstract{---!!!---an abstract is required---!!!---}
-\Plainauthor{\@author}
-\Plaintitle{\@title}
-\Shorttitle{\@title}
-\Keywords{---!!!---at least one keyword is required---!!!---}
-\Plainkeywords{\@Keywords}
-
-%% Sweave(-like)
-\DefineVerbatimEnvironment{Sinput}{Verbatim}{fontshape=sl}
-\DefineVerbatimEnvironment{Soutput}{Verbatim}{}
-\DefineVerbatimEnvironment{Scode}{Verbatim}{fontshape=sl}
-\newenvironment{Schunk}{}{}
-\setkeys{Gin}{width=0.8\textwidth}
-
-%% new \maketitle
-\def\maketitle{
- \begingroup
- \def\thefootnote{\fnsymbol{footnote}}
- \def\@makefnmark{\hbox to 0pt{$^{\@thefnmark}$\hss}}
- \long\def\@makefntext##1{\parindent 1em\noindent
- \hbox to1.8em{\hss $\m at th ^{\@thefnmark}$}##1}
- \@maketitle \@thanks
- \endgroup
- \setcounter{footnote}{0}
- \thispagestyle{empty}
- \markboth{\centerline{\@Shorttitle}}{\centerline{\@Plainauthor}}
- \pagestyle{myheadings}
-
- \let\maketitle\relax \let\@maketitle\relax
- \gdef\@thanks{}\gdef\@author{}\gdef\@title{}\let\thanks\relax
-}
-
-\def\@maketitle{\vbox{\hsize\textwidth \linewidth\hsize
- {\centering
- {\LARGE\bf \@title\par}
- \def\And{\end{tabular}\hfil\linebreak[0]\hfil
- \begin{tabular}[t]{c}\large\bf\rule{\z@}{24pt}\ignorespaces}%
- \begin{tabular}[t]{c}\large\bf\rule{\z@}{24pt}\@author\end{tabular}%
- \vskip 0.3in minus 0.1in
- \hrule
- \begin{abstract}
- \@Abstract
- \end{abstract}}
- \textit{Keywords}:~\@Keywords.
- \vskip 0.1in minus 0.05in
- \hrule
- \vskip 0.2in minus 0.1in
-}}
-
-
-%% sections, subsections, and subsubsections
-\newlength{\preXLskip}
-\newlength{\preLskip}
-\newlength{\preMskip}
-\newlength{\preSskip}
-\newlength{\postMskip}
-\newlength{\postSskip}
-\setlength{\preXLskip}{1.8\baselineskip plus 0.5ex minus 0ex}
-\setlength{\preLskip}{1.5\baselineskip plus 0.3ex minus 0ex}
-\setlength{\preMskip}{1\baselineskip plus 0.2ex minus 0ex}
-\setlength{\preSskip}{.8\baselineskip plus 0.2ex minus 0ex}
-\setlength{\postMskip}{.5\baselineskip plus 0ex minus 0.1ex}
-\setlength{\postSskip}{.3\baselineskip plus 0ex minus 0.1ex}
-
-\newcommand{\jsssec}[2][default]{\vskip \preXLskip%
- \pdfbookmark[1]{#1}{Section.\thesection.#1}%
- \refstepcounter{section}%
- \centerline{\textbf{\Large \thesection. #2}} \nopagebreak
- \vskip \postMskip \nopagebreak}
-\newcommand{\jsssecnn}[1]{\vskip \preXLskip%
- \centerline{\textbf{\Large #1}} \nopagebreak
- \vskip \postMskip \nopagebreak}
-
-\newcommand{\jsssubsec}[2][default]{\vskip \preMskip%
- \pdfbookmark[2]{#1}{Subsection.\thesubsection.#1}%
- \refstepcounter{subsection}%
- \textbf{\large \thesubsection. #2} \nopagebreak
- \vskip \postSskip \nopagebreak}
-\newcommand{\jsssubsecnn}[1]{\vskip \preMskip%
- \textbf{\large #1} \nopagebreak
- \vskip \postSskip \nopagebreak}
-
-\newcommand{\jsssubsubsec}[2][default]{\vskip \preSskip%
- \pdfbookmark[3]{#1}{Subsubsection.\thesubsubsection.#1}%
- \refstepcounter{subsubsection}%
- {\large \textit{#2}} \nopagebreak
- \vskip \postSskip \nopagebreak}
-\newcommand{\jsssubsubsecnn}[1]{\vskip \preSskip%
- {\textit{\large #1}} \nopagebreak
- \vskip \postSskip \nopagebreak}
-
-\newcommand{\jsssimplesec}[2][default]{\vskip \preLskip%
-%% \pdfbookmark[1]{#1}{Section.\thesection.#1}%
- \refstepcounter{section}%
- \textbf{\large #1} \nopagebreak
- \vskip \postSskip \nopagebreak}
-\newcommand{\jsssimplesecnn}[1]{\vskip \preLskip%
- \textbf{\large #1} \nopagebreak
- \vskip \postSskip \nopagebreak}
-
-\renewcommand{\section}{\secdef \jsssec \jsssecnn}
-\renewcommand{\subsection}{\secdef \jsssubsec \jsssubsecnn}
-\renewcommand{\subsubsection}{\secdef \jsssubsubsec \jsssubsubsecnn}
-
-%% colors
-\definecolor{Red}{rgb}{0.7,0,0}
-\definecolor{Blue}{rgb}{0,0,0.8}
-\hypersetup{%
- hyperindex = {true},
- colorlinks = {true},
- linktocpage = {true},
- plainpages = {false},
- linkcolor = {Blue},
- citecolor = {Blue},
- urlcolor = {Red},
- pdfstartview = {Fit},
- pdfpagemode = {UseOutlines},
- pdfview = {XYZ null null null}
-}
-
-\AtBeginDocument{
- \hypersetup{%
- pdfauthor = {\@Plainauthor},
- pdftitle = {\@Plaintitle},
- pdfkeywords = {\@Plainkeywords}
- }
-}
-\AtBeginDocument{\maketitle}
diff --git a/vignettes/cloning3.dot b/vignettes/cloning3.dot
deleted file mode 100755
index 7ed2657..0000000
--- a/vignettes/cloning3.dot
+++ /dev/null
@@ -1,8 +0,0 @@
-digraph G {
-graph [rankdir = BT];
-"oo.res" -> "oo" ;
-"oos" -> "oo" ;
-"oos.res" -> "oos" ;
-"oos.res" -> "oo.res" [style=dashed] ;
-}
-
diff --git a/vignettes/cloning3.pdf b/vignettes/cloning3.pdf
old mode 100755
new mode 100644
diff --git a/vignettes/proto-concordance.tex b/vignettes/proto-concordance.tex
new file mode 100644
index 0000000..278eb24
--- /dev/null
+++ b/vignettes/proto-concordance.tex
@@ -0,0 +1,2 @@
+\Sconcordance{concordance:proto.tex:proto.Rnw:%
+1 1357 1}
diff --git a/vignettes/proto-dot.pdf b/vignettes/proto-dot.pdf
old mode 100755
new mode 100644
index f812be2..38f1d50
Binary files a/vignettes/proto-dot.pdf and b/vignettes/proto-dot.pdf differ
diff --git a/vignettes/proto-dot.tex b/vignettes/proto-dot.tex
old mode 100755
new mode 100644
diff --git a/vignettes/proto-raw b/vignettes/proto-raw
deleted file mode 100755
index 032d818..0000000
--- a/vignettes/proto-raw
+++ /dev/null
@@ -1,1276 +0,0 @@
-\SweaveOpts{engine=R,eps=FALSE}
-
-%\VignetteIndexEntry{proto: An R Package for Prototype Programming}
-%\VignetteDepends{}
-%\VignetteKeywords{object oriented, prototype programming, S3, R}
-%\VignettePackage{proto}
-
-
-\documentclass{Z}
-\DeclareGraphicsExtensions{.pdf, .eps, .png}
-
-%% need no \usepackage{Sweave}
-
-\newlength{\half}
-\setlength{\half}{70mm}
-
-\author{Louis Kates\\GKX Associates Inc. \And
- Thomas Petzoldt\\Technische Universit\"at Dresden}
-\Plainauthor{Louis Kates, Thomas Petzoldt}
-
-\title{\pkg{proto}: An \proglang{R} Package for Prototype Programming}
-%% \Shorttitle{\pkg{proto}: An \proglang{R} Package for Prototype Programming}
-
-\Plaintitle{proto: An R Package for Prototype Programming}
-
-\Keywords{prototype programming, delegation, inheritance, clone,
- object orientated, \proglang{S3}, \proglang{R}}
-\Plainkeywords{object oriented, prototype programming, S3, R}
-
-\Abstract{
-
- \pkg{proto} is an \proglang{R} package which facilitates a style
- of programming known as prototype
- programming. Prototype programming is a type of object
- oriented programming in which there are no classes.
- \pkg{proto} is simple yet retains the object oriented features of
- delegation (the prototype counterpart to inheritance)
- and object oriented dispatch. \code{proto} can be used
- to organize the concrete data and procedures in statistical studies
- and other applications
- without the necessity of defining classes while still providing convenient
- access to an object oriented style of programming. Furthermore, it
- can be used in a class-based style as well so that incremental design can
- begin with defining the concrete objects and later transition to abstract
- classes, once the general case is understood, without having to change to
- object-oriented frameworks.
- The key goals of the package are to integrate into \proglang{R}
- while providing nothing more than a thin layer on top of it.
-}
-
-\hyphenation{ma-ni-pu-lating}
-
-\begin{document}
-
-
-
-<<preliminaries,echo=FALSE,results=hide>>=
-rm(list=ls())
-library(proto)
-@
-
-\section{Introduction} \label{sec:intro}
-
-\subsection[Object Oriented Programming in R]{Object Oriented Programming in \proglang{R}}
-\label{sec:oo}
-
-The \proglang{R} system for statistical computing
-\citep[\url{http://www.R-project.org/}]{Rcore2005} ships with two
-systems for object oriented programming referred to as \proglang{S3}
-and \proglang{S4}. With the increased interest in object oriented
-programming within \proglang{R} over the last years additional object
-oriented programming packages emerged. These include the \pkg{R.oo}
-package \citep{Bengtsson2003} and the \pkg{OOP} package
-\citep[\url{http://www.omegahat.org/OOP/}]{Rnews:Chambers+Lang:2001a}.
-The common thread among these packages is that they use
-classes as the basis of inheritance. When a message is sent to an
-object the class of the object is examined and that class determines the
-specific function to be executed. In contrast, in prototype programming
-there are no classes yet it retains much of the power of
-class-based programming. In the fact, \pkg{proto} is so simple that
-there are only two significant new routine name, \code{proto}, and
-\code{clone2}. The
-other routines are just the expected support routines such as
-\code{as.proto} to coerce objects to proto objects, \code{\$} to
-access and set proto object components and \code{is.proto} to check
-whether an object is a proto object. In addition, \code{graph.proto}
-will generate a graphical ancestor tree showing the parent-child
-relationships among generated \code{proto} objects.
-
-The aim of the package is to provide a lightweight layer for prototype
-programming in \proglang{R} written only in \proglang{R} leveraging the
-existing facilities of the language rather than adding its own.
-
-\subsection{History}
-\label{sec:history}
-
-The concept of prototype programming
-\citep{Lieberman1986, Taivalsaari1996a, Noble1999}
-has developed over a number of years with the \proglang{Self}
-language \citep{Agesen1992}
-being the key evolved programming language to demonstrate
-the concept. In statistics, the \proglang{Lisp}-based
-\proglang{LispStat} programming language \citep{Tierney1990} was
-the first and possibly only statistical system to feature prototype
-programming.
-
-Despite having been developed over 20 years ago, and some attempts to
-enter the mainstream (e.g. \proglang{Newtonscript}
-on the Newton computer, which
-is no longer available, and \proglang{Javascript} where
-it is available but whose
-domain of application largely precludes use of prototype programming)
-prototype programming is not well known due to lack of language
-support in popular programming languages such as \proglang{C} and
-\proglang{Java}. It tends
-to be the domain of research languages or \proglang{Lisp}.
-
-Thus the availability of a popular language,
-\proglang{R} \footnote{Some indications of the popularity of R are
-the high volume mailing lists, international development team, the
-existence of over 1000 addon packages, conferences and numerous books
-and papers devoted to R.},
-that does provide the key infrastructure could be important for developers.
-
-This work grew out of the need to organize multiple scenarios of model
-simulations in ecological modelling \citep{Rnews:Petzoldt:2003} and
-was subsequently generalized to the present package. A number of
-iterations of the code, some motivated by the ever increasing feature
-set in \proglang{R}, resulted in a series of utilities and ultimately
-successive versions of an \proglang{R} package developed over a period of
-several years. An initial version used \proglang{R} lists as the basis of the
-package. Subsequently the package was changed to use \proglang{R}
-environments. The first version to use environments stored the
-receiver object variable in a proxy parent environment which was
-created on-the-fly at each method call. The present version of
-the \pkg{proto} package passes the receiver object through the argument list,
-while hiding this from the caller. It defines the \code{proto} class
-as a subclass of the \code{environment} class so that
-functionality built into \proglang{R} for the environment class is
-automatically inherited by the \code{proto} class.
-
-\subsection{Overview}
-\label{sec:overview}
-
-It is assumed that the reader has some general
-familiarity with object oriented programming concepts and with
-\proglang{R}.
-
-The paper will proceed primarily by example focusing on illustrating
-the package \code{proto} through such demonstration. The remainder of
-the paper is organized as follows: Section~\ref{sec:proto-class}
-explains how \code{"proto"} objects are created and illustrates the
-corresponding methods for setting and getting components. It further
-discusses how object oriented delegation (the prototype programming
-analogue of inheritance) is handled and finally discusses the
-internals of the package. This section uses small examples chosen for
-their simplicity in illustrating the concepts. In
-Section~\ref{sec:examples} we provide additional examples of prototype
-programming in action. Four examples are shown. The first involves
-smoothing of data. Secondly we demonstrate the calculation of
-correlation confidence intervals using classical (Fisher Transform)
-and modern (bootstrapping) methods. Thirdly we demonstrate the
-development of a binary tree as would be required for a dendrogram.
-Fourthly, we use the solution of linear equations to illustrate
-program evolution from object-based to class-based, all
-within the \pkg{proto} framework.
-Section~\ref{sec:summary} gives a few summarizing remarks. Finally,
-an appendix provides a reference card that summarizes the
-functionality contained in \pkg{proto} in terms of its constituent
-commands.
-
-%% \pagebreak[4]
-
-\section[The class "proto" and its methods]{The class \code{"proto"} and its methods}
-\label{sec:proto-class}
-
-\subsection[Creation of "proto" objects]{Creation of \code{"proto"} objects}
-\label{sec:proto}
-
-In this section we shall show, by example, the creation of two
-prototype objects and related operations. The simple idea is that
-each \code{"proto"} object is a set of components: functions (methods)
-and variables, which are tightly related in some way.
-
-A prototype object is an environment holding the variables and
-methods of the object. \footnote{In particular this implies that
-\code{"proto"} objects have single inheritance, follow ordinary
-environment scoping rules and have mutable state as environments
-do.}
-
-A prototype object is created using the constructor function
-\code{proto} (see Appendix~\ref{sec:ref} at the end of this paper or
-\pkg{proto} package help for complete syntax of commands).
-
-\begin{Scode}
-addProto <- proto( x = rnorm(5), add = function(.) sum(.$x) )
-\end{Scode}
-
-In this simple example, the \code{proto} function defines two
-components: a variable \code{x} and a method \code{add}. The variable
-\code{x} is a vector of 5 numbers and the method sums those numbers.
-The \code{proto} object \code{addProto} contains the variable and the
-method. Thus the \code{addProto} \code{proto} object can be used to compute
-the sum of the values stored in it.
-As shown with the \code{add} method in this example, formal argument
-lists of methods must always have a first argument of dot
-(i.e. \code{.}) which signifies the object on which the method is
-operating. The dot refers to the current object in the same way that
-a dot refers to the current directory in UNIX. Within the method one
-must refer to other variables and methods in the object by prefacing
-each with \code{.\$}. For example, in the above we write
-\code{sum(.\$x)}. Finally, note that the data and the method are very
-closely related. Such close coupling is important in order to create
-an easily maintained system.
-
-To illustrate the usage of \code{proto}, we first load the package and
-set the random seed to make the examples in this paper exactly
-reproducible.
-
-<<proto-library>>=
-library(proto)
-set.seed(123)
-@
-
-Then, we create the \code{proto} object from above
-and call its \code{add} method.
-<<proto-addProto>>=
-addProto <- proto( x = rnorm(5), add = function(.) sum(.$x) )
-addProto$add()
-@
-We also create another object, \code{addProto2}
-with a different \code{x} vector and
-invoke its \code{add} method too.
-<<proto-addProto2>>=
-addProto2 <- addProto$proto( x = 1:5 )
-addProto2$add()
-@
-In the examples above, we created a prototype object \code{addProto}
-and then called its \code{add} method as just explained.
-The notation \code{addProto\$add}
-tells the system to look for the \code{add} method
-in the \code{addProto} object. In the expression \code{addProto\$add},
-the \code{proto} object to the left
-of the dollar sign, \code{addProto} here, is referred to as the
-\emph{receiver} object. This expression
-also has a second purpose which is to
-pass the receiver object implicitly as the first argument of \code{add}.
-Note that we called \code{add} as if it had zero arguments but, in fact,
-it has one argument because the receiver is automatically and implicitly
-supplied as the first argument. In general,
-the notation \code{object\$method(arguments)} is
-used to invoke the indicated method of the receiver object using the
-object as the implicit first argument along with the indicated
-arguments as the subsequent arguments.
-As with the \code{addProto} example, the receiver
-object not only determines where to find the
-method but also is implicitly passed to the method through
-the first argument. The motivation for this notation
-is to relieve the user of
-specifying the receiver object twice:
-once to locate the method in the object and a second
-time to pass the object itself to the method.
-The \code{\$} is overloaded by the \code{proto}
-class to automatically do both with one reference to the receiver object.
-Even though, as with the \code{addProto} example, the first
-argument is not listed in the call
-it still must be listed among the formal arguments
-in the definition of the method. It
-is conventional to use
-a dot \code{.} as the first formal argument in the method/function
-definition. That is, we call \code{add} using \code{addProto\$add()}
-displaying zero arguments
-but we define \code{add} in \code{addProto} displaying
-one argument \code{add <- function(.)}, the dot.
-
-In this example,
-we also created a second object, \code{addProto2},
-which has the first object, \code{addProto} as its parent.
-Any reference to a
-component in the second object that is unsuccessful will cause
-search to continue in the parent. Thus the call \code{addProto2\$add()}
-looks for \code{add} in \code{addProto2} and not finding it there
-searches its parent, \code{addProto}, where it is, indeed, found.
-\code{add} is invoked with the receiver object, \code{addProto2}, as
-the value of dot.
-The call \code{addProto2\$add()} actually causes the \code{add}
-in \code{addProto} to run but it still uses the \code{x} from
-\code{addProto2} since dot (\code{.}) is \code{addProto2} here
-and \code{add} references \code{.\$x}.
-Note that the reference to \code{.\$x} in the
-\code{add} found in \code{addProto}
-does not refer to the \code{x} in \code{addProto} itself.
-The \code{x} in \code{addProto2} has overridden the \code{x} in its parent.
-This point is important so the reader should take care to absorb this
-point.
-
-This simple example already shows the key elements of the system
-and how \emph{delegation} (the prototype programming term for inheritance)
-works without classes.
-
-We can add new components or replace components in an object and
-invoke various methods like this:
-<<proto-addProto2more>>=
-addProto2$y <- seq(2,10,2)
-addProto2$x <- 1:10
-addProto2$add3 <- function(., z) sum(.$x) + sum(.$y) + sum(z)
-addProto2$add()
-addProto2$add3(c(2,3,5))
-addProto2$y
-@
-
-In this example, we insert variable \code{y} into the object \code{addProto2}
-with a value of \code{seq(2,10,2)},
-reset variable \code{x} to a new value and insert a new method,
-\code{add3}. Then we invoke
-our two methods and display \code{y}. Again, note that in the case of
-\code{protoAdd2\$add} the \code{add} method is not present in
-\code{protoAdd2} and so search continues to the parent \code{addProto}
-where it is found.
-
-\subsection{Internals}
-\label{sec:internals}
-
-So far, we have used simple examples to illustrate the basic manipulation
-of objects: construction, getting and setting components and method
-invocation. We now discuss the internals of the package and how it relates
-to \proglang{R} constructs.
-\code{proto} is actually an \proglang{S3} class which is a subclass
-of the \code{environment} class. Every \code{proto} object is an
-environment and its class is \code{c("proto", "environment")}. The \code{\$}
-accessor is similar to the same accessor in environments except it will
-use the \proglang{R} \code{get} function to
-search up parent links if it cannot otherwise find the object (unlike
-environments). When accessing a method, \code{\$}
-automatically supplies the
-first argument to the method
-unless the object is \code{.that} or \code{.super}. \code{.that}
-is a special variable which \code{proto} adds to every \code{proto} object
-denoting the object itself. \code{.super} is also added to every
-proto object and is the parent of \code{.that}. \code{.that}
-and \code{.super} are normally used
-within methods of an object to refer to other components of the same
-or parent object, respectively,
-as opposed to the receiver (\code{.}). For example,
-suppose we want \code{add} in \code{addProto2} to add the elements
-of \code{x} together and the elements of
-\code{y} together and then add these two sums. We could redefine add like this:
-
-<<proto-addProto2-super>>=
-addProto2$add <- function(.) .super$add(.) + sum(.$y)
-@
-
-making use of the \code{add} already defined in the parent.
-One exception should be noted here. When one uses \code{.super},
-as above, or \code{.that} to specify a method then the receiver
-object must be explicitly specified
-in argument one (since in those cases the receiver
-is possibly different than
-\code{.super} or \code{.that} so the system cannot automatically supply it
-to the call.)
-
-Setting a value is similar to the corresponding operation for
-environments except that any function, i.e method, which is
-inserted has its environment set to the environment of the object
-into which it is being inserted. This is necessary so that such
-methods can reference \code{.that} and \code{.super} using
-lexical scoping.
-
-In closing this section a few points should be re-emphasized and
-expanded upon. A
-\code{proto} object is an environment whose parent object is the
-parent environment of the \code{proto} object. The methods in the \code{proto}
-objects are ordinary functions that have the containing object as their
-environment.
-
-The \proglang{R} \code{with} function can be used with environments and
-therefore can be used with \code{proto} objects since \code{proto}
-objects are environments too. Thus \code{with(addProto, x)} refers
-to the variable \code{x} in \code{proto} object \code{addProto}
-and \code{with(addProto, add)} refers to the method \code{add}
-in the same way. \code{with(addProto, add)(addProto)} can be used
-to call \code{add}. These constructs all follow from their corresponding
-use in environments from which they are inherited.
-
-Because the \code{with} expressions are somewhat verbose, two common
-cases can be shortened using the \code{\$} operator. \code{addProto\$x}
-can be used to refer to variable \code{x} in \code{proto} object
-\code{addProto} and has the same meaning as \code{with(addProto, x)}.
-In particular like \code{with} but
-unlike the the behavior of the \code{\$} operator on
-environments, when used with \code{proto} objects, \code{\$} will
-search not only the object itself but also its ancestors.
-Similarly \code{addProto\$add()} can be used to call
-method \code{add} in \code{addProto} also searching through ancestors
-if not found in \code{addProto}. Note that \code{addProto\$add}
-returns an object of class
-
-\code{c("instantiatedProtoMethod", "function")}
-which is derived from \code{add} such that the first argument,
-the \code{proto} object,
-is already inserted. Note that there is a \code{print} method for
-class \code{"instantiatedProtoMethod"} so printing such objects will
-display the underlying function but returning such objects
-is not the same as returning the function without slot one inserted.
-Thus, if one wants exactly the original \code{add}
-as a value one should use \code{with(addProto, add)} or
-\code{addProto\$with(add)}.
-
-Within a method, if a variable is referred to without
-qualification simply as \code{x}, say, then its meaning is
-unchanged from how it is otherwise used in \proglang{R} and
-follows the same scope rules as any variable to resolve its name. If it is
-desired that the variable have object scope, i.e. looked up
-in the receiver object and its ancestors, then \code{.\$x}
-or similar \code{with} notation, i.e. \code{with(., x)}, should be used.
-Similarly \code{.\$f(x)} calls
-method \code{f} automatically inserting the receiver object
-into argument one and using \code{x} for argument two. It
-looks for \code{f} first in the receiver object and then its
-ancestors.
-
-\subsection{Traits}
-\label{sec:traits}
-
-Let us look at the definition of a child object once again.
-In the code below,
-\code{addProto} is the previously defined parent object
-and the expression \code{addProto\$proto(x = 1:5)} defines
-a child object of \code{addProto} and assigns it to variable
-\code{addProto2a}.
-
-<<proto-addProto2a>>=
-addProto2a <- addProto$proto(x = 1:5)
-addProto2a$add()
-@
-
-That is, \code{proto} can be used to create a new child of
-an existing object by writing the
-parent object on the left of the \code{\$} and
-\code{proto} on its right. Any contents to
-be added to the new child are listed in arguments of \code{proto}
-as shown.
-
-For example, first let us create a class-like structure. In the
-following \code{Add} is an object that behaves very much like a class
-with an \code{add} method and a method \code{new} which constructs
-new objects. In the line creating object \code{add1} the expression
-\code{Add\$new(x = 1:5)} invokes the \code{new} constructor of the
-receiver object \code{Add}. The method \code{new} has an argument of
-\code{x = 1:5} which defines an \code{x} variable in the \code{add1}
-object being instantiated. We similarly create another object
-\code{add2}.
-
-<<proto-Add>>=
-Add <- proto(
- add = function(.) sum(.$x),
- new = function(., x) .$proto(x=x)
-)
-add1 <- Add$new(x = 1:5)
-add1$add()
-add2 <- Add$new(x = 1:10)
-add2$add()
-@
-
-An object which contains only methods and variables that are
-intended to be shared by all its children (as opposed to an
-object whose purpose is to have its own methods and variables)
-is known as a \emph{trait} \citep{Agesen1992}. It
-is similar to a class in class-based
-object oriented programming.
-Note that the objects \code{add1} and \code{add2} have the trait
-\code{Add} as their parent. We could implement subclass-like and
-superclass-like objects by simply defining similar trait objects to
-be the parent or child of \code{Add}. For example, suppose we
-want a class which calculates the sum of the logarithms of the data. We
-could define:
-
-<<proto-Logadd>>=
-Logadd <- Add$proto( logadd = function(.) log( .$add() ) )
-logadd1 <- Logadd$new(1:5)
-logadd1$logadd()
-@
-
-Here the capitalized objects are traits.
-\code{Logadd} is a trait. It is a child of \code{Add}
-which is also a trait. \code{logadd1} is an ordinary object,
-not a trait.
-One possible design is to create a tree of traits and other objects
-in which the leaves are ordinary objects and the remaining nodes
-are traits. This would closely correspond to class-based
-object oriented programming.
-
-Note that the delegation of methods from
-one trait to another as in
-\code{new} which is inherited by \code{Logadd} from \code{Add}
-is nothing more than the same mechanism by which traits delegate
-methods to
-objects since, of course, traits are just objects no different
-from any other object other than by the conventions we impose on them.
-This unification of subclassing and instantiation beautifully
-shows the simplification that prototype programming represents.
-
-\subsection{Utilities}
-\label{sec:utilities}
-The fact that method calls automatically insert the first argument
-can be used to good effect in leveraging existing \proglang{R}
-functions while allowing an object-oriented syntax.
-
-For example, \code{ls()} can be used to list the components of
-\code{proto} objects:
-
-<<proto-util>>=
-addProto$ls()
-@
-
-Functions like:
-
-<<proto-util2,eval=FALSE>>=
-addProto$str()
-addProto$print()
-addProto$as.list()
-addProto2a$parent.env()
-@
-
-show additional information about the elements. \code{eapply}
-can be used to explore more properties such as the
-the length of each component of an object:
-
-<<proto-util3,eval=FALSE>>=
-addProto$eapply(length) # show length of each component
-@
-
-Another example of some interest in any object oriented system
-which allows multiple references to one single object is that
-object identity
-can be tested using the respective base function:
-
-<<proto-util3>>=
-addProto$identical(addProto2)
-@
-
-\code{proto} does contain a special purpose \code{str.proto} function
-but in the main it
-is important to notice here, that
-\code{proto} has no code that is specific to \code{ls} or
-any of the other ordinary \proglang{R}
-functions listed. We are simply making use of the
-fact that \code{obj\$fun(...)} is transformed into \code{get("fun",
-obj)(obj, ...)} by the proto \code{\$} operator. For example, in the
-case of \code{addProto\$ls()} the system looks for \code{ls} in object
-\code{addProto}. It cannot find it there so it looks to its parent,
-which is the global environment. It does not find it there so it
-searches the remainder of the search path, i.e. the path shown by
-running the \proglang{R} command \code{search()}, and finally finds it
-in the base package, invoking it with an argument of \code{addProto}.
-Since all \code{proto} objects are also environments
-\code{ls(addProto)} interprets \code{addProto} as an environment and
-runs the \code{ls} command with it. In the \code{ls} example there
-were no arguments other than \code{addProto}, and even that one was
-implicit, but if there were
-additional arguments then they would be passed as shown in the
-\code{eapply} and \code{identical} examples above.
-
-\subsection{Plotting}
-\label{sec:plot}
-
-The \code{graph.proto} function can be used to create
-graphs that can be rendered by the \code{Rgraphviz} package
-creating visual representations of ancestor trees (figure
-\ref{fig:proto-dot}).
-That package provides an interface to the
-\proglang{GraphViz} \code{dot} program \citep{Ganser+North:1999}.
-
-\code{graph.proto} takes three arguments, all of which are
-usually omitted. The first argument is a \code{proto} object
-(or an environment) out of which all contained \code{proto} objects
-and their parents (but not higher order ancestors) are graphed.
-If it is omitted, the current environment is assumed.
-The second argument is a graph (in the sense of the \code{graph}
-package) to which the nodes and edges are added. If it is omitted
-an empty graph is assumed. The last argument is a logical variable
-that specifies the orientation of arrows. If omitted arrows are
-drawn from children to their parents.
-
-<<proto-dot,fig=TRUE,height=5,split=TRUE,include=FALSE,prefix=FALSE>>=
-library(Rgraphviz)
-g <- graph.proto()
-plot(g)
-@
-
-\input{proto-dot}
-
-\begin{figure}[htbp]
-\begin{center}
-\includegraphics{proto-dot}
-\caption{\label{fig:proto-dot} Ancestor tree generated using graph.proto. Edges
-point from child to parent.}
-\end{center}
-\end{figure}
-
-\pagebreak[4]
-
-\section{Examples}
-\label{sec:examples}
-
-\subsection{Smoothing}
-\label{sec:smooth}
-
-In the following we create a \code{proto} object named \code{oo}
-containing a vector of data \code{x} (generated from a simulated
-autoregressive model) and time points
-\code{tt}, an intermediate result
-\code{x.smooth}, some plotting parameters \code{xlab}, \code{ylab},
-\code{pch}, \code{col} and three methods \code{smooth}, \code{plot}
-and \code{residuals} which smooth the data, plot the data and
-calculate residuals, respectively. We also define \code{..x.smooth}
-which holds intermediate results. Names beginning with two dots
-prevent them from being delegated to children. If we override
-\code{x} in a child we would not want an out-of-sync \code{x.smooth}.
-Note that the components of an object can be specified using a code
-block in place of the argument notation we used previously in the
-\code{proto} command.
-
-<<proto-smoothing01>>=
-oo <- proto(expr = {
- x <- rnorm(251, 0, 0.15)
- x <- filter(x, c(1.2, -0.05, -0.18), method = "recursive")
- x <- unclass(x[-seq(100)]) * 2 + 20
- tt <- seq(12200, length = length(x))
- ..x.smooth <- NA
- xlab <- "Time (days)"
- ylab <- "Temp (deg C)"
- pch <- "."
- col <- rep("black",2)
- smooth <- function(., ...) {
- .$..x.smooth <- supsmu(.$tt, .$x, ...)$y
- }
- plot <- function(.) with(., {
- graphics::plot(tt, x, pch = pch, xlab = xlab,
- ylab = ylab, col = col[1])
- if (!is.na(..x.smooth[1]))
- lines(tt, ..x.smooth, col=col[2])
- })
- residuals <- function(.) with(., {
- data.frame(t = tt, y = x - ..x.smooth)
- })
- })
-@
-
-Having defined our \code{proto} object we can inspect it, as shown
-below, using
-\code{print} which is automatically invoked if the
-name of the object, \code{oo}, is entered on a line by itself.
-In this case, there is no proto print method so we inherit the
-environment print method which displays the environment hash code.
-Although it produces too much output to show here,
-we could have displayed a
-list of the entire contents of the object \code{oo}
-via \code{oo\$as.list(all.names = TRUE)}.
-We can get a list of the names of the
-components of the object using \code{oo\$ls(all.names = TRUE)} and will look
-at the contents of one component, \code{oo\$pch}.
-
-<<proto-smoothing02>>=
-## inspect the object
-oo
-oo$ls(all.names = TRUE)
-oo$pch
-@
-
-Let us illustrate a variety of manipulations. We will set up the
-output to plot 2 plots per screen using \code{mfrow}. We change the
-plotting symbol, smooth the data, invoke the \code{plot} method to
-display a plot of the data and the smooth and then plot the residuals
-in the second plot (figure \ref{fig:proto-smooting03}).
-
-<<proto-smoothing03,split=TRUE,height=3,fig=TRUE,include=FALSE,prefix=FALSE>>=
-## call plot method
-par(mfrow=c(1,2))
-# oo$plot()
-## set a slot
-oo$pch <- 20
-## smooth curve and plot
-oo$smooth()
-oo$plot()
-## plot and analyse residuals, stored in the object
-plot(oo$residuals(), type="l")
-# hist(oo$residuals()$y)
-# acf(oo$residuals()$y)
-@
-
-\input{proto-smoothing03}
-
-\begin{figure}[h!]
-\begin{center}
-\includegraphics[width=\textwidth]{proto-smoothing03}
-\end{center}
-\caption{Data and smooth from \code{oo\$plot()} (left) and plot of
-\code{oo\$residuals()} (right).}
-\label{fig:proto-smooting03}
-\end{figure}
-
-
-Now let us illustrate the creation of a child object and delegation.
-We create a new child object of \code{oo} called \code{oo.res}. We
-will override the \code{x} value in its parent by setting \code{x} in
-the child to the value of the residuals in the parent. We will also
-override the \code{pch} and \code{ylab} plotting parameters. We will
-return to 1 plot per screen and run \code{plot} using the
-\code{oo.res} object as the receiver invoking the \code{smooth} and
-\code{plot} methods (which are delegated from the parent \code{oo})
-with the data in the child (figure \ref{fig:smoothing04}).
-
-<<proto-smoothing04,fig=TRUE,height=5,split=TRUE,include=FALSE,prefix=FALSE>>=
-## derive a new object and change local settings
-oo.res <- oo$proto( pch = "-", x = oo$residuals()$y,
- ylab = "Residuals deg K" )
-
-par(mfrow=c(1,1))
-oo.res$smooth()
-oo.res$plot()
-@
-\input{proto-smoothing04}
-% \begin{figure}[tp]
-\begin{figure}[h!]
-\begin{center}
-\includegraphics[width=\half]{proto-smoothing04}
-\end{center}
-\caption{Output of \code{oo.res\$plot()}.
-\code{oo.res\$x} contains the residuals from \code{oo}.}
-\label{fig:smoothing04}
-\end{figure}
-Now we make use of delegation to change the parent
-and child in a consistent way with respect to certain plot characteristics.
-We have been using a numeric time axis.
-Let us interpret these numbers as the number of days since the Epoch,
-January 1, 1970, and let us also change the plot colors.
-
-<<proto-smoothing05>>=
-## change date format of the parent
-oo$tt <- oo$tt + as.Date("1970-01-01")
-oo$xlab <- format(oo.res$tt[1], "%Y")
-## change colors
-oo$col <- c("blue", "red")
-@
-
-
-We can introduce a new method, \code{splot}, into
-the parent \code{oo} and have it automatically
-inherited by its children. In this example
-it smooths and then plots and we use it with
-both \code{oo} and \code{oo.res} (figure \ref{fig:smoothing06}).
-
-<<proto-smoothing06,fig=TRUE,height=3,split=TRUE,include=FALSE,prefix=FALSE>>=
-## introduce a new function to the parent
-oo$splot <- function(., ...) {
- .$smooth(...)
- .$plot()
-}
-
-## the new function is now available to all children of oo
-par(mfrow=c(1,2))
-oo$splot(bass=2)
-oo.res$splot()
-@
-
-\input{proto-smoothing06}
-
-\begin{figure}[tbp]
-\begin{center}
-\includegraphics[width=\textwidth]{proto-smoothing06}
-\caption{Plotting options and \code{splot} function applied
-to both parent (left) and child (right) object}
-\label{fig:smoothing06}
-\end{center}
-\end{figure}
-
-Numerous possibilities exist to make use of the
-mechanisms shown, so one may create different child objects, apply
-different smoothing parameters, overwrite the smoothing function with
-a lowess smoother and finally compare fits and residuals.
-
-Now lets change the data and repeat the analysis. Rather than
-overwrite the data we will preserve it in \code{oo} and create a child
-\code{oos} to hold an analysis with sinusoidal data.
-
-<<proto-smoothing08,fig=FALSE>>=
-## and at last we change the data and repeat the analysis
-oos <- oo$proto( expr = {
- tt <- seq(0,4*pi, length=1000)
- x <- sin(tt) + rnorm(tt, 0, .2)
-})
-oos$splot()
-#plot(oos$residuals())
-@
-
-Lets perform the residual analysis with \code{oos}.
-We will make a deep copy of \code{oo.res}, i.e. duplicate its
-contents and not merely delegate it, by copying \code{oo.res}
-to a list from which we create the duplicate, or cloned,
-\code{proto} object (figure \ref{fig:smoothing10} and \ref{fig:cloning}):
-
-<<proto-smoothing09,fig=FALSE>>=
-oos.res <- as.proto( oo.res$as.list(), parent = oos )
-oos.res$x <- oos$residuals()$y
-oos.res$splot()
-@
-
-<<proto-smoothing10,fig=TRUE,height=3,split=TRUE,include=FALSE,prefix=FALSE>>=
-par(mfrow=c(1,2))
-oos$splot()
-oos.res$splot()
-@
-
-\begin{figure}[tbp]
-\begin{center}
-\includegraphics[width=\textwidth]{proto-smoothing10}
-\caption{Smoothing of sinusoidal data (left)
-and of their residuals (right)}\label{fig:smoothing10}
-\end{center}
-\end{figure}
-
-\begin{figure}[h!]
-\begin{center}
-\includegraphics[width=50mm]{cloning3.pdf}
-\caption{Cloning (dashed line) and delegation (solid line). Edges point
-from child to parent.}\label{fig:cloning}
-\end{center}
-\end{figure}
-
-We have delegated variables
-and methods and overridden both.
-Thus, even with such a simple analysis, object orientation
-and delegation came into play.
-The reader can plainly see that smoothing and residual
-analysis were not crucial to the example and this example
-could be replaced with any statistical analysis including
-likelihood or other estimation techniques, time series, survival
-analysis, stochastic processes and so on. The key aspect is
-just that we are performing one-of analyses and do not want to
-set up an elaborate class infrastructure but just want to
-directly create objects to organize our calculations while
-relying on delegation and dispatch to eliminate redundancy.
-
-\subsection{Correlation, Fisher's Transform and Bootstrapping}
-\label{sec:corr}
-
-The common approach to
-confidence intervals for the correlation coefficient is to
-assume normality of the underlying data and then use Fisher's transform
-to transform the correlation coefficient to an approximately normal
-random variable.
-Fisher showed that with the above normality assumption, transforming
-the correlation coefficient using
-the hyperbolic arc tangent function
-yields a random variable
-approximately distributed with an
-$\frac{N(p, 1)}{\sqrt(n-3)}$ distribution. The transformed random
-variable can be used to create normal distribution confidence intervals
-and the procedure can be back transformed to get confidence intervals
-for the original correlation coefficient.
-
-A more recent approach to confidence intervals for the correlation
-coefficient is to use bootstrapping. This does not require the
-assumption of normality of the underlying distribution and requires
-no special purpose theory devoted solely to the correlation coefficient,
-
-Let us calculate the 95\%
-confidence intervals using Fisher's transform
-first. We use \code{GNP} and \code{Unemployed} from the Longley data
-set. First we retrieve the data set and extract the required columns
-into \code{x}. Then we set \code{n} to the number of cases
-and \code{pp} to the percentiles
-of interest. Finally we calculate the sample correlation and
-create a function to calculate the confidence interval using
-Fisher's Transform. This function not only returns the confidence
-interval but also stores it in \code{CI} in the receiver object.
-
-<<proto-bootstrap01>>=
-longley.ci <- proto( expr = {
- data(longley)
- x <- longley[,c("GNP", "Unemployed")]
- n <- nrow(x)
- pp <- c(.025, .975)
-
- corx <- cor(x)[1,2]
- ci <- function(.)
- (.$CI <- tanh( atanh(.$corx) + qnorm(.$pp)/sqrt(.$n-3) ))
-})
-@
-
-Now let us repeat this analysis using the bootstrapping approach. We
-derive a new object \code{longley.ci.boot} as child of
-\code{longley.ci}, setting the number of replications, \code{N}, and
-defining the procedure, \code{ci} which does the actual bootstrap
-calculation.
-
-<<proto-bootstrap02>>=
-longley.ci.boot <- longley.ci$proto({
- N <- 1000
- ci <- function(.) {
- corx <- function(idx) cor(.$x[idx,])[1,2]
- samp <- replicate(.$N, corx(sample(.$n, replace = TRUE)))
- (.$CI <- quantile(samp, .$pp))
- }
-})
-@
-
-In the example code below the first line runs the Fisher Transform
-procedure and the second runs the bootstrap procedure. Just to check
-that we have performed sufficient bootstrap iterations we rerun it in
-the third line, creating a delegated object on-the-fly running its
-\code{ci} method and then immediately throwing the object away.
-The fact that 4,000
-replications give roughly the same result as 1,000 replications
-satisfies us that we have used a sufficient number of replications.
-
-<<proto-bootstrap03>>=
-longley.ci$ci()
-longley.ci.boot$ci()
-longley.ci.boot$proto(N=4000)$ci()
-@
-
-We now have the results stored in two objects nicely organized for the
-future. Note, again, that despite the simplicity of the example we
-have used the features of object oriented programming, coupling the
-data and methods that go together, while relying on delegation and
-dispatch to avoid duplication.
-
-\subsection{Dendrograms}
-\label{sec:tree}
-
-In \cite{Gentleman2002} there is an \proglang{S4}
-example of creating a binary tree
-for use as a dendrogram. Here we directly define a binary tree with no
-setup at all. To keep it short we will create a binary tree of only
-two nodes having a root whose left branch points to a leaf. The leaf
-inherits the \code{value} and \code{incr} components from the root.
-The attractive feature is that the leaf be defined as a child of the
-parent using \code{proto} before the parent is even finished
-being defined. Compared to the cited \proglang{S4} example where it
-was necessary to create an extra class to introduce the required level of
-indirection there is no need to take any similar action.
-
-\code{tree} is the root node of the tree. It has four components. A
-method \code{incr} which increments the \code{value} component, a
-\code{..Name}, the \code{value} component itself and the left branch
-\code{..left}. \code{..left} is itself a proto object which is a
-child of \code{tree}. The leaf inherits the \code{value} component
-from its parent, the root. As mentioned, at the time we define
-\code{..left} we have not even finished defining \code{tree} yet we
-are able to implicitly reference the yet to be defined parent.
-
-<<proto-tree01>>=
- # do not need left <- right <- NULL anymore in leaf
- # also eliminated right <- NULL in parent
- tree <- proto(expr = {
- incr <- function(., val) .$value <- .$value + val
- ..Name <- "root"
- value <- 3
- ..left <- proto( expr = { ..Name = "leaf" })
- })
-@
-
-Although this is a simple structure we could have embedded additional
-children into \code{root} and \code{leaf} and so on recursively making
-the tree or dendrogram arbitrarily complex.
-
-Let us do some computation with this structure. We display the
-\code{value} fields in the two nodes, increment the value field in the
-root and then display the two nodes again to show .that the leaf
-changed too.
-
-<<proto-tree02>>=
- cat("root:", tree$value, "leaf:", tree$..left$value, "\n")
-
- # incrementing root increments leaf too
- tree$incr(1)
- cat("root:", tree$value, "leaf:", tree$..left$value, "\n")
-@
-
-If we increment \code{value} in \code{leaf} directly (see the example
-below where we increment it by 10) then it receives its own copy of
-\code{value} so from that point on \code{leaf} no longer inherits
-\code{value} from \code{root}. Thus incrementing the root by 5 no
-longer increments the \code{value} field in the leaf.
-
-<<proto-tree03>>=
- # incrementing leaf gives it its own value field
- # so now incrementing root does not increment leaf
- tree$..left$incr(10)
- cat("root:", tree$value, "leaf:", tree$..left$value, "\n")
- tree$incr(5)
- cat("root:", tree$value, "leaf:", tree$..left$value, "\n")
-@
-
-\subsection{From Prototypes to Classes}
-\label{sec:increment}
-
-In many cases we will use \pkg{proto} for a design that uses prototypes
-during the full development cycle. In other cases we may use it in an
-incremental way starting with prototypes but ultimately transitioning
-to classes.
-As shown in Section~\ref{sec:traits} the \pkg{proto} package is
-powerful enough to handle class-based as well as class-free programming.
-Here we illustrate this process of incremental design
-starting with
-concrete objects and then over time classifing them into classes,
-evolving a class-based program. \pkg{proto} provides a smooth
-transition path since it can handle both the class-free and the class-based
-phases -- there is no need to switch object systems part way through.
-In this example, we define an object which holds a linear equation, \code{eq},
-represented as a character string in terms of the unknown variable \code{x}
-and a \code{print} and a \code{solve} method. We execute the
-\code{print} method
-to solve it. We also create child object \code{lineq2}
-which overrides \code{eq} and execute its \code{print} method.
-
-<<proto-lineq01>>=
-lineq <- proto(eq = "6*x + 12 - 10*x/4 = 2*x",
- solve = function(.) {
- e <- eval(parse(text=paste(sub("=", "-(", .$eq), ")")), list(x = 1i))
- -Re(e)/Im(e)
- },
- print = function(.) cat("Equation:", .$eq, "Solution:", .$solve(), "\n")
-)
-lineq$print()
-
-lineq2 <- lineq$proto(eq = "2*x = 7*x-12+x")
-lineq2$print()
-@
-
-We could continue with enhancements but at this point we decide that we
-have a general case and so wish
-to abstract \code{lineq} into a class. Thus we define a trait,
-\code{Lineq}, which is just \code{lineq} minus \code{eq} plus
-a constructor \code{new}. The key difference between \code{new}
-and the usual \code{proto} function
-is that with \code{new} the initialization of \code{eq} is mandatory.
-Having completed this definition
-we instantiate an object of
-class/trait \code{Lineq} and execute it.
-
-<<proto-lineq02>>=
-Lineq <- lineq
-rm(eq, envir = Lineq)
-Lineq$new <- function(., eq) proto(., eq = eq)
-
-lineq3 <- Lineq$new("3*x=6")
-lineq3$print()
-@
-
-Note how we have transitioned from a prototype style of programming
-to a class-based style of programming all the while staying within
-the \pkg{proto} framework.
-
-\section{Summary} \label{sec:summary}
-
-\subsection{Benefits}
-\label{sec:benefits}
-
-The key benefit of the \pkg{proto} package is to provide
-access to a style of programming that has not been conveniently
-accessible within \proglang{R} or any other mainstream language today.
-
-\pkg{proto} can be used in two key ways: class-free object oriented programming
-and class-based object oriented programming.
-
-A key application for \pkg{proto} in class-free programming is to wrap the code
-and data for each run of a particular statistical study into an object for
-purposes of organization and reproducibility. It provides such organization
-directly and without the need and overhead of class definitions
-yet still provides the
-inheritance and dispatch advantages of object oriented programming.
-We provide examples of this style of programming in
-Section~\ref{sec:smooth}
-and
-Section~\ref{sec:corr}.
-A third example in
-Section~\ref{sec:tree} illustrates a beneficial use of \pkg{proto} with
-recursive data structures.
-
-Another situation where prototype programming is of interest is in the initial
-development stages of a program. In this case, the design may not be fully
-clear so it is more convenient to create concrete objects individually rather
-than premature abstractions through classes. The \code{graph.proto}
-function can be used to generate visual representations of the object
-tree suggesting classifications of objects so that
-as the program evolves the general case becomes clearer and
-in a bottom up fashion the objects are incrementally abstracted into
-classes. In this case,
-\pkg{proto} provides a smooth transition path since it not only supports
-class-free programming but, as explained in the Section~\ref{sec:traits}, is
-sufficiently powerful to support class-based programming, as well.
-
-
-\subsection{Conclusion}
-\label{sec:conclusion}
-
-The package \pkg{proto} provides an \proglang{S3} subclass of the
-\code{environment} class for constructing and manipulating object
-oriented systems without classes. It can also emulate classes even
-though classes are not a primitive structure. Its key design goals
-are to provide as simple and as thin a layer as practically possible
-while giving the user convenient access to this alternate object
-oriented paradigm. This paper describes, by example, how prototype
-programming can be carried out in \proglang{R} using \pkg{proto} and
-illustrates such usage. Delegation, cloning traits and general
-manipulation and incremental development are all reviewed by example.
-
-\section*{Computational details}
-\label{sec:compute}
-
-The results in this paper were obtained using \proglang{R} 2.1.0 with
-the package \pkg{proto} 0.3--2. \proglang{R} itself and the
-\pkg{proto} package are available from CRAN at
-\url{http://CRAN.R-project.org/}. The GraphViz software is available
-from \url{http://www.graphviz.org}.
-
-\phantomsection
-\addcontentsline{toc}{section}{References}
-\bibliography{proto}
-%\input{proto.bbl}
-
-\newpage\mbox{}
-\begin{appendix}
-\section{Frequently Asked Questions}
-\label{sec:faq}
-\begin{enumerate}
-\item{What scope do unqualified object references within methods use?
-
-A \pkg{proto} object is an environment and that environment
-is the environment
-of the methods in it (by default).
-That is, unqualified object references
-within a \pkg{proto} method look first in the method itself and secondly in the
-\pkg{proto} object containing the method.
-This is referred to as object
-scope as opposed to lexical scope or dynamic scope. It allows simple
-situations, where delegation is not used, to use unqualified names. Thus
-simple situations remain simple.
-\citep{Kates2004}
-discusses the fragile base class problem which
-relates to this question. Also note that if a \pkg{proto} object is created
-via the \code{proto} function using an argument of \code{funEnvir = FALSE}
-then the environment of the function/method will not be set as just
-described (but rather it will retain its original environment) so the
-above does not apply. This can be used for instances when non-default
-processing is desirable.}
-\item{Why does \code{obj\$meth} not return the method, \code{meth}?
-
-Conceptually \code{obj\$meth} returns \code{meth} but with
-\code{obj} already inserted into its first argument.
-This is termed an instantiated
-\pkg{proto}
-method and is of \proglang{S3} class \code{"instantiatedProtoMethod"}.
-
-In contrast, the method itself (i.e. the uninstantited method)
-would not have the first argument already
-inserted. To return the method itself use \code{with(obj, meth}.
-
-The main advantage of a design that makes the distinction between instantiated
-and uninstantiated methods is that uninstantiated methods are never
-changed so
-debugging can be more readily carried out (as discussed in the next
-question and answer).
-}
-\item{How does one debug a method?
-
-\pkg{proto} does not dynamically redefine methods. This has the advantage
-that the ordinary \proglang{R} \code{debug} and \code{undebug} commands can be
-used. When using these be sure that to use them with the uninstantiated method
-itself and not the instantiated method derived from it. That is,
-use:
-\begin{verbatim}
- with(obj, debug(meth))
-\end{verbatim}
-
-and not
-\begin{verbatim}
- debug(obj$meth) # wrong
-\end{verbatim}
-}
-\item{Is multiple inheritance supported?
-
-No. \pkg{proto} is just a thin layer on top of \proglang{R}
-environments and \proglang{R} environments
-provide single inheritance only. \citep{Kates2004}
-discusses some ways of handling situations which would otherwise require
-multiple inheritance.}
-\item{Does \pkg{proto} support lazy evaluation?
-
-Since \code{proto} methods are just \proglang{R} functions they do support
-lazy evaluation; however, the \code{proto} function itself
-does evaluate its arguments. To get the
-effect of lazy evaluation when using the \code{proto}
-function replace any properties with a function.
-
-If the caller is the parent of the \code{proto} object then its
-particularly simple. Note how we got the equivalent of lazy evaluation
-in the second example where f is a function:
-
-\begin{verbatim}
-# eager evaluation
-x <- 0
-p <- proto(f = x, g = function(.) $x)
-x <- 1
-p$f # 0
-
-# versus making f a function
-
-# simulates lazy evaluation
-x <- 0
-p <- proto(f = function(.) x, g = function(.) .$x)
-x <- 1
-p$f() # 1
-\end{verbatim}
-
-If we cannot guarantee that the proto object has the caller
-as its parent then ensure that the environment of the function
-has not been reset. If no method needs to reference \code{.that}
-or \code{.super} then we can arrange for that using
-\code{funEnvir=FALSE} as seen here in the second example:
-\begin{verbatim}
-
-# does not work as intended
-x <- 0
-p <- proto(x = 99)
-q <- p$proto(f = function(.) x, g = function(.) .$x)
-x <- 1
-q$f() # 99
-
-# does work
-x <- 0
-p <- proto(x = 99)
-q <- p$proto(f = function(.) x, g = function(.) .$x, funEnvir = FALSE)
-x <- 1
-q$f() # 1
-\end{verbatim}
-
-If we wish only to not reset the function used to simulate
-lazy evaluation then we can do it using either of the
-two equivalent alternatives below. \code{g}
-is an ordinary method whose environment is reset to \code{q}
-whereas \code{f} is a function whose environment is not reset and
-serves to provide lazy evaluation for \code{x} found in the caller.
-
-\begin{verbatim}
-x <- 0
-p <- proto(x = 99)
-# g will use q's y in children of q even if those children
-# override y
-q <- p$proto(y = 25, g = function(.) .that$y + .$x)
-q[["f"]] <- function(.) x
-x <- 1
-q$f() # 1
-
-# equivalent alternative
-
-x <- 0
-p <- proto(x = 99)
-q <- proto(f = function(.) x, funEnvir = FALSE,
- envir = p$proto(y = 25, g = function(.) .that$y + .$x))
-x <- 1
-q$f() # 1
-\end{verbatim}
-}
-\end{enumerate}
-\newpage{}
-\section{Reference Card}
-\label{sec:ref}
-\input{protoref-raw}
-\end{appendix}
-
-\end{document}
-
diff --git a/vignettes/proto-raw.tex b/vignettes/proto-raw.tex
deleted file mode 100755
index 3afd74c..0000000
--- a/vignettes/proto-raw.tex
+++ /dev/null
@@ -1,1359 +0,0 @@
-
-
-%\VignetteIndexEntry{proto: An R Package for Prototype Programming}
-%\VignetteDepends{}
-%\VignetteKeywords{object oriented, prototype programming, S3, R}
-%\VignettePackage{proto}
-
-
-\documentclass{Z}
-\DeclareGraphicsExtensions{.pdf, .eps, .png}
-
-%% need no \usepackage{Sweave}
-
-\newlength{\half}
-\setlength{\half}{70mm}
-
-\author{Louis Kates\\GKX Associates Inc. \And
- Thomas Petzoldt\\Technische Universit\"at Dresden}
-\Plainauthor{Louis Kates, Thomas Petzoldt}
-
-\title{\pkg{proto}: An \proglang{R} Package for Prototype Programming}
-%% \Shorttitle{\pkg{proto}: An \proglang{R} Package for Prototype Programming}
-
-\Plaintitle{proto: An R Package for Prototype Programming}
-
-\Keywords{prototype programming, delegation, inheritance, clone,
- object orientated, \proglang{S3}, \proglang{R}}
-\Plainkeywords{object oriented, prototype programming, S3, R}
-
-\Abstract{
-
- \pkg{proto} is an \proglang{R} package which facilitates a style
- of programming known as prototype
- programming. Prototype programming is a type of object
- oriented programming in which there are no classes.
- \pkg{proto} is simple yet retains the object oriented features of
- delegation (the prototype counterpart to inheritance)
- and object oriented dispatch. \code{proto} can be used
- to organize the concrete data and procedures in statistical studies
- and other applications
- without the necessity of defining classes while still providing convenient
- access to an object oriented style of programming. Furthermore, it
- can be used in a class-based style as well so that incremental design can
- begin with defining the concrete objects and later transition to abstract
- classes, once the general case is understood, without having to change to
- object-oriented frameworks.
- The key goals of the package are to integrate into \proglang{R}
- while providing nothing more than a thin layer on top of it.
-}
-
-\hyphenation{ma-ni-pu-lating}
-
-\begin{document}
-
-
-
-
-\section{Introduction} \label{sec:intro}
-
-\subsection[Object Oriented Programming in R]{Object Oriented Programming in \proglang{R}}
-\label{sec:oo}
-
-The \proglang{R} system for statistical computing
-\citep[\url{http://www.R-project.org/}]{Rcore2005} ships with two
-systems for object oriented programming referred to as \proglang{S3}
-and \proglang{S4}. With the increased interest in object oriented
-programming within \proglang{R} over the last years additional object
-oriented programming packages emerged. These include the \pkg{R.oo}
-package \citep{Bengtsson2003} and the \pkg{OOP} package
-\citep[\url{http://www.omegahat.org/OOP/}]{Rnews:Chambers+Lang:2001a}.
-The common thread among these packages is that they use
-classes as the basis of inheritance. When a message is sent to an
-object the class of the object is examined and that class determines the
-specific function to be executed. In contrast, in prototype programming
-there are no classes yet it retains much of the power of
-class-based programming. In the fact, \pkg{proto} is so simple that
-there are only two significant new routine name, \code{proto}, and
-\code{clone2}. The
-other routines are just the expected support routines such as
-\code{as.proto} to coerce objects to proto objects, \code{\$} to
-access and set proto object components and \code{is.proto} to check
-whether an object is a proto object. In addition, \code{graph.proto}
-will generate a graphical ancestor tree showing the parent-child
-relationships among generated \code{proto} objects.
-
-The aim of the package is to provide a lightweight layer for prototype
-programming in \proglang{R} written only in \proglang{R} leveraging the
-existing facilities of the language rather than adding its own.
-
-\subsection{History}
-\label{sec:history}
-
-The concept of prototype programming
-\citep{Lieberman1986, Taivalsaari1996a, Noble1999}
-has developed over a number of years with the \proglang{Self}
-language \citep{Agesen1992}
-being the key evolved programming language to demonstrate
-the concept. In statistics, the \proglang{Lisp}-based
-\proglang{LispStat} programming language \citep{Tierney1990} was
-the first and possibly only statistical system to feature prototype
-programming.
-
-Despite having been developed over 20 years ago, and some attempts to
-enter the mainstream (e.g. \proglang{Newtonscript}
-on the Newton computer, which
-is no longer available, and \proglang{Javascript} where
-it is available but whose
-domain of application largely precludes use of prototype programming)
-prototype programming is not well known due to lack of language
-support in popular programming languages such as \proglang{C} and
-\proglang{Java}. It tends
-to be the domain of research languages or \proglang{Lisp}.
-
-Thus the availability of a popular language,
-\proglang{R} \footnote{Some indications of the popularity of R are
-the high volume mailing lists, international development team, the
-existence of over 1000 addon packages, conferences and numerous books
-and papers devoted to R.},
-that does provide the key infrastructure could be important for developers.
-
-This work grew out of the need to organize multiple scenarios of model
-simulations in ecological modelling \citep{Rnews:Petzoldt:2003} and
-was subsequently generalized to the present package. A number of
-iterations of the code, some motivated by the ever increasing feature
-set in \proglang{R}, resulted in a series of utilities and ultimately
-successive versions of an \proglang{R} package developed over a period of
-several years. An initial version used \proglang{R} lists as the basis of the
-package. Subsequently the package was changed to use \proglang{R}
-environments. The first version to use environments stored the
-receiver object variable in a proxy parent environment which was
-created on-the-fly at each method call. The present version of
-the \pkg{proto} package passes the receiver object through the argument list,
-while hiding this from the caller. It defines the \code{proto} class
-as a subclass of the \code{environment} class so that
-functionality built into \proglang{R} for the environment class is
-automatically inherited by the \code{proto} class.
-
-\subsection{Overview}
-\label{sec:overview}
-
-It is assumed that the reader has some general
-familiarity with object oriented programming concepts and with
-\proglang{R}.
-
-The paper will proceed primarily by example focusing on illustrating
-the package \code{proto} through such demonstration. The remainder of
-the paper is organized as follows: Section~\ref{sec:proto-class}
-explains how \code{"proto"} objects are created and illustrates the
-corresponding methods for setting and getting components. It further
-discusses how object oriented delegation (the prototype programming
-analogue of inheritance) is handled and finally discusses the
-internals of the package. This section uses small examples chosen for
-their simplicity in illustrating the concepts. In
-Section~\ref{sec:examples} we provide additional examples of prototype
-programming in action. Four examples are shown. The first involves
-smoothing of data. Secondly we demonstrate the calculation of
-correlation confidence intervals using classical (Fisher Transform)
-and modern (bootstrapping) methods. Thirdly we demonstrate the
-development of a binary tree as would be required for a dendrogram.
-Fourthly, we use the solution of linear equations to illustrate
-program evolution from object-based to class-based, all
-within the \pkg{proto} framework.
-Section~\ref{sec:summary} gives a few summarizing remarks. Finally,
-an appendix provides a reference card that summarizes the
-functionality contained in \pkg{proto} in terms of its constituent
-commands.
-
-%% \pagebreak[4]
-
-\section[The class "proto" and its methods]{The class \code{"proto"} and its methods}
-\label{sec:proto-class}
-
-\subsection[Creation of "proto" objects]{Creation of \code{"proto"} objects}
-\label{sec:proto}
-
-In this section we shall show, by example, the creation of two
-prototype objects and related operations. The simple idea is that
-each \code{"proto"} object is a set of components: functions (methods)
-and variables, which are tightly related in some way.
-
-A prototype object is an environment holding the variables and
-methods of the object. \footnote{In particular this implies that
-\code{"proto"} objects have single inheritance, follow ordinary
-environment scoping rules and have mutable state as environments
-do.}
-
-A prototype object is created using the constructor function
-\code{proto} (see Appendix~\ref{sec:ref} at the end of this paper or
-\pkg{proto} package help for complete syntax of commands).
-
-\begin{Scode}
-addProto <- proto( x = rnorm(5), add = function(.) sum(.$x) )
-\end{Scode}
-
-In this simple example, the \code{proto} function defines two
-components: a variable \code{x} and a method \code{add}. The variable
-\code{x} is a vector of 5 numbers and the method sums those numbers.
-The \code{proto} object \code{addProto} contains the variable and the
-method. Thus the \code{addProto} \code{proto} object can be used to compute
-the sum of the values stored in it.
-As shown with the \code{add} method in this example, formal argument
-lists of methods must always have a first argument of dot
-(i.e. \code{.}) which signifies the object on which the method is
-operating. The dot refers to the current object in the same way that
-a dot refers to the current directory in UNIX. Within the method one
-must refer to other variables and methods in the object by prefacing
-each with \code{.\$}. For example, in the above we write
-\code{sum(.\$x)}. Finally, note that the data and the method are very
-closely related. Such close coupling is important in order to create
-an easily maintained system.
-
-To illustrate the usage of \code{proto}, we first load the package and
-set the random seed to make the examples in this paper exactly
-reproducible.
-
-\begin{Schunk}
-\begin{Sinput}
-> library(proto)
-> set.seed(123)
-\end{Sinput}
-\end{Schunk}
-
-Then, we create the \code{proto} object from above
-and call its \code{add} method.
-\begin{Schunk}
-\begin{Sinput}
-> addProto <- proto(x = rnorm(5), add = function(.) sum(.$x))
-> addProto$add()
-\end{Sinput}
-\begin{Soutput}
-[1] 0.9678513
-\end{Soutput}
-\end{Schunk}
-We also create another object, \code{addProto2}
-with a different \code{x} vector and
-invoke its \code{add} method too.
-\begin{Schunk}
-\begin{Sinput}
-> addProto2 <- addProto$proto(x = 1:5)
-> addProto2$add()
-\end{Sinput}
-\begin{Soutput}
-[1] 15
-\end{Soutput}
-\end{Schunk}
-In the examples above, we created a prototype object \code{addProto}
-and then called its \code{add} method as just explained.
-The notation \code{addProto\$add}
-tells the system to look for the \code{add} method
-in the \code{addProto} object. In the expression \code{addProto\$add},
-the \code{proto} object to the left
-of the dollar sign, \code{addProto} here, is referred to as the
-\emph{receiver} object. This expression
-also has a second purpose which is to
-pass the receiver object implicitly as the first argument of \code{add}.
-Note that we called \code{add} as if it had zero arguments but, in fact,
-it has one argument because the receiver is automatically and implicitly
-supplied as the first argument. In general,
-the notation \code{object\$method(arguments)} is
-used to invoke the indicated method of the receiver object using the
-object as the implicit first argument along with the indicated
-arguments as the subsequent arguments.
-As with the \code{addProto} example, the receiver
-object not only determines where to find the
-method but also is implicitly passed to the method through
-the first argument. The motivation for this notation
-is to relieve the user of
-specifying the receiver object twice:
-once to locate the method in the object and a second
-time to pass the object itself to the method.
-The \code{\$} is overloaded by the \code{proto}
-class to automatically do both with one reference to the receiver object.
-Even though, as with the \code{addProto} example, the first
-argument is not listed in the call
-it still must be listed among the formal arguments
-in the definition of the method. It
-is conventional to use
-a dot \code{.} as the first formal argument in the method/function
-definition. That is, we call \code{add} using \code{addProto\$add()}
-displaying zero arguments
-but we define \code{add} in \code{addProto} displaying
-one argument \code{add <- function(.)}, the dot.
-
-In this example,
-we also created a second object, \code{addProto2},
-which has the first object, \code{addProto} as its parent.
-Any reference to a
-component in the second object that is unsuccessful will cause
-search to continue in the parent. Thus the call \code{addProto2\$add()}
-looks for \code{add} in \code{addProto2} and not finding it there
-searches its parent, \code{addProto}, where it is, indeed, found.
-\code{add} is invoked with the receiver object, \code{addProto2}, as
-the value of dot.
-The call \code{addProto2\$add()} actually causes the \code{add}
-in \code{addProto} to run but it still uses the \code{x} from
-\code{addProto2} since dot (\code{.}) is \code{addProto2} here
-and \code{add} references \code{.\$x}.
-Note that the reference to \code{.\$x} in the
-\code{add} found in \code{addProto}
-does not refer to the \code{x} in \code{addProto} itself.
-The \code{x} in \code{addProto2} has overridden the \code{x} in its parent.
-This point is important so the reader should take care to absorb this
-point.
-
-This simple example already shows the key elements of the system
-and how \emph{delegation} (the prototype programming term for inheritance)
-works without classes.
-
-We can add new components or replace components in an object and
-invoke various methods like this:
-\begin{Schunk}
-\begin{Sinput}
-> addProto2$y <- seq(2, 10, 2)
-> addProto2$x <- 1:10
-> addProto2$add3 <- function(., z) sum(.$x) + sum(.$y) + sum(z)
-> addProto2$add()
-\end{Sinput}
-\begin{Soutput}
-[1] 55
-\end{Soutput}
-\begin{Sinput}
-> addProto2$add3(c(2, 3, 5))
-\end{Sinput}
-\begin{Soutput}
-[1] 95
-\end{Soutput}
-\begin{Sinput}
-> addProto2$y
-\end{Sinput}
-\begin{Soutput}
-[1] 2 4 6 8 10
-\end{Soutput}
-\end{Schunk}
-
-In this example, we insert variable \code{y} into the object \code{addProto2}
-with a value of \code{seq(2,10,2)},
-reset variable \code{x} to a new value and insert a new method,
-\code{add3}. Then we invoke
-our two methods and display \code{y}. Again, note that in the case of
-\code{protoAdd2\$add} the \code{add} method is not present in
-\code{protoAdd2} and so search continues to the parent \code{addProto}
-where it is found.
-
-\subsection{Internals}
-\label{sec:internals}
-
-So far, we have used simple examples to illustrate the basic manipulation
-of objects: construction, getting and setting components and method
-invocation. We now discuss the internals of the package and how it relates
-to \proglang{R} constructs.
-\code{proto} is actually an \proglang{S3} class which is a subclass
-of the \code{environment} class. Every \code{proto} object is an
-environment and its class is \code{c("proto", "environment")}. The \code{\$}
-accessor is similar to the same accessor in environments except it will
-use the \proglang{R} \code{get} function to
-search up parent links if it cannot otherwise find the object (unlike
-environments). When accessing a method, \code{\$}
-automatically supplies the
-first argument to the method
-unless the object is \code{.that} or \code{.super}. \code{.that}
-is a special variable which \code{proto} adds to every \code{proto} object
-denoting the object itself. \code{.super} is also added to every
-proto object and is the parent of \code{.that}. \code{.that}
-and \code{.super} are normally used
-within methods of an object to refer to other components of the same
-or parent object, respectively,
-as opposed to the receiver (\code{.}). For example,
-suppose we want \code{add} in \code{addProto2} to add the elements
-of \code{x} together and the elements of
-\code{y} together and then add these two sums. We could redefine add like this:
-
-\begin{Schunk}
-\begin{Sinput}
-> addProto2$add <- function(.) .super$add(.) + sum(.$y)
-\end{Sinput}
-\end{Schunk}
-
-making use of the \code{add} already defined in the parent.
-One exception should be noted here. When one uses \code{.super},
-as above, or \code{.that} to specify a method then the receiver
-object must be explicitly specified
-in argument one (since in those cases the receiver
-is possibly different than
-\code{.super} or \code{.that} so the system cannot automatically supply it
-to the call.)
-
-Setting a value is similar to the corresponding operation for
-environments except that any function, i.e method, which is
-inserted has its environment set to the environment of the object
-into which it is being inserted. This is necessary so that such
-methods can reference \code{.that} and \code{.super} using
-lexical scoping.
-
-In closing this section a few points should be re-emphasized and
-expanded upon. A
-\code{proto} object is an environment whose parent object is the
-parent environment of the \code{proto} object. The methods in the \code{proto}
-objects are ordinary functions that have the containing object as their
-environment.
-
-The \proglang{R} \code{with} function can be used with environments and
-therefore can be used with \code{proto} objects since \code{proto}
-objects are environments too. Thus \code{with(addProto, x)} refers
-to the variable \code{x} in \code{proto} object \code{addProto}
-and \code{with(addProto, add)} refers to the method \code{add}
-in the same way. \code{with(addProto, add)(addProto)} can be used
-to call \code{add}. These constructs all follow from their corresponding
-use in environments from which they are inherited.
-
-Because the \code{with} expressions are somewhat verbose, two common
-cases can be shortened using the \code{\$} operator. \code{addProto\$x}
-can be used to refer to variable \code{x} in \code{proto} object
-\code{addProto} and has the same meaning as \code{with(addProto, x)}.
-In particular like \code{with} but
-unlike the the behavior of the \code{\$} operator on
-environments, when used with \code{proto} objects, \code{\$} will
-search not only the object itself but also its ancestors.
-Similarly \code{addProto\$add()} can be used to call
-method \code{add} in \code{addProto} also searching through ancestors
-if not found in \code{addProto}. Note that \code{addProto\$add}
-returns an object of class
-
-\code{c("instantiatedProtoMethod", "function")}
-which is derived from \code{add} such that the first argument,
-the \code{proto} object,
-is already inserted. Note that there is a \code{print} method for
-class \code{"instantiatedProtoMethod"} so printing such objects will
-display the underlying function but returning such objects
-is not the same as returning the function without slot one inserted.
-Thus, if one wants exactly the original \code{add}
-as a value one should use \code{with(addProto, add)} or
-\code{addProto\$with(add)}.
-
-Within a method, if a variable is referred to without
-qualification simply as \code{x}, say, then its meaning is
-unchanged from how it is otherwise used in \proglang{R} and
-follows the same scope rules as any variable to resolve its name. If it is
-desired that the variable have object scope, i.e. looked up
-in the receiver object and its ancestors, then \code{.\$x}
-or similar \code{with} notation, i.e. \code{with(., x)}, should be used.
-Similarly \code{.\$f(x)} calls
-method \code{f} automatically inserting the receiver object
-into argument one and using \code{x} for argument two. It
-looks for \code{f} first in the receiver object and then its
-ancestors.
-
-\subsection{Traits}
-\label{sec:traits}
-
-Let us look at the definition of a child object once again.
-In the code below,
-\code{addProto} is the previously defined parent object
-and the expression \code{addProto\$proto(x = 1:5)} defines
-a child object of \code{addProto} and assigns it to variable
-\code{addProto2a}.
-
-\begin{Schunk}
-\begin{Sinput}
-> addProto2a <- addProto$proto(x = 1:5)
-> addProto2a$add()
-\end{Sinput}
-\begin{Soutput}
-[1] 15
-\end{Soutput}
-\end{Schunk}
-
-That is, \code{proto} can be used to create a new child of
-an existing object by writing the
-parent object on the left of the \code{\$} and
-\code{proto} on its right. Any contents to
-be added to the new child are listed in arguments of \code{proto}
-as shown.
-
-For example, first let us create a class-like structure. In the
-following \code{Add} is an object that behaves very much like a class
-with an \code{add} method and a method \code{new} which constructs
-new objects. In the line creating object \code{add1} the expression
-\code{Add\$new(x = 1:5)} invokes the \code{new} constructor of the
-receiver object \code{Add}. The method \code{new} has an argument of
-\code{x = 1:5} which defines an \code{x} variable in the \code{add1}
-object being instantiated. We similarly create another object
-\code{add2}.
-
-\begin{Schunk}
-\begin{Sinput}
-> Add <- proto(add = function(.) sum(.$x), new = function(., x) .$proto(x = x))
-> add1 <- Add$new(x = 1:5)
-> add1$add()
-\end{Sinput}
-\begin{Soutput}
-[1] 15
-\end{Soutput}
-\begin{Sinput}
-> add2 <- Add$new(x = 1:10)
-> add2$add()
-\end{Sinput}
-\begin{Soutput}
-[1] 55
-\end{Soutput}
-\end{Schunk}
-
-An object which contains only methods and variables that are
-intended to be shared by all its children (as opposed to an
-object whose purpose is to have its own methods and variables)
-is known as a \emph{trait} \citep{Agesen1992}. It
-is similar to a class in class-based
-object oriented programming.
-Note that the objects \code{add1} and \code{add2} have the trait
-\code{Add} as their parent. We could implement subclass-like and
-superclass-like objects by simply defining similar trait objects to
-be the parent or child of \code{Add}. For example, suppose we
-want a class which calculates the sum of the logarithms of the data. We
-could define:
-
-\begin{Schunk}
-\begin{Sinput}
-> Logadd <- Add$proto(logadd = function(.) log(.$add()))
-> logadd1 <- Logadd$new(1:5)
-> logadd1$logadd()
-\end{Sinput}
-\begin{Soutput}
-[1] 2.70805
-\end{Soutput}
-\end{Schunk}
-
-Here the capitalized objects are traits.
-\code{Logadd} is a trait. It is a child of \code{Add}
-which is also a trait. \code{logadd1} is an ordinary object,
-not a trait.
-One possible design is to create a tree of traits and other objects
-in which the leaves are ordinary objects and the remaining nodes
-are traits. This would closely correspond to class-based
-object oriented programming.
-
-Note that the delegation of methods from
-one trait to another as in
-\code{new} which is inherited by \code{Logadd} from \code{Add}
-is nothing more than the same mechanism by which traits delegate
-methods to
-objects since, of course, traits are just objects no different
-from any other object other than by the conventions we impose on them.
-This unification of subclassing and instantiation beautifully
-shows the simplification that prototype programming represents.
-
-\subsection{Utilities}
-\label{sec:utilities}
-The fact that method calls automatically insert the first argument
-can be used to good effect in leveraging existing \proglang{R}
-functions while allowing an object-oriented syntax.
-
-For example, \code{ls()} can be used to list the components of
-\code{proto} objects:
-
-\begin{Schunk}
-\begin{Sinput}
-> addProto$ls()
-\end{Sinput}
-\begin{Soutput}
-[1] "add" "x"
-\end{Soutput}
-\end{Schunk}
-
-Functions like:
-
-\begin{Schunk}
-\begin{Sinput}
-> addProto$str()
-> addProto$print()
-> addProto$as.list()
-> addProto2a$parent.env()
-\end{Sinput}
-\end{Schunk}
-
-show additional information about the elements. \code{eapply}
-can be used to explore more properties such as the
-the length of each component of an object:
-
-\begin{Schunk}
-\begin{Sinput}
-> addProto$eapply(length)
-\end{Sinput}
-\end{Schunk}
-
-Another example of some interest in any object oriented system
-which allows multiple references to one single object is that
-object identity
-can be tested using the respective base function:
-
-\begin{Schunk}
-\begin{Sinput}
-> addProto$identical(addProto2)
-\end{Sinput}
-\begin{Soutput}
-[1] FALSE
-\end{Soutput}
-\end{Schunk}
-
-\code{proto} does contain a special purpose \code{str.proto} function
-but in the main it
-is important to notice here, that
-\code{proto} has no code that is specific to \code{ls} or
-any of the other ordinary \proglang{R}
-functions listed. We are simply making use of the
-fact that \code{obj\$fun(...)} is transformed into \code{get("fun",
-obj)(obj, ...)} by the proto \code{\$} operator. For example, in the
-case of \code{addProto\$ls()} the system looks for \code{ls} in object
-\code{addProto}. It cannot find it there so it looks to its parent,
-which is the global environment. It does not find it there so it
-searches the remainder of the search path, i.e. the path shown by
-running the \proglang{R} command \code{search()}, and finally finds it
-in the base package, invoking it with an argument of \code{addProto}.
-Since all \code{proto} objects are also environments
-\code{ls(addProto)} interprets \code{addProto} as an environment and
-runs the \code{ls} command with it. In the \code{ls} example there
-were no arguments other than \code{addProto}, and even that one was
-implicit, but if there were
-additional arguments then they would be passed as shown in the
-\code{eapply} and \code{identical} examples above.
-
-\subsection{Plotting}
-\label{sec:plot}
-
-The \code{graph.proto} function can be used to create
-graphs that can be rendered by the \code{Rgraphviz} package
-creating visual representations of ancestor trees (figure
-\ref{fig:proto-dot}).
-That package provides an interface to the
-\proglang{GraphViz} \code{dot} program \citep{Ganser+North:1999}.
-
-\code{graph.proto} takes three arguments, all of which are
-usually omitted. The first argument is a \code{proto} object
-(or an environment) out of which all contained \code{proto} objects
-and their parents (but not higher order ancestors) are graphed.
-If it is omitted, the current environment is assumed.
-The second argument is a graph (in the sense of the \code{graph}
-package) to which the nodes and edges are added. If it is omitted
-an empty graph is assumed. The last argument is a logical variable
-that specifies the orientation of arrows. If omitted arrows are
-drawn from children to their parents.
-
-
-\input{proto-dot}
-
-\begin{figure}[htbp]
-\begin{center}
-\includegraphics{proto-dot}
-\caption{\label{fig:proto-dot} Ancestor tree generated using graph.proto. Edges
-point from child to parent.}
-\end{center}
-\end{figure}
-
-\pagebreak[4]
-
-\section{Examples}
-\label{sec:examples}
-
-\subsection{Smoothing}
-\label{sec:smooth}
-
-In the following we create a \code{proto} object named \code{oo}
-containing a vector of data \code{x} (generated from a simulated
-autoregressive model) and time points
-\code{tt}, an intermediate result
-\code{x.smooth}, some plotting parameters \code{xlab}, \code{ylab},
-\code{pch}, \code{col} and three methods \code{smooth}, \code{plot}
-and \code{residuals} which smooth the data, plot the data and
-calculate residuals, respectively. We also define \code{..x.smooth}
-which holds intermediate results. Names beginning with two dots
-prevent them from being delegated to children. If we override
-\code{x} in a child we would not want an out-of-sync \code{x.smooth}.
-Note that the components of an object can be specified using a code
-block in place of the argument notation we used previously in the
-\code{proto} command.
-
-\begin{Schunk}
-\begin{Sinput}
-> oo <- proto(expr = {
-+ x <- rnorm(251, 0, 0.15)
-+ x <- filter(x, c(1.2, -0.05, -0.18), method = "recursive")
-+ x <- unclass(x[-seq(100)]) * 2 + 20
-+ tt <- seq(12200, length = length(x))
-+ ..x.smooth <- NA
-+ xlab <- "Time (days)"
-+ ylab <- "Temp (deg C)"
-+ pch <- "."
-+ col <- rep("black", 2)
-+ smooth <- function(., ...) {
-+ .$..x.smooth <- supsmu(.$tt, .$x, ...)$y
-+ }
-+ plot <- function(.) with(., {
-+ graphics::plot(tt, x, pch = pch, xlab = xlab, ylab = ylab,
-+ col = col[1])
-+ if (!is.na(..x.smooth[1]))
-+ lines(tt, ..x.smooth, col = col[2])
-+ })
-+ residuals <- function(.) with(., {
-+ data.frame(t = tt, y = x - ..x.smooth)
-+ })
-+ })
-\end{Sinput}
-\end{Schunk}
-
-Having defined our \code{proto} object we can inspect it, as shown
-below, using
-\code{print} which is automatically invoked if the
-name of the object, \code{oo}, is entered on a line by itself.
-In this case, there is no proto print method so we inherit the
-environment print method which displays the environment hash code.
-Although it produces too much output to show here,
-we could have displayed a
-list of the entire contents of the object \code{oo}
-via \code{oo\$as.list(all.names = TRUE)}.
-We can get a list of the names of the
-components of the object using \code{oo\$ls(all.names = TRUE)} and will look
-at the contents of one component, \code{oo\$pch}.
-
-\begin{Schunk}
-\begin{Sinput}
-> oo
-\end{Sinput}
-\begin{Soutput}
-<environment: 0x04330010>
-attr(,"class")
-[1] "proto" "environment"
-\end{Soutput}
-\begin{Sinput}
-> oo$ls(all.names = TRUE)
-\end{Sinput}
-\begin{Soutput}
- [1] "..x.smooth" ".super" ".that" "col" "pch"
- [6] "plot" "residuals" "smooth" "tt" "x"
-[11] "xlab" "ylab"
-\end{Soutput}
-\begin{Sinput}
-> oo$pch
-\end{Sinput}
-\begin{Soutput}
-[1] "."
-\end{Soutput}
-\end{Schunk}
-
-Let us illustrate a variety of manipulations. We will set up the
-output to plot 2 plots per screen using \code{mfrow}. We change the
-plotting symbol, smooth the data, invoke the \code{plot} method to
-display a plot of the data and the smooth and then plot the residuals
-in the second plot (figure \ref{fig:proto-smooting03}).
-
-
-\input{proto-smoothing03}
-
-\begin{figure}[h!]
-\begin{center}
-\includegraphics[width=\textwidth]{proto-smoothing03}
-\end{center}
-\caption{Data and smooth from \code{oo\$plot()} (left) and plot of
-\code{oo\$residuals()} (right).}
-\label{fig:proto-smooting03}
-\end{figure}
-
-
-Now let us illustrate the creation of a child object and delegation.
-We create a new child object of \code{oo} called \code{oo.res}. We
-will override the \code{x} value in its parent by setting \code{x} in
-the child to the value of the residuals in the parent. We will also
-override the \code{pch} and \code{ylab} plotting parameters. We will
-return to 1 plot per screen and run \code{plot} using the
-\code{oo.res} object as the receiver invoking the \code{smooth} and
-\code{plot} methods (which are delegated from the parent \code{oo})
-with the data in the child (figure \ref{fig:smoothing04}).
-
-\input{proto-smoothing04}
-% \begin{figure}[tp]
-\begin{figure}[h!]
-\begin{center}
-\includegraphics[width=\half]{proto-smoothing04}
-\end{center}
-\caption{Output of \code{oo.res\$plot()}.
-\code{oo.res\$x} contains the residuals from \code{oo}.}
-\label{fig:smoothing04}
-\end{figure}
-Now we make use of delegation to change the parent
-and child in a consistent way with respect to certain plot characteristics.
-We have been using a numeric time axis.
-Let us interpret these numbers as the number of days since the Epoch,
-January 1, 1970, and let us also change the plot colors.
-
-\begin{Schunk}
-\begin{Sinput}
-> oo$tt <- oo$tt + as.Date("1970-01-01")
-> oo$xlab <- format(oo.res$tt[1], "%Y")
-> oo$col <- c("blue", "red")
-\end{Sinput}
-\end{Schunk}
-
-
-We can introduce a new method, \code{splot}, into
-the parent \code{oo} and have it automatically
-inherited by its children. In this example
-it smooths and then plots and we use it with
-both \code{oo} and \code{oo.res} (figure \ref{fig:smoothing06}).
-
-
-\input{proto-smoothing06}
-
-\begin{figure}[tbp]
-\begin{center}
-\includegraphics[width=\textwidth]{proto-smoothing06}
-\caption{Plotting options and \code{splot} function applied
-to both parent (left) and child (right) object}
-\label{fig:smoothing06}
-\end{center}
-\end{figure}
-
-Numerous possibilities exist to make use of the
-mechanisms shown, so one may create different child objects, apply
-different smoothing parameters, overwrite the smoothing function with
-a lowess smoother and finally compare fits and residuals.
-
-Now lets change the data and repeat the analysis. Rather than
-overwrite the data we will preserve it in \code{oo} and create a child
-\code{oos} to hold an analysis with sinusoidal data.
-
-\begin{Schunk}
-\begin{Sinput}
-> oos <- oo$proto(expr = {
-+ tt <- seq(0, 4 * pi, length = 1000)
-+ x <- sin(tt) + rnorm(tt, 0, 0.2)
-+ })
-> oos$splot()
-\end{Sinput}
-\end{Schunk}
-
-Lets perform the residual analysis with \code{oos}.
-We will make a deep copy of \code{oo.res}, i.e. duplicate its
-contents and not merely delegate it, by copying \code{oo.res}
-to a list from which we create the duplicate, or cloned,
-\code{proto} object (figure \ref{fig:smoothing10} and \ref{fig:cloning}):
-
-\begin{Schunk}
-\begin{Sinput}
-> oos.res <- as.proto(oo.res$as.list(), parent = oos)
-> oos.res$x <- oos$residuals()$y
-> oos.res$splot()
-\end{Sinput}
-\end{Schunk}
-
-
-\begin{figure}[tbp]
-\begin{center}
-\includegraphics[width=\textwidth]{proto-smoothing10}
-\caption{Smoothing of sinusoidal data (left)
-and of their residuals (right)}\label{fig:smoothing10}
-\end{center}
-\end{figure}
-
-\begin{figure}[h!]
-\begin{center}
-\includegraphics[width=50mm]{cloning3.pdf}
-\caption{Cloning (dashed line) and delegation (solid line). Edges point
-from child to parent.}\label{fig:cloning}
-\end{center}
-\end{figure}
-
-We have delegated variables
-and methods and overridden both.
-Thus, even with such a simple analysis, object orientation
-and delegation came into play.
-The reader can plainly see that smoothing and residual
-analysis were not crucial to the example and this example
-could be replaced with any statistical analysis including
-likelihood or other estimation techniques, time series, survival
-analysis, stochastic processes and so on. The key aspect is
-just that we are performing one-of analyses and do not want to
-set up an elaborate class infrastructure but just want to
-directly create objects to organize our calculations while
-relying on delegation and dispatch to eliminate redundancy.
-
-\subsection{Correlation, Fisher's Transform and Bootstrapping}
-\label{sec:corr}
-
-The common approach to
-confidence intervals for the correlation coefficient is to
-assume normality of the underlying data and then use Fisher's transform
-to transform the correlation coefficient to an approximately normal
-random variable.
-Fisher showed that with the above normality assumption, transforming
-the correlation coefficient using
-the hyperbolic arc tangent function
-yields a random variable
-approximately distributed with an
-$\frac{N(p, 1)}{\sqrt(n-3)}$ distribution. The transformed random
-variable can be used to create normal distribution confidence intervals
-and the procedure can be back transformed to get confidence intervals
-for the original correlation coefficient.
-
-A more recent approach to confidence intervals for the correlation
-coefficient is to use bootstrapping. This does not require the
-assumption of normality of the underlying distribution and requires
-no special purpose theory devoted solely to the correlation coefficient,
-
-Let us calculate the 95\%
-confidence intervals using Fisher's transform
-first. We use \code{GNP} and \code{Unemployed} from the Longley data
-set. First we retrieve the data set and extract the required columns
-into \code{x}. Then we set \code{n} to the number of cases
-and \code{pp} to the percentiles
-of interest. Finally we calculate the sample correlation and
-create a function to calculate the confidence interval using
-Fisher's Transform. This function not only returns the confidence
-interval but also stores it in \code{CI} in the receiver object.
-
-\begin{Schunk}
-\begin{Sinput}
-> longley.ci <- proto(expr = {
-+ data(longley)
-+ x <- longley[, c("GNP", "Unemployed")]
-+ n <- nrow(x)
-+ pp <- c(0.025, 0.975)
-+ corx <- cor(x)[1, 2]
-+ ci <- function(.) (.$CI <- tanh(atanh(.$corx) + qnorm(.$pp)/sqrt(.$n -
-+ 3)))
-+ })
-\end{Sinput}
-\end{Schunk}
-
-Now let us repeat this analysis using the bootstrapping approach. We
-derive a new object \code{longley.ci.boot} as child of
-\code{longley.ci}, setting the number of replications, \code{N}, and
-defining the procedure, \code{ci} which does the actual bootstrap
-calculation.
-
-\begin{Schunk}
-\begin{Sinput}
-> longley.ci.boot <- longley.ci$proto({
-+ N <- 1000
-+ ci <- function(.) {
-+ corx <- function(idx) cor(.$x[idx, ])[1, 2]
-+ samp <- replicate(.$N, corx(sample(.$n, replace = TRUE)))
-+ (.$CI <- quantile(samp, .$pp))
-+ }
-+ })
-\end{Sinput}
-\end{Schunk}
-
-In the example code below the first line runs the Fisher Transform
-procedure and the second runs the bootstrap procedure. Just to check
-that we have performed sufficient bootstrap iterations we rerun it in
-the third line, creating a delegated object on-the-fly running its
-\code{ci} method and then immediately throwing the object away.
-The fact that 4,000
-replications give roughly the same result as 1,000 replications
-satisfies us that we have used a sufficient number of replications.
-
-\begin{Schunk}
-\begin{Sinput}
-> longley.ci$ci()
-\end{Sinput}
-\begin{Soutput}
-[1] 0.1549766 0.8464304
-\end{Soutput}
-\begin{Sinput}
-> longley.ci.boot$ci()
-\end{Sinput}
-\begin{Soutput}
- 2.5% 97.5%
-0.2299395 0.8211854
-\end{Soutput}
-\begin{Sinput}
-> longley.ci.boot$proto(N = 4000)$ci()
-\end{Sinput}
-\begin{Soutput}
- 2.5% 97.5%
-0.2480999 0.8259276
-\end{Soutput}
-\end{Schunk}
-
-We now have the results stored in two objects nicely organized for the
-future. Note, again, that despite the simplicity of the example we
-have used the features of object oriented programming, coupling the
-data and methods that go together, while relying on delegation and
-dispatch to avoid duplication.
-
-\subsection{Dendrograms}
-\label{sec:tree}
-
-In \cite{Gentleman2002} there is an \proglang{S4}
-example of creating a binary tree
-for use as a dendrogram. Here we directly define a binary tree with no
-setup at all. To keep it short we will create a binary tree of only
-two nodes having a root whose left branch points to a leaf. The leaf
-inherits the \code{value} and \code{incr} components from the root.
-The attractive feature is that the leaf be defined as a child of the
-parent using \code{proto} before the parent is even finished
-being defined. Compared to the cited \proglang{S4} example where it
-was necessary to create an extra class to introduce the required level of
-indirection there is no need to take any similar action.
-
-\code{tree} is the root node of the tree. It has four components. A
-method \code{incr} which increments the \code{value} component, a
-\code{..Name}, the \code{value} component itself and the left branch
-\code{..left}. \code{..left} is itself a proto object which is a
-child of \code{tree}. The leaf inherits the \code{value} component
-from its parent, the root. As mentioned, at the time we define
-\code{..left} we have not even finished defining \code{tree} yet we
-are able to implicitly reference the yet to be defined parent.
-
-\begin{Schunk}
-\begin{Sinput}
-> tree <- proto(expr = {
-+ incr <- function(., val) .$value <- .$value + val
-+ ..Name <- "root"
-+ value <- 3
-+ ..left <- proto(expr = {
-+ ..Name = "leaf"
-+ })
-+ })
-\end{Sinput}
-\end{Schunk}
-
-Although this is a simple structure we could have embedded additional
-children into \code{root} and \code{leaf} and so on recursively making
-the tree or dendrogram arbitrarily complex.
-
-Let us do some computation with this structure. We display the
-\code{value} fields in the two nodes, increment the value field in the
-root and then display the two nodes again to show .that the leaf
-changed too.
-
-\begin{Schunk}
-\begin{Sinput}
-> cat("root:", tree$value, "leaf:", tree$..left$value, "\n")
-\end{Sinput}
-\begin{Soutput}
-root: 3 leaf: 3
-\end{Soutput}
-\begin{Sinput}
-> tree$incr(1)
-> cat("root:", tree$value, "leaf:", tree$..left$value, "\n")
-\end{Sinput}
-\begin{Soutput}
-root: 4 leaf: 4
-\end{Soutput}
-\end{Schunk}
-
-If we increment \code{value} in \code{leaf} directly (see the example
-below where we increment it by 10) then it receives its own copy of
-\code{value} so from that point on \code{leaf} no longer inherits
-\code{value} from \code{root}. Thus incrementing the root by 5 no
-longer increments the \code{value} field in the leaf.
-
-\begin{Schunk}
-\begin{Sinput}
-> tree$..left$incr(10)
-> cat("root:", tree$value, "leaf:", tree$..left$value, "\n")
-\end{Sinput}
-\begin{Soutput}
-root: 4 leaf: 14
-\end{Soutput}
-\begin{Sinput}
-> tree$incr(5)
-> cat("root:", tree$value, "leaf:", tree$..left$value, "\n")
-\end{Sinput}
-\begin{Soutput}
-root: 9 leaf: 14
-\end{Soutput}
-\end{Schunk}
-
-\subsection{From Prototypes to Classes}
-\label{sec:increment}
-
-In many cases we will use \pkg{proto} for a design that uses prototypes
-during the full development cycle. In other cases we may use it in an
-incremental way starting with prototypes but ultimately transitioning
-to classes.
-As shown in Section~\ref{sec:traits} the \pkg{proto} package is
-powerful enough to handle class-based as well as class-free programming.
-Here we illustrate this process of incremental design
-starting with
-concrete objects and then over time classifing them into classes,
-evolving a class-based program. \pkg{proto} provides a smooth
-transition path since it can handle both the class-free and the class-based
-phases -- there is no need to switch object systems part way through.
-In this example, we define an object which holds a linear equation, \code{eq},
-represented as a character string in terms of the unknown variable \code{x}
-and a \code{print} and a \code{solve} method. We execute the
-\code{print} method
-to solve it. We also create child object \code{lineq2}
-which overrides \code{eq} and execute its \code{print} method.
-
-\begin{Schunk}
-\begin{Sinput}
-> lineq <- proto(eq = "6*x + 12 - 10*x/4 = 2*x", solve = function(.) {
-+ e <- eval(parse(text = paste(sub("=", "-(", .$eq), ")")),
-+ list(x = 0+1i))
-+ -Re(e)/Im(e)
-+ }, print = function(.) cat("Equation:", .$eq, "Solution:", .$solve(),
-+ "\n"))
-> lineq$print()
-\end{Sinput}
-\begin{Soutput}
-Equation: 6*x + 12 - 10*x/4 = 2*x Solution: -8
-\end{Soutput}
-\begin{Sinput}
-> lineq2 <- lineq$proto(eq = "2*x = 7*x-12+x")
-> lineq2$print()
-\end{Sinput}
-\begin{Soutput}
-Equation: 2*x = 7*x-12+x Solution: 2
-\end{Soutput}
-\end{Schunk}
-
-We could continue with enhancements but at this point we decide that we
-have a general case and so wish
-to abstract \code{lineq} into a class. Thus we define a trait,
-\code{Lineq}, which is just \code{lineq} minus \code{eq} plus
-a constructor \code{new}. The key difference between \code{new}
-and the usual \code{proto} function
-is that with \code{new} the initialization of \code{eq} is mandatory.
-Having completed this definition
-we instantiate an object of
-class/trait \code{Lineq} and execute it.
-
-\begin{Schunk}
-\begin{Sinput}
-> Lineq <- lineq
-> rm(eq, envir = Lineq)
-> Lineq$new <- function(., eq) proto(., eq = eq)
-> lineq3 <- Lineq$new("3*x=6")
-> lineq3$print()
-\end{Sinput}
-\begin{Soutput}
-Equation: 3*x=6 Solution: 2
-\end{Soutput}
-\end{Schunk}
-
-Note how we have transitioned from a prototype style of programming
-to a class-based style of programming all the while staying within
-the \pkg{proto} framework.
-
-\section{Summary} \label{sec:summary}
-
-\subsection{Benefits}
-\label{sec:benefits}
-
-The key benefit of the \pkg{proto} package is to provide
-access to a style of programming that has not been conveniently
-accessible within \proglang{R} or any other mainstream language today.
-
-\pkg{proto} can be used in two key ways: class-free object oriented programming
-and class-based object oriented programming.
-
-A key application for \pkg{proto} in class-free programming is to wrap the code
-and data for each run of a particular statistical study into an object for
-purposes of organization and reproducibility. It provides such organization
-directly and without the need and overhead of class definitions
-yet still provides the
-inheritance and dispatch advantages of object oriented programming.
-We provide examples of this style of programming in
-Section~\ref{sec:smooth}
-and
-Section~\ref{sec:corr}.
-A third example in
-Section~\ref{sec:tree} illustrates a beneficial use of \pkg{proto} with
-recursive data structures.
-
-Another situation where prototype programming is of interest is in the initial
-development stages of a program. In this case, the design may not be fully
-clear so it is more convenient to create concrete objects individually rather
-than premature abstractions through classes. The \code{graph.proto}
-function can be used to generate visual representations of the object
-tree suggesting classifications of objects so that
-as the program evolves the general case becomes clearer and
-in a bottom up fashion the objects are incrementally abstracted into
-classes. In this case,
-\pkg{proto} provides a smooth transition path since it not only supports
-class-free programming but, as explained in the Section~\ref{sec:traits}, is
-sufficiently powerful to support class-based programming, as well.
-
-
-\subsection{Conclusion}
-\label{sec:conclusion}
-
-The package \pkg{proto} provides an \proglang{S3} subclass of the
-\code{environment} class for constructing and manipulating object
-oriented systems without classes. It can also emulate classes even
-though classes are not a primitive structure. Its key design goals
-are to provide as simple and as thin a layer as practically possible
-while giving the user convenient access to this alternate object
-oriented paradigm. This paper describes, by example, how prototype
-programming can be carried out in \proglang{R} using \pkg{proto} and
-illustrates such usage. Delegation, cloning traits and general
-manipulation and incremental development are all reviewed by example.
-
-\section*{Computational details}
-\label{sec:compute}
-
-The results in this paper were obtained using \proglang{R} 2.1.0 with
-the package \pkg{proto} 0.3--2. \proglang{R} itself and the
-\pkg{proto} package are available from CRAN at
-\url{http://CRAN.R-project.org/}. The GraphViz software is available
-from \url{http://www.graphviz.org}.
-
-\phantomsection
-\addcontentsline{toc}{section}{References}
-\bibliography{proto}
-%\input{proto.bbl}
-
-\newpage\mbox{}
-\begin{appendix}
-\section{Frequently Asked Questions}
-\label{sec:faq}
-\begin{enumerate}
-\item{What scope do unqualified object references within methods use?
-
-A \pkg{proto} object is an environment and that environment
-is the environment
-of the methods in it (by default).
-That is, unqualified object references
-within a \pkg{proto} method look first in the method itself and secondly in the
-\pkg{proto} object containing the method.
-This is referred to as object
-scope as opposed to lexical scope or dynamic scope. It allows simple
-situations, where delegation is not used, to use unqualified names. Thus
-simple situations remain simple.
-\citep{Kates2004}
-discusses the fragile base class problem which
-relates to this question. Also note that if a \pkg{proto} object is created
-via the \code{proto} function using an argument of \code{funEnvir = FALSE}
-then the environment of the function/method will not be set as just
-described (but rather it will retain its original environment) so the
-above does not apply. This can be used for instances when non-default
-processing is desirable.}
-\item{Why does \code{obj\$meth} not return the method, \code{meth}?
-
-Conceptually \code{obj\$meth} returns \code{meth} but with
-\code{obj} already inserted into its first argument.
-This is termed an instantiated
-\pkg{proto}
-method and is of \proglang{S3} class \code{"instantiatedProtoMethod"}.
-
-In contrast, the method itself (i.e. the uninstantited method)
-would not have the first argument already
-inserted. To return the method itself use \code{with(obj, meth}.
-
-The main advantage of a design that makes the distinction between instantiated
-and uninstantiated methods is that uninstantiated methods are never
-changed so
-debugging can be more readily carried out (as discussed in the next
-question and answer).
-}
-\item{How does one debug a method?
-
-\pkg{proto} does not dynamically redefine methods. This has the advantage
-that the ordinary \proglang{R} \code{debug} and \code{undebug} commands can be
-used. When using these be sure that to use them with the uninstantiated method
-itself and not the instantiated method derived from it. That is,
-use:
-\begin{verbatim}
- with(obj, debug(meth))
-\end{verbatim}
-
-and not
-\begin{verbatim}
- debug(obj$meth) # wrong
-\end{verbatim}
-}
-\item{Is multiple inheritance supported?
-
-No. \pkg{proto} is just a thin layer on top of \proglang{R}
-environments and \proglang{R} environments
-provide single inheritance only. \citep{Kates2004}
-discusses some ways of handling situations which would otherwise require
-multiple inheritance.}
-\item{Does \pkg{proto} support lazy evaluation?
-
-Since \code{proto} methods are just \proglang{R} functions they do support
-lazy evaluation; however, the \code{proto} function itself
-does evaluate its arguments. To get the
-effect of lazy evaluation when using the \code{proto}
-function replace any properties with a function.
-
-If the caller is the parent of the \code{proto} object then its
-particularly simple. Note how we got the equivalent of lazy evaluation
-in the second example where f is a function:
-
-\begin{verbatim}
-# eager evaluation
-x <- 0
-p <- proto(f = x, g = function(.) $x)
-x <- 1
-p$f # 0
-
-# versus making f a function
-
-# simulates lazy evaluation
-x <- 0
-p <- proto(f = function(.) x, g = function(.) .$x)
-x <- 1
-p$f() # 1
-\end{verbatim}
-
-If we cannot guarantee that the proto object has the caller
-as its parent then ensure that the environment of the function
-has not been reset. If no method needs to reference \code{.that}
-or \code{.super} then we can arrange for that using
-\code{funEnvir=FALSE} as seen here in the second example:
-\begin{verbatim}
-
-# does not work as intended
-x <- 0
-p <- proto(x = 99)
-q <- p$proto(f = function(.) x, g = function(.) .$x)
-x <- 1
-q$f() # 99
-
-# does work
-x <- 0
-p <- proto(x = 99)
-q <- p$proto(f = function(.) x, g = function(.) .$x, funEnvir = FALSE)
-x <- 1
-q$f() # 1
-\end{verbatim}
-
-If we wish only to not reset the function used to simulate
-lazy evaluation then we can do it using either of the
-two equivalent alternatives below. \code{g}
-is an ordinary method whose environment is reset to \code{q}
-whereas \code{f} is a function whose environment is not reset and
-serves to provide lazy evaluation for \code{x} found in the caller.
-
-\begin{verbatim}
-x <- 0
-p <- proto(x = 99)
-# g will use q's y in children of q even if those children
-# override y
-q <- p$proto(y = 25, g = function(.) .that$y + .$x)
-q[["f"]] <- function(.) x
-x <- 1
-q$f() # 1
-
-# equivalent alternative
-
-x <- 0
-p <- proto(x = 99)
-q <- proto(f = function(.) x, funEnvir = FALSE,
- envir = p$proto(y = 25, g = function(.) .that$y + .$x))
-x <- 1
-q$f() # 1
-\end{verbatim}
-}
-\end{enumerate}
-\newpage{}
-\section{Reference Card}
-\label{sec:ref}
-\input{protoref-raw}
-\end{appendix}
-
-\end{document}
-
diff --git a/vignettes/proto-smoothing03.pdf b/vignettes/proto-smoothing03.pdf
old mode 100755
new mode 100644
index 574036d..77220c3
Binary files a/vignettes/proto-smoothing03.pdf and b/vignettes/proto-smoothing03.pdf differ
diff --git a/vignettes/proto-smoothing03.tex b/vignettes/proto-smoothing03.tex
old mode 100755
new mode 100644
diff --git a/vignettes/proto-smoothing04.pdf b/vignettes/proto-smoothing04.pdf
old mode 100755
new mode 100644
index d2dd1c2..f94bedf
Binary files a/vignettes/proto-smoothing04.pdf and b/vignettes/proto-smoothing04.pdf differ
diff --git a/vignettes/proto-smoothing04.tex b/vignettes/proto-smoothing04.tex
old mode 100755
new mode 100644
diff --git a/vignettes/proto-smoothing06.pdf b/vignettes/proto-smoothing06.pdf
old mode 100755
new mode 100644
index 595dc28..a884c17
Binary files a/vignettes/proto-smoothing06.pdf and b/vignettes/proto-smoothing06.pdf differ
diff --git a/vignettes/proto-smoothing06.tex b/vignettes/proto-smoothing06.tex
old mode 100755
new mode 100644
diff --git a/vignettes/proto-smoothing10.pdf b/vignettes/proto-smoothing10.pdf
old mode 100755
new mode 100644
index c222e1e..429cd7f
Binary files a/vignettes/proto-smoothing10.pdf and b/vignettes/proto-smoothing10.pdf differ
diff --git a/vignettes/proto-smoothing10.tex b/vignettes/proto-smoothing10.tex
old mode 100755
new mode 100644
diff --git a/vignettes/proto.Rnw b/vignettes/proto.Rnw
old mode 100755
new mode 100644
index 47316a9..f5ba084
--- a/vignettes/proto.Rnw
+++ b/vignettes/proto.Rnw
@@ -1,22 +1,1358 @@
-% To build the vignette:
-% 1. run Sweave("proto-raw") to create proto-raw.tex
-% 2. build as usual using Rcmd build proto
-%
-% To build vignette manually:
-% 1. Sweave("proto-raw") to create proto-raw.tex
-% 2. Sweave("proto.Rnw")
-% 3. pdflatex proto.tex
-%
-% To build manually using sweave.bat using batchfiles on Windows:
-% 1. sweave proto-raw --tex
-% 2. sweave proto
-
-\SweaveOpts{engine=R,eps=FALSE}
-
-%\VignetteIndexEntry{proto: An R Package for Prototype Programming}
-%\VignetteDepends{}
-%\VignetteKeywords{object oriented, prototype programming, S3, R}
-%\VignettePackage{proto}
-
-\input{proto-raw}
-
+%\VignetteIndexEntry{proto: An R Package for Prototype Programming}
+%\VignetteDepends{}
+%\VignetteKeywords{object oriented, prototype programming, S3, R}
+%\VignettePackage{proto}
+
+\documentclass[nojss]{jss}
+\usepackage{Sweave}
+\DeclareGraphicsExtensions{.pdf, .eps, .png}
+
+\newlength{\half}
+\setlength{\half}{70mm}
+
+\author{Louis Kates\\GKX Associates Inc. \And
+ Thomas Petzoldt\\Technische Universit\"at Dresden}
+\Plainauthor{Louis Kates, Thomas Petzoldt}
+
+\title{\pkg{proto}: An \proglang{R} Package for Prototype Programming}
+%% \Shorttitle{\pkg{proto}: An \proglang{R} Package for Prototype Programming}
+
+\Plaintitle{proto: An R Package for Prototype Programming}
+
+\Keywords{prototype programming, delegation, inheritance, clone,
+ object orientated, \proglang{S3}, \proglang{R}}
+\Plainkeywords{object oriented, prototype programming, S3, R}
+
+\Abstract{
+
+ \pkg{proto} is an \proglang{R} package which facilitates a style
+ of programming known as prototype
+ programming. Prototype programming is a type of object
+ oriented programming in which there are no classes.
+ \pkg{proto} is simple yet retains the object oriented features of
+ delegation (the prototype counterpart to inheritance)
+ and object oriented dispatch. \code{proto} can be used
+ to organize the concrete data and procedures in statistical studies
+ and other applications
+ without the necessity of defining classes while still providing convenient
+ access to an object oriented style of programming. Furthermore, it
+ can be used in a class-based style as well so that incremental design can
+ begin with defining the concrete objects and later transition to abstract
+ classes, once the general case is understood, without having to change to
+ object-oriented frameworks.
+ The key goals of the package are to integrate into \proglang{R}
+ while providing nothing more than a thin layer on top of it.
+}
+
+\hyphenation{ma-ni-pu-lating}
+
+\begin{document}
+\SweaveOpts{concordance=TRUE}
+
+
+
+
+\section{Introduction} \label{sec:intro}
+
+\subsection[Object Oriented Programming in R]{Object Oriented Programming in \proglang{R}}
+\label{sec:oo}
+
+The \proglang{R} system for statistical computing
+\citep[\url{http://www.R-project.org/}]{Rcore2005} ships with two
+systems for object oriented programming referred to as \proglang{S3}
+and \proglang{S4}. With the increased interest in object oriented
+programming within \proglang{R} over the last years additional object
+oriented programming packages emerged. These include the \pkg{R.oo}
+package \citep{Bengtsson2003} and the \pkg{OOP} package
+\citep[\url{http://www.omegahat.net/OOP/}]{Rnews:Chambers+Lang:2001a}.
+All these packages have the common thread that they use
+classes as the basis of inheritance. When a message is sent to an
+object the class of the object is examined and that class determines the
+specific function to be executed. In prototype programming there
+are no classes making it simple yet it retains much of the power of
+class-based programming. In the fact, \pkg{proto} is so simple that
+there is only one significant new routine name, \code{proto}. The
+other routines are just the expected support routines such as
+\code{as.proto} to coerce objects to proto objects, \code{\$} to
+access and set proto object components and \code{is.proto} to check
+whether an object is a proto object. In addition, \code{graph.proto}
+will generate a graphical ancestor tree showing the parent-child
+relationships among generated \code{proto} objects.
+
+The aim of the package is to provide a lightweight layer for prototype
+programming in \proglang{R} written only in \proglang{R} leveraging the
+existing facilities of the language rather than adding its own.
+
+\subsection{History}
+\label{sec:history}
+
+The concept of
+prototype programming
+\citep{Lieberman1986, Taivalsaari1996a, Noble1999}
+has developed over a number of years with the \proglang{Self}
+language \citep{Agesen1992}
+being the key evolved programming language to demonstrate
+the concept. In statistics, the \proglang{Lisp}-based
+\proglang{LispStat} programming language \citep{Tierney1990} was
+the first and possibly only statistical system to feature prototype
+programming.
+
+Despite having been developed over 20 years ago, and some attempts to
+enter the mainstream (e.g. \proglang{Newtonscript}
+on the Newton computer, which
+is no longer available, and \proglang{Javascript} where
+it is available but whose
+domain of application largely precluses use of prototype programming)
+prototype programming is not well known due to lack of language
+support in popular programming languages such as \proglang{C} and
+\proglang{Java}. It tends
+to be the domain of research languages or \proglang{Lisp}.
+
+Thus the
+the availability of a popular language,
+\proglang{R} \footnote{Some indications of the popularity of R are
+the high volume mailing lists, international development team, the
+existence of over 500 addon packages, conferences and numerous books
+and papers devoted to R.},
+that finally does provide the key infrastructure
+is an important development.
+
+This work grew out of the need to organize multiple scenarios of model
+simulations in ecological modelling \citep{Rnews:Petzoldt:2003} and
+was subsequently generalized to the present package. A number of
+iterations of the code, some motivated by the ever increasing feature
+set in \proglang{R}, resulted in a series of utilities and ultimately
+successive versions of an \proglang{R} package developed over the last
+year. An initial version used \proglang{R} lists as the basis of the
+package. Subsequently the package was changed to use \proglang{R}
+environments. The first version to use environments stored the
+receiver object variable in a proxy parent environment which was
+created on-the-fly at each method call. The present version of
+the \pkg{proto} package passes the receiver object through the argument list,
+while hiding this from the caller. It defines the \code{proto} class
+as a subclass of the \code{environment} class so that
+functionality built into \proglang{R} for the environment class is
+automatically inherited by the \code{proto} class.
+
+\subsection{Overview}
+\label{sec:overview}
+
+It is assumed that the reader has some general
+familiarity with object oriented programming concepts and with
+\proglang{R}.
+
+The paper will proceed primarily by example focusing on illustrating
+the package \code{proto} through such demonstration. The remainder of
+the paper is organized as follows: Section~\ref{sec:proto-class}
+explains how \code{"proto"} objects are created and illustrates the
+corresponding methods for setting and getting components. It further
+discusses how object oriented delegation (the prototype programming
+analogue of inheritance) is handled and finally discusses the
+internals of the package. This section uses small examples chosen for
+their simplicity in illustrating the concepts. In
+Section~\ref{sec:examples} we provide additional examples of prototype
+programming in action. Four examples are shown. The first involves
+smoothing of data. Secondly we demonstrate the calculation of
+correlation confidence intervals using classical (Fisher Transform)
+and modern (bootstrapping) methods. Thirdly we demonstrate the
+development of a binary tree as would be required for a dendrogram.
+Fourthly, we use the solution of linear equations to illustrate
+program evolution from object-based to class-based, all
+within the \pkg{proto} framework.
+Section~\ref{sec:summary} gives a few summarizing remarks. Finally,
+an appendix provides a reference card that summarizes the
+functionality contained in \pkg{proto} in terms of its constituent
+commands.
+
+%% \pagebreak[4]
+
+\section[The class "proto" and its methods]{The class \code{"proto"} and its methods}
+\label{sec:proto-class}
+
+\subsection[Creation of "proto" objects]{Creation of \code{"proto"} objects}
+\label{sec:proto}
+
+In this section we shall show, by example, the creation of two
+prototype objects and related operations. The simple idea is that
+each \code{"proto"} object is a set of components: functions (methods)
+and variables, which are tightly related in some way.
+
+A prototype object is an environment holding the variables and
+methods of the object. \footnote{In particular this implies that
+\code{"proto"} objects have single inheritance, follow ordinary
+environment scoping rules and have mutable state as environments
+do.}
+
+A prototype object is created using the constructor function
+\code{proto} (see Appendix~\ref{sec:ref} at the end of this paper or
+\pkg{proto} package help for complete syntax of commands).
+
+\begin{Scode}
+addProto <- proto( x = rnorm(5), add = function(.) sum(.$x) )
+\end{Scode}
+
+In this simple example, the \code{proto} function defines two
+components: a variable \code{x} and a method \code{add}. The variable
+\code{x} is a vector of 5 numbers and the method sums those numbers.
+The \code{proto} object \code{addProto} contains the variable and the
+method. Thus the \code{addProto} \code{proto} object can be used to compute
+the sum of the values stored in it.
+As shown with the \code{add} method in this example, formal argument
+lists of methods must always have a first argument of dot
+(i.e. \code{.}) which signifies the object on which the method is
+operating. The dot refers to the current object in the same way that
+a dot refers to the current directory in UNIX. Within the method one
+must refer to other variables and methods in the object by prefacing
+each with \code{.\$}. For example, in the above we write
+\code{sum(.\$x)}. Finally, note that the data and the method are very
+closely related. Such close coupling is important in order to create
+an easily maintained system.
+
+To illustrate the usage of \code{proto}, we first load the package and
+set the random seed to make the examples in this paper exactly
+reproducible.
+
+\begin{Schunk}
+\begin{Sinput}
+> library(proto)
+> set.seed(123)
+\end{Sinput}
+\end{Schunk}
+
+Then, we create the \code{proto} object from above
+and call its \code{add} method.
+\begin{Schunk}
+\begin{Sinput}
+> addProto <- proto(x = rnorm(5), add = function(.) sum(.$x))
+> addProto$add()
+\end{Sinput}
+\begin{Soutput}
+[1] 0.9678513
+\end{Soutput}
+\end{Schunk}
+We also create another object, \code{addProto2}
+with a different \code{x} vector and
+invoke its \code{add} method too.
+\begin{Schunk}
+\begin{Sinput}
+> addProto2 <- addProto$proto(x = 1:5)
+> addProto2$add()
+\end{Sinput}
+\begin{Soutput}
+[1] 15
+\end{Soutput}
+\end{Schunk}
+In the examples above, we created a prototype object \code{addProto}
+and then called its \code{add} method as just explained.
+The notation \code{addProto\$add}
+tells the system to look for the \code{add} method
+in the \code{addProto} object. In the expression \code{addProto\$add},
+the \code{proto} object to the left
+of the dollar sign, \code{addProto} here, is referred to as the
+\emph{receiver} object. This expression
+also has a second purpose which is to
+pass the receiver object implicitly as the first argument of \code{add}.
+Note that we called \code{add} as if it had zero arguments but, in fact,
+it has one argument because the receiver is automatically and implicitly
+supplied as the first argument. In general,
+the notation \code{object\$method(arguments)} is
+used to invoke the indicated method of the receiver object using the
+object as the implicit first argument along with the indicated
+arguments as the subsequent arguments.
+As with the \code{addProto} example, the receiver
+object not only determines where to find the
+method but also is implicitly passed to the method through
+the first argument. The motivation for this notation
+is to relieve the user of
+specifying the receiver object twice:
+once to locate the method in the object and a second
+time to pass the object itself to the method.
+The \code{\$} is overloaded by the \code{proto}
+class to automatically do both with one reference to the receiver object.
+Even though, as with the \code{addProto} example, the first
+argument is not listed in the call
+it still must be listed among the formal arguments
+in the definition of the method. It
+is conventional to use
+a dot \code{.} as the first formal argument in the method/function
+definition. That is, we call \code{add} using \code{addProto\$add()}
+displaying zero arguments
+but we define \code{add} in \code{addProto} displaying
+one argument \code{add <- function(.)}, the dot.
+
+In this example,
+we also created a second object, \code{addProto2},
+which has the first object, \code{addProto} as its parent.
+Any reference to a
+component in the second object that is unsuccessful will cause
+search to continue in the parent. Thus the call \code{addProto2\$add()}
+looks for \code{add} in \code{addProto2} and not finding it there
+searches its parent, \code{addProto}, where it is, indeed, found.
+\code{add} is invoked with the receiver object, \code{addProto2}, as
+the value of dot.
+The call \code{addProto2\$add()} actually causes the \code{add}
+in \code{addProto} to run but it still uses the \code{x} from
+\code{addProto2} since dot (\code{.}) is \code{addProto2} here
+and \code{add} references \code{.\$x}.
+Note that the reference to \code{.\$x} in the
+\code{add} found in \code{addProto}
+does not refer to the \code{x} in \code{addProto} itself.
+The \code{x} in \code{addProto2} has overridden the \code{x} in its parent.
+This point is important so the reader should take care to absorb this
+point.
+
+This simple example already shows the key elements of the system
+and how \emph{delegation} (the prototype programming term for inheritance)
+works without classes.
+
+We can add new components or replace components in an object and
+invoke various methods like this:
+\begin{Schunk}
+\begin{Sinput}
+> addProto2$y <- seq(2, 10, 2)
+> addProto2$x <- 1:10
+> addProto2$add3 <- function(., z) sum(.$x) + sum(.$y) + sum(z)
+> addProto2$add()
+\end{Sinput}
+\begin{Soutput}
+[1] 55
+\end{Soutput}
+\begin{Sinput}
+> addProto2$add3(c(2, 3, 5))
+\end{Sinput}
+\begin{Soutput}
+[1] 95
+\end{Soutput}
+\begin{Sinput}
+> addProto2$y
+\end{Sinput}
+\begin{Soutput}
+[1] 2 4 6 8 10
+\end{Soutput}
+\end{Schunk}
+
+In this example, we insert variable \code{y} into the object \code{addProto2}
+with a value of \code{seq(2,10,2)},
+reset variable \code{x} to a new value and insert a new method,
+\code{add3}. Then we invoke
+our two methods and display \code{y}. Again, note that in the case of
+\code{protoAdd2\$add} the \code{add} method is not present in
+\code{protoAdd2} and so search continues to the parent \code{addProto}
+where it is found.
+
+\subsection{Internals}
+\label{sec:internals}
+
+So far, we have used simple examples to illustrate the basic manipulation
+of objects: construction, getting and setting components and method
+invocation. We now discuss the internals of the package and how it relates
+to \proglang{R} constructs.
+\code{proto} is actually an \proglang{S3} class which is a subclass
+of the \code{environment} class. Every \code{proto} object is an
+environment and its class is \code{c("proto", "environment")}. The \code{\$}
+accessor is similar to the same accessor in environments except it will
+use the \proglang{R} \code{get} function to
+search up parent links if it cannot otherwise find the object (unlike
+environments). When accessing a method, \code{\$}
+automatically supplies the
+first argument to the method
+unless the object is \code{.that} or \code{.super}. \code{.that}
+is a special variable which \code{proto} adds to every \code{proto} object
+denoting the object itself. \code{.super} is also added to every
+proto object and is the parent of \code{.that}. \code{.that}
+and \code{.super} are normally used
+within methods of an object to refer to other components of the same
+or parent object, respectively,
+as opposed to the receiver (\code{.}). For example,
+suppose we want \code{add} in \code{addProto2} to add the elements
+of \code{x} together and the elements of
+\code{y} together and then add these two sums. We could redefine add like this:
+
+\begin{Schunk}
+\begin{Sinput}
+> addProto2$add <- function(.) .super$add(.) + sum(.$y)
+\end{Sinput}
+\end{Schunk}
+
+making use of the \code{add} already defined in the parent.
+One exception should be noted here. When one uses \code{.super},
+as above, or \code{.that} to specify a method then the receiver
+object must be explicitly specified
+in argument one (since in those cases the receiver
+is possibly different than
+\code{.super} or \code{.that} so the system cannot automatically supply it
+to the call.)
+
+Setting a value is similar to the corresponding operation for
+environments except that any function, i.e method, which is
+inserted has its environment set to the environment of the object
+into which it is being inserted. This is necessary so that such
+methods can reference \code{.that} and \code{.super} using
+lexical scoping.
+
+In closing this section a few points should be re-emphasized and
+expanded upon. A
+\code{proto} object is an environment whose parent object is the
+parent environment of the \code{proto} object. The methods in the \code{proto}
+objects are ordinary functions that have the containing object as their
+environment.
+
+The \proglang{R} \code{with} function can be used with environments and
+therefore can be used with \code{proto} objects since \code{proto}
+objects are environments too. Thus \code{with(addProto, x)} refers
+to the variable \code{x} in \code{proto} object \code{addProto}
+and \code{with(addProto, add)} refers to the method \code{add}
+in the same way. \code{with(addProto, add)(addProto)} can be used
+to call \code{add}. These constructs all follow from their corresponding
+use in environments from which they are inherited.
+
+Because the \code{with} expressions are somewhat verbose, two common
+cases can be shortened using the \code{\$} operator. \code{addProto\$x}
+can be used to refer to variable \code{x} in \code{proto} object
+\code{addProto} and has the same meaning as \code{with(addProto, x)}.
+In particular like \code{with} but
+unlike the the behavior of the \code{\$} operator on
+environments, when used with \code{proto} objects, \code{\$} will
+search not only the object itself but also its ancestors.
+Similarly \code{addProto\$add()} can be used to call
+method \code{add} in \code{addProto} also searching through ancestors
+if not found in \code{addProto}. Note that \code{addProto\$add}
+returns an object of class
+
+\code{c("instantiatedProtoMethod", "function")}
+which is derived from \code{add} such that the first argument,
+the \code{proto} object,
+is already inserted. Note that there is a \code{print} method for
+class \code{"instantiatedProtoMethod"} so printing such objects will
+display the underlying function but returning such objects
+is not the same as returning the function without slot one inserted.
+Thus, if one wants exactly the original \code{add}
+as a value one should use \code{with(addProto, add)} or
+\code{addProto\$with(add)}.
+
+Within a method, if a variable is referred to without
+qualification simply as \code{x}, say, then its meaning is
+unchanged from how it is otherwise used in \proglang{R} and
+follows the same scope rules as any variable to resolve its name. If it is
+desired that the variable have object scope, i.e. looked up
+in the receiver object and its ancestors, then \code{.\$x}
+or similar \code{with} notation, i.e. \code{with(., x)}, should be used.
+Similarly \code{.\$f(x)} calls
+method \code{f} automatically inserting the receiver object
+into argument one and using \code{x} for argument two. It
+looks for \code{f} first in the receiver object and then its
+ancestors.
+
+\subsection{Traits}
+\label{sec:traits}
+
+Let us look at the definition of a child object once again.
+In the code below,
+\code{addProto} is the previously defined parent object
+and the expression \code{addProto\$proto(x = 1:5)} defines
+a child object of \code{addProto} and assigns it to variable
+\code{addProto2a}.
+
+\begin{Schunk}
+\begin{Sinput}
+> addProto2a <- addProto$proto(x = 1:5)
+> addProto2a$add()
+\end{Sinput}
+\begin{Soutput}
+[1] 15
+\end{Soutput}
+\end{Schunk}
+
+That is, \code{proto} can be used to create a new child of
+an existing object by writing the
+parent object on the left of the \code{\$} and
+\code{proto} on its right. Any contents to
+be added to the new child are listed in arguments of \code{proto}
+as shown.
+
+For example, first let us create a class-like structure. In the
+following \code{Add} is an object that behaves very much like a class
+with an \code{add} method and a method \code{new} which constructs
+new objects. In the line creating object \code{add1} the expression
+\code{Add\$new(x = 1:5)} invokes the \code{new} constructor of the
+receiver object \code{Add}. The method \code{new} has an argument of
+\code{x = 1:5} which defines an \code{x} variable in the \code{add1}
+object being instantiated. We similarly create another object
+\code{add2}.
+
+\begin{Schunk}
+\begin{Sinput}
+> Add <- proto(add = function(.) sum(.$x), new = function(., x) .$proto(x = x))
+> add1 <- Add$new(x = 1:5)
+> add1$add()
+\end{Sinput}
+\begin{Soutput}
+[1] 15
+\end{Soutput}
+\begin{Sinput}
+> add2 <- Add$new(x = 1:10)
+> add2$add()
+\end{Sinput}
+\begin{Soutput}
+[1] 55
+\end{Soutput}
+\end{Schunk}
+
+An object which contains only methods and variables that are
+intended to be shared by all its children (as opposed to an
+object whose purpose is to have its own methods and variables)
+is known as a \emph{trait} \citep{Agesen1992}. It
+is similar to a class in class-based
+object oriented programming.
+Note that the objects \code{add1} and \code{add2} have the trait
+\code{Add} as their parent. We could implement subclass-like and
+superclass-like objects by simply defining similar trait objects to
+be the parent or child of \code{Add}. For example, suppose we
+want a class which calculates the sum of the logarithms of the data. We
+could define:
+
+\begin{Schunk}
+\begin{Sinput}
+> Logadd <- Add$proto(logadd = function(.) log(.$add()))
+> logadd1 <- Logadd$new(1:5)
+> logadd1$logadd()
+\end{Sinput}
+\begin{Soutput}
+[1] 2.70805
+\end{Soutput}
+\end{Schunk}
+
+Here the capitalized objects are traits.
+\code{Logadd} is a trait. It is a child of \code{Add}
+which is also a trait. \code{logadd1} is an ordinary object,
+not a trait.
+One possible design is to create a tree of traits and other objects
+in which the leaves are ordinary objects and the remaining nodes
+are traits. This would closely correspond to class-based
+object oriented programming.
+
+Note that the delegation of methods from
+one trait to another as in
+\code{new} which is inherited by \code{Logadd} from \code{Add}
+is nothing more than the same mechanism by which traits delegate
+methods to
+objects since, of course, traits are just objects no different
+from any other object other than by the conventions we impose on them.
+This unification of subclassing and instantiation beautifully
+shows the simplification that prototype programming represents.
+
+\subsection{Utilities}
+\label{sec:utilities}
+The fact that method calls automatically insert the first argument
+can be used to good effect in leveraging existing \proglang{R}
+functions while allowing an object-oriented syntax.
+
+For example, \code{ls()} can be used to list the components of
+\code{proto} objects:
+
+\begin{Schunk}
+\begin{Sinput}
+> addProto$ls()
+\end{Sinput}
+\begin{Soutput}
+[1] "add" "x"
+\end{Soutput}
+\end{Schunk}
+
+Functions like:
+
+\begin{Schunk}
+\begin{Sinput}
+> addProto$str()
+> addProto$print()
+> addProto$as.list()
+> addProto2a$parent.env()
+\end{Sinput}
+\end{Schunk}
+
+show additional information about the elements. \code{eapply}
+can be used to explore more properties such as the
+the length of each component of an object:
+
+\begin{Schunk}
+\begin{Sinput}
+> addProto$eapply(length)
+\end{Sinput}
+\end{Schunk}
+
+Another example of some interest in any object oriented system
+which allows multiple references to one single object is that
+object identity
+can be tested using the respective base function:
+
+\begin{Schunk}
+\begin{Sinput}
+> addProto$identical(addProto2)
+\end{Sinput}
+\begin{Soutput}
+[1] FALSE
+\end{Soutput}
+\end{Schunk}
+
+\code{proto} does contain a special purpose \code{str.proto} function
+but in the main it
+is important to notice here, that
+\code{proto} has no code that is specific to \code{ls} or
+any of the other ordinary \proglang{R}
+functions listed. We are simply making use of the
+fact that \code{obj\$fun(...)} is transformed into \code{get("fun",
+obj)(obj, ...)} by the proto \code{\$} operator. For example, in the
+case of \code{addProto\$ls()} the system looks for \code{ls} in object
+\code{addProto}. It cannot find it there so it looks to its parent,
+which is the global environment. It does not find it there so it
+searches the remainder of the search path, i.e. the path shown by
+running the \proglang{R} command \code{search()}, and finally finds it
+in the base package, invoking it with an argument of \code{addProto}.
+Since all \code{proto} objects are also environments
+\code{ls(addProto)} interprets \code{addProto} as an environment and
+runs the \code{ls} command with it. In the \code{ls} example there
+were no arguments other than \code{addProto}, and even that one was
+implicit, but if there were
+additional arguments then they would be passed as shown in the
+\code{eapply} and \code{identical} examples above.
+
+\subsection{Plotting}
+\label{sec:plot}
+
+The \code{graph.proto} function can be used to create
+graphs that can be rendered by the \code{Rgraphviz} package
+creating visual representations of ancestor trees (figure
+\ref{fig:proto-dot}).
+That package provides an interface to the
+\proglang{GraphViz} \code{dot} program \citep{Ganser+North:1999}.
+
+\code{graph.proto} takes three arguments, all of which are
+usually omitted. The first argument is a \code{proto} object
+(or an environment) out of which all contained \code{proto} objects
+and their parents (but not higher order ancestors) are graphed.
+If it is omitted, the current environment is assumed.
+The second argument is a graph (in the sense of the \code{graph}
+package) to which the nodes and edges are added. If it is omitted
+an empty graph is assumed. The last argument is a logical variable
+that specifies the orientation of arrows. If omitted arrows are
+drawn from children to their parents.
+
+
+\input{proto-dot}
+
+\begin{figure}[htbp]
+\begin{center}
+\includegraphics{proto-dot}
+\caption{\label{fig:proto-dot} Ancestor tree generated using graph.proto. Edges
+point from child to parent.}
+\end{center}
+\end{figure}
+
+\pagebreak[4]
+
+\section{Examples}
+\label{sec:examples}
+
+\subsection{Smoothing}
+\label{sec:smooth}
+
+In the following we create a \code{proto} object named \code{oo}
+containing a vector of data \code{x} (generated from a simulated
+autoregressive model) and time points
+\code{tt}, an intermediate result
+\code{x.smooth}, some plotting parameters \code{xlab}, \code{ylab},
+\code{pch}, \code{col} and three methods \code{smooth}, \code{plot}
+and \code{residuals} which smooth the data, plot the data and
+calculate residuals, respectively. We also define \code{..x.smooth}
+which holds intermediate results. Names beginning with two dots
+prevent them from being delegated to children. If we override
+\code{x} in a child we would not want an out-of-sync \code{x.smooth}.
+Note that the components of an object can be specified using a code
+block in place of the argument notation we used previously in the
+\code{proto} command.
+
+\begin{Schunk}
+\begin{Sinput}
+> oo <- proto(expr = {
++ x <- rnorm(251, 0, 0.15)
++ x <- filter(x, c(1.2, -0.05, -0.18), method = "recursive")
++ x <- unclass(x[-seq(100)]) * 2 + 20
++ tt <- seq(12200, length = length(x))
++ ..x.smooth <- NA
++ xlab <- "Time (days)"
++ ylab <- "Temp (deg C)"
++ pch <- "."
++ col <- rep("black", 2)
++ smooth <- function(., ...) {
++ .$..x.smooth <- supsmu(.$tt, .$x, ...)$y
++ }
++ plot <- function(.) with(., {
++ graphics::plot(tt, x, pch = pch, xlab = xlab, ylab = ylab,
++ col = col[1])
++ if (!is.na(..x.smooth[1]))
++ lines(tt, ..x.smooth, col = col[2])
++ })
++ residuals <- function(.) with(., {
++ data.frame(t = tt, y = x - ..x.smooth)
++ })
++ })
+\end{Sinput}
+\end{Schunk}
+
+Having defined our \code{proto} object we can inspect it, as shown
+below, using
+\code{print} which is automatically invoked if the
+name of the object, \code{oo}, is entered on a line by itself.
+In this case, there is no proto print method so we inherit the
+environment print method which displays the environment hash code.
+Although it produces too much output to show here,
+we could have displayed a
+list of the entire contents of the object \code{oo}
+via \code{oo\$as.list(all.names = TRUE)}.
+We can get a list of the names of the
+components of the object using \code{oo\$ls(all.names = TRUE)} and will look
+at the contents of one component, \code{oo\$pch}.
+
+\begin{Schunk}
+\begin{Sinput}
+> oo
+\end{Sinput}
+\begin{Soutput}
+<environment: 0x01fbd8c8>
+attr(,"class")
+[1] "proto" "environment"
+\end{Soutput}
+\begin{Sinput}
+> oo$ls(all.names = TRUE)
+\end{Sinput}
+\begin{Soutput}
+ [1] "..x.smooth" ".super" ".that" "col" "pch"
+ [6] "plot" "residuals" "smooth" "tt" "x"
+[11] "xlab" "ylab"
+\end{Soutput}
+\begin{Sinput}
+> oo$pch
+\end{Sinput}
+\begin{Soutput}
+[1] "."
+\end{Soutput}
+\end{Schunk}
+
+Let us illustrate a variety of manipulations. We will set up the
+output to plot 2 plots per screen using \code{mfrow}. We change the
+plotting symbol, smooth the data, invoke the \code{plot} method to
+display a plot of the data and the smooth and then plot the residuals
+in the second plot (figure \ref{fig:proto-smooting03}).
+
+
+\input{proto-smoothing03}
+
+\begin{figure}[h!]
+\begin{center}
+\includegraphics[width=\textwidth]{proto-smoothing03}
+\end{center}
+\caption{Data and smooth from \code{oo\$plot()} (left) and plot of
+\code{oo\$residuals()} (right).}
+\label{fig:proto-smooting03}
+\end{figure}
+
+
+Now let us illustrate the creation of a child object and delegation.
+We create a new child object of \code{oo} called \code{oo.res}. We
+will override the \code{x} value in its parent by setting \code{x} in
+the child to the value of the residuals in the parent. We will also
+override the \code{pch} and \code{ylab} plotting parameters. We will
+return to 1 plot per screen and run \code{plot} using the
+\code{oo.res} object as the receiver invoking the \code{smooth} and
+\code{plot} methods (which are delegated from the parent \code{oo})
+with the data in the child (figure \ref{fig:smoothing04}).
+
+\input{proto-smoothing04}
+% \begin{figure}[tp]
+\begin{figure}[h!]
+\begin{center}
+\includegraphics[width=\half]{proto-smoothing04}
+\end{center}
+\caption{Output of \code{oo.res\$plot()}.
+\code{oo.res\$x} contains the residuals from \code{oo}.}
+\label{fig:smoothing04}
+\end{figure}
+Now we make use of delegation to change the parent
+and child in a consistent way with respect to certain plot characteristics.
+We have been using a numeric time axis.
+Let us interpret these numbers as the number of days since the Epoch,
+January 1, 1970, and let us also change the plot colors.
+
+\begin{Schunk}
+\begin{Sinput}
+> oo$tt <- oo$tt + as.Date("1970-01-01")
+> oo$xlab <- format(oo.res$tt[1], "%Y")
+> oo$col <- c("blue", "red")
+\end{Sinput}
+\end{Schunk}
+
+
+We can introduce a new method, \code{splot}, into
+the parent \code{oo} and have it automatically
+inherited by its children. In this example
+it smooths and then plots and we use it with
+both \code{oo} and \code{oo.res} (figure \ref{fig:smoothing06}).
+
+
+\input{proto-smoothing06}
+
+\begin{figure}[tbp]
+\begin{center}
+\includegraphics[width=\textwidth]{proto-smoothing06}
+\caption{Plotting options and \code{splot} function applied
+to both parent (left) and child (right) object}
+\label{fig:smoothing06}
+\end{center}
+\end{figure}
+
+Numerous possibilities exist to make use of the
+mechanisms shown, so one may create different child objects, apply
+different smoothing parameters, overwrite the smoothing function with
+a lowess smoother and finally compare fits and residuals.
+
+Now lets change the data and repeat the analysis. Rather than
+overwrite the data we will preserve it in \code{oo} and create a child
+\code{oos} to hold an analysis with sinusoidal data.
+
+\begin{Schunk}
+\begin{Sinput}
+> oos <- oo$proto(expr = {
++ tt <- seq(0, 4 * pi, length = 1000)
++ x <- sin(tt) + rnorm(tt, 0, 0.2)
++ })
+> oos$splot()
+\end{Sinput}
+\end{Schunk}
+
+Lets perform the residual analysis with \code{oos}.
+We will make a deep copy of \code{oo.res}, i.e. duplicate its
+contents and not merely delegate it, by copying \code{oo.res}
+to a list from which we create the duplicate, or cloned,
+\code{proto} object (figure \ref{fig:smoothing10} and \ref{fig:cloning}):
+
+\begin{Schunk}
+\begin{Sinput}
+> oos.res <- as.proto(oo.res$as.list(), parent = oos)
+> oos.res$x <- oos$residuals()$y
+> oos.res$splot()
+\end{Sinput}
+\end{Schunk}
+
+
+\begin{figure}[tbp]
+\begin{center}
+\includegraphics[width=\textwidth]{proto-smoothing10}
+\caption{Smoothing of sinusoidal data (left)
+and of their residuals (right)}\label{fig:smoothing10}
+\end{center}
+\end{figure}
+
+\begin{figure}[h!]
+\begin{center}
+\includegraphics[width=50mm]{cloning3.pdf}
+\caption{Cloning (dashed line) and delegation (solid line). Edges point
+from child to parent.}\label{fig:cloning}
+\end{center}
+\end{figure}
+
+We have delegated variables
+and methods and overridden both.
+Thus, even with such a simple analysis, object orientation
+and delegation came into play.
+The reader can plainly see that smoothing and residual
+analysis were not crucial to the example and this example
+could be replaced with any statistical analysis including
+likelihood or other estimation techniques, time series, survival
+analysis, stochastic processes and so on. The key aspect is
+just that we are performing one-of analyses and do not want to
+set up an elaborate class infrastructure but just want to
+directly create objects to organize our calculations while
+relying on delegation and dispatch to eliminate redundancy.
+
+\subsection{Correlation, Fisher's Transform and Bootstrapping}
+\label{sec:corr}
+
+The common approach to
+confidence intervals for the correlation coefficient is to
+assume normality of the underlying data and then use Fisher's transform
+to transform the correlation coefficient to an approximately normal
+random variable.
+Fisher showed that with the above normality assumption, transforming
+the correlation coefficient using
+the hyperbolic arc tangent function
+yields a random variable
+approximately distributed with an
+$\frac{N(p, 1)}{\sqrt(n-3)}$ distribution. The transformed random
+variable can be used to create normal distribution confidence intervals
+and the procedure can be back transformed to get confidence intervals
+for the original correlation coefficient.
+
+A more recent approach to confidence intervals for the correlation
+coefficient is to use bootstrapping. This does not require the
+assumption of normality of the underlying distribution and requires
+no special purpose theory devoted solely to the correlation coefficient,
+
+Let us calculate the 95\%
+confidence intervals using Fisher's transform
+first. We use \code{GNP} and \code{Unemployed} from the Longley data
+set. First we retrieve the data set and extract the required columns
+into \code{x}. Then we set \code{n} to the number of cases
+and \code{pp} to the percentiles
+of interest. Finally we calculate the sample correlation and
+create a function to calculate the confidence interval using
+Fisher's Transform. This function not only returns the confidence
+interval but also stores it in \code{CI} in the receiver object.
+
+\begin{Schunk}
+\begin{Sinput}
+> longley.ci <- proto(expr = {
++ data(longley)
++ x <- longley[, c("GNP", "Unemployed")]
++ n <- nrow(x)
++ pp <- c(0.025, 0.975)
++ corx <- cor(x)[1, 2]
++ ci <- function(.) (.$CI <- tanh(atanh(.$corx) + qnorm(.$pp)/sqrt(.$n -
++ 3)))
++ })
+\end{Sinput}
+\end{Schunk}
+
+Now let us repeat this analysis using the bootstrapping approach. We
+derive a new object \code{longley.ci.boot} as child of
+\code{longley.ci}, setting the number of replications, \code{N}, and
+defining the procedure, \code{ci} which does the actual bootstrap
+calculation.
+
+\begin{Schunk}
+\begin{Sinput}
+> longley.ci.boot <- longley.ci$proto({
++ N <- 1000
++ ci <- function(.) {
++ corx <- function(idx) cor(.$x[idx, ])[1, 2]
++ samp <- replicate(.$N, corx(sample(.$n, replace = TRUE)))
++ (.$CI <- quantile(samp, .$pp))
++ }
++ })
+\end{Sinput}
+\end{Schunk}
+
+In the example code below the first line runs the Fisher Transform
+procedure and the second runs the bootstrap procedure. Just to check
+that we have performed sufficient bootstrap iterations we rerun it in
+the third line, creating a delegated object on-the-fly running its
+\code{ci} method and then immediately throwing the object away.
+The fact that 4,000
+replications give roughly the same result as 1,000 replications
+satisfies us that we have used a sufficient number of replications.
+
+\begin{Schunk}
+\begin{Sinput}
+> longley.ci$ci()
+\end{Sinput}
+\begin{Soutput}
+[1] 0.1549766 0.8464304
+\end{Soutput}
+\begin{Sinput}
+> longley.ci.boot$ci()
+\end{Sinput}
+\begin{Soutput}
+ 2.5% 97.5%
+0.2299395 0.8211854
+\end{Soutput}
+\begin{Sinput}
+> longley.ci.boot$proto(N = 4000)$ci()
+\end{Sinput}
+\begin{Soutput}
+ 2.5% 97.5%
+0.2480999 0.8259276
+\end{Soutput}
+\end{Schunk}
+
+We now have the results stored in two objects nicely organized for the
+future. Note, again, that despite the simplicity of the example we
+have used the features of object oriented programming, coupling the
+data and methods that go together, while relying on delegation and
+dispatch to avoid duplication.
+
+\subsection{Dendrograms}
+\label{sec:tree}
+
+In \cite{Gentleman2002} there is an \proglang{S4}
+example of creating a binary tree
+for use as a dendrogram. Here we directly define a binary tree with no
+setup at all. To keep it short we will create a binary tree of only
+two nodes having a root whose left branch points to a leaf. The leaf
+inherits the \code{value} and \code{incr} components from the root.
+The attractive feature is that the leaf be defined as a child of the
+parent using \code{proto} before the parent is even finished
+being defined. Compared to the cited \proglang{S4} example where it
+was necessary to create an extra class to introduce the required level of
+indirection there is no need to take any similar action.
+
+\code{tree} is the root node of the tree. It has four components. A
+method \code{incr} which increments the \code{value} component, a
+\code{..Name}, the \code{value} component itself and the left branch
+\code{..left}. \code{..left} is itself a proto object which is a
+child of \code{tree}. The leaf inherits the \code{value} component
+from its parent, the root. As mentioned, at the time we define
+\code{..left} we have not even finished defining \code{tree} yet we
+are able to implicitly reference the yet to be defined parent.
+
+\begin{Schunk}
+\begin{Sinput}
+> tree <- proto(expr = {
++ incr <- function(., val) .$value <- .$value + val
++ ..Name <- "root"
++ value <- 3
++ ..left <- proto(expr = {
++ ..Name = "leaf"
++ })
++ })
+\end{Sinput}
+\end{Schunk}
+
+Although this is a simple structure we could have embedded additional
+children into \code{root} and \code{leaf} and so on recursively making
+the tree or dendrogram arbitrarily complex.
+
+Let us do some computation with this structure. We display the
+\code{value} fields in the two nodes, increment the value field in the
+root and then display the two nodes again to show .that the leaf
+changed too.
+
+\begin{Schunk}
+\begin{Sinput}
+> cat("root:", tree$value, "leaf:", tree$..left$value, "\n")
+\end{Sinput}
+\begin{Soutput}
+root: 3 leaf: 3
+\end{Soutput}
+\begin{Sinput}
+> tree$incr(1)
+> cat("root:", tree$value, "leaf:", tree$..left$value, "\n")
+\end{Sinput}
+\begin{Soutput}
+root: 4 leaf: 4
+\end{Soutput}
+\end{Schunk}
+
+If we increment \code{value} in \code{leaf} directly (see the example
+below where we increment it by 10) then it receives its own copy of
+\code{value} so from that point on \code{leaf} no longer inherits
+\code{value} from \code{root}. Thus incrementing the root by 5 no
+longer increments the \code{value} field in the leaf.
+
+\begin{Schunk}
+\begin{Sinput}
+> tree$..left$incr(10)
+> cat("root:", tree$value, "leaf:", tree$..left$value, "\n")
+\end{Sinput}
+\begin{Soutput}
+root: 4 leaf: 14
+\end{Soutput}
+\begin{Sinput}
+> tree$incr(5)
+> cat("root:", tree$value, "leaf:", tree$..left$value, "\n")
+\end{Sinput}
+\begin{Soutput}
+root: 9 leaf: 14
+\end{Soutput}
+\end{Schunk}
+
+\subsection{From Prototypes to Classes}
+\label{sec:increment}
+
+In many cases we will use \pkg{proto} for a design that uses prototypes
+during the full development cycle. In other cases we may use it in an
+incremental way starting with prototypes but ultimately transitioning
+to classes.
+As shown in Section~\ref{sec:traits} the \pkg{proto} package is
+powerful enough to handle class-based as well as class-free programming.
+Here we illustrate this process of incremental design
+starting with
+concrete objects and then over time classifing them into classes,
+evolving a class-based program. \pkg{proto} provides a smooth
+transition path since it can handle both the class-free and the class-based
+phases -- there is no need to switch object systems part way through.
+In this example, we define an object which holds a linear equation, \code{eq},
+represented as a character string in terms of the unknown variable \code{x}
+and a \code{print} and a \code{solve} method. We execute the
+\code{print} method
+to solve it. We also create child object \code{lineq2}
+which overrides \code{eq} and execute its \code{print} method.
+
+\begin{Schunk}
+\begin{Sinput}
+> lineq <- proto(eq = "6*x + 12 - 10*x/4 = 2*x", solve = function(.) {
++ e <- eval(parse(text = paste(sub("=", "-(", .$eq), ")")),
++ list(x = 0+1i))
++ -Re(e)/Im(e)
++ }, print = function(.) cat("Equation:", .$eq, "Solution:", .$solve(),
++ "\n"))
+> lineq$print()
+\end{Sinput}
+\begin{Soutput}
+Equation: 6*x + 12 - 10*x/4 = 2*x Solution: -8
+\end{Soutput}
+\begin{Sinput}
+> lineq2 <- lineq$proto(eq = "2*x = 7*x-12+x")
+> lineq2$print()
+\end{Sinput}
+\begin{Soutput}
+Equation: 2*x = 7*x-12+x Solution: 2
+\end{Soutput}
+\end{Schunk}
+
+We could continue with enhancements but at this point we decide that we
+have a general case and so wish
+to abstract \code{lineq} into a class. Thus we define a trait,
+\code{Lineq}, which is just \code{lineq} minus \code{eq} plus
+a constructor \code{new}. The key difference between \code{new}
+and the usual \code{proto} function
+is that with \code{new} the initialization of \code{eq} is mandatory.
+Having completed this definition
+we instantiate an object of
+class/trait \code{Lineq} and execute it.
+
+\begin{Schunk}
+\begin{Sinput}
+> Lineq <- lineq
+> rm(eq, envir = Lineq)
+> Lineq$new <- function(., eq) proto(., eq = eq)
+> lineq3 <- Lineq$new("3*x=6")
+> lineq3$print()
+\end{Sinput}
+\begin{Soutput}
+Equation: 3*x=6 Solution: 2
+\end{Soutput}
+\end{Schunk}
+
+Note how we have transitioned from a prototype style of programming
+to a class-based style of programming all the while staying within
+the \pkg{proto} framework.
+
+\section{Summary} \label{sec:summary}
+
+\subsection{Benefits}
+\label{sec:benefits}
+
+The key benefit of the \pkg{proto} package is to provide
+access to a style of programming that has not been conveniently
+accessible within \proglang{R} or any other mainstream language today.
+
+\pkg{proto} can be used in two key ways: class-free object oriented programming
+and class-based object oriented programming.
+
+A key application for \pkg{proto} in class-free programming is to wrap the code
+and data for each run of a particular statistical study into an object for
+purposes of organization and reproducibility. It provides such organization
+directly and without the need and overhead of class definitions
+yet still provides the
+inheritance and dispatch advantages of object oriented programming.
+We provide examples of this style of programming in
+Section~\ref{sec:smooth}
+and
+Section~\ref{sec:corr}.
+A third example in
+Section~\ref{sec:tree} illustrates a beneficial use of \pkg{proto} with
+recursive data structures.
+
+Another situation where prototype programming is of interest is in the initial
+development stages of a program. In this case, the design may not be fully
+clear so it is more convenient to create concrete objects individually rather
+than premature abstractions through classes. The \code{graph.proto}
+function can be used to generate visual representations of the object
+tree suggesting classifications of objects so that
+as the program evolves the general case becomes clearer and
+in a bottom up fashion the objects are incrementally abstracted into
+classes. In this case,
+\pkg{proto} provides a smooth transition path since it not only supports
+class-free programming but, as explained in the Section~\ref{sec:traits}, is
+sufficiently powerful to support class-based programming, as well.
+
+
+\subsection{Conclusion}
+\label{sec:conclusion}
+
+The package \pkg{proto} provides an \proglang{S3} subclass of the
+\code{environment} class for constructing and manipulating object
+oriented systems without classes. It can also emulate classes even
+though classes are not a primitive structure. Its key design goals
+are to provide as simple and as thin a layer as practically possible
+while giving the user convenient access to this alternate object
+oriented paradigm. This paper describes, by example, how prototype
+programming can be carried out in \proglang{R} using \pkg{proto} and
+illustrates such usage. Delegation, cloning traits and general
+manipulation and incremental development are all reviewed by example.
+
+\section*{Computational details}
+\label{sec:compute}
+
+The results in this paper were obtained using \proglang{R} 2.1.0 with
+the package \pkg{proto} 0.3--2. \proglang{R} itself and the
+\pkg{proto} package are available from CRAN at
+\url{http://CRAN.R-project.org/}. The GraphViz software is available
+from \url{http://www.graphviz.org}.
+
+\phantomsection
+\addcontentsline{toc}{section}{References}
+\bibliography{proto}
+%\input{proto.bbl}
+
+\newpage\mbox{}
+\begin{appendix}
+\section{Frequently Asked Questions}
+\label{sec:faq}
+\begin{enumerate}
+\item{What scope do unqualified object references within methods use?
+
+A \pkg{proto} object is an environment and that environment
+is the environment
+of the methods in it (by default).
+That is, unqualified object references
+within a \pkg{proto} method look first in the method itself and secondly in the
+\pkg{proto} object containing the method.
+This is referred to as object
+scope as opposed to lexical scope or dynamic scope. It allows simple
+situations, where delegation is not used, to use unqualified names. Thus
+simple situations remain simple.
+\citep{Kates2004}
+discusses the fragile base class problem which
+relates to this question. Also note that if a \pkg{proto} object is created
+via the \code{proto} function using an argument of \code{funEnvir = FALSE}
+then the environment of the function/method will not be set as just
+described (but rather it will retain its original environment) so the
+above does not apply. This can be used for instances when non-default
+processing is desirable.}
+\item{Why does \code{obj\$meth} not return the method, \code{meth}?
+
+Conceptually \code{obj\$meth} returns \code{meth} but with
+\code{obj} already inserted into its first argument.
+This is termed an instantiated
+\pkg{proto}
+method and is of \proglang{S3} class \code{"instantiatedProtoMethod"}.
+
+In contrast, the method itself (i.e. the uninstantited method)
+would not have the first argument already
+inserted. To return the method itself use \code{with(obj, meth}.
+
+The main advantage of a design that makes the distinction between instantiated
+and uninstantiated methods is that uninstantiated methods are never
+changed so
+debugging can be more readily carried out (as discussed in the next
+question and answer).
+}
+\item{How does one debug a method?
+
+\pkg{proto} does not dynamically redefine methods. This has the advantage
+that the ordinary \proglang{R} \code{debug} and \code{undebug} commands can be
+used. When using these be sure that to use them with the uninstantiated method
+itself and not the instantiated method derived from it. That is,
+use:
+\begin{verbatim}
+ with(obj, debug(meth))
+\end{verbatim}
+
+and not
+\begin{verbatim}
+ debug(obj$meth) # wrong
+\end{verbatim}
+}
+\item{Is multiple inheritance supported?
+
+No. \pkg{proto} is just a thin layer on top of \proglang{R}
+environments and \proglang{R} environments
+provide single inheritance only. \citep{Kates2004}
+discusses some ways of handling situations which would otherwise require
+multiple inheritance.}
+\item{Does \pkg{proto} support lazy evaluation?
+
+Since \code{proto} methods are just \proglang{R} functions they do support
+lazy evaluation; however, the \code{proto} function itself
+does evaluate its arguments. To get the
+effect of lazy evaluation when using the \code{proto}
+function replace any properties with a function.
+
+If the caller is the parent of the \code{proto} object then its
+particularly simple. Note how we got the equivalent of lazy evaluation
+in the second example where f is a function:
+
+\begin{verbatim}
+# eager evaluation
+x <- 0
+p <- proto(f = x, g = function(.) $x)
+x <- 1
+p$f # 0
+
+# versus making f a function
+
+# simulates lazy evaluation
+x <- 0
+p <- proto(f = function(.) x, g = function(.) .$x)
+x <- 1
+p$f() # 1
+\end{verbatim}
+
+If we cannot guarantee that the proto object has the caller
+as its parent then ensure that the environment of the function
+has not been reset. If no method needs to reference \code{.that}
+or \code{.super} then we can arrange for that using
+\code{funEnvir=FALSE} as seen here in the second example:
+\begin{verbatim}
+
+# does not work as intended
+x <- 0
+p <- proto(x = 99)
+q <- p$proto(f = function(.) x, g = function(.) .$x)
+x <- 1
+q$f() # 99
+
+# does work
+x <- 0
+p <- proto(x = 99)
+q <- p$proto(f = function(.) x, g = function(.) .$x, funEnvir = FALSE)
+x <- 1
+q$f() # 1
+\end{verbatim}
+
+If we wish only to not reset the function used to simulate
+lazy evaluation then we can do it using either of the
+two equivalent alternatives below. \code{g}
+is an ordinary method whose environment is reset to \code{q}
+whereas \code{f} is a function whose environment is not reset and
+serves to provide lazy evaluation for \code{x} found in the caller.
+
+\begin{verbatim}
+x <- 0
+p <- proto(x = 99)
+# g will use q's y in children of q even if those children
+# override y
+q <- p$proto(y = 25, g = function(.) .that$y + .$x)
+q[["f"]] <- function(.) x
+x <- 1
+q$f() # 1
+
+# equivalent alternative
+
+x <- 0
+p <- proto(x = 99)
+q <- proto(f = function(.) x, funEnvir = FALSE,
+ envir = p$proto(y = 25, g = function(.) .that$y + .$x))
+x <- 1
+q$f() # 1
+\end{verbatim}
+}
+\end{enumerate}
+\newpage{}
+\section{Reference Card}
+\label{sec:ref}
+\input{protoref-raw}
+\end{appendix}
+
+\end{document}
+
diff --git a/vignettes/proto.bib b/vignettes/proto.bib
old mode 100755
new mode 100644
diff --git a/vignettes/proto.tex b/vignettes/proto.tex
old mode 100755
new mode 100644
index 6970659..8ba6946
--- a/vignettes/proto.tex
+++ b/vignettes/proto.tex
@@ -1,22 +1,1358 @@
-% To build the vignette:
-% 1. run Sweave("proto-raw") to create proto-raw.tex
-% 2. build as usual using Rcmd build proto
-%
-% To build vignette manually:
-% 1. Sweave("proto-raw") to create proto-raw.tex
-% 2. Sweave("proto.Rnw")
-% 3. pdflatex proto.tex
-%
-% To build manually using sweave.bat using batchfiles on Windows:
-% 1. sweave proto-raw --tex
-% 2. sweave proto
-
-
-
-%\VignetteIndexEntry{proto: An R Package for Prototype Programming}
-%\VignetteDepends{}
-%\VignetteKeywords{object oriented, prototype programming, S3, R}
-%\VignettePackage{proto}
-
-\input{proto-raw}
-
+%\VignetteIndexEntry{proto: An R Package for Prototype Programming}
+%\VignetteDepends{}
+%\VignetteKeywords{object oriented, prototype programming, S3, R}
+%\VignettePackage{proto}
+
+\documentclass[nojss]{jss}
+\usepackage{Sweave}
+\DeclareGraphicsExtensions{.pdf, .eps, .png}
+
+\newlength{\half}
+\setlength{\half}{70mm}
+
+\author{Louis Kates\\GKX Associates Inc. \And
+ Thomas Petzoldt\\Technische Universit\"at Dresden}
+\Plainauthor{Louis Kates, Thomas Petzoldt}
+
+\title{\pkg{proto}: An \proglang{R} Package for Prototype Programming}
+%% \Shorttitle{\pkg{proto}: An \proglang{R} Package for Prototype Programming}
+
+\Plaintitle{proto: An R Package for Prototype Programming}
+
+\Keywords{prototype programming, delegation, inheritance, clone,
+ object orientated, \proglang{S3}, \proglang{R}}
+\Plainkeywords{object oriented, prototype programming, S3, R}
+
+\Abstract{
+
+ \pkg{proto} is an \proglang{R} package which facilitates a style
+ of programming known as prototype
+ programming. Prototype programming is a type of object
+ oriented programming in which there are no classes.
+ \pkg{proto} is simple yet retains the object oriented features of
+ delegation (the prototype counterpart to inheritance)
+ and object oriented dispatch. \code{proto} can be used
+ to organize the concrete data and procedures in statistical studies
+ and other applications
+ without the necessity of defining classes while still providing convenient
+ access to an object oriented style of programming. Furthermore, it
+ can be used in a class-based style as well so that incremental design can
+ begin with defining the concrete objects and later transition to abstract
+ classes, once the general case is understood, without having to change to
+ object-oriented frameworks.
+ The key goals of the package are to integrate into \proglang{R}
+ while providing nothing more than a thin layer on top of it.
+}
+
+\hyphenation{ma-ni-pu-lating}
+
+\begin{document}
+\input{proto-concordance}
+
+
+
+
+\section{Introduction} \label{sec:intro}
+
+\subsection[Object Oriented Programming in R]{Object Oriented Programming in \proglang{R}}
+\label{sec:oo}
+
+The \proglang{R} system for statistical computing
+\citep[\url{http://www.R-project.org/}]{Rcore2005} ships with two
+systems for object oriented programming referred to as \proglang{S3}
+and \proglang{S4}. With the increased interest in object oriented
+programming within \proglang{R} over the last years additional object
+oriented programming packages emerged. These include the \pkg{R.oo}
+package \citep{Bengtsson2003} and the \pkg{OOP} package
+\citep[\url{http://www.omegahat.net/OOP/}]{Rnews:Chambers+Lang:2001a}.
+All these packages have the common thread that they use
+classes as the basis of inheritance. When a message is sent to an
+object the class of the object is examined and that class determines the
+specific function to be executed. In prototype programming there
+are no classes making it simple yet it retains much of the power of
+class-based programming. In the fact, \pkg{proto} is so simple that
+there is only one significant new routine name, \code{proto}. The
+other routines are just the expected support routines such as
+\code{as.proto} to coerce objects to proto objects, \code{\$} to
+access and set proto object components and \code{is.proto} to check
+whether an object is a proto object. In addition, \code{graph.proto}
+will generate a graphical ancestor tree showing the parent-child
+relationships among generated \code{proto} objects.
+
+The aim of the package is to provide a lightweight layer for prototype
+programming in \proglang{R} written only in \proglang{R} leveraging the
+existing facilities of the language rather than adding its own.
+
+\subsection{History}
+\label{sec:history}
+
+The concept of
+prototype programming
+\citep{Lieberman1986, Taivalsaari1996a, Noble1999}
+has developed over a number of years with the \proglang{Self}
+language \citep{Agesen1992}
+being the key evolved programming language to demonstrate
+the concept. In statistics, the \proglang{Lisp}-based
+\proglang{LispStat} programming language \citep{Tierney1990} was
+the first and possibly only statistical system to feature prototype
+programming.
+
+Despite having been developed over 20 years ago, and some attempts to
+enter the mainstream (e.g. \proglang{Newtonscript}
+on the Newton computer, which
+is no longer available, and \proglang{Javascript} where
+it is available but whose
+domain of application largely precluses use of prototype programming)
+prototype programming is not well known due to lack of language
+support in popular programming languages such as \proglang{C} and
+\proglang{Java}. It tends
+to be the domain of research languages or \proglang{Lisp}.
+
+Thus the
+the availability of a popular language,
+\proglang{R} \footnote{Some indications of the popularity of R are
+the high volume mailing lists, international development team, the
+existence of over 500 addon packages, conferences and numerous books
+and papers devoted to R.},
+that finally does provide the key infrastructure
+is an important development.
+
+This work grew out of the need to organize multiple scenarios of model
+simulations in ecological modelling \citep{Rnews:Petzoldt:2003} and
+was subsequently generalized to the present package. A number of
+iterations of the code, some motivated by the ever increasing feature
+set in \proglang{R}, resulted in a series of utilities and ultimately
+successive versions of an \proglang{R} package developed over the last
+year. An initial version used \proglang{R} lists as the basis of the
+package. Subsequently the package was changed to use \proglang{R}
+environments. The first version to use environments stored the
+receiver object variable in a proxy parent environment which was
+created on-the-fly at each method call. The present version of
+the \pkg{proto} package passes the receiver object through the argument list,
+while hiding this from the caller. It defines the \code{proto} class
+as a subclass of the \code{environment} class so that
+functionality built into \proglang{R} for the environment class is
+automatically inherited by the \code{proto} class.
+
+\subsection{Overview}
+\label{sec:overview}
+
+It is assumed that the reader has some general
+familiarity with object oriented programming concepts and with
+\proglang{R}.
+
+The paper will proceed primarily by example focusing on illustrating
+the package \code{proto} through such demonstration. The remainder of
+the paper is organized as follows: Section~\ref{sec:proto-class}
+explains how \code{"proto"} objects are created and illustrates the
+corresponding methods for setting and getting components. It further
+discusses how object oriented delegation (the prototype programming
+analogue of inheritance) is handled and finally discusses the
+internals of the package. This section uses small examples chosen for
+their simplicity in illustrating the concepts. In
+Section~\ref{sec:examples} we provide additional examples of prototype
+programming in action. Four examples are shown. The first involves
+smoothing of data. Secondly we demonstrate the calculation of
+correlation confidence intervals using classical (Fisher Transform)
+and modern (bootstrapping) methods. Thirdly we demonstrate the
+development of a binary tree as would be required for a dendrogram.
+Fourthly, we use the solution of linear equations to illustrate
+program evolution from object-based to class-based, all
+within the \pkg{proto} framework.
+Section~\ref{sec:summary} gives a few summarizing remarks. Finally,
+an appendix provides a reference card that summarizes the
+functionality contained in \pkg{proto} in terms of its constituent
+commands.
+
+%% \pagebreak[4]
+
+\section[The class "proto" and its methods]{The class \code{"proto"} and its methods}
+\label{sec:proto-class}
+
+\subsection[Creation of "proto" objects]{Creation of \code{"proto"} objects}
+\label{sec:proto}
+
+In this section we shall show, by example, the creation of two
+prototype objects and related operations. The simple idea is that
+each \code{"proto"} object is a set of components: functions (methods)
+and variables, which are tightly related in some way.
+
+A prototype object is an environment holding the variables and
+methods of the object. \footnote{In particular this implies that
+\code{"proto"} objects have single inheritance, follow ordinary
+environment scoping rules and have mutable state as environments
+do.}
+
+A prototype object is created using the constructor function
+\code{proto} (see Appendix~\ref{sec:ref} at the end of this paper or
+\pkg{proto} package help for complete syntax of commands).
+
+\begin{Scode}
+addProto <- proto( x = rnorm(5), add = function(.) sum(.$x) )
+\end{Scode}
+
+In this simple example, the \code{proto} function defines two
+components: a variable \code{x} and a method \code{add}. The variable
+\code{x} is a vector of 5 numbers and the method sums those numbers.
+The \code{proto} object \code{addProto} contains the variable and the
+method. Thus the \code{addProto} \code{proto} object can be used to compute
+the sum of the values stored in it.
+As shown with the \code{add} method in this example, formal argument
+lists of methods must always have a first argument of dot
+(i.e. \code{.}) which signifies the object on which the method is
+operating. The dot refers to the current object in the same way that
+a dot refers to the current directory in UNIX. Within the method one
+must refer to other variables and methods in the object by prefacing
+each with \code{.\$}. For example, in the above we write
+\code{sum(.\$x)}. Finally, note that the data and the method are very
+closely related. Such close coupling is important in order to create
+an easily maintained system.
+
+To illustrate the usage of \code{proto}, we first load the package and
+set the random seed to make the examples in this paper exactly
+reproducible.
+
+\begin{Schunk}
+\begin{Sinput}
+> library(proto)
+> set.seed(123)
+\end{Sinput}
+\end{Schunk}
+
+Then, we create the \code{proto} object from above
+and call its \code{add} method.
+\begin{Schunk}
+\begin{Sinput}
+> addProto <- proto(x = rnorm(5), add = function(.) sum(.$x))
+> addProto$add()
+\end{Sinput}
+\begin{Soutput}
+[1] 0.9678513
+\end{Soutput}
+\end{Schunk}
+We also create another object, \code{addProto2}
+with a different \code{x} vector and
+invoke its \code{add} method too.
+\begin{Schunk}
+\begin{Sinput}
+> addProto2 <- addProto$proto(x = 1:5)
+> addProto2$add()
+\end{Sinput}
+\begin{Soutput}
+[1] 15
+\end{Soutput}
+\end{Schunk}
+In the examples above, we created a prototype object \code{addProto}
+and then called its \code{add} method as just explained.
+The notation \code{addProto\$add}
+tells the system to look for the \code{add} method
+in the \code{addProto} object. In the expression \code{addProto\$add},
+the \code{proto} object to the left
+of the dollar sign, \code{addProto} here, is referred to as the
+\emph{receiver} object. This expression
+also has a second purpose which is to
+pass the receiver object implicitly as the first argument of \code{add}.
+Note that we called \code{add} as if it had zero arguments but, in fact,
+it has one argument because the receiver is automatically and implicitly
+supplied as the first argument. In general,
+the notation \code{object\$method(arguments)} is
+used to invoke the indicated method of the receiver object using the
+object as the implicit first argument along with the indicated
+arguments as the subsequent arguments.
+As with the \code{addProto} example, the receiver
+object not only determines where to find the
+method but also is implicitly passed to the method through
+the first argument. The motivation for this notation
+is to relieve the user of
+specifying the receiver object twice:
+once to locate the method in the object and a second
+time to pass the object itself to the method.
+The \code{\$} is overloaded by the \code{proto}
+class to automatically do both with one reference to the receiver object.
+Even though, as with the \code{addProto} example, the first
+argument is not listed in the call
+it still must be listed among the formal arguments
+in the definition of the method. It
+is conventional to use
+a dot \code{.} as the first formal argument in the method/function
+definition. That is, we call \code{add} using \code{addProto\$add()}
+displaying zero arguments
+but we define \code{add} in \code{addProto} displaying
+one argument \code{add <- function(.)}, the dot.
+
+In this example,
+we also created a second object, \code{addProto2},
+which has the first object, \code{addProto} as its parent.
+Any reference to a
+component in the second object that is unsuccessful will cause
+search to continue in the parent. Thus the call \code{addProto2\$add()}
+looks for \code{add} in \code{addProto2} and not finding it there
+searches its parent, \code{addProto}, where it is, indeed, found.
+\code{add} is invoked with the receiver object, \code{addProto2}, as
+the value of dot.
+The call \code{addProto2\$add()} actually causes the \code{add}
+in \code{addProto} to run but it still uses the \code{x} from
+\code{addProto2} since dot (\code{.}) is \code{addProto2} here
+and \code{add} references \code{.\$x}.
+Note that the reference to \code{.\$x} in the
+\code{add} found in \code{addProto}
+does not refer to the \code{x} in \code{addProto} itself.
+The \code{x} in \code{addProto2} has overridden the \code{x} in its parent.
+This point is important so the reader should take care to absorb this
+point.
+
+This simple example already shows the key elements of the system
+and how \emph{delegation} (the prototype programming term for inheritance)
+works without classes.
+
+We can add new components or replace components in an object and
+invoke various methods like this:
+\begin{Schunk}
+\begin{Sinput}
+> addProto2$y <- seq(2, 10, 2)
+> addProto2$x <- 1:10
+> addProto2$add3 <- function(., z) sum(.$x) + sum(.$y) + sum(z)
+> addProto2$add()
+\end{Sinput}
+\begin{Soutput}
+[1] 55
+\end{Soutput}
+\begin{Sinput}
+> addProto2$add3(c(2, 3, 5))
+\end{Sinput}
+\begin{Soutput}
+[1] 95
+\end{Soutput}
+\begin{Sinput}
+> addProto2$y
+\end{Sinput}
+\begin{Soutput}
+[1] 2 4 6 8 10
+\end{Soutput}
+\end{Schunk}
+
+In this example, we insert variable \code{y} into the object \code{addProto2}
+with a value of \code{seq(2,10,2)},
+reset variable \code{x} to a new value and insert a new method,
+\code{add3}. Then we invoke
+our two methods and display \code{y}. Again, note that in the case of
+\code{protoAdd2\$add} the \code{add} method is not present in
+\code{protoAdd2} and so search continues to the parent \code{addProto}
+where it is found.
+
+\subsection{Internals}
+\label{sec:internals}
+
+So far, we have used simple examples to illustrate the basic manipulation
+of objects: construction, getting and setting components and method
+invocation. We now discuss the internals of the package and how it relates
+to \proglang{R} constructs.
+\code{proto} is actually an \proglang{S3} class which is a subclass
+of the \code{environment} class. Every \code{proto} object is an
+environment and its class is \code{c("proto", "environment")}. The \code{\$}
+accessor is similar to the same accessor in environments except it will
+use the \proglang{R} \code{get} function to
+search up parent links if it cannot otherwise find the object (unlike
+environments). When accessing a method, \code{\$}
+automatically supplies the
+first argument to the method
+unless the object is \code{.that} or \code{.super}. \code{.that}
+is a special variable which \code{proto} adds to every \code{proto} object
+denoting the object itself. \code{.super} is also added to every
+proto object and is the parent of \code{.that}. \code{.that}
+and \code{.super} are normally used
+within methods of an object to refer to other components of the same
+or parent object, respectively,
+as opposed to the receiver (\code{.}). For example,
+suppose we want \code{add} in \code{addProto2} to add the elements
+of \code{x} together and the elements of
+\code{y} together and then add these two sums. We could redefine add like this:
+
+\begin{Schunk}
+\begin{Sinput}
+> addProto2$add <- function(.) .super$add(.) + sum(.$y)
+\end{Sinput}
+\end{Schunk}
+
+making use of the \code{add} already defined in the parent.
+One exception should be noted here. When one uses \code{.super},
+as above, or \code{.that} to specify a method then the receiver
+object must be explicitly specified
+in argument one (since in those cases the receiver
+is possibly different than
+\code{.super} or \code{.that} so the system cannot automatically supply it
+to the call.)
+
+Setting a value is similar to the corresponding operation for
+environments except that any function, i.e method, which is
+inserted has its environment set to the environment of the object
+into which it is being inserted. This is necessary so that such
+methods can reference \code{.that} and \code{.super} using
+lexical scoping.
+
+In closing this section a few points should be re-emphasized and
+expanded upon. A
+\code{proto} object is an environment whose parent object is the
+parent environment of the \code{proto} object. The methods in the \code{proto}
+objects are ordinary functions that have the containing object as their
+environment.
+
+The \proglang{R} \code{with} function can be used with environments and
+therefore can be used with \code{proto} objects since \code{proto}
+objects are environments too. Thus \code{with(addProto, x)} refers
+to the variable \code{x} in \code{proto} object \code{addProto}
+and \code{with(addProto, add)} refers to the method \code{add}
+in the same way. \code{with(addProto, add)(addProto)} can be used
+to call \code{add}. These constructs all follow from their corresponding
+use in environments from which they are inherited.
+
+Because the \code{with} expressions are somewhat verbose, two common
+cases can be shortened using the \code{\$} operator. \code{addProto\$x}
+can be used to refer to variable \code{x} in \code{proto} object
+\code{addProto} and has the same meaning as \code{with(addProto, x)}.
+In particular like \code{with} but
+unlike the the behavior of the \code{\$} operator on
+environments, when used with \code{proto} objects, \code{\$} will
+search not only the object itself but also its ancestors.
+Similarly \code{addProto\$add()} can be used to call
+method \code{add} in \code{addProto} also searching through ancestors
+if not found in \code{addProto}. Note that \code{addProto\$add}
+returns an object of class
+
+\code{c("instantiatedProtoMethod", "function")}
+which is derived from \code{add} such that the first argument,
+the \code{proto} object,
+is already inserted. Note that there is a \code{print} method for
+class \code{"instantiatedProtoMethod"} so printing such objects will
+display the underlying function but returning such objects
+is not the same as returning the function without slot one inserted.
+Thus, if one wants exactly the original \code{add}
+as a value one should use \code{with(addProto, add)} or
+\code{addProto\$with(add)}.
+
+Within a method, if a variable is referred to without
+qualification simply as \code{x}, say, then its meaning is
+unchanged from how it is otherwise used in \proglang{R} and
+follows the same scope rules as any variable to resolve its name. If it is
+desired that the variable have object scope, i.e. looked up
+in the receiver object and its ancestors, then \code{.\$x}
+or similar \code{with} notation, i.e. \code{with(., x)}, should be used.
+Similarly \code{.\$f(x)} calls
+method \code{f} automatically inserting the receiver object
+into argument one and using \code{x} for argument two. It
+looks for \code{f} first in the receiver object and then its
+ancestors.
+
+\subsection{Traits}
+\label{sec:traits}
+
+Let us look at the definition of a child object once again.
+In the code below,
+\code{addProto} is the previously defined parent object
+and the expression \code{addProto\$proto(x = 1:5)} defines
+a child object of \code{addProto} and assigns it to variable
+\code{addProto2a}.
+
+\begin{Schunk}
+\begin{Sinput}
+> addProto2a <- addProto$proto(x = 1:5)
+> addProto2a$add()
+\end{Sinput}
+\begin{Soutput}
+[1] 15
+\end{Soutput}
+\end{Schunk}
+
+That is, \code{proto} can be used to create a new child of
+an existing object by writing the
+parent object on the left of the \code{\$} and
+\code{proto} on its right. Any contents to
+be added to the new child are listed in arguments of \code{proto}
+as shown.
+
+For example, first let us create a class-like structure. In the
+following \code{Add} is an object that behaves very much like a class
+with an \code{add} method and a method \code{new} which constructs
+new objects. In the line creating object \code{add1} the expression
+\code{Add\$new(x = 1:5)} invokes the \code{new} constructor of the
+receiver object \code{Add}. The method \code{new} has an argument of
+\code{x = 1:5} which defines an \code{x} variable in the \code{add1}
+object being instantiated. We similarly create another object
+\code{add2}.
+
+\begin{Schunk}
+\begin{Sinput}
+> Add <- proto(add = function(.) sum(.$x), new = function(., x) .$proto(x = x))
+> add1 <- Add$new(x = 1:5)
+> add1$add()
+\end{Sinput}
+\begin{Soutput}
+[1] 15
+\end{Soutput}
+\begin{Sinput}
+> add2 <- Add$new(x = 1:10)
+> add2$add()
+\end{Sinput}
+\begin{Soutput}
+[1] 55
+\end{Soutput}
+\end{Schunk}
+
+An object which contains only methods and variables that are
+intended to be shared by all its children (as opposed to an
+object whose purpose is to have its own methods and variables)
+is known as a \emph{trait} \citep{Agesen1992}. It
+is similar to a class in class-based
+object oriented programming.
+Note that the objects \code{add1} and \code{add2} have the trait
+\code{Add} as their parent. We could implement subclass-like and
+superclass-like objects by simply defining similar trait objects to
+be the parent or child of \code{Add}. For example, suppose we
+want a class which calculates the sum of the logarithms of the data. We
+could define:
+
+\begin{Schunk}
+\begin{Sinput}
+> Logadd <- Add$proto(logadd = function(.) log(.$add()))
+> logadd1 <- Logadd$new(1:5)
+> logadd1$logadd()
+\end{Sinput}
+\begin{Soutput}
+[1] 2.70805
+\end{Soutput}
+\end{Schunk}
+
+Here the capitalized objects are traits.
+\code{Logadd} is a trait. It is a child of \code{Add}
+which is also a trait. \code{logadd1} is an ordinary object,
+not a trait.
+One possible design is to create a tree of traits and other objects
+in which the leaves are ordinary objects and the remaining nodes
+are traits. This would closely correspond to class-based
+object oriented programming.
+
+Note that the delegation of methods from
+one trait to another as in
+\code{new} which is inherited by \code{Logadd} from \code{Add}
+is nothing more than the same mechanism by which traits delegate
+methods to
+objects since, of course, traits are just objects no different
+from any other object other than by the conventions we impose on them.
+This unification of subclassing and instantiation beautifully
+shows the simplification that prototype programming represents.
+
+\subsection{Utilities}
+\label{sec:utilities}
+The fact that method calls automatically insert the first argument
+can be used to good effect in leveraging existing \proglang{R}
+functions while allowing an object-oriented syntax.
+
+For example, \code{ls()} can be used to list the components of
+\code{proto} objects:
+
+\begin{Schunk}
+\begin{Sinput}
+> addProto$ls()
+\end{Sinput}
+\begin{Soutput}
+[1] "add" "x"
+\end{Soutput}
+\end{Schunk}
+
+Functions like:
+
+\begin{Schunk}
+\begin{Sinput}
+> addProto$str()
+> addProto$print()
+> addProto$as.list()
+> addProto2a$parent.env()
+\end{Sinput}
+\end{Schunk}
+
+show additional information about the elements. \code{eapply}
+can be used to explore more properties such as the
+the length of each component of an object:
+
+\begin{Schunk}
+\begin{Sinput}
+> addProto$eapply(length)
+\end{Sinput}
+\end{Schunk}
+
+Another example of some interest in any object oriented system
+which allows multiple references to one single object is that
+object identity
+can be tested using the respective base function:
+
+\begin{Schunk}
+\begin{Sinput}
+> addProto$identical(addProto2)
+\end{Sinput}
+\begin{Soutput}
+[1] FALSE
+\end{Soutput}
+\end{Schunk}
+
+\code{proto} does contain a special purpose \code{str.proto} function
+but in the main it
+is important to notice here, that
+\code{proto} has no code that is specific to \code{ls} or
+any of the other ordinary \proglang{R}
+functions listed. We are simply making use of the
+fact that \code{obj\$fun(...)} is transformed into \code{get("fun",
+obj)(obj, ...)} by the proto \code{\$} operator. For example, in the
+case of \code{addProto\$ls()} the system looks for \code{ls} in object
+\code{addProto}. It cannot find it there so it looks to its parent,
+which is the global environment. It does not find it there so it
+searches the remainder of the search path, i.e. the path shown by
+running the \proglang{R} command \code{search()}, and finally finds it
+in the base package, invoking it with an argument of \code{addProto}.
+Since all \code{proto} objects are also environments
+\code{ls(addProto)} interprets \code{addProto} as an environment and
+runs the \code{ls} command with it. In the \code{ls} example there
+were no arguments other than \code{addProto}, and even that one was
+implicit, but if there were
+additional arguments then they would be passed as shown in the
+\code{eapply} and \code{identical} examples above.
+
+\subsection{Plotting}
+\label{sec:plot}
+
+The \code{graph.proto} function can be used to create
+graphs that can be rendered by the \code{Rgraphviz} package
+creating visual representations of ancestor trees (figure
+\ref{fig:proto-dot}).
+That package provides an interface to the
+\proglang{GraphViz} \code{dot} program \citep{Ganser+North:1999}.
+
+\code{graph.proto} takes three arguments, all of which are
+usually omitted. The first argument is a \code{proto} object
+(or an environment) out of which all contained \code{proto} objects
+and their parents (but not higher order ancestors) are graphed.
+If it is omitted, the current environment is assumed.
+The second argument is a graph (in the sense of the \code{graph}
+package) to which the nodes and edges are added. If it is omitted
+an empty graph is assumed. The last argument is a logical variable
+that specifies the orientation of arrows. If omitted arrows are
+drawn from children to their parents.
+
+
+\input{proto-dot}
+
+\begin{figure}[htbp]
+\begin{center}
+\includegraphics{proto-dot}
+\caption{\label{fig:proto-dot} Ancestor tree generated using graph.proto. Edges
+point from child to parent.}
+\end{center}
+\end{figure}
+
+\pagebreak[4]
+
+\section{Examples}
+\label{sec:examples}
+
+\subsection{Smoothing}
+\label{sec:smooth}
+
+In the following we create a \code{proto} object named \code{oo}
+containing a vector of data \code{x} (generated from a simulated
+autoregressive model) and time points
+\code{tt}, an intermediate result
+\code{x.smooth}, some plotting parameters \code{xlab}, \code{ylab},
+\code{pch}, \code{col} and three methods \code{smooth}, \code{plot}
+and \code{residuals} which smooth the data, plot the data and
+calculate residuals, respectively. We also define \code{..x.smooth}
+which holds intermediate results. Names beginning with two dots
+prevent them from being delegated to children. If we override
+\code{x} in a child we would not want an out-of-sync \code{x.smooth}.
+Note that the components of an object can be specified using a code
+block in place of the argument notation we used previously in the
+\code{proto} command.
+
+\begin{Schunk}
+\begin{Sinput}
+> oo <- proto(expr = {
++ x <- rnorm(251, 0, 0.15)
++ x <- filter(x, c(1.2, -0.05, -0.18), method = "recursive")
++ x <- unclass(x[-seq(100)]) * 2 + 20
++ tt <- seq(12200, length = length(x))
++ ..x.smooth <- NA
++ xlab <- "Time (days)"
++ ylab <- "Temp (deg C)"
++ pch <- "."
++ col <- rep("black", 2)
++ smooth <- function(., ...) {
++ .$..x.smooth <- supsmu(.$tt, .$x, ...)$y
++ }
++ plot <- function(.) with(., {
++ graphics::plot(tt, x, pch = pch, xlab = xlab, ylab = ylab,
++ col = col[1])
++ if (!is.na(..x.smooth[1]))
++ lines(tt, ..x.smooth, col = col[2])
++ })
++ residuals <- function(.) with(., {
++ data.frame(t = tt, y = x - ..x.smooth)
++ })
++ })
+\end{Sinput}
+\end{Schunk}
+
+Having defined our \code{proto} object we can inspect it, as shown
+below, using
+\code{print} which is automatically invoked if the
+name of the object, \code{oo}, is entered on a line by itself.
+In this case, there is no proto print method so we inherit the
+environment print method which displays the environment hash code.
+Although it produces too much output to show here,
+we could have displayed a
+list of the entire contents of the object \code{oo}
+via \code{oo\$as.list(all.names = TRUE)}.
+We can get a list of the names of the
+components of the object using \code{oo\$ls(all.names = TRUE)} and will look
+at the contents of one component, \code{oo\$pch}.
+
+\begin{Schunk}
+\begin{Sinput}
+> oo
+\end{Sinput}
+\begin{Soutput}
+<environment: 0x01fbd8c8>
+attr(,"class")
+[1] "proto" "environment"
+\end{Soutput}
+\begin{Sinput}
+> oo$ls(all.names = TRUE)
+\end{Sinput}
+\begin{Soutput}
+ [1] "..x.smooth" ".super" ".that" "col" "pch"
+ [6] "plot" "residuals" "smooth" "tt" "x"
+[11] "xlab" "ylab"
+\end{Soutput}
+\begin{Sinput}
+> oo$pch
+\end{Sinput}
+\begin{Soutput}
+[1] "."
+\end{Soutput}
+\end{Schunk}
+
+Let us illustrate a variety of manipulations. We will set up the
+output to plot 2 plots per screen using \code{mfrow}. We change the
+plotting symbol, smooth the data, invoke the \code{plot} method to
+display a plot of the data and the smooth and then plot the residuals
+in the second plot (figure \ref{fig:proto-smooting03}).
+
+
+\input{proto-smoothing03}
+
+\begin{figure}[h!]
+\begin{center}
+\includegraphics[width=\textwidth]{proto-smoothing03}
+\end{center}
+\caption{Data and smooth from \code{oo\$plot()} (left) and plot of
+\code{oo\$residuals()} (right).}
+\label{fig:proto-smooting03}
+\end{figure}
+
+
+Now let us illustrate the creation of a child object and delegation.
+We create a new child object of \code{oo} called \code{oo.res}. We
+will override the \code{x} value in its parent by setting \code{x} in
+the child to the value of the residuals in the parent. We will also
+override the \code{pch} and \code{ylab} plotting parameters. We will
+return to 1 plot per screen and run \code{plot} using the
+\code{oo.res} object as the receiver invoking the \code{smooth} and
+\code{plot} methods (which are delegated from the parent \code{oo})
+with the data in the child (figure \ref{fig:smoothing04}).
+
+\input{proto-smoothing04}
+% \begin{figure}[tp]
+\begin{figure}[h!]
+\begin{center}
+\includegraphics[width=\half]{proto-smoothing04}
+\end{center}
+\caption{Output of \code{oo.res\$plot()}.
+\code{oo.res\$x} contains the residuals from \code{oo}.}
+\label{fig:smoothing04}
+\end{figure}
+Now we make use of delegation to change the parent
+and child in a consistent way with respect to certain plot characteristics.
+We have been using a numeric time axis.
+Let us interpret these numbers as the number of days since the Epoch,
+January 1, 1970, and let us also change the plot colors.
+
+\begin{Schunk}
+\begin{Sinput}
+> oo$tt <- oo$tt + as.Date("1970-01-01")
+> oo$xlab <- format(oo.res$tt[1], "%Y")
+> oo$col <- c("blue", "red")
+\end{Sinput}
+\end{Schunk}
+
+
+We can introduce a new method, \code{splot}, into
+the parent \code{oo} and have it automatically
+inherited by its children. In this example
+it smooths and then plots and we use it with
+both \code{oo} and \code{oo.res} (figure \ref{fig:smoothing06}).
+
+
+\input{proto-smoothing06}
+
+\begin{figure}[tbp]
+\begin{center}
+\includegraphics[width=\textwidth]{proto-smoothing06}
+\caption{Plotting options and \code{splot} function applied
+to both parent (left) and child (right) object}
+\label{fig:smoothing06}
+\end{center}
+\end{figure}
+
+Numerous possibilities exist to make use of the
+mechanisms shown, so one may create different child objects, apply
+different smoothing parameters, overwrite the smoothing function with
+a lowess smoother and finally compare fits and residuals.
+
+Now lets change the data and repeat the analysis. Rather than
+overwrite the data we will preserve it in \code{oo} and create a child
+\code{oos} to hold an analysis with sinusoidal data.
+
+\begin{Schunk}
+\begin{Sinput}
+> oos <- oo$proto(expr = {
++ tt <- seq(0, 4 * pi, length = 1000)
++ x <- sin(tt) + rnorm(tt, 0, 0.2)
++ })
+> oos$splot()
+\end{Sinput}
+\end{Schunk}
+
+Lets perform the residual analysis with \code{oos}.
+We will make a deep copy of \code{oo.res}, i.e. duplicate its
+contents and not merely delegate it, by copying \code{oo.res}
+to a list from which we create the duplicate, or cloned,
+\code{proto} object (figure \ref{fig:smoothing10} and \ref{fig:cloning}):
+
+\begin{Schunk}
+\begin{Sinput}
+> oos.res <- as.proto(oo.res$as.list(), parent = oos)
+> oos.res$x <- oos$residuals()$y
+> oos.res$splot()
+\end{Sinput}
+\end{Schunk}
+
+
+\begin{figure}[tbp]
+\begin{center}
+\includegraphics[width=\textwidth]{proto-smoothing10}
+\caption{Smoothing of sinusoidal data (left)
+and of their residuals (right)}\label{fig:smoothing10}
+\end{center}
+\end{figure}
+
+\begin{figure}[h!]
+\begin{center}
+\includegraphics[width=50mm]{cloning3.pdf}
+\caption{Cloning (dashed line) and delegation (solid line). Edges point
+from child to parent.}\label{fig:cloning}
+\end{center}
+\end{figure}
+
+We have delegated variables
+and methods and overridden both.
+Thus, even with such a simple analysis, object orientation
+and delegation came into play.
+The reader can plainly see that smoothing and residual
+analysis were not crucial to the example and this example
+could be replaced with any statistical analysis including
+likelihood or other estimation techniques, time series, survival
+analysis, stochastic processes and so on. The key aspect is
+just that we are performing one-of analyses and do not want to
+set up an elaborate class infrastructure but just want to
+directly create objects to organize our calculations while
+relying on delegation and dispatch to eliminate redundancy.
+
+\subsection{Correlation, Fisher's Transform and Bootstrapping}
+\label{sec:corr}
+
+The common approach to
+confidence intervals for the correlation coefficient is to
+assume normality of the underlying data and then use Fisher's transform
+to transform the correlation coefficient to an approximately normal
+random variable.
+Fisher showed that with the above normality assumption, transforming
+the correlation coefficient using
+the hyperbolic arc tangent function
+yields a random variable
+approximately distributed with an
+$\frac{N(p, 1)}{\sqrt(n-3)}$ distribution. The transformed random
+variable can be used to create normal distribution confidence intervals
+and the procedure can be back transformed to get confidence intervals
+for the original correlation coefficient.
+
+A more recent approach to confidence intervals for the correlation
+coefficient is to use bootstrapping. This does not require the
+assumption of normality of the underlying distribution and requires
+no special purpose theory devoted solely to the correlation coefficient,
+
+Let us calculate the 95\%
+confidence intervals using Fisher's transform
+first. We use \code{GNP} and \code{Unemployed} from the Longley data
+set. First we retrieve the data set and extract the required columns
+into \code{x}. Then we set \code{n} to the number of cases
+and \code{pp} to the percentiles
+of interest. Finally we calculate the sample correlation and
+create a function to calculate the confidence interval using
+Fisher's Transform. This function not only returns the confidence
+interval but also stores it in \code{CI} in the receiver object.
+
+\begin{Schunk}
+\begin{Sinput}
+> longley.ci <- proto(expr = {
++ data(longley)
++ x <- longley[, c("GNP", "Unemployed")]
++ n <- nrow(x)
++ pp <- c(0.025, 0.975)
++ corx <- cor(x)[1, 2]
++ ci <- function(.) (.$CI <- tanh(atanh(.$corx) + qnorm(.$pp)/sqrt(.$n -
++ 3)))
++ })
+\end{Sinput}
+\end{Schunk}
+
+Now let us repeat this analysis using the bootstrapping approach. We
+derive a new object \code{longley.ci.boot} as child of
+\code{longley.ci}, setting the number of replications, \code{N}, and
+defining the procedure, \code{ci} which does the actual bootstrap
+calculation.
+
+\begin{Schunk}
+\begin{Sinput}
+> longley.ci.boot <- longley.ci$proto({
++ N <- 1000
++ ci <- function(.) {
++ corx <- function(idx) cor(.$x[idx, ])[1, 2]
++ samp <- replicate(.$N, corx(sample(.$n, replace = TRUE)))
++ (.$CI <- quantile(samp, .$pp))
++ }
++ })
+\end{Sinput}
+\end{Schunk}
+
+In the example code below the first line runs the Fisher Transform
+procedure and the second runs the bootstrap procedure. Just to check
+that we have performed sufficient bootstrap iterations we rerun it in
+the third line, creating a delegated object on-the-fly running its
+\code{ci} method and then immediately throwing the object away.
+The fact that 4,000
+replications give roughly the same result as 1,000 replications
+satisfies us that we have used a sufficient number of replications.
+
+\begin{Schunk}
+\begin{Sinput}
+> longley.ci$ci()
+\end{Sinput}
+\begin{Soutput}
+[1] 0.1549766 0.8464304
+\end{Soutput}
+\begin{Sinput}
+> longley.ci.boot$ci()
+\end{Sinput}
+\begin{Soutput}
+ 2.5% 97.5%
+0.2299395 0.8211854
+\end{Soutput}
+\begin{Sinput}
+> longley.ci.boot$proto(N = 4000)$ci()
+\end{Sinput}
+\begin{Soutput}
+ 2.5% 97.5%
+0.2480999 0.8259276
+\end{Soutput}
+\end{Schunk}
+
+We now have the results stored in two objects nicely organized for the
+future. Note, again, that despite the simplicity of the example we
+have used the features of object oriented programming, coupling the
+data and methods that go together, while relying on delegation and
+dispatch to avoid duplication.
+
+\subsection{Dendrograms}
+\label{sec:tree}
+
+In \cite{Gentleman2002} there is an \proglang{S4}
+example of creating a binary tree
+for use as a dendrogram. Here we directly define a binary tree with no
+setup at all. To keep it short we will create a binary tree of only
+two nodes having a root whose left branch points to a leaf. The leaf
+inherits the \code{value} and \code{incr} components from the root.
+The attractive feature is that the leaf be defined as a child of the
+parent using \code{proto} before the parent is even finished
+being defined. Compared to the cited \proglang{S4} example where it
+was necessary to create an extra class to introduce the required level of
+indirection there is no need to take any similar action.
+
+\code{tree} is the root node of the tree. It has four components. A
+method \code{incr} which increments the \code{value} component, a
+\code{..Name}, the \code{value} component itself and the left branch
+\code{..left}. \code{..left} is itself a proto object which is a
+child of \code{tree}. The leaf inherits the \code{value} component
+from its parent, the root. As mentioned, at the time we define
+\code{..left} we have not even finished defining \code{tree} yet we
+are able to implicitly reference the yet to be defined parent.
+
+\begin{Schunk}
+\begin{Sinput}
+> tree <- proto(expr = {
++ incr <- function(., val) .$value <- .$value + val
++ ..Name <- "root"
++ value <- 3
++ ..left <- proto(expr = {
++ ..Name = "leaf"
++ })
++ })
+\end{Sinput}
+\end{Schunk}
+
+Although this is a simple structure we could have embedded additional
+children into \code{root} and \code{leaf} and so on recursively making
+the tree or dendrogram arbitrarily complex.
+
+Let us do some computation with this structure. We display the
+\code{value} fields in the two nodes, increment the value field in the
+root and then display the two nodes again to show .that the leaf
+changed too.
+
+\begin{Schunk}
+\begin{Sinput}
+> cat("root:", tree$value, "leaf:", tree$..left$value, "\n")
+\end{Sinput}
+\begin{Soutput}
+root: 3 leaf: 3
+\end{Soutput}
+\begin{Sinput}
+> tree$incr(1)
+> cat("root:", tree$value, "leaf:", tree$..left$value, "\n")
+\end{Sinput}
+\begin{Soutput}
+root: 4 leaf: 4
+\end{Soutput}
+\end{Schunk}
+
+If we increment \code{value} in \code{leaf} directly (see the example
+below where we increment it by 10) then it receives its own copy of
+\code{value} so from that point on \code{leaf} no longer inherits
+\code{value} from \code{root}. Thus incrementing the root by 5 no
+longer increments the \code{value} field in the leaf.
+
+\begin{Schunk}
+\begin{Sinput}
+> tree$..left$incr(10)
+> cat("root:", tree$value, "leaf:", tree$..left$value, "\n")
+\end{Sinput}
+\begin{Soutput}
+root: 4 leaf: 14
+\end{Soutput}
+\begin{Sinput}
+> tree$incr(5)
+> cat("root:", tree$value, "leaf:", tree$..left$value, "\n")
+\end{Sinput}
+\begin{Soutput}
+root: 9 leaf: 14
+\end{Soutput}
+\end{Schunk}
+
+\subsection{From Prototypes to Classes}
+\label{sec:increment}
+
+In many cases we will use \pkg{proto} for a design that uses prototypes
+during the full development cycle. In other cases we may use it in an
+incremental way starting with prototypes but ultimately transitioning
+to classes.
+As shown in Section~\ref{sec:traits} the \pkg{proto} package is
+powerful enough to handle class-based as well as class-free programming.
+Here we illustrate this process of incremental design
+starting with
+concrete objects and then over time classifing them into classes,
+evolving a class-based program. \pkg{proto} provides a smooth
+transition path since it can handle both the class-free and the class-based
+phases -- there is no need to switch object systems part way through.
+In this example, we define an object which holds a linear equation, \code{eq},
+represented as a character string in terms of the unknown variable \code{x}
+and a \code{print} and a \code{solve} method. We execute the
+\code{print} method
+to solve it. We also create child object \code{lineq2}
+which overrides \code{eq} and execute its \code{print} method.
+
+\begin{Schunk}
+\begin{Sinput}
+> lineq <- proto(eq = "6*x + 12 - 10*x/4 = 2*x", solve = function(.) {
++ e <- eval(parse(text = paste(sub("=", "-(", .$eq), ")")),
++ list(x = 0+1i))
++ -Re(e)/Im(e)
++ }, print = function(.) cat("Equation:", .$eq, "Solution:", .$solve(),
++ "\n"))
+> lineq$print()
+\end{Sinput}
+\begin{Soutput}
+Equation: 6*x + 12 - 10*x/4 = 2*x Solution: -8
+\end{Soutput}
+\begin{Sinput}
+> lineq2 <- lineq$proto(eq = "2*x = 7*x-12+x")
+> lineq2$print()
+\end{Sinput}
+\begin{Soutput}
+Equation: 2*x = 7*x-12+x Solution: 2
+\end{Soutput}
+\end{Schunk}
+
+We could continue with enhancements but at this point we decide that we
+have a general case and so wish
+to abstract \code{lineq} into a class. Thus we define a trait,
+\code{Lineq}, which is just \code{lineq} minus \code{eq} plus
+a constructor \code{new}. The key difference between \code{new}
+and the usual \code{proto} function
+is that with \code{new} the initialization of \code{eq} is mandatory.
+Having completed this definition
+we instantiate an object of
+class/trait \code{Lineq} and execute it.
+
+\begin{Schunk}
+\begin{Sinput}
+> Lineq <- lineq
+> rm(eq, envir = Lineq)
+> Lineq$new <- function(., eq) proto(., eq = eq)
+> lineq3 <- Lineq$new("3*x=6")
+> lineq3$print()
+\end{Sinput}
+\begin{Soutput}
+Equation: 3*x=6 Solution: 2
+\end{Soutput}
+\end{Schunk}
+
+Note how we have transitioned from a prototype style of programming
+to a class-based style of programming all the while staying within
+the \pkg{proto} framework.
+
+\section{Summary} \label{sec:summary}
+
+\subsection{Benefits}
+\label{sec:benefits}
+
+The key benefit of the \pkg{proto} package is to provide
+access to a style of programming that has not been conveniently
+accessible within \proglang{R} or any other mainstream language today.
+
+\pkg{proto} can be used in two key ways: class-free object oriented programming
+and class-based object oriented programming.
+
+A key application for \pkg{proto} in class-free programming is to wrap the code
+and data for each run of a particular statistical study into an object for
+purposes of organization and reproducibility. It provides such organization
+directly and without the need and overhead of class definitions
+yet still provides the
+inheritance and dispatch advantages of object oriented programming.
+We provide examples of this style of programming in
+Section~\ref{sec:smooth}
+and
+Section~\ref{sec:corr}.
+A third example in
+Section~\ref{sec:tree} illustrates a beneficial use of \pkg{proto} with
+recursive data structures.
+
+Another situation where prototype programming is of interest is in the initial
+development stages of a program. In this case, the design may not be fully
+clear so it is more convenient to create concrete objects individually rather
+than premature abstractions through classes. The \code{graph.proto}
+function can be used to generate visual representations of the object
+tree suggesting classifications of objects so that
+as the program evolves the general case becomes clearer and
+in a bottom up fashion the objects are incrementally abstracted into
+classes. In this case,
+\pkg{proto} provides a smooth transition path since it not only supports
+class-free programming but, as explained in the Section~\ref{sec:traits}, is
+sufficiently powerful to support class-based programming, as well.
+
+
+\subsection{Conclusion}
+\label{sec:conclusion}
+
+The package \pkg{proto} provides an \proglang{S3} subclass of the
+\code{environment} class for constructing and manipulating object
+oriented systems without classes. It can also emulate classes even
+though classes are not a primitive structure. Its key design goals
+are to provide as simple and as thin a layer as practically possible
+while giving the user convenient access to this alternate object
+oriented paradigm. This paper describes, by example, how prototype
+programming can be carried out in \proglang{R} using \pkg{proto} and
+illustrates such usage. Delegation, cloning traits and general
+manipulation and incremental development are all reviewed by example.
+
+\section*{Computational details}
+\label{sec:compute}
+
+The results in this paper were obtained using \proglang{R} 2.1.0 with
+the package \pkg{proto} 0.3--2. \proglang{R} itself and the
+\pkg{proto} package are available from CRAN at
+\url{http://CRAN.R-project.org/}. The GraphViz software is available
+from \url{http://www.graphviz.org}.
+
+\phantomsection
+\addcontentsline{toc}{section}{References}
+\bibliography{proto}
+%\input{proto.bbl}
+
+\newpage\mbox{}
+\begin{appendix}
+\section{Frequently Asked Questions}
+\label{sec:faq}
+\begin{enumerate}
+\item{What scope do unqualified object references within methods use?
+
+A \pkg{proto} object is an environment and that environment
+is the environment
+of the methods in it (by default).
+That is, unqualified object references
+within a \pkg{proto} method look first in the method itself and secondly in the
+\pkg{proto} object containing the method.
+This is referred to as object
+scope as opposed to lexical scope or dynamic scope. It allows simple
+situations, where delegation is not used, to use unqualified names. Thus
+simple situations remain simple.
+\citep{Kates2004}
+discusses the fragile base class problem which
+relates to this question. Also note that if a \pkg{proto} object is created
+via the \code{proto} function using an argument of \code{funEnvir = FALSE}
+then the environment of the function/method will not be set as just
+described (but rather it will retain its original environment) so the
+above does not apply. This can be used for instances when non-default
+processing is desirable.}
+\item{Why does \code{obj\$meth} not return the method, \code{meth}?
+
+Conceptually \code{obj\$meth} returns \code{meth} but with
+\code{obj} already inserted into its first argument.
+This is termed an instantiated
+\pkg{proto}
+method and is of \proglang{S3} class \code{"instantiatedProtoMethod"}.
+
+In contrast, the method itself (i.e. the uninstantited method)
+would not have the first argument already
+inserted. To return the method itself use \code{with(obj, meth}.
+
+The main advantage of a design that makes the distinction between instantiated
+and uninstantiated methods is that uninstantiated methods are never
+changed so
+debugging can be more readily carried out (as discussed in the next
+question and answer).
+}
+\item{How does one debug a method?
+
+\pkg{proto} does not dynamically redefine methods. This has the advantage
+that the ordinary \proglang{R} \code{debug} and \code{undebug} commands can be
+used. When using these be sure that to use them with the uninstantiated method
+itself and not the instantiated method derived from it. That is,
+use:
+\begin{verbatim}
+ with(obj, debug(meth))
+\end{verbatim}
+
+and not
+\begin{verbatim}
+ debug(obj$meth) # wrong
+\end{verbatim}
+}
+\item{Is multiple inheritance supported?
+
+No. \pkg{proto} is just a thin layer on top of \proglang{R}
+environments and \proglang{R} environments
+provide single inheritance only. \citep{Kates2004}
+discusses some ways of handling situations which would otherwise require
+multiple inheritance.}
+\item{Does \pkg{proto} support lazy evaluation?
+
+Since \code{proto} methods are just \proglang{R} functions they do support
+lazy evaluation; however, the \code{proto} function itself
+does evaluate its arguments. To get the
+effect of lazy evaluation when using the \code{proto}
+function replace any properties with a function.
+
+If the caller is the parent of the \code{proto} object then its
+particularly simple. Note how we got the equivalent of lazy evaluation
+in the second example where f is a function:
+
+\begin{verbatim}
+# eager evaluation
+x <- 0
+p <- proto(f = x, g = function(.) $x)
+x <- 1
+p$f # 0
+
+# versus making f a function
+
+# simulates lazy evaluation
+x <- 0
+p <- proto(f = function(.) x, g = function(.) .$x)
+x <- 1
+p$f() # 1
+\end{verbatim}
+
+If we cannot guarantee that the proto object has the caller
+as its parent then ensure that the environment of the function
+has not been reset. If no method needs to reference \code{.that}
+or \code{.super} then we can arrange for that using
+\code{funEnvir=FALSE} as seen here in the second example:
+\begin{verbatim}
+
+# does not work as intended
+x <- 0
+p <- proto(x = 99)
+q <- p$proto(f = function(.) x, g = function(.) .$x)
+x <- 1
+q$f() # 99
+
+# does work
+x <- 0
+p <- proto(x = 99)
+q <- p$proto(f = function(.) x, g = function(.) .$x, funEnvir = FALSE)
+x <- 1
+q$f() # 1
+\end{verbatim}
+
+If we wish only to not reset the function used to simulate
+lazy evaluation then we can do it using either of the
+two equivalent alternatives below. \code{g}
+is an ordinary method whose environment is reset to \code{q}
+whereas \code{f} is a function whose environment is not reset and
+serves to provide lazy evaluation for \code{x} found in the caller.
+
+\begin{verbatim}
+x <- 0
+p <- proto(x = 99)
+# g will use q's y in children of q even if those children
+# override y
+q <- p$proto(y = 25, g = function(.) .that$y + .$x)
+q[["f"]] <- function(.) x
+x <- 1
+q$f() # 1
+
+# equivalent alternative
+
+x <- 0
+p <- proto(x = 99)
+q <- proto(f = function(.) x, funEnvir = FALSE,
+ envir = p$proto(y = 25, g = function(.) .that$y + .$x))
+x <- 1
+q$f() # 1
+\end{verbatim}
+}
+\end{enumerate}
+\newpage{}
+\section{Reference Card}
+\label{sec:ref}
+\input{protoref-raw}
+\end{appendix}
+
+\end{document}
+
diff --git a/vignettes/protoref-raw.tex b/vignettes/protoref-raw.tex
old mode 100755
new mode 100644
diff --git a/vignettes/protoref.Rnw b/vignettes/protoref.Rnw
old mode 100755
new mode 100644
index f46c9c8..00d00d3
--- a/vignettes/protoref.Rnw
+++ b/vignettes/protoref.Rnw
@@ -1,26 +1,27 @@
-\SweaveOpts{engine=R,eps=FALSE}
-
-%\VignetteIndexEntry{protoref: proto Reference Card}
-%\VignetteDepends{}
-%\VignetteKeywords{object oriented, prototype programming, S3, R}
-%\VignettePackage{proto}
-
-\documentclass[a4]{article}
-\usepackage{Rd}
-
-%\newlength{\refcardwidth}
-%\setlength{\refcardwidth}{20cm}
-
-% \usepackage{c:/PROGRA~1/R/RW2010~1/share/texmf/Sweave}
-\begin{document}
-\pagestyle{empty}
-
-%\begin{landscape}
-\centerline{\Large \bf \pkg{proto} reference card}
-\vspace{0.8cm}
-\begin{small}
-\input{protoref-raw}
-\end{small}
-%\end{landscape}
-
-\end{document}
+\SweaveOpts{engine=R,eps=FALSE}
+
+%\VignetteIndexEntry{protoref: proto Reference Card}
+%\VignetteDepends{}
+%\VignetteKeywords{object oriented, prototype programming, S3, R}
+%\VignettePackage{proto}
+
+\documentclass[a4]{article}
+\usepackage{Rd}
+\usepackage{Sweave}
+
+%\newlength{\refcardwidth}
+%\setlength{\refcardwidth}{20cm}
+
+\begin{document}
+\SweaveOpts{concordance=TRUE}
+\pagestyle{empty}
+
+%\begin{landscape}
+\centerline{\Large \bf \pkg{proto} reference card}
+\vspace{0.8cm}
+\begin{small}
+\input{protoref-raw}
+\end{small}
+%\end{landscape}
+
+\end{document}
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/debian-med/r-cran-proto.git
More information about the debian-med-commit
mailing list