Updoc
From Erights
(this is a stub, but I had to put something) |
m (→Running Updoc: typo) |
||
Line 1: | Line 1: | ||
''Updoc'' is a tool for creating checkable documentation and regression tests. | ''Updoc'' is a tool for creating checkable documentation and regression tests. | ||
- | Please read more about it here: | + | Please read more about it here: http://www.erights.org/elang/tools/updoc.html |
- | + | ==[[:Category:E specification|E specification]]== | |
+ | |||
+ | The E specification contained in this wiki incorporates a test suite written in Updoc. | ||
+ | |||
+ | ==Running Updoc== | ||
+ | |||
+ | In [[E-on-Java]], the program <code>scripts/updoc.e</code> runs Updoc tests. It takes one argument which is an Updoc file or a directory containing them. Updoc may be by itself, embedded in E source, or embedded in HTML. | ||
+ | |||
+ | {{XXX|Explain startup options}} | ||
+ | |||
+ | {{XXX|doc E-on-CL}} | ||
+ | |||
+ | ==Updoc syntax and behavior== | ||
+ | |||
+ | {{XXX|write the rest of this}} | ||
+ | |||
+ | An updoc test failure occurs when the actual answers resulting from evaluation are not equal (except for stack traces) to the expected answers written in the test script. | ||
+ | |||
+ | {{XXX|Note: E-on-Java currently permits the actual "value" answer to be anything if the script does not contain one. We have decided that this behavior is too hazardous (hiding leaks) but it has not yet been fixed.}} | ||
+ | |||
+ | ===Parsing=== | ||
+ | |||
+ | Exactly like an interactive session, parser pragmas persist from one step to the next. | ||
+ | |||
+ | ? accum [] for _ in "" { _ + [1] }; null | ||
+ | # syntax error: The optional e.enable.accumulator feature (see org/erights/e/elang/syntax/syntax-props-default.txt) is currently off. | ||
+ | |||
+ | ? pragma.enable("accumulator") | ||
+ | ? accum [] for _ in "" { _ + [1] }; null | ||
+ | ? pragma.syntax("0.9") | ||
+ | ? accum [] for _ in "" { _ + [1] }; null | ||
+ | # syntax error: The optional e.enable.accumulator feature (see org/erights/e/elang/syntax/syntax-props-default.txt) is currently off. | ||
+ | |||
+ | ===Printing=== | ||
+ | |||
+ | In the Updoc [[environment]], the text printed via the output objects <code>stdout</code>, <code>stderr</code>, <code>print</code>, and <code>println</code> is part of the results checked. | ||
+ | |||
+ | Semantics: stdout and stderr write to separate buffers. At the following times in the execution of each step, the contents of each buffer, if nonempty, are moved into answers named "stdout" and "stderr": | ||
+ | * after evaluation of the step, but before the <code>value</code> is printed | ||
+ | * after interp.waitAtTop/blockAtTop pauses and after all turns queued by the step have executed, but before the evaluation of the next step | ||
+ | |||
+ | {{XXX|Review whether this definition matches E-on-CL and E-on-Java}} | ||
+ | |||
+ | Line breaks and buffers: | ||
+ | |||
+ | ? stdout.print("a") | ||
+ | # stdout: a | ||
+ | |||
+ | ? stdout.print("a\n") | ||
+ | # stdout: a | ||
+ | # | ||
+ | |||
+ | ? stdout.print("a"); stderr.print("b") | ||
+ | # stdout: a | ||
+ | |||
+ | # stderr: b | ||
+ | |||
+ | Timing: | ||
+ | |||
+ | ? stdout.print("a"); stdout <- print("b"); "c" | ||
+ | # stdout: a | ||
+ | |||
+ | # value: "c" | ||
+ | |||
+ | # stdout: b | ||
+ | |||
+ | ? # This step should have no output. | ||
+ | |||
+ | <code>print</code> and <code>println</code>: | ||
+ | |||
+ | ? println("a", "b"); print("c", "d") | ||
+ | # stdout: ab | ||
+ | # cd | ||
+ | |||
+ | {{stub}} | ||
+ | [[Category:E specification]] |
Latest revision as of 14:21, 26 September 2011
Updoc is a tool for creating checkable documentation and regression tests.
Please read more about it here: http://www.erights.org/elang/tools/updoc.html
Contents |
E specification
The E specification contained in this wiki incorporates a test suite written in Updoc.
Running Updoc
In E-on-Java, the program scripts/updoc.e
runs Updoc tests. It takes one argument which is an Updoc file or a directory containing them. Updoc may be by itself, embedded in E source, or embedded in HTML.
XXX Explain startup options
XXX doc E-on-CL
Updoc syntax and behavior
XXX write the rest of this
An updoc test failure occurs when the actual answers resulting from evaluation are not equal (except for stack traces) to the expected answers written in the test script.
XXX Note: E-on-Java currently permits the actual "value" answer to be anything if the script does not contain one. We have decided that this behavior is too hazardous (hiding leaks) but it has not yet been fixed.
Parsing
Exactly like an interactive session, parser pragmas persist from one step to the next.
? accum [] for _ in "" { _ + [1] }; null # syntax error: The optional e.enable.accumulator feature (see org/erights/e/elang/syntax/syntax-props-default.txt) is currently off. ? pragma.enable("accumulator") ? accum [] for _ in "" { _ + [1] }; null ? pragma.syntax("0.9") ? accum [] for _ in "" { _ + [1] }; null # syntax error: The optional e.enable.accumulator feature (see org/erights/e/elang/syntax/syntax-props-default.txt) is currently off.
Printing
In the Updoc environment, the text printed via the output objects stdout
, stderr
, print
, and println
is part of the results checked.
Semantics: stdout and stderr write to separate buffers. At the following times in the execution of each step, the contents of each buffer, if nonempty, are moved into answers named "stdout" and "stderr":
- after evaluation of the step, but before the
value
is printed - after interp.waitAtTop/blockAtTop pauses and after all turns queued by the step have executed, but before the evaluation of the next step
XXX Review whether this definition matches E-on-CL and E-on-Java
Line breaks and buffers:
? stdout.print("a") # stdout: a ? stdout.print("a\n") # stdout: a # ? stdout.print("a"); stderr.print("b") # stdout: a # stderr: b
Timing:
? stdout.print("a"); stdout <- print("b"); "c" # stdout: a # value: "c" # stdout: b ? # This step should have no output.
print
and println
:
? println("a", "b"); print("c", "d") # stdout: ab # cd
- This page is a stub; it should be expanded with more information. If doing so, check the original E web site and the mailing list archives for content which could be moved into this page.