Commit 4ec281c7 authored by matu3ba's avatar matu3ba
Browse files

fix(manual): document various documentation issues, refactor to test documentation

The long-term plan is to test the builtin documentation with the binary output and cache it.
parent ab5e0c82
......@@ -20,43 +20,6 @@ DESCRIPTION
Returns true if the value given to it is equal to '1' or 'true'.
```
## math - Floating-point calculator
```txt
SYNOPSIS
math [EXPRESSION]
DESCRIPTION
Evaluates arithmetic expressions
SPECIAL EXPRESSIONS
help (only in interactive mode)
prints this help text
--help (only in non-interactive mode)
prints this help text
exit (only in interactive mode)
exits the program
NOTATIONS
infix notation
e.g. 3 * 4 + 5
polish notation
e.g. + * 3 4 5
EXAMPLES
Add two plus two in infix notation
math 2+2
Add two plus two in polish notation
math + 2 2
AUTHOR
Written by Hunter Goldstein.
```
## cd - Change directory.
```txt
......@@ -298,6 +261,25 @@ DESCRIPTION
Get the short description for BUILTIN. If no argument is provided, list all the builtins
```
## history - print command history
```txt
SYNOPSIS
history [option]
DESCRIPTION
Prints or manupulate the command history.
OPTIONS:
+inc_append: Append each command to history as entered.
-inc_append: Default, do not append each command to history as entered.
+shared: Share history between shells using the same history file, implies inc_append.
-shared: Default, do not share shell history.
+duplicates: Default, allow duplicates in history.
-duplicates: Do not allow duplicates in history.
```
## eq, is - checks if two arguments are the same
```txt
......@@ -349,6 +331,43 @@ EXAMPLES
matches x xs
```
## math - Floating-point calculator
```txt
SYNOPSIS
math [EXPRESSION]
DESCRIPTION
Evaluates arithmetic expressions
SPECIAL EXPRESSIONS
help (only in interactive mode)
prints this help text
--help (only in non-interactive mode)
prints this help text
exit (only in interactive mode)
exits the program
NOTATIONS
infix notation
e.g. 3 * 4 + 5
polish notation
e.g. + * 3 4 5
EXAMPLES
Add two plus two in infix notation
math 2+2
Add two plus two in polish notation
math + 2 2
AUTHOR
Written by Hunter Goldstein.
```
## popd - shift through the directory stack
```txt
......
......@@ -15,11 +15,14 @@ have been read. Then the characters that were collected will be used as the name
variable to substitute with.
```sh
$ let string = "example string"
$ echo $string
> example string
$ echo $string:$string
> example string:example string
let string = "example string"
echo $string
echo $string:$string
```
```txt
example string
example string:example string
```
**NOTE:**
......@@ -33,10 +36,11 @@ return an array of strings. This means that it's possible to use an array variab
in a command, as each element in the array will be treated as a separate shell word.
```sh
$ let array = [one two three]
$ echo @array
> one two three
$ cmd @args
let array = [one two three]
echo @array
```
```txt
one two three
```
However, do note that double-quoted arrays are coerced into strings, with spaces separating each
......
......@@ -13,3 +13,20 @@ let array = [ @(cmd args...) ]
**NOTES:**
- To split outputs by line, see [@lines($(cmd))](https://doc.redox-os.org/ion-manual/html/expansions/05-method.html#lines).
- `@(cmd)` is equivalent to [@split($(cmd))](https://doc.redox-os.org/ion-manual/html/expansions/05-method.html#split).
```sh
mkdir -p _tmp _tmp/t1 _tmp/t2
cd _tmp
let res = $(ls)
let res2 = [ @(ls) ]
echo $res # output the string
echo @res2 # output the array
cd ..
rm -fr _tmp
```
```txt
t1
t2
t1 t2
```
......@@ -9,53 +9,54 @@ permutations.
**NOTE:** Brace expansions will not work within double quotes.
```sh
$ echo filename.{ext1,ext2}
> filename.ext1 filename.ext2
echo filename.{ext1,ext2}
```
```txt
filename.ext1 filename.ext2
```
Multiple brace tokens may occur within a braced collection, where each token expands the
possible permutation variants.
```sh
$ echo job_{01,02}.{ext1,ext2}
> job_01.ext1 job_01.ext2 job_02.ext1 job_02.ext2
echo job_{01,02}.{ext1,ext2}
```
```txt
job_01.ext1 job_01.ext2 job_02.ext1 job_02.ext2
```
Brace tokens may even contain brace tokens of their own, as each brace element will also be
expanded.
```sh
$ echo job_{01_{out,err},02_{out,err}}.txt
> job_01_out.txt job_01_err.txt job_02_out.txt job_02_err.txt
echo job_{01_{out,err},02_{out,err}}.txt
```
```txt
job_01_out.txt job_01_err.txt job_02_out.txt job_02_err.txt
```
Braces elements may also be designated as ranges, which may be either inclusive or exclusive,
descending or ascending, numbers or latin alphabet characters.
```sh
$ echo {1..10}
> 1 2 3 4 5 6 7 8 9
$ echo {1...10}
> 1 2 3 4 5 6 7 8 9 10
$ echo {10..1}
> 10 9 8 7 6 5 4 3 2
$ echo {10...1}
> 10 9 8 7 6 5 4 3 2 1
$ echo {a..d}
> a b c
$ echo {a...d}
> a b c d
$ echo {d..a}
> d c b
$ echo {d...a}
> d c b a
echo {1..10}
echo {10..1}
echo {1...10}
echo {10...1}
echo {a..d}
echo {d..a}
echo {a...d}
echo {d...a}
```
```txt
1 2 3 4 5 6 7 8 9
10 9 8 7 6 5 4 3 2
1 2 3 4 5 6 7 8 9 10
10 9 8 7 6 5 4 3 2 1
a b c
d c b
a b c d
d c b a
```
It's also important to note that, as brace expansions return arrays, they may be used in for loops.
......@@ -65,3 +66,6 @@ for num in {1..10}
echo $num
end
```
```txt
1 2 3 4 5 6 7 8 9
```
......@@ -89,10 +89,7 @@ basename (complete filename, extension included). IE: `/parent/filename.ext` ->
```sh
echo $basename("/parent/filename.ext")
```
#### Output
```
```txt
filename.ext
```
......@@ -106,10 +103,7 @@ extension of the complete filename. IE: `/parent/filename.ext` -> `ext`.
```sh
echo $extension("/parent/filename.ext")
```
#### Output
```
```txt
ext
```
......@@ -123,10 +117,7 @@ file name portion of the complete filename. IE: `/parent/filename.ext` -> `filen
```sh
echo $filename("/parent/filename.ext")
```
#### Output
```
```txt
filename
```
......@@ -143,10 +134,7 @@ let array = [1 2 3 4 5]
echo $join(array)
echo $join(array ", ")
```
#### Output
```
```txt
1 2 3 4 5
1, 2, 3, 4, 5
```
......@@ -162,10 +150,7 @@ string appears. It returns `-1` if it isn't contained.
echo $find("FOOBAR" "OB")
echo $find("FOOBAR" "ob")
```
#### Output
```
```txt
2
-1
```
......@@ -183,10 +168,7 @@ echo $len("foobar")
echo $len("❤️")
echo $len([one two three four])
```
#### Output
```
```txt
6
1
4
......@@ -203,10 +185,7 @@ in the output, not the number of graphemes.
echo $len_bytes("foobar")
echo $len_bytes("❤️")
```
#### Output
```
```txt
6
6
```
......@@ -221,10 +200,7 @@ parent directory's name. IE: `/root/parent/filename.ext` -> `/root/parent`
```sh
echo $parent("/root/parent/filename.ext")
```
#### Output
```
```txt
/root/parent
```
......@@ -238,10 +214,7 @@ amount of times, where N is the supplied number.
```sh
echo $repeat("abc, " 3)
```
#### Output
```
```txt
abc, abc, abc,
```
......@@ -257,10 +230,7 @@ let input = "one two one two"
echo $replace(input one 1)
echo $replace($replace(input one 1) two 2)
```
#### Output
```
```txt
1 two 1 two
1 2 1 2
```
......@@ -277,10 +247,7 @@ let input = "one two one two"
echo $replacen(input "one" "three" 1)
echo $replacen(input "two" "three" 2)
```
#### Output
```
```txt
three two one two
one three one three
```
......@@ -298,10 +265,7 @@ as a regex.
echo $regex_replace("bob" "^b" "B")
echo $regex_replace("bob" 'b$' "B")
```
#### Output
```
```txt
Bob
boB
```
......@@ -316,10 +280,7 @@ in reverse order.
```sh
echo $reverse("foobar")
```
#### Output
```
```txt
raboof
```
......@@ -333,10 +294,7 @@ lowercase equivalent, if an lowercase equivalent exists.
```sh
echo $to_lowercase("FOOBAR")
```
#### Output
```
```txt
foobar
```
......@@ -350,10 +308,7 @@ uppercase equivalent, if an uppercase equivalent exists.
```sh
echo $to_uppercase("foobar")
```
#### Output
```
```txt
FOOBAR
```
......@@ -367,10 +322,7 @@ Defaults to string variables. Escapes the content of the string.
let line = " Mary had\ta little \n\t lamb\t"
echo $escape($line)
```
#### Output
```
```txt
Mary had\\ta little \\n\\t lamb\\t
```
......@@ -384,10 +336,7 @@ Defaults to string variables. Unescapes the content of the string.
let line = " Mary had\ta little \n\t lamb\t"
echo $unescape($line)
```
#### Output
```
```txt
Mary had a little
lamb
```
......@@ -403,10 +352,7 @@ echo $or($unknown_variable "Fallback")
let var = 42
echo $or($var "Not displayed")
```
#### Output
```
```txt
Fallback
42
```
......@@ -435,10 +381,7 @@ for line in @lines($unescape("first\nsecond\nthird"))
echo $line
end
```
#### Output
```
```txt
first
second
third
......@@ -461,10 +404,7 @@ for data in @split("person age data")
echo $data
end
```
#### Output
```
```txt
person
age
some data
......@@ -485,10 +425,7 @@ echo @split_at("FOOBAR")
echo @split_at("FOOBAR" "-1")
echo @split_at("FOOBAR" "8")
```
#### Output
```
```txt
FOO BAR
ion: split_at: requires an argument
ion: split_at: requires a valid number as an argument
......@@ -505,10 +442,7 @@ each byte is displayed as their actual 8-bit number.
```sh
echo @bytes("abc")
```
#### Output
```
```txt
97 98 99
```
......@@ -523,10 +457,7 @@ for char in @chars("foobar")
echo $char
end
```
#### Output
```
```txt
f
o
o
......@@ -546,10 +477,7 @@ for grapheme in @graphemes("foobar")
echo $grapheme
end
```
#### Output
```
```txt
f
o
o
......@@ -567,10 +495,6 @@ Defaults to array variables. Returns a reversed copy of the input array.
```sh
echo @reverse([1 2 3])
```
#### Output
```
```txt
3 2 1
```
......@@ -94,3 +94,12 @@ When using Ion as a shell library, it is possible you may want to change the bui
If you do this, all function calls will use the new builtins to run. meaning that if you removed the builtin function it the shell will try to find the command, and if you added a builtin, that will override any other command.
## Advanced usage (THIS MAY BREAK ANY TIME)
```sh
fn square x:int; echo $(( x * x )); end
square 22
```
```txt
484
```
......@@ -21,6 +21,13 @@ true
false
```
The REPL provides the following useful shortcuts for history searching:
- Ctrl + s => forward search history ;
- Ctrl + r => reverse search history ;
- Ctrl + f => accept autosuggestion ;
- Ctrl + u => delete content ;
- Ctrl + c => interrupt command .
## Variables
The following local variables can be used to modify Ion's history behavior:
......
......@@ -5,7 +5,9 @@ strings are sliced and indexed by graphemes. Arrays are sliced and indexed by th
Slicing uses the same **[]** characters as arrays, but the shell can differentiate 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.
**NOTE:** It's important to note that indexes count from 0, as in most other system programming languages.
**NOTE:** `...` and `..=` can be used interchangeable.
## Exclusive Range
......@@ -14,18 +16,19 @@ the Nth element, where N is the last index value. The Nth element's ID is always
less than the Nth value.
```sh
$ let array = [{1...10}]
$ echo @array[0..5]
> 1 2 3 4 5
$ echo @array[..5]
> 1 2 3 4 5
let array = [{1...10}]
echo @array[0..5]
echo @array[..5]
$ let string = "hello world"
$ echo $string[..5]
> hello
$ echo $string[6..]
> world
let string = "hello world"
echo $string[..5]
echo $string[6..]
```
```txt
1 2 3 4 5
1 2 3 4 5
hello
world
```
## Inclusive Range
......@@ -33,16 +36,20 @@ $ echo $string[6..]
When using inclusive ranges, the end index does not refer to the Nth value, but the actual index ID.
```sh
$ let array = [{1...10}]
$ echo @array[0...5]
> 1 2 3 4 5 6
let array = [{1...10}]
echo @array[0...5]
```
```txt
1 2 3 4 5 6
```
The `=` character may be used instead of the third dot.
```sh
$ echo @array[0..=5]
> 1 2 3 4 5 6
echo @array[0..=5]
```
```txt
1 2 3 4 5 6
```
## Descending Ranges
......@@ -51,10 +58,12 @@ Ranges do not have to always be specified in ascending order. Descending ranges
supported. However, at this time you cannot provide an descending range as an index to an array.
```sh
$ echo {10...1}
> 10 9 8 7 6 5 4 3 2 1
$ echo {10..1}
> 10 9 8 7 6 5 4 3 2
echo {10...1}
echo {10..1}
```
```txt