line_binding: Locates a line matching a redpen pattern and conducts tests...

In dtkaplan/checkr2: Exploring ideas for successor to checkr

Description

Looks for a line matching all of the redpen patterns. If the match is found, the tests (see ...) are evaluated in order using the bindings established in the redpen match. A pass or a fail causes an immediate termination of the testing and returns that result. If no pass or fail occurs, a neutral result ("ok") is created so that evaluation can proceed to subsequent statements.

Usage

line_binding(ex, keys, ..., message = "No match found to specified patterns.",
  qkeys = NULL)

Arguments

ex	a checkr_result object produced by some previous checkr function, e.g. for_checkr()
keys	an R statement used for pattern matching and binding, based on the redpen package. This can also be a -bracketed set of patterns. If the expression involves assignment, the keys will be matched only to the RHS of assignment, not the whole expression. See details for what becomes of assignment.
...	tests to apply to expressions in ex. These are typically made with passif(), failif(), noteif(), check_binding(), and so on. In addition to the bindings defined in keys, for each line the name of the object assigned to will be bound to the pronoun Z. (Z will be "" when there's no assignment in the line.)
message	a character string message. If the patterns don't match, the message to give with the failed checkr_result.
qkeys	(for internal use only) a quoted expression containing the keys.

Details

If any of the redpen patterns fails to match, a checkr_result "fail" is returned with the message specified in the message argument, and with code being the same as the input code.

In additon to the passif/failif/noteif tests, you can use line_ functions as a test. Of course, the the functions used in the tests will have an input that is only one line, so the name "line_" may be misleading. check_binding() is just an alias for line_binding. Not really needed, but it seems nicer to use check_binding() within a "line_binding"

Remember that the keys should be designed around statements not involving assignment. If you want to check assignment, use the Z pronoun.

The pattern or patterns in keys are applied to each of the expressions in ex. The tests are only considered for the first expression in ex that matches the pattern. passif() and failif() tests, when satisfied, lead to immediate return: no later tests are performed. noteif() just adds a note, without terminating the testing. The redpen patterns are compared just to the RHS of any assignment. The Z pronoun will store the name of any assignment (and will be "" if there's no assignment.)

Value

A checkr_test object with an action ("pass", "fail", or "ok")

a checkr_result object.

Examples

ex <- for_checkr(quote(z <- 2+2))
line_binding(ex, 2 + 2, passif(TRUE, "The pattern matched."), message = "I was looking for 2+2.")
line_binding(ex, 3 + 3, message = "I was looking for 3 + 3")
# The Z pronoun for assignment is added by default
line_binding(ex, 2 + 2, passif(Z == "z", "Assignment to {{Z}}."))
line_binding(ex, 2 + ..(y),
    failif(y != 2,
         "{{expression_string}} wasn't right. Second argument should be 2,  not {{y}}"))
line_binding(ex, `+`(.(a), .(b)), passif(TRUE, "Found a match."))
line_binding(ex, `+`(.(a), .(b)),
  passif(a==b, message = "Yes, the arguments to + are equal. They are both {{a}}."))
wrong1 <- for_checkr(quote(2 - 2))
wrong2 <- for_checkr(quote(2*2))
line_binding(wrong1, {.(expr); .(f)(.(a), .(b))},
  passif(f == `+`, "Right! Addition means {{f}}."),
  failif(f != `+`, "In {{expr}}, you used {{f}} instead of +."))
line_binding(wrong2, {.(fn)(.(a), .(b)); ..(val)},
  noteif(val == 4, "Right overall answer: {{val}}."),
  failif(fn != `+`, "You need to use the `+` function, not {{fn}}."),
  noteif(val != 4, "The result should be 4, not {{val}}."),
  passif(fn == `+` && val == 4 && a == b))
code2 <- for_checkr(quote({data(mtcars); plot(mpg ~ hp, data = mtcars)}))
line_binding(code2,
  # note, single . with .(fn)
  {..(val); .(fn)(.(formula), data = mtcars);},
  passif(fn == plot, "You made the plot!"))

dtkaplan/checkr2 documentation built on May 17, 2019, 4:01 p.m.