Commit 1f2d8e25 authored by matu3ba's avatar matu3ba
Browse files

fix(manual): split string and array methods from section methods and test them

parent e033ca1c
......@@ -25,6 +25,8 @@
- [Brace Expansions](expansions/03-brace.md)
- [Arithmetic Expansions](expansions/04-arithmetic.md)
- [Method Expansions](expansions/05-method.md)
- [String Methods](expansions/06-stringmethods.md)
- [Array Methods](expansions/07-arraymethods.md)
- [Slicing Syntax](slicing.md)
......
# Method Expansions
There are two forms of methods within Ion: array methods, and string methods. Array methods are
There are two forms of methods within Ion: [string methods](06-stringmethods.md) and [array methods](07-arraymethods.md). Array methods are
methods which return arrays, and string methods are methods which return strings. The distinction
is made between the two by the sigil that is invoked when calling a method. For example, if the
method is denoted by the `$` sigil, then it is a string method. Otherwise, if it is denoted by the
......@@ -55,446 +55,3 @@ method, for example, may be optionally supplied a pattern for splitting.
for elem in @split("some space-delimited values"); echo $elem; end
for elem in @split("some, comma-separated, values" ", "); echo $elem; end
```
## String Methods
The following are the currently-supported string methods:
- [basename](#basename)
- [extension](#extension)
- [filename](#filename)
- [join](#join)
- [find](#find)
- [len](#len)
- [len_bytes](#len_bytes)
- [parent](#parent)
- [repeat](#repeat)
- [replace](#replace)
- [replacen](#replacen)
- [regex_replace](#regex_replace)
- [reverse](#reverse)
- [to_lowercase](#to_lowercase)
- [to_uppercase](#to_uppercase)
- [escape](#escape)
- [unescape](#unescape)
- [or](#or)
### basename
Defaults to string variables. When given a path-like string as input, this will return the
basename (complete filename, extension included). IE: `/parent/filename.ext` -> `filename.ext`
#### Examples
```sh
echo $basename("/parent/filename.ext")
```
```txt
filename.ext
```
### extension
Defaults to string variables. When given a path-like string as input, this will return the
extension of the complete filename. IE: `/parent/filename.ext` -> `ext`.
#### Examples
```sh
echo $extension("/parent/filename.ext")
```
```txt
ext
```
### filename
Defaults to string variables. When given a path-like string as input, this will return the
file name portion of the complete filename. IE: `/parent/filename.ext` -> `filename`.
#### Examples
```sh
echo $filename("/parent/filename.ext")
```
```txt
filename
```
### join
Defaults to array variables. When given an array as input, the join string method will concatenate
each element in the array and return a string. If no argument is given, then those elements will
be joined by a single space. Otherwise, each element will be joined with a given pattern.
#### Examples
```sh
let array = [1 2 3 4 5]
echo $join(array)
echo $join(array ", ")
```
```txt
1 2 3 4 5
1, 2, 3, 4, 5
```
### find
Defaults to string variables. When given an string, it returns the first index in which that
string appears. It returns `-1` if it isn't contained.
#### Examples
```sh
echo $find("FOOBAR" "OB")
echo $find("FOOBAR" "ob")
```
```txt
2
-1
```
### len
Defaults to string variables. Counts the number of graphemes in the output. If an array expression
is supplied, it will print the number of elements in the array.
#### Examples
```sh
echo $len("foobar")
echo $len("❤️")
echo $len([one two three four])
```
```txt
6
1
4
```
### len_bytes
Defaults to string variables. Similar to the `len` method, but counts the number of actual bytes
in the output, not the number of graphemes.
#### Examples
```sh
echo $len_bytes("foobar")
echo $len_bytes("❤️")
```
```txt
6
6
```
### parent
Defaults to string variables. When given a path-like string as input, this will return the
parent directory's name. IE: `/root/parent/filename.ext` -> `/root/parent`
#### Examples
```sh
echo $parent("/root/parent/filename.ext")
```
```txt
/root/parent
```
### repeat
Defaults to string variables. When supplied with a number, it will repeat the input N
amount of times, where N is the supplied number.
#### Examples
```sh
echo $repeat("abc, " 3)
```
```txt
abc, abc, abc,
```
### replace
Defaults to string variables. Given a pattern to match, and a replacement to replace each match
with, a new string will be returned with all matches replaced.
#### Examples
```sh
let input = "one two one two"
echo $replace(input one 1)
echo $replace($replace(input one 1) two 2)
```
```txt
1 two 1 two
1 2 1 2
```
### replacen
Defaults to string variables. Equivalent to `replace`, but will only replace the first N amount
of matches.
#### Examples
```sh
let input = "one two one two"
echo $replacen(input "one" "three" 1)
echo $replacen(input "two" "three" 2)
```
```txt
three two one two
one three one three
```
### regex\_replace
Defaults to string variables. Equivalent to `replace`, but the first argument will be treated
as a regex.
**PS:** By default, unicode support will be disabled to trim the size of Ion. Add the "unicode" flag to enable it.
#### Examples
```sh
echo $regex_replace("bob" "^b" "B")
echo $regex_replace("bob" 'b$' "B")
```
```txt
Bob
boB
```
### reverse
Defaults to string variables. Simply returns the same string, but with each grapheme displayed
in reverse order.
#### Examples
```sh
echo $reverse("foobar")
```
```txt
raboof
```
### to_lowercase
Defaults to string variables. All given strings have their characters converted to an
lowercase equivalent, if an lowercase equivalent exists.
#### Examples
```sh
echo $to_lowercase("FOOBAR")
```
```txt
foobar
```
### to_uppercase
Defaults to string variables. All given strings have their characters converted to an
uppercase equivalent, if an uppercase equivalent exists.
#### Examples
```sh
echo $to_uppercase("foobar")
```
```txt
FOOBAR
```
### escape
Defaults to string variables. Escapes the content of the string.
#### Example
```sh
let line = " Mary had\ta little \n\t lamb\t"
echo $escape($line)
```
```txt
Mary had\\ta little \\n\\t lamb\\t
```
### unescape
Defaults to string variables. Unescapes the content of the string.
#### Example
```
let line = " Mary had\ta little \n\t lamb\t"
echo $unescape($line)
```
```txt
Mary had a little
lamb
```
### or
Defaults to string variables. Fallback to a given value if the variable is not defined or is an empty string.
#### Example
```
echo $or($unknown_variable "Fallback")
let var = 42
echo $or($var "Not displayed")
```
```txt
Fallback
42
```
## Array Methods
The following are the currently-supported array methods.
- [lines](#lines)
- [split](#split)
- [split_at](#split_at)
- [bytes](#bytes)
- [chars](#chars)
- [graphemes](#graphemes)
- [reverse](#reverse)
### lines
Defaults to string variables. The supplied string will be split into one string per line in the input argument.
This is equivalent to `@split(value '\n')`.
#### Examples
```sh
for line in @lines($unescape("first\nsecond\nthird"))
echo $line
end
```
```txt
first
second
third
```
### split
Defaults to string variables. The supplied string will be split according to a pattern specified
as an argument in the method. If no pattern is supplied, then the input will be split by
whitespace characters. Useful for splitting simple tabular data.
#### Examples
```sh
for data in @split("person, age, some data" ", ")
echo $data
end
for data in @split("person age data")
echo $data
end
```
```txt
person
age
some data
person
age
data
```
### split_at
Defaults to string variables. The supplied string will be split in two pieces, from the index specified in the second argument.
#### Examples
```
echo @split_at("FOOBAR" "3")
echo @split_at("FOOBAR")
echo @split_at("FOOBAR" "-1")
echo @split_at("FOOBAR" "8")
```
```txt
FOO BAR
ion: split_at: requires an argument
ion: split_at: requires a valid number as an argument
ion: split_at: value is out of bounds
```
### bytes
Defaults to string variables. Returns an array where the given input string is split by bytes and
each byte is displayed as their actual 8-bit number.
#### Examples
```sh
echo @bytes("abc")
```
```txt
97 98 99
```
### chars
Defaults to string variables. Returns an array where the given input string is split by chars.
#### Examples
```sh
for char in @chars("foobar")
echo $char
end
```
```txt
f
o
o
b
a
r
```
### graphemes
Defaults to string variables. Returns an array where the given input string is split by graphemes.
#### Examples
```sh
for grapheme in @graphemes("foobar")
echo $grapheme
end
```
```txt
f
o
o
b
a
r
```
### reverse
Defaults to array variables. Returns a reversed copy of the input array.
#### Examples
```sh
echo @reverse([1 2 3])
```
```txt
3 2 1
```
## String Methods
The following are the currently-supported string methods:
- [basename](#basename)
- [extension](#extension)
- [filename](#filename)
- [join](#join)
- [find](#find)
- [len](#len)
- [len_bytes](#len_bytes)
- [parent](#parent)
- [repeat](#repeat)
- [replace](#replace)
- [replacen](#replacen)
- [regex_replace](#regex_replace)
- [reverse](#reverse)
- [to_lowercase](#to_lowercase)
- [to_uppercase](#to_uppercase)
- [escape](#escape)
- [unescape](#unescape)
- [or](#or)
### basename
Defaults to string variables. When given a path-like string as input, this will return the
basename (complete filename, extension included). IE: `/parent/filename.ext` -> `filename.ext`
```sh
{{#include ../../../tests/string_methods.ion:basename}}
```
```txt
{{#include ../../../tests/string_methods.out:basename}}
```
### extension
Defaults to string variables. When given a path-like string as input, this will return the
extension of the complete filename. IE: `/parent/filename.ext` -> `ext`.
```sh
{{#include ../../../tests/string_methods.ion:extension}}
```
```txt
{{#include ../../../tests/string_methods.out:extension}}
```
### filename
Defaults to string variables. When given a path-like string as input, this will return the
file name portion of the complete filename. IE: `/parent/filename.ext` -> `filename`.
```sh
{{#include ../../../tests/string_methods.ion:filename}}
```
```txt
{{#include ../../../tests/string_methods.out:filename}}
```
### join
Defaults to array variables. When given an array as input, the join string method will concatenate
each element in the array and return a string. If no argument is given, then those elements will
be joined by a single space. Otherwise, each element will be joined with a given pattern.
```sh
{{#include ../../../tests/string_methods.ion:join}}
```
```txt
{{#include ../../../tests/string_methods.out:join}}
```
### find
Defaults to string variables. When given an string, it returns the first index in which that
string appears. It returns `-1` if it isn't contained.
```sh
{{#include ../../../tests/string_methods.ion:find}}
```
```txt
{{#include ../../../tests/string_methods.out:find}}
```
### len
Defaults to string variables. Counts the number of graphemes in the output. If an array expression
is supplied, it will print the number of elements in the array.
```sh
{{#include ../../../tests/string_methods.ion:len}}
```
```txt
{{#include ../../../tests/string_methods.out:len}}
```
### len_bytes
Defaults to string variables. Similar to the `len` method, but counts the number of actual bytes
in the output, not the number of graphemes.
```sh
{{#include ../../../tests/string_methods.ion:len_bytes}}
```
```txt
{{#include ../../../tests/string_methods.out:len_bytes}}
```
### parent
Defaults to string variables. When given a path-like string as input, this will return the
parent directory's name. IE: `/root/parent/filename.ext` -> `/root/parent`
```sh
{{#include ../../../tests/string_methods.ion:parent}}
```
```txt
{{#include ../../../tests/string_methods.out:parent}}
```
### repeat
Defaults to string variables. When supplied with a number, it will repeat the input N
amount of times, where N is the supplied number.
```sh
{{#include ../../../tests/string_methods.ion:repeat}}
```
```txt
{{#include ../../../tests/string_methods.out:repeat}}
```
### replace
Defaults to string variables. Given a pattern to match, and a replacement to replace each match
with, a new string will be returned with all matches replaced.
```sh
{{#include ../../../tests/string_methods.ion:replace}}
```
```txt
{{#include ../../../tests/string_methods.out:replace}}
```
### replacen
Defaults to string variables. Equivalent to `replace`, but will only replace the first N amount
of matches.
```sh
{{#include ../../../tests/string_methods.ion:replacen}}
```
```txt
{{#include ../../../tests/string_methods.out:replacen}}
```
### regex\_replace
Defaults to string variables. Equivalent to `replace`, but the first argument will be treated
as a regex.
**PS:** By default, unicode support will be disabled to trim the size of Ion. Add the "unicode" flag to enable it.
```sh
{{#include ../../../tests/string_methods.ion:regex_replace}}
```
```txt
{{#include ../../../tests/string_methods.out:regex_replace}}
```
### reverse
Defaults to string variables. Simply returns the same string, but with each grapheme displayed
in reverse order.
```sh
{{#include ../../../tests/string_methods.ion:reverse}}
```
```txt
{{#include ../../../tests/string_methods.out:reverse}}
```
### to_lowercase
Defaults to string variables. All given strings have their characters converted to an
lowercase equivalent, if an lowercase equivalent exists.
```sh
{{#include ../../../tests/string_methods.ion:to_lowercase}}
```
```txt
{{#include ../../../tests/string_methods.out:to_lowercase}}
```
### to_uppercase
Defaults to string variables. All given strings have their characters converted to an
uppercase equivalent, if an uppercase equivalent exists.
```sh