The R Project SVN R

Rev

Rev 63173 | Rev 63205 | Go to most recent revision | Show entire file | Ignore whitespace | Details | Blame | Last modification | View Log | RSS feed

Rev 63173 Rev 63197
Line 1... Line 1...
1 
\name{assertCondition}
 1 
\name{assertCondition}
2 
\alias{assertCondition}
 2 
\alias{assertCondition}
- 
 
 3 
\alias{assertWarning}
- 
 
 4 
\alias{assertError}
3 
\title{Asserting Error Conditions}
 5 
\title{Asserting Error Conditions}
4 
\description{
 6 
\description{
5 
  When testing code, it is not sufficient to check that results are correct,
 7 
  When testing code, it is not sufficient to check that results are correct,
6 
  but also that errors or warnings are signalled in appropriate
 8 
  but also that errors or warnings are signalled in appropriate
7 
  situations.  \code{assertCondition()} allows to perform such checks
 9 
  situations.  The functions described here provide a convenient
- 
 
 10 
  facility for doing so.  The three functions check that evaluating the
- 
 
 11 
  supplied expression produces an error, a warning or one of a
- 
 
 12 
  specified list of conditions, respectively.  If the assertion fails,
8 
  conveniently.
 13 
  an error is signalled.
9 
}
 14 
}
10 
\usage{
 15 
\usage{
- 
 
 16 
assertError(expr)
- 
 
 17 
assertWarning(expr)
11 
assertCondition(expr, ..., verbose = getOption("verbose"))
 18 
assertCondition(expr, ..., .exprString = )
12 
}
 19 
}
13 
\arguments{
 20 
\arguments{
14 
  \item{expr}{an unevaluated \R expression which will be evaluated via
 21 
  \item{expr}{an unevaluated \R expression which will be evaluated via
15 
    \code{\link{tryCatch}(expr, ..)}.}
 22 
    \code{\link{tryCatch}(expr, ..)}.}
16 
  \item{\dots}{\code{\link{character}} strings such as \code{"error"} or
 23 
  \item{\dots}{\code{\link{character}} strings corresponding to the
- 
 
 24 
      classes of the conditions that would satisfy the assertion; e.g., \code{"error"} or
17 
    \code{"warning"}; defaults to \code{"condition"}.}
 25 
    \code{"warning"}. If none are specified, any condition will
- 
 
 26 
    satisfy the assertion.  See the details section. }
- 
 
 27 
  \item{.exprString}{The string to be printed corresponding to
- 
 
 28 
      \code{expr}. By default, the actual \code{expr} will be
18 
  \item{verbose}{logical indicating if the message should be shown even
 29 
      deparsed.  Will be omitted if the function is supplied with the
- 
 
 30 
      actual expression to be tested.  If \code{assertCondition()} is
- 
 
 31 
      called from another
- 
 
 32 
        function, with the actual expression passed as an argument to
19 
    when the condition is asserted.}
 33 
        that function, supply the deparsed version.}
20 
}
 34 
}
21 
%% \details{
 35 
\details{
- 
 
 36 
  \code{assertCondition()} uses the general condition mechanism to
- 
 
 37 
  check all the conditions generated in evaluating \code{expr}.  The
- 
 
 38 
  occurrence of any of the supplied condition classes among these satisfies the
- 
 
 39 
  assertion regardless of what other conditions may be signalled.
- 
 
 40 
 
- 
 
 41 
  \code{assertError()} is a convenience function for asserting errors;
- 
 
 42 
  it calls \code{assertCondition()}.
- 
 
 43 
 
- 
 
 44 
  \code{assertWarning()} asserts that a warning will be signalled, but
- 
 
 45 
  \emph{not} an error, whereas \code{assertCondition(expr, "warning")}
- 
 
 46 
  will be satisfied even if an error follows the warning.  See the examples.
22 
%% }
 47 
 }
23 
\value{
 48 
\value{
24 
  if the \code{assertCondition(*)} does not signal an error, this means that
 49 
  If the assertion is satisfied, a list of all the condition objects
- 
 
 50 
  signalled is returned, invisibly. See \code{\link{conditionMessage}} for the
- 
 
 51 
  interpretation of these objects.  Note that \emph{all} conditions
25 
  \code{expr} \emph{did} signal a condition, and that  returned
 52 
  signalled during the evaluation are returned, whether or not they
26 
  invisibly in this case.
 53 
  were among the requirements.
27 
}
 54 
}
28 
\author{John Chambers (and Martin Maechler)}
 55 
\author{John Chambers and Martin Maechler}
29 
\seealso{
 56 
\seealso{
30 
  \code{\link{stop}}, \code{\link{warning}};
 57 
  \code{\link{stop}}, \code{\link{warning}};
31 
  \code{\link{signalCondition}}, \code{\link{tryCatch}}, etc.
 58 
  \code{\link{signalCondition}}, \code{\link{tryCatch}}.
32 
}
 59 
}
33 
\examples{
 60 
\examples{
- 
 
 61 
  assertError(sqrt("abc"))
- 
 
 62 
  assertWarning(matrix(1:8, 4,3))
- 
 
 63 
 
34 
assertCondition( ""-1 ) # ok, as it signals a "condition"
 64 
  assertCondition( ""-1 ) # ok, any condition would satisfy this
35 
 
 65 
 
36 
try( assertCondition(sqrt(2), "warning") )
 66 
try( assertCondition(sqrt(2), "warning") )
37 
## .. Failed to get expected warning in evaluating sqrt(2)
 67 
## .. Failed to get warning in evaluating sqrt(2)
38 
     assertCondition(sqrt("abc"), "error")   # ok
 68 
     assertCondition(sqrt("abc"), "error")   # ok
39 
try( assertCondition(sqrt("abc"), "warning") )# -> error: had no warning
 69 
try( assertCondition(sqrt("abc"), "warning") )# -> error: had no warning
40 
## verbose ==> show error message additionally:
 70 
     assertCondition(sqrt("abc"), "error")
41 
     assertCondition(sqrt("abc"), verbose=TRUE, "error")
 71 
  ## identical to assertError() call above
42 
 
 72 
 
43 
assertCondition(matrix(1:5, 2,3), "warning")
 73 
assertCondition(matrix(1:5, 2,3), "warning")
44 
try( assertCondition(matrix(1:8, 4,3), "error") )
 74 
try( assertCondition(matrix(1:8, 4,3), "error") )
45 
## .. Failed to get expected error ....
 75 
## .. Failed to get expected error ....
46 
 
 76 
 
47 
## either warning or worse:
 77 
## either warning or worse:
48 
assertCondition(matrix(1:8, 4,3), verbose=TRUE, "error","warning") # OK
 78 
assertCondition(matrix(1:8, 4,3), "error","warning") # OK
49 
assertCondition(matrix(1:8, 4, 3), "warning", "error") # ditto
 79 
assertCondition(matrix(1:8, 4, 3), "warning") # OK
50 
 
 80 
 
51 
## when both are signalled:
 81 
## when both are signalled:
52 
ff <- function() { warning("my warning"); stop("my error") }
 82 
ff <- function() { warning("my warning"); stop("my error") }
53 
    assertCondition(ff(), "warning")
 83 
    assertCondition(ff(), "warning")
- 
 
 84 
## but assertWarning does not allow an error to follow
- 
 
 85 
try(assertWarning(ff()))
54 
    assertCondition(ff(), "error")          # ok
 86 
    assertCondition(ff(), "error")          # ok
55 
assertCondition(ff(), "error", "warning") # ok (quietly, catching warning)
 87 
assertCondition(ff(), "error", "warning") # ok (quietly, catching warning)
56 
 
 88 
 
57 
## assert that assertC..() does not assert [and use *one* argument only]
 89 
## assert that assertC..() does not assert [and use *one* argument only]
58 
assertCondition( assertCondition(sqrt( 2   ), "warning") )
 90 
assertCondition( assertCondition(sqrt( 2   ), "warning") )
59 
assertCondition( assertCondition(sqrt("abc"), "warning"), "error")
 91 
assertCondition( assertCondition(sqrt("abc"), "warning"), "error")
60 
assertCondition( assertCondition(matrix(1:8, 4,3), "error"),
 92 
assertCondition( assertCondition(matrix(1:8, 4,3), "error"),
61 
                "error", verbose=TRUE)
 93 
                "error")
62 
}
 94 
}
63 
\keyword{programming}
 95 
\keyword{programming}
64 
\keyword{error}
 96 
\keyword{error}