Merge pull request #226 from HigherOrderCO/feature/sc-499/add-documen…

…tation-on-passing-arguments-to

[sc-499] Add documentation on cli arguments

README.md

@@ -194,6 +194,7 @@ Other features are described in the following documentation files:
 - 📗 Pattern matching: [Pattern matching](docs/pattern-matching.md)
 - 📗 Native numbers and operations: [Native numbers](docs/native-numbers.md)
 - 📗 Builtin definitions: [Builtin definitions](docs/builtin-defs.md)
+- 📗 CLI arguments: [CLI arguments](docs/cli-arguments.md)
 - 📙 Duplications and superpositions: [Dups and sups](docs/dups-and-sups.md)
 - 📙 Scopeless lambdas: [Using scopeless lambdas](docs/using-scopeless-lambdas.md)
 - 📙 Tagged lambdas and applications: [Automatic vectorization with tagged lambdas](docs/automatic-vectorization-with-tagged-lambdas.md)

docs/cli-arguments.md

@@ -0,0 +1,25 @@
+# CLI arguments
+
+It's possible to pass arguments to a program executed with `hvml run`:
+```sh
+hvml run <Path to program> [Arguments in expression form]...
+```
+It accepts any expression that would also be valid inside an hvm-lang function.
+
+Arguments are passed to programs by applying them to the entrypoint function:
+```js
+main x1 x2 x3 = (MainBody x1 x2 x3)
+
+// Calling with `hvml run <file> arg1 arg2 arg3`, it becomes:
+
+main = (λx1 λx2 λx3 (MainBody x1 x2 x3) arg1 arg2 arg3)
+```
+
+The entrypoint function must receive exactly the number of arguments specified in the left-hand side of its definition.
+```
+// Must pass exactly 3 arguments when running
+main x y z = (MainBody x y z)
+
+// Can't receive CLI arguments
+main = λx λy λz (MainBody x y z)
+```

src/term/transform/apply_args.rs

@@ -21,6 +21,16 @@ impl Display for ArgError {
 }
 
 impl Ctx<'_> {
+  /// Applies the arguments to the program being run by applying them to the main function.
+  ///
+  /// Example:
+  /// ```hvm
+  /// main x1 x2 x3 = (MainBody x1 x2 x3)
+  /// ```
+  /// Calling with `hvml run <file> arg1 arg2 arg3`, it becomes:
+  /// ```hvm
+  /// main = (λx1 λx2 λx3 (MainBody x1 x2 x3) arg1 arg2 arg3)
+  /// ```
   pub fn apply_args(&mut self, args: Option<Vec<Term>>) -> Result<(), Info> {
     self.info.start_pass();