add. This takes two parameters, adds them up, and returns the result.
So, you may write:
```arturo
print add 2 3
```
and Arturo will print out `5` for you.
Now, if you don't want to use the add function (and *prefix notation*, which is the standard for *all* function calls), there is a *symbol-alias* for that: `+`
So, you could just as well write:
```arturo
print 2 + 3
```
Only, this time you're expressing it more like you would in a normal math expression: with *infix notation*.
Here is the complete list of symbols recognized in Arturo, along with their predefined usage - if any:
| Symbol | Usage |
|---|---|
<= | alias of dup (prefix) |
=> | syntactic sugar |
<=> | alias of between? (infix) |
<<= | - |
=>> | - |
<<=>> | - |
<- | - |
-> | syntactic sugar |
<-> | - |
<<- | - |
->> | - |
<<->> | - |
-< | - |
>- | - |
>-< | - |
-<< | - |
>>- | - |
>>-<< | - |
<< | alias of read (prefix) |
>> | alias of write (infix) |
<<< | - |
>>> | - |
<-- | - |
--> | alias of convert (infix) |
<--> | - |
<== | - |
==> | - |
<==> | - |
<~ | - |
~> | - |
<~> | - |
|> | - |
<| | - |
<|> | - |
=< | alias of lessOrEqual? (infix) |
>= | alias of greaterOrEqual? (infix) |
<> | alias of notEqual? (infix) |
<: | - |
-: | - |
>: | - |
~ | alias of render (prefix) |
! | syntactic sugar |
!! | - |
? | alias of switch (infix) |
?? | alias of coalesce (infix) |
@ | alias of array (prefix) |
# | alias of dictionary (prefix) |
## | - |
### | - |
#### | - |
##### | - |
###### | - |
$ | alias of function (prefix) |
% | alias of mod (infix) |
^ | alias of pow (infix) |
& | - |
* | alias of mul (infix) |
** | - |
- | alias of sub (infix) |
-- | alias of remove (infix) |
= | alias of equal? (infix) |
== | - |
=~ | - |
+ | alias of add (infix) |
++ | alias of append (infix) |
< | alias of less? (infix) |
> | alias of greater? (infix) |
/ | alias of div (infix) |
/% | alias of divmod (infix) |
// | alias of fdiv (infix) |
\ | - |
\\ | - |
| | syntactic sugar |
|- | - |
|= | - |
.. | alias of range (infix) |
... | - |
./ | alias of relative (prefix) |
: | alias of let (infix) |
:: | syntactic sugar |
:= | alias of conforms? (infix) |
|| | - |
∅ | alias of null |
∞ | alias of infinite |
∑ | alias of sum (prefix) |
∏ | alias of product (prefix) |
∩ | alias of intersection (infix) |
∪ | alias of union (infix) |
⊂ | - |
⊃ | - |
⊆ | alias of subset? (infix) |
⊇ | alias of superset? (infix) |
∈ | alias of in? (infix) |
∉ | - |
∧ | alias of and? (infix) |
∨ | alias of or? (infix) |
⊻ | alias of xor? (infix) |
⊼ | alias of nand? (infix) |
¬ | alias of not? (prefix) |
split, to split a string into parts:
```arturo
split "hello world"
; => ["h" "e" "l" "l" "o" " " "w" "o" "r" "l" "d"]
```
That does what it says: splits the string into an array of strings.
What if we want to split the string into words? For that, there is the `.words` attribute for the function split. So:
```arturo
split.words "hello world"
; = ["hello" "world"]
```
> [!TIP] The order in which you pass the different attributes does not matter. Also, there is no issue at all whether you want to use spaces between them and the surrounding function call; Arturo will still be able to parse them and recognize them fine.
null, like:
```arturo
x: null
```
maybe value.
```arturo
x: true
y: false
z: maybe
```
to. Arturo comes with full support for complex numbers and all the associated operations.
```arturo
a: to :complex [1 2] ; a: 1.0+2.0i
b: to :complex @[pi pi] ; b: 3.141592653589793+3.141592653589793i
print a + b
; 4.141592653589793+5.141592653589793i
```
to. And again, Arturo comes with full support for rational numbers and all the associated operations.
```arturo
a: to :rational [1 2] ; 1/2
b: to :rational [3 4] ; 3/4
print a + b
; 5/4
```
define for that: e.g.
> ```arturo
> define :person [
> init: method [name :string][
> \name: name
> ]
> ]
> p: to :person ["John"]!
> print p\name ; John
> ```
render (or `~`) to process it accordingly: e.g.
> ```arturo
> x: 2
> print ~"my variable is: |x|"
>
> ; prints:
> ; my variable is: 2
> ```
range function (or its `..` infix equivalent):
```arturo
numbers: 1..10 ; contains all numbers from 1 to 10 (inclusive)
downwards: 10..1 ; this is valid as well
chars: 'a'..'z' ; yes, we can actually have character ranges too
```
Ranges can be used in most functions as-is, e.g. Iterators, where we can take full advantage of their "lazy" nature: they are not evaluated until needed.
However, you can still evaluate a lazy range into its corresponding block any time you want:
```arturo
@1..10 ; [1,2,3,4,5,6,7,8,9,10]
```
info takes as an argument the name of the function for which you want some information. If you wrote like `info print`, the interpreter would execute the function print and try to... print something (which would not be there). If you wanted to refer to the *name* of the function -- that is: without actually calling it -- you would precede it with a `'` (single-quote): `'[\w+]`
```arturo
func: 'print
info func
```
However, literals may be used for much more - e.g. modifying a passed parameter in-place, without having to re-assign the result of an operation to a new variable. To learn more, have a look at **[In-place variable modification](#in-place-variable-modification)**.
dictionary function (or use the `#` alias) a block with different labels, and it'll automatically convert it to a dictionary.
```arturo
user: #[
name: "John"
surname: "Doe"
age: 34
]
```
What the `#` function here does is:
- execute the block
- retrieve only the words/variables defined in there
- return a dictionary with the aforementioned words
> [!IMPORTANT] As you can probably assume from the above definition, a dictionary block doesn't necessarily have to contain just labels and word definitions - it may contain whatever you want, even function calls; only it will return you back just a table with the defined words in there.
to and a new custom type you have defined before:
```arturo
newClient: to :person ["John" "Doe"]!
; yep, we've just created a new Object value!
```
Technically, Objects are nothing but supercharged Dictionaries that come with a twist:
their functions (see: methods) can have access to their own fields and methods, *from within* - using `this`. But other than that, don't let them scare you: it's just another tool in our toolkit! ;-)
module function. Modules allow you to organize code and create isolated scopes with their own functions and variables.
By default, only methods marked with `.public` are accessible from outside the module. You can use export to make the module's public members available in the outer scope:
```arturo
ui: module [
; private method - not accessible outside
namedRule: method [title :string width :integer][
title: ~" |title| "
pad.center.with: '=' title width
]
; public method - accessible via export
section: method.public [title :string content :string width :integer][
~{
|\namedRule title width|
|content|
|\namedRule title width|
}
]
]
export ui!
print section "Hello" "World" 50
; ===================== Hello ======================
; World
; ===================== Hello ======================
```
Modules can also be initialized with parameters using `.with:`:
```arturo
ui: [
init: method [symbol :char][
\symbol: symbol
]
namedRule: method [title :string width :integer][
title: ~" |title| "
pad.center.with: \symbol title width
]
section: method.public [title :string content :string width :integer][
~{
|\namedRule title width|
|content|
|\namedRule title width|
}
]
]
export module.with: ['~'] ui!
print section "Example" "This is an example" 40
; ~~~~~~~~~~~~~~~ Example ~~~~~~~~~~~~~~~~
; This is an example
; ~~~~~~~~~~~~~~~ Example ~~~~~~~~~~~~~~~~
```
Modules are particularly useful for:
- Creating libraries and reusable code
- Encapsulating implementation details (private vs public methods)
- Avoiding naming conflicts
- Organizing larger programs
function... function (or use the `$` alias) followed by two parameters:
- the parameters' names (this can be either a literal, e.g. `'x` - if it's just one argument - or a block, e.g. `[x y]`. If you want to use commas for readability, like `[x,y]` you are free to do so: Arturo will simply ignore them.)
```arturo
multiply: function [x y][
x * y
]
print multiply 2 3
; would print 6
```
or
```arturo
addThemUp: $[x,y][x+y]
print addThemUp 2 3
; would print 5
```
define) or in a module context
- We'd use them only when we want to have access to `this` (= in a few words, when we want to access other fields/functions/methods of the same object; if we don't need that, we could still use a function)
A quick example:
```arturo
define :car [
init: method [; our constructor
brand :string
speed :quantity
][
this\brand: brand
this\speed: speed
]
distanceTravelled: method [inHours :quantity][
this\speed * inHours
]
]
myCar: to :car ["Volvo" 100`km/h]!
print ["In 2 hours, we'll have travelled:" myCar\distanceTravelled 2`h]
```
We may also have *magic methods*, that is: making our custom types accessible-to or "overloading" normal stdlib methods.
For example, if we want to be able to print one of our custom objects, we'd first have to define a way that this custom object is meant to be converted to a string.
For that, we'd define a `string` magic method:
```arturo
define :car [
; as previously
string: method [][
return "CAR :: " ++ \name
]
]
myCar: to :car ["Volvo C30" 100`km/h]!
print myCar ; this would print: CAR :: Volvo C30
```
**Supported Magic methods:**
```
get: method [what] ; this\what
set: method [what, value] ; this\what: value
changing: method [] ; object about to change
changed: method [] ; object changed
compare: method [that] ; comparator definition (to compare between `this` and a second object)
equal?: method [that] ; this = that
less?: method [that] ; this < that
greater?: method [that] ; this > that
add: method [that] ; this + that
sub: method [that] ; this - that
mul: method [that] ; this * that
div: method [that] ; this / that
fdiv: method [that] ; this // that
mod: method [that] ; this % that
pow: method [that] ; this ^ that
inc: method [] ; inc this
dec: method [] ; dec this
neg: method [] ; neg this
key?: method [key] ; key? this key
contains?: method [field] ; contains? this field
append: method [what] ; this ++ what
remove: method [what] ; this -- what
string: method [] ; to :string this
integer: method [] ; to :integer this
floating: method [] ; to :floating this
rational: method [] ; to :rational this
complex: method [] ; to :complex this
quantity: method [] ; to :quantity this
logical: method [] ; to :logical this
block: method [] ; to :block this
dictionary: method [] ; to :dictionary this
```
now returns a `:date` object, representing the current point in time. And it can be handled pretty much like you would handle a `:dictionary`.
```arturo
print now
; would print 2020-10-26T10:27:14+01:00
print now\year
; would print 2020
```
open, you can create a database value and then use it to query the database in question and much more.
```arturo
db: open.sqlite "my.db"
print query db "SELECT * FROM users"
print type db ; would print: :database
```
listen:
```arturo
; start a server listening on port 18966
server: listen 18966 ; and, yes, that's a socket!
```
to.
```arturo
; let's create some Arturo bytecode from scratch
bcode: to :bytecode [
loop 1..10 'x [
print x
]
]
; and execute it!
do bcode
; we can also inspect it
inspect bcode
; [ :bytecode
; ================================
; DATA
; ================================
; 0: [ :block
; print :word
; x :word
; ]
; 1: x :literal
;
; ================================
; CODE
; ================================
; push0
; eol #4
; push1
; consti10
; consti1
; range
; loop
; end
; ]
```
throw function or caught during error handling:
```arturo
; Errors are typically caught when operations fail
result: try [
; some operation that might fail
]
if error? result [
print ["An error occurred:" result]
]
```
Error values contain information about what went wrong and can be inspected to handle different error conditions appropriately.
print function and then the second one. Nothing new here.
Now let's take the first print. How is it working?
Let's see:
- First, the value `2` is pushed onto the stack
- Then, we push the value `1`
- Then, we execute the function add: it pops two values from the stack, adds them up, and pushes the result (`3`) back onto the stack
- Finally, we execute the function print: it pops the top value from the stack (`3`) and prints it.
Then, execution would move on and... `print "Done."`
What you have to understand here is that evaluation within an expression will *always* be done from right to left, irrespective of what you might know from other languages or math operator precedence. In Arturo, you have to learn no precedence rules at all. You'll just have to remember to always calculate from right to left.
Re-visiting our previous, seemingly paradoxical, example:
```arturo
2 * 3 + 4
```
> [!IMPORTANT] Remember: our `+` and `*` operators are nothing but simple *infix* aliases to the functions add and mul respectively -- nothing more!
This is as if we had written (moving the operators in front):
```arturo
* 2 + 3 4
```
which practically means: FIRST add 3 and 4 and THEN take the result and multiply it with 2.
If this is not what you intended, then the right way in Arturo would be, either:
```arturo
4 + 2 * 3
```
or (giving precedence to the multiplication, artificially, using parentheses):
```arturo
(2 * 3) + 4
```
**Another example:**
Let's say we want to concatenate a number and a string into a new string.
```arturo
to :string 3 ++ " <-- this is our number"
```
The above example wouldn't work, because first it tries to concatenate `3` with a string (`" <-- this is our number"`) and *then* performs `to :string`.
While what we actually want is to *first* convert our number to a string and *then* concatenate the two strings.
The correct code in that case would be:
```arturo
(to :string 3) ++ " <-- this is our number"
```
loop, map, etc) always work with a block as well. But in a special way.
Basically, the logic is identical to that of blocks, but with a slight difference:
- the *injected* variables (e.g. the iteration arguments), are available only inside the block, but not after the iteration is over
- any previous value is "protected" and restored if needed
```arturo
x: 3
loop.with:'i ["one" "two" "three"] 'x [
print i ; prints 0, 1, 2,...
print x ; prints "one", "two", "three",...
]
print x ; prints 3 (the value of x has been restored)
print i ; ERROR: variable not found
; (i is not available anymore)
```
set on it, in which case it does alter its inner structure).
So, basically, when you do this...
```arturo
a: [1 5 2 4 3]
sort a
```
...all you do is to take an array, sort it, and push the sorted array onto the stack. Variable `a` simply does not change.
So, what would you do if you wanted to get the array back, but sorted?
The simple - and most obvious - way would be to re-assign the returned result from sort:
```arturo
a: [1 5 2 4 3]
a: sort a
```
And now, yes, `a` does contain the sorted version of the initial array.
But what if you want to perform the modification in-place, which is normally faster and without the need for intermediate variables? Literals come to the rescue!
sort is:
```arturo
sort collection :literal :dictionary :block
```
As we can see, sort takes one parameter (*collection*) which is either a `:dictionary` or `:block` OR a `:literal`.
Why pass a literal? Simply because this turns in-place modification on! Let's have a look:
```arturo
a: [1 5 2 4 3]
sort 'a ; yep, now a *has* been sorted in-place!
```
And this is *very powerful*: in Arturo, most of the built-in functions in the library come with this feature included. Practically, whenever you see a function taking a literal first parameter, that means you can use it for in-place modifying a variable (yes, even add works like that!).
> ⚠️ **Word of caution:**
> Values in Arturo are always passed by reference - unless they are constant/readonly values. So if you want to assign one variable to another and then modify one of them in-place, make sure you use new; otherwise, both values will change!
>
> ```arturo
> a: 1
> b: a
> inc 'a ; both a and b are now 2
>
> c: 1
> d: new c ; we copy the value of c into d
> inc 'c ; now c is 2 and d is 1, as expected
> ```
do block (more or less).
Or the shorter version:
- Have you just created a new custom-type object? (e.g. `to :myObject []`)?
- Have you imported an external package? (e.g. `import 'somePackage`)?
Then just put `!` at the end of the statement (e.g. `import 'somePackage!`) and everything will work as you expect.
**The long explanation:**
Arturo, when parsing a block of code, has to know which symbols correspond to function calls and how many arguments they take. The exact same is valid for object methods.
When we create a new object (e.g. `p: to :person ["John"]`), if we attempt to use `p\someMethod` from the exact same block where this `p` value was initialized, there is no possible way to know beforehand that e.g. `someMethod` is a method. We'll know that only *after* `to :person ["John"]` has been executed. But then, it's already too late. So, how do we make sure that Arturo knows about the object before we attempt to call inner methods? By putting a "stopper" after the object creation, and that stopper is our beloved... `!`.
> [!NOTE] Technically we could achieve the same thing without the `!` sugar:
> ```arturo
> p: to :person ["John"]
> do [
> p\sayHello
> ]
> ```
> That would work too, for all practical purposes. But: `!` is looking good. And it's also far more performant, based on the way it's implemented internally! ;-)
The time is: <||= now ||>
} ] GET "/post/(?This is some content
```