From 0fe2d4eaac87b56d22f6b4652d6511f51a0fedeb Mon Sep 17 00:00:00 2001
From: Michael Aaron Murphy <mmstick@pm.me>
Date: Sun, 14 Apr 2019 12:15:33 -0600
Subject: [PATCH] :book: Update the Ion API manual
---
manual/src/SUMMARY.md | 2 --
manual/src/control/02-loops.md | 34 ++++++++++++++++++++++++++--
manual/src/expansions/01-variable.md | 1 -
manual/src/expansions/02-process.md | 1 -
manual/src/features.md | 1 -
manual/src/misc/.md | 3 ---
manual/src/misc/03-quotation.md | 6 ++---
manual/src/slicing.md | 2 +-
8 files changed, 35 insertions(+), 15 deletions(-)
delete mode 100644 manual/src/features.md
delete mode 100644 manual/src/misc/.md
diff --git a/manual/src/SUMMARY.md b/manual/src/SUMMARY.md
index 645da981..45d083fc 100644
--- a/manual/src/SUMMARY.md
+++ b/manual/src/SUMMARY.md
@@ -2,8 +2,6 @@
- [Introduction](introduction.md)
-- [Feature Overview](features.md)
-
- [Miscellaneous](misc/index.md)
- [Implicit `cd`](misc/01-implicitcd.md)
diff --git a/manual/src/control/02-loops.md b/manual/src/control/02-loops.md
index 92fb1446..4550c76a 100644
--- a/manual/src/control/02-loops.md
+++ b/manual/src/control/02-loops.md
@@ -15,13 +15,43 @@ for element in @array
end
```
+## Splitting Arguments
+
+When working with strings that you would like to splice into multiple elements for iteration, see
+the splicing method, `@split`:
+
+```sh
+let value = "one two three four"
+for element in @split(value)
+ echo $element
+end
+```
+
+By default, this will split a string by whitespace. Custom patterns may also be provided:
+
+```sh
+let value = "one,two,three,four"
+for element in @split(value ',')
+ echo $element
+end
+```
+
+A convenience method is also provided for `@split(value '\n')`: `@lines`
+
+```sh
+let file = $(cat file)
+for line in @lines(file)
+ echo = $line =
+end
+```
+
## Breaking From Loops
Sometimes you may need to exit from the loop before the looping is finished. This is achievable
using the `break` keyword.
```sh
-for element in {1...10}
+for element in {1..=10}
echo $element
if test $element -eq 5
break
@@ -42,7 +72,7 @@ In other times, if you need to abort further execution of the current loop and s
loop, the `continue` keyword serves that purpose.
```sh
-for elem in {1...10}
+for elem in {1..=10}
if test $((elem % 2)) -eq 1
continue
end
diff --git a/manual/src/expansions/01-variable.md b/manual/src/expansions/01-variable.md
index 779d38b4..5d86cc83 100644
--- a/manual/src/expansions/01-variable.md
+++ b/manual/src/expansions/01-variable.md
@@ -24,7 +24,6 @@ $ echo $string:$string
**NOTE:**
- Accepted characters are **unicode** alphanumeric characters and **_**.
-- If not double quoted, newlines will be replaced with spaces.
## Array Variables
diff --git a/manual/src/expansions/02-process.md b/manual/src/expansions/02-process.md
index f62d6b75..9706897a 100644
--- a/manual/src/expansions/02-process.md
+++ b/manual/src/expansions/02-process.md
@@ -13,4 +13,3 @@ let array = @(cmd args...)
**NOTES:**
- To split outputs by line, see `@lines($(cmd))`.
- `@(cmd)` is equivalent to `@split($(cmd))`
-- If not double quoted, newlines will be replaced with spaces
diff --git a/manual/src/features.md b/manual/src/features.md
deleted file mode 100644
index ead02231..00000000
--- a/manual/src/features.md
+++ /dev/null
@@ -1 +0,0 @@
-# Features
diff --git a/manual/src/misc/.md b/manual/src/misc/.md
deleted file mode 100644
index bc67b1dd..00000000
--- a/manual/src/misc/.md
+++ /dev/null
@@ -1,3 +0,0 @@
-# Miscellaneous Features
-
-These are features of Ion that don't belong to any specific category:
diff --git a/manual/src/misc/03-quotation.md b/manual/src/misc/03-quotation.md
index 55587945..0a7b7195 100644
--- a/manual/src/misc/03-quotation.md
+++ b/manual/src/misc/03-quotation.md
@@ -1,6 +1,4 @@
# Quoting Rules
-In general, double quotes allow expansions within quoted text, whereas single quotes do not.
-An exception to the rule is brace expansions, where double quotes are not allowed. When
-arguments are parsed, the general rule is the replace newlines with spaces. When double-quoted
-expansions will retain their newlines. Quoting rules are reversed for heredocs and for loops.
+- Variables are expanded in double quotes, but not single quotes.
+- Braces are expanded when unquoted, but not when quoted.
diff --git a/manual/src/slicing.md b/manual/src/slicing.md
index 623564c8..d03a1757 100644
--- a/manual/src/slicing.md
+++ b/manual/src/slicing.md
@@ -2,7 +2,7 @@
Ion supports a universal syntax for slicing strings and arrays. For maximum language support,
strings are sliced and indexed by graphemes. Arrays are sliced and indexed by their elements.
-Slicing uses the same **[]** characters as arrays, but the shell can differentation between
+Slicing uses the same **[]** characters as arrays, but the shell can differentiation between
a slice and an array based on the placement of the characters (immediately after an expansion).
**NOTE:** It's important to note that indexes count from 0, as in most other languages.
--
GitLab