Explain the module system

index.md

@@ -10,20 +10,23 @@ Val aims to be:
 - **Simple**: Val borrows heavily from the [Swift programming language](https://swift.org) which has demonstrated a user-friendly approach to generic programming. Further, its user model emphasizes on value, leaving out the typical complexities associated with reference semantics (e.g., memory regions, lifetime annotations, etc.).
 - **Interoperable with C++**: Programming languages rarely survive in vacuum. Val aims to take advantage of the vast software capital of C++ by supporting full interperability.
 
-The [language tour](./language-tour.html).) gives an overview of Val's most salient feature.
+The [language tour](./language-tour.html) gives an overview of Val's most salient feature.
 The [specification](https://github.com/val-lang/specification/blob/main/spec.md) (work in progress) provides detailed information about Val's syntax and semantics.
 
 Val is under active development and is not ready to be used yet.
 The code of the compiler is open source and [hosted on GitHub](https://github.com/val-lang/val).
 
-# Enough, show me some code!
+## Enough, show me some code!
+
+Okay, okay.
+Here's a simple program.
 
 ```val
 subscript longer_of(_ a: inout String, _ b: inout String): String {
   yield if b.count() > a.count() { &b } else { &a }
 }
 
-fun main() {
+public fun main() {
   var (x, y) = ("Hi", "World")
   inout z = longer_of[&x, &y]
   z .append("!")

language-tour.md

@@ -2,8 +2,6 @@
 layout: default
 ---
 
-## Language tour
-
 This page gives a quick tour of Val's feature in the form of a progressive guide.
 It assumes familiarity with an imperative programming language (e.g., C++) and basic concepts of [memory management](https://en.wikipedia.org/wiki/Memory_management).
 
@@ -13,7 +11,7 @@ You may consult the [specification](https://github.com/val-lang/specification/bl
 Keep in mind that Val is under active development.
 Some of the features presented in this tour (and in the specification) may not be fully implemented yet or subject to change in the future.
 
-### Hello, World!
+## Hello, World!
 
 The tradition says language guides should start with a program that displays "Hello, World!" on the screen.
 Let's oblige!
@@ -29,21 +27,93 @@ That function never takes any argument and never returns anything.
 Here, `main` contains single statement, which is a call to a global function `print` with a string argument.
 
 *The standard library vends an API to interact with the program's environment.*
-*Command line arguments are accessed by reading a global array of strings named `Environment.arguments`.*
+*Command line arguments are accessed by reading a constant named `Environment.arguments`.*
 *Return statuses are signalued by calling the global function `exit(status:)`.*
 
 To run this program:
-- Copy that `main` function in a file `hello.val`.
-- Run the command `valc hello.val`.
+- Copy that `main` function in a file `Hello.val`.
+- Run the command `valc Hello.val -o hello`.
 - Run the command `./ hello` to run the executable.
 
-### Modules
+## Modules
 
 A Val program is made of **modules** that are linked together to build one **executable**.
 A module is a collection of one or multiple files.
 A module that defines a public `main` function is called an entry module.
 A program shall contain only one entry module.
 
+The program we wrote above is made of two modules.
+The first contains the `hello.val` file and is the program's entry module.
+The second is Val's standard library, which is always implicitly imported, and defines common types, traits, functions and subscripts.
+
+### Bundling files
+
+You may bundle multiple files in a single module by passing all of them as arguments to `valc`.
+For example, let us define a function that prints a specialized greeting in a separate file and call it from `Hello.val`:
+
+```val
+// In `Hello.val`
+public fun main() {
+  greet("World")
+}
+
+// In `Greet.val`
+fun greet(_ name: String) {
+  print("Hello, ${name}!")
+}
+```
+
+Here, we declare a function `greet` that takes a single argument of type `String`.
+The underscore (i.e., `_`) before the parameter name signals that it is unlabeled.
+We'll come back to labels later.
+
+To run this program:
+- Run the command `valc Hello.val Greet.val -o hello`
+- Run the command `./hello`
+
+*Alternatively, you may put both source files in a folder, say `Sources`, and compile the program with `valc Sources -o hello`.*
+
+Note that `greet` need not to be `public` to be visible from another file in the module.
+All entities declared at the top level of a file are visible everywhere in a module, but not beyond that module's boundary.
+
+### Bundling modules
+
+The simplest way to work with multiple modules is to gather source files in different folders.
+For example, let's move `greet` in a different module, using the following arborescence:
+
+```
+Sources
+  |- Hello
+  |  |- Hello.val
+  |- Greet
+  |  |- Greet.val
+```
+
+Let's also slightly modify both source files:
+
+```val
+// In `Sources/Hello/Hello.val`
+import Greet
+public fun main() {
+  greet("World")
+}
+
+// In `Sources/Greet/Greet.val`
+public fun greet(_ name: String) {
+  print("Hello, ${name}!")
+}
+```
+
+The statement `import Greet` at the top of `Hello.val` tells the compiler it should import the module `Greet` when it compiles that source file.
+Implicitly, that makes `Greet` a dependency of `Hello`.
+
+Notice that `greet` had to be made public because we want it to cross module boundary.
+As such, it can be called from `Hello.val`.
+
+To run this program:
+- Run the command `valc --modules Sources/Hello Sources/Greet -o hello`
+- Run the command `./hello`
+
 * * *
 
 [Home](./)