diff --git a/ml-proto/README.md b/ml-proto/README.md index ee0a63e980..f4c294a28d 100644 --- a/ml-proto/README.md +++ b/ml-proto/README.md @@ -61,6 +61,8 @@ Either way, in order to run the test suite you'll need to have Python installed. ## Synopsis +#### Running Modules or Scripts + You can call the executable with ``` @@ -73,6 +75,8 @@ By default, the interpreter validates all modules. The `-u` option selects "unchecked mode", which skips validation and runs code as is. Runtime type errors will be captured and reported appropriately. +#### Converting Modules or Scripts + A file prefixed by `-o` is taken to be an output file. Depending on its extension, this will write out the preceding module definition in either S-expression or binary format. This option can be used to convert between the two in both directions, e.g.: ``` @@ -84,12 +88,28 @@ In the second case, the produced script contains exactly one module definition. The `-d` option selects "dry mode" and ensures that the input module is not run, even if it has a start section. In addition, the `-u` option for "unchecked mode" can be used to convert even modules that do not validate. +The interpreter can also convert entire test scripts: + +``` +wasm -d script.wast -o script.bin.wast +wasm -d script.wast -o script2.wast +wasm -d script.wast -o script.js +``` + +The first creates a new test scripts where all embedded modules are converted to binary, the second one where all are converted to textual. + +The last invocation produces an equivalent, self-contained JavaScript test file. + +#### Command Line Expressions + Finally, the option `-e` allows to provide arbitrary script commands directly on the command line. For example: ``` wasm module.wasm -e '(invoke "foo")' ``` +#### Interactive Mode + If neither a file nor any of the previous options is given, you'll land in the REPL and can enter script commands interactively. You can also get into the REPL by explicitly passing `-` as a file name. You can do that in combination to giving a module file, so that you can then invoke its exports interactively, e.g.: ``` @@ -240,31 +260,40 @@ script: * cmd: ;; define, validate, and initialize module - ;; perform action and print results ( register ? ) ;; register module for imports +module with given failure string + ;; perform action and print results + ;; assert result of an action + ;; meta command + +action: + ( invoke ? * ) ;; invoke function export + ( get ? ) ;; get global export + +assertion: ( assert_return * ) ;; assert action has expected results ( assert_return_nan ) ;; assert action results in NaN ( assert_trap ) ;; assert action traps with given failure string + ( assert_malformed ) ;; assert module cannot be decoded with given failure string ( assert_invalid ) ;; assert module is invalid with given failure string - ( assert_unlinkable ) ;; assert module fails to link module with given failure string - ( input ) ;; read script or module from file - ( output ? ? ) ;; output module to stout or file + ( assert_unlinkable ) ;; assert module fails to link -action: - ( invoke ? * ) ;; invoke function export - ( get ? ) ;; get global export +meta: + ( script ?