From a346494922986378d6bc49ded50b095779ec60be Mon Sep 17 00:00:00 2001
From: PureFox48 <64583745+PureFox48@users.noreply.github.com>
Date: Fri, 16 Apr 2021 19:09:28 +0100
Subject: [PATCH] Documents 'return from module'. (#976)
Fixes #974.
---
doc/site/modularity.markdown | 14 ++++++++++++++
test/language/module/returns/module_return.wren | 4 ++++
.../module/returns/module_return_value.wren | 4 ++++
test/language/module/returns/return.wren | 3 +++
.../module/returns/return_from_import.wren | 5 +++++
test/language/module/returns/return_value.wren | 3 +++
.../module/returns/return_value_from_import.wren | 5 +++++
7 files changed, 38 insertions(+)
create mode 100644 test/language/module/returns/module_return.wren
create mode 100644 test/language/module/returns/module_return_value.wren
create mode 100644 test/language/module/returns/return.wren
create mode 100644 test/language/module/returns/return_from_import.wren
create mode 100644 test/language/module/returns/return_value.wren
create mode 100644 test/language/module/returns/return_value_from_import.wren
diff --git a/doc/site/modularity.markdown b/doc/site/modularity.markdown
index 5c215056..0d62bb03 100644
--- a/doc/site/modularity.markdown
+++ b/doc/site/modularity.markdown
@@ -306,5 +306,19 @@ This sounds super hairy, but that's because cyclic dependencies are hairy in
general. The key point here is that Wren *can* handle them in the rare cases
where you need them.
+## Exiting a module early
+
+Although the `return` statement is normally used to exit from a [method](classes.html#methods) or a [function](functions.html), it can also be used from a module's top-level code to exit the module. For example, if the script consists of a single module, this code would exit the module (and therefore the script) early:
+
+
+for (i in 1..2) {
+ if (i == 2) return
+ System.print(i) //> prints 1 but not 2
+}
+System.print(3) //> not reached
+
+
+Although it is not invalid to return a value, there is no way to access that value and it is therefore simply discarded.
+
← Error Handling
diff --git a/test/language/module/returns/module_return.wren b/test/language/module/returns/module_return.wren
new file mode 100644
index 00000000..1d152ce7
--- /dev/null
+++ b/test/language/module/returns/module_return.wren
@@ -0,0 +1,4 @@
+// nontest
+System.print("foo")
+return
+System.print("bar")
diff --git a/test/language/module/returns/module_return_value.wren b/test/language/module/returns/module_return_value.wren
new file mode 100644
index 00000000..d96d65f4
--- /dev/null
+++ b/test/language/module/returns/module_return_value.wren
@@ -0,0 +1,4 @@
+// nontest
+System.print("foo")
+return 42
+System.print("bar")
diff --git a/test/language/module/returns/return.wren b/test/language/module/returns/return.wren
new file mode 100644
index 00000000..bc647a4e
--- /dev/null
+++ b/test/language/module/returns/return.wren
@@ -0,0 +1,3 @@
+System.print("foo") // expect: foo
+return
+System.print("bar")
diff --git a/test/language/module/returns/return_from_import.wren b/test/language/module/returns/return_from_import.wren
new file mode 100644
index 00000000..3fbc3cf7
--- /dev/null
+++ b/test/language/module/returns/return_from_import.wren
@@ -0,0 +1,5 @@
+import "./module_return"
+
+System.print("baz")
+// expect: foo
+// expect: baz
diff --git a/test/language/module/returns/return_value.wren b/test/language/module/returns/return_value.wren
new file mode 100644
index 00000000..eb821e9f
--- /dev/null
+++ b/test/language/module/returns/return_value.wren
@@ -0,0 +1,3 @@
+System.print("foo") // expect: foo
+return 42
+System.print("bar")
diff --git a/test/language/module/returns/return_value_from_import.wren b/test/language/module/returns/return_value_from_import.wren
new file mode 100644
index 00000000..a092d8bd
--- /dev/null
+++ b/test/language/module/returns/return_value_from_import.wren
@@ -0,0 +1,5 @@
+import "./module_return_value"
+
+System.print("baz")
+// expect: foo
+// expect: baz