There are two forms of methods within Ion: array methods, and string methods. 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 @ sigil, then it is an array method. Example as follows:

echo $method_name(variable)
for elem in @method_name(variable); echo $elem; end

Methods are executed at the same time as other expansions, so this leads to a performance optimization when combining methods with other methods or expansions. Ion includes a number of these methods for common use cases, but it is possible to create and/or install new methods to enhance the functionality of Ion. Just ensure that systems executing your Ion scripts that require those plugins are equipped with and have those plugins enabled. If you have ideas for useful methods that would be worth including in Ion by default, feel free to open a feature request to discuss the idea.

So we heard that you like methods, so we put methods in your methods. Ion methods accept taking expressions as their arguments -- both for the input parameter, and any supplied arguments to control the behavior of the method.

echo $method($(cmd...) arg)

let string_var = "value in variable"
echo $method(string_var)

echo $method("actual value" arg)

Some methods may also perform different actions when supplied a different type. The $len() method, for example, will report the number of graphemes within a string, or the number of elements within an array. Ion is able to determine which of the two were provided based on the first character in the expression. Quoted expressions, and expressions with start with $, are strings; whereas expressions that start with either [ or @ are treated as arrays.

echo $len("a string")
echo $len([1 2 3 4 5])

Some methods may have their behavior tweaked by supplying some additional arguments. The @split() method, for example, may be optionally supplied a pattern for splitting. At the moment, a comma is used to specify that arguments are to follow the input, but each argument supplied after that is space-delimited.

for elem in @split("some space-delimited values"); echo $elem; end
for elem in @split("some, comma-separated, values" ", "); echo $elem; end

The following are the currently-supported string methods:

• ends_with
• contains
• starts_with
• basename
• extension
• filename
• join
• find
• len
• len_bytes
• parent
• repeat
• replace
• replacen
• regex_replace
• reverse
• to_lowercase
• to_uppercase
• escape
• unescape

Defaults to string variables. When supplied with a pattern, it will return one if the string ends with it. Zero otherwise.

echo $ends_with("FOOBAR" "BAR")
echo $ends_with("FOOBAR" "FOO")

1
0

Defaults to string variables. When supplied with a pattern, it will return one if the string contains with it. Zero otherwise.

echo $contains("FOOBAR" "OOB")
echo $contains("FOOBAR" "foo")

1
0

Defaults to string variables. When supplied with a pattern, it will return one if the string starts with it. Zero otherwise.

echo $starts_with("FOOBAR" "FOO")
echo $starts_with("FOOBAR" "BAR")

1
0

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

echo $basename("/parent/filename.ext")

filename.ext

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.

echo $extension("/parent/filename.ext")

ext

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.

echo $filename("/parent/filename.ext")

filename

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.

let array = [1 2 3 4 5]
echo $join(array)
echo $join(array ", ")

1 2 3 4 5
1, 2, 3, 4, 5

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.

echo $find("FOOBAR" "OB")
echo $find("FOOBAR" "ob")

2
-1

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.

echo $len("foobar")
echo $len("❤️")
echo $len([one two three four])

6
1
4

Defaults to string variables. Similar to the len method, but counts the number of actual bytes in the output, not the number of graphemes.

echo $len_bytes("foobar")
echo $len_bytes("❤️")

6
6

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

echo $parent("/root/parent/filename.ext")

/root/parent

Defaults to string variables. When supplied with a number, it will repeat the input N amount of times, where N is the supplied number.

echo $repeat("abc, " 3)

abc, abc, abc, 

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.

let input = "one two one two"
echo $replace(input, one 1)
echo $replace($replace(input one 1) two 2)

1 two 1 two
1 2 1 2

Defaults to string variables. Equivalent to replace, but will only replace the first N amount of matches.

let input = "one two one two"
echo $replacen(input "one" "three" 1)
echo $replacen(input "two" "three" 2)

three two one two
one three one three

Defaults to string variables. Equivalent to replace, but the first argument will be treated as a regex.

echo $regex_replace("FOOBAR" "^F" "f")
echo $regex_replace("FOOBAR" "^f" "F")

fOOBAR
FOOBAR

Defaults to string variables. Simply returns the same string, but with each grapheme displayed in reverse order.

echo $reverse("foobar")

raboof

Defaults to string variables. All given strings have their characters converted to an lowercase equivalent, if an lowercase equivalent exists.

echo $to_lowercase("FOOBAR")

foobar

Defaults to string variables. All given strings have their characters converted to an uppercase equivalent, if an uppercase equivalent exists.

echo $to_uppercase("foobar")

FOOBAR

Defaults to string variables. Escapes the content of the string.

let line = " Mary   had\ta little  \n\t lamb\t"
echo $escape($line)

 Mary   had\\ta little  \\n\\t lamb\\t

Defaults to string variables. Unescapes the content of the string.

let line = " Mary   had\ta little  \n\t lamb\t"
echo $unescape($line)

 Mary   had	a little  
     lamb

The following are the currently-supported array methods.

• lines
• split
• split_at
• bytes
• chars
• graphemes
• reverse

Defaults to string variables. The supplied string will be split into one string per line in the input argument.

for line in @lines($unescape("first\nsecond\nthird")
    echo $line
end

first
second
third

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.

for data in @split("person, age, some data" ", ")
    echo $data
end

for data in @split("person age data")
    echo $data
end

person
age
some data
person
age
data

Defaults to string variables. The supplied string will be split in two pieces, from the index specified in the second argument.

echo @split_at("FOOBAR" "3")
echo @split_at("FOOBAR")
echo @split_at("FOOBAR" "-1")
echo @split_at("FOOBAR" "8")

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

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.

echo @bytes("foobar")

102 111 111 98 97 114

Defaults to string variables. Returns an array where the given input string is split by chars.

for char in @chars("foobar")
    echo $char
end

f
o
o
b
a
r

Defaults to string variables. Returns an array where the given input string is split by graphemes.

for grapheme in @graphemes("foobar")
    echo $grapheme
end

f
o
o
b
a
r

Defaults to array variables. Returns a reversed copy of the input array.

echo @reverse([1 2 3])

3 2 1