Revert "repl-characterization: document the syntax"
This reverts commit 0d6b372c19.
Reason for revert: In the time between this getting +2 and it being merged, all repl tests and its syntax have been migrated to f2, making these changes null and to dead code
Change-Id: I00f5237bf3f2ca3a60cc1584f67fb67196805e7e
This commit is contained in:
Rutile
committed by
Lix Systems Gerrit
Lix Systems Gerrit
parent
0d6b372c19
commit
d748b4e509
@@ -1,82 +0,0 @@
|
||||
# repl characterization tests
|
||||
|
||||
> or, literate programming for your REPL tests!
|
||||
|
||||
The core idea behind repl-characterization is to make it very easy to write and maintain REPL tests by turning session transcripts directly into tests.
|
||||
|
||||
This infrastructure is written in C++ but we want to [rewrite it in functional2][riif2] in the near future.
|
||||
|
||||
[riif2]: https://git.lix.systems/lix-project/lix/issues/1196
|
||||
|
||||
To write a repl-characterization test, you can open up `nix repl` and then you copy paste the output into the test file, then indent it.
|
||||
Add your unindented commentary alongside the output text.
|
||||
Add any necessary args.
|
||||
Then it should run!
|
||||
|
||||
## Syntax
|
||||
|
||||
The syntax of repl-characterization contains four types of things:
|
||||
- Prompts to the repl, indented: ` nix-repl> 2 + 2` for example.
|
||||
- Blocks of output, indented.
|
||||
These are denoted by indented non-empty lines, perhaps with some blank lines between them which are part of the output.
|
||||
- Directives, unindented.
|
||||
These are:
|
||||
- `@args some args with "shell quoting"`.
|
||||
Adds the args to the invocation of `nix repl`.
|
||||
Multiple may be used.
|
||||
|
||||
`${PWD}` will be replaced by the actual working directory.
|
||||
- `@should-start false`
|
||||
This is used to indicate that the repl is expected to fail to start, giving some output and no prompt to the system.
|
||||
- Commentary.
|
||||
This is any unindented text, including blank lines outside output blocks.
|
||||
|
||||
One of the core ideas of the syntax is that it's possible to write an unparser for it such that we can update test session files in-place, retaining your commentary.
|
||||
This is [not implemented in the C++ version][bug-autoupdate], and I think we will probably only do it in the Python version.
|
||||
|
||||
[bug-autoupdate]: https://git.lix.systems/lix-project/lix/issues/36
|
||||
|
||||
Here is a simplified version of the syntax in pseudo-[EBNF]:
|
||||
|
||||
[EBNF]: https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_form
|
||||
|
||||
```ebnf
|
||||
indent = " " (* space times config.indent; 2 in practice *) ;
|
||||
line-char = ( ? anything but nl ? )+ ;
|
||||
nl = "\n" ;
|
||||
|
||||
prompt = "nix-repl>" ;
|
||||
command = line-char* ;
|
||||
prompt-line = indent , prompt , command ;
|
||||
|
||||
bool = "true" | "false" ;
|
||||
|
||||
args-directive = "args " , line-char+ ;
|
||||
should-start-directive = "should-start " , bool ;
|
||||
unknown-directive = ? this is an error ? ; (* there's a bug in the C++ impl where we don't actually error on this *)
|
||||
directive = args-directive | should-start-directive | unknown-directive ;
|
||||
directive-line = "@" , directive ;
|
||||
|
||||
(* anything unindented is a comment *)
|
||||
commentary-line = line-char+ ;
|
||||
|
||||
output-line = indent , line-char+ ;
|
||||
output-continuation = output-line? , nl ;
|
||||
(* in other words: output blocks are considered to contain any *inner* blank
|
||||
lines within them, but *not* trailing blank lines. This enables updating
|
||||
them automatically while retaining the blank lines surrounding your stanzas
|
||||
in your session.
|
||||
|
||||
This is implemented as a postprocessing step so that our parsing doesn't
|
||||
require lookahead. *)
|
||||
output-block = output-line , nl , ((blank-line , nl)+ , output-line , nl)+ ;
|
||||
|
||||
input = ((prompt-line | directive-line | commentary-line) , nl) | output-block ;
|
||||
file = input* ;
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
Tests are written in `./data/*.test`, and have a corresponding macro call in `./repl_characterization.cc` (the macro thing is basically a hack because the infra was never quite finished).
|
||||
|
||||
You can run the suite with `just install && just test --suite installcheck repl-characterization-tests`.
|
||||
@@ -2,7 +2,10 @@
|
||||
///@file
|
||||
|
||||
#include "lix/libutil/error.hh"
|
||||
#include <compare>
|
||||
#include <memory>
|
||||
#include <optional>
|
||||
#include <sstream>
|
||||
#include <string>
|
||||
#include <variant>
|
||||
#include <vector>
|
||||
@@ -163,7 +166,13 @@ struct Config {
|
||||
* comments.
|
||||
*
|
||||
* Syntax:
|
||||
* See tests/functional/repl_characterization/README.md.
|
||||
* ```
|
||||
* ( COMMENTARY
|
||||
* | INDENT PROMPT COMMAND
|
||||
* | INDENT OUTPUT
|
||||
* | @args ARGS
|
||||
* | @should-start ( true | false )) *
|
||||
* ```
|
||||
*
|
||||
* e.g.
|
||||
* ```
|
||||
|
||||
Reference in New Issue
Block a user