Arturo Programming language

Language overview

Arturo is a very simple language. Even without any prior experience, I estimate it would take you roughly half an hour before you are comfortable enough to write your first program.

Here, you'll find everything you may need to know about the language (and perhaps a bit more). In a single page.

Introduction
The basics
- Words
- Labels
- Symbols
- Attributes
  - :attribute
  - :attributeLabel
- More values
  - :null
  - :logical
  - :integer
  - :floating
  - :complex
  - :rational
  - :version
  - :type
  - :char
  - :string
  - :range
  - :regex
  - :path
  - :pathLabel
  - :literal
  - :symbolLiteral
  - :pathLiteral
  - :inline
  - :block
  - :dictionary
  - :store
  - :object
  - :function
  - :method
  - :unit
  - :quantity
  - :color
  - :date
  - :database
  - :socket
  - :binary
  - :bytecode
Important concepts
Syntactic sugar
Conclusion

Introduction

Arturo's syntax is probably as easy as it could get. Basically, you could say: there is no syntax.

Let's try to resume some key points of Arturo's no-syntax:

Code is just a list of words, labels, symbols, values and attributes (you'll learn what all this is about very soon!)
Code can be grouped into blocks (that is: a list of words, labels, symbols, and values within square brackets: [ ... ]
A block has no meaning until it is given one, or interpreted within some specific context, that is: [ lorem ipsum ] is perfectly valid Arturo code, until you try to "run" it - where the interpreter will complain that it has no idea what lorem and ipsum is. Pretty much like if I tell you a word in Swahili - you'll most likely need a dictionary to figure out what it might mean.
There are no reserved "keywords". Every word can be re-defined.
You can format your code any way you want: no semicolons to add, no obligatory newlines, no commas, no parentheses, no Python-style indentation rules
Every function expects a pre-determined number of arguments. Initially, we check during evaluation, and during runtime, we "consume" values until we reach the number of arguments required.

As you can see, there is not much to learn from scratch here:

Once you learn what the language building blocks are & a few details about precedence and evaluation, then only with the Library Reference at hand (the built-in functions that are already there for you, available to use), you're pretty much ready to write any program. ;-)

So, let's get to the gist of the matter!

The basics

Words

Words in Arturo are pretty much like words in English: a series of characters separated by spaces or some symbol. E.g.: this is a series of words (in this case, this, is, a, series, of, words are all - well... - words.

💡 In Arturo, a word can be start with any letter or underscore followed by any letter/numbers/underscore or a question mark (?).

As with a real (spoken) language, every word has a specific meaning. And if you don't know the meaning of a word, you'll have to look it up in the dictionary. That's pretty much the way things work in Arturo as well.

In Arturo, a word may have 3 main different uses:

refer to a value (that is: a variable, e.g. x + 2)
refer to an action, which does something (that is: a function, e.g. doSomething) - Arturo comes with hundreds already defined in its standard library
refer to nothing (that is: a word without meaning, as in the [lorem ipsum] example above)

Labels

A label is nothing but Arturo's way of assigning meaning (to be read as a value) to a word - what you would normally call variable assignment or variable initialization. (In Arturo, these two terms can be used invariably, since there is practically no difference: you can set and re-define a word/variable as many times as you wish).

So, let's say you want to give a new meaning to the word x:

x: 2

That was it: from now on, x will mean 2 (until and if it's changed). So if you follow the above statement with:

print x

...Arturo will print 2 for you.

Symbols

As the mere word says, symbols are used to symbolize something, mainly as an alias to an existing word - although, by convention, as infix operators.

Hence, let's take the function add. This takes two parameters, adds them up, and returns the result.

So, you may write:

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:

print 2 + 3

Only, this time you're expressing it more like you would in a normal math expression: with infix notation.

Some of the existing aliases in the built-in dictionary:

%ALIAS_LIST%

Symbol	Aliased word

All valid symbols:

<=, =>, <=>, <<=, =>>, <<=>>, <-, ->, <->, <<-, ->>, <<->>, -<, >-, >-<, -<<, >>-, >>-<<, <<, >>, <<<, >>>, <--, -->, <-->, <==, ==>, <==>, <~, ~>, <~>, |>, <|, <|>, =<, >=, <>, <:, -:, >:, ~, !, !!, ?, ??, @, #, ##, ###, ####, #####, ######, $, %, ^, &, *, **, -, --, =, ==, =~, +, ++, <, >, /, /%, //, \\, \\\\, |, |-, |=, .., ..., ./, :, ::, :=, ||, ∅, ∞, ∑, ∏, ∩, ∪, ⊂, ⊃, ⊆, ⊇, ∈, ∉, ∧, ∨, ⊻, ⊼, ¬

Attributes

Another interesting feature of Arturo is what we'll analyze here: attributes.

Technically, attributes are nothing but an easy way of defining optional named parameters for functions - but which can however transcend between different function calls.

There are two types:

a. attributes
b. attribute labels

:attribute

Attributes are actually optional on/off-type of values, set during a function call, that is there to denote some variation of the initial meaning of the function. To define an attribute, we'll be using a .(dot) followed by a normal word: \.\w+

Let's say we used the function split, to split a string into parts:

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 :chars.

What if we want for example to split the string into words? For that, there is the .words attribute for the function split. So:

split.words "hello world"

; = ["hello" "world"]

💡 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

:attributeLabel

Attribute labels are pretty much like simple attributes, only they can also take a value. As it worked with attributes, we'll be using a .(dot) followed by a normal word, but now also followed by a :(colon) -- exactly like with normal labels, as we've seen above.

Here's an example:

split .every: 2 "hello world"

; => ["he" "ll" "ow" "or" "ld"]

More Values

Values are the very core of Arturo and are used to refer to pretty much all the different kinds of data you can have.

💡 Words, labels, and symbols - that we already saw above - can be considered "values" as well; and treated as such, unless we proceed to evaluate them!

We could split values into 2 categories: a) literal values - that is values you can directly define in your code and b) constructible - values that are created using some function.

The (hopefully) complete list follows.

:null

Null values generally denote nothing and it's mostly used as a return value by functions to inform us that something went wrong. If you want to set it as a value, you may just use the word null, like:

x: null

:logical

Logicals are Arturo's logical values. They are like normal boolean values (true, false), with a twist: they fully support ternary logic and an additional maybe value.

x: true
y: false
z: maybe

:integer

Integers represent positive or negative integers. When they are declared they are comprised only by digits ([0-9]+) and they can be as long as you want - Arturo does support big numbers.

x: 2
y: 876528347613438247982374913423423947329

:floating

Floating values are basically floating-point numbers, that is: decimals. They begin with an initial all-digit part, followed by a . (dot) and another all-digit part: [0-9]+\.[0-9]+

pi: 3.14159

:complex

Even though there is no special syntax for defining a complex number, you can always create one using to. Arturo comes with full support for complex numbers and all the associated operations.

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

:rational

The syntax for rational literals is simply a number followed by a colon, followed by a number (pretty much like you would normally represent a ratio).

a: 1:2                   ; 1/2
b: 3:4                   ; 3/4

As with complex numbers, rationals can also be defined using to. And again, Arturo comes with full support for rational numbers and all the associated operations.

a: to :rational [1 2]     ; 1/2
b: to :rational [3 4]     ; 3/4

print a + b 
; 5/4

:version

Version values are nothing but a fancy and portable way of defining SemVer-compliant versions (e.g. for packaging an application). The rule is rather simple: it has three numeric parts, separated by a . (dot) and an optional part with build or prerelease information.

package: 1.0.3

if package > 1.0.0 -> print "yep, the version is right!"

version: 1.2.3-rc1+build123

:type

Type is a value representing another... type. To specify a type value, the format is a : (colon) followed by a word - the type's name: :\w+

myType: :integer

if (type x) = :integer [ print "it's an integer!" ]

💡 If you want to define your own custom types (think "classes" in OOP languages), we have define for that: e.g.
define :person [
   init: method [name :string][
       \name: name 
   ]
]
p: to :person ["John"]!
print p\name ; John

:char

Characters in Arturo can be declared using single quotes: '\w'

ch: 'a'

:string

A string is nothing but a series of characters, seen as one unit. In Arturo, to define a string, there are various ways:

Single-line strings

using double quotes: x: "this is a string" (with escaped characters)
using right smart-quote notation x: « This is a string (in this case, everything following « till the end of the line, will be stripped and considered one string)

Multi-line strings

using curly-brace blocks (the result will be stripped and un-indented):

x: {
    this is yet
    another
    very
    long string
    that spans more
    than
    one
    line
}

using verbatim curly-brace blocks (the result will remain exactly as-is):

x: {:
  this is yet
    another
    very
  long string
  that spans more
      than
          one
          line
:}

using dash notation (where everything after the line, until the end of the file, is a string - stripped and un-indented):
```
x: 
------
this is the last very
long string
that spans more
than
one
line
```

💡 If you want your string to contain sub-expressions that will be evaluated on the fly - that is string interpolation - all you have to do is include your code inside the string within pipe-bars and then call the function render (or ~) to process it accordingly: e.g.
x: 2
print ~"my variable is: |x|"

; prints: 
; my variable is: 2

:range

Arturo comes with full support of lazy ranges.

To create a range all you have to do is use the built-in range function (or its .. infix equivalent):

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:

@1..10 ; [1,2,3,4,5,6,7,8,9,10]

:regex

A regex value is nothing but a string containing a regular expression (that is then compiled and treated as such).

The normal syntax is {/regex/}:

type {/[A-Z]/}                    ; => :regex

replace "HelLo" {/[A-Z]/} "X"     ; here we replace all capital letters
                                  ; with an X

While we may - optionally - use any of the supported PCRE-compliant flags:

i: case-insensitive matching
m: multiline
s: dot-all

match "Hello" {/he/i}             ; => ["He"]

:path

Paths in Arturo are a way of defining some hierarchy between values, something along the lines of parent -> child -> grandchild. For this, in Arturo, we'd use a series of values or words delimited with a \ (backslash). You can think of them as indexes in other programming languages.

print user\name

x: "name"
print user\[x]

myArray: ["zero" "one" "two" "three"]
print myArray\1

; prints "one"

:pathLabel

If paths are the way of defining some hierarchy between values, with pathLabels we are also able to assign values to some specific path.

user: #[
    name: "John"
    surname: "Doe"
]
print user\name  ; will print "John"

; let's change this user's name
user\name: "Jane"

; we can also do it like that
x: "name"
user\[x]: "Jane"

print user\name ; ok, now it should print "Jane"

💡 If you we are inside a custom type, an easy way to refer to fields of the same object is using this. However, Arturo comes with a shortcut: e.g.
define :person [
   init: constructor [name :string]
   sayHello: method [][
       print ["Hello" \name] ; this is equivalent to `this\name`
   ]
]
which generally helps us write more better-looking code. :)

:literal

Literals in Arturo are just a way of referring to the name of a word or symbol. Think of it as the string version of a word, or like Ruby's symbols.

For example, the function 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+]

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.

:symbolLiteral

Symbol literals are to symbols pretty much what literals are to words. That is: the "literal", unevaluated form of the symbol.

To declare a symbol literal, we may follow the example of normal, literals: single quote + accompanied by the symbol in question:

type '++        ; => :symbolliteral

:pathLiteral

Now, that we've seen both "normal" literals and paths, I guess you can already imagine what Path Literals are about... :)

And, yes, you guessed right:

type 'this\is\a\path  ; => :pathliteral

:inline

Inlines in Arturo generally denote a list of words/symbols/values that are grouped and given some type of priority in evaluation. An inline block is denoted by (...) (parentheses).

print (2+3)*4

Please note though that, apart from precedence, :inline is a value type on its own:

a: [(one) two three]
print type a\0      ; that is: (one)

; prints :inline

:block

Blocks are a fundamental part of Arturo.

As we've already said, it's just a [...] (square-bracket enclosed) block of words/symbols/values that - in contrast with inline blocks above which are evaluated in-place - are not evaluated until it's necessary.

myBlock: [one two three]
anArray: [1 2 3 4 5]
anotherArray: ["zero" 1 "two" 3 "cuatro"]

As you can see, blocks can contain practically anything: any word, any symbol, and any value. Of course, they can contain other blocks too:

:dictionary

Dictionaries in Arturo as what in other languages you'd call an associative array or hash table. In Arturo, it's practically the same, only with an added twist: they are ordered hash tables. If you want to create one, just give the dictionary function (or use the # alias) a block, with different labels, and it'll automatically convert it to a dictionary.

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

💡 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

:store

Now, that you've seen Dictionaries, imagine a dictionary that could actually save its contents to disk for every change you make to it. Or retrieve it from disk when you start your program again, offering you seamless integration with your data. And safety too.

Well, that's exactly what Stores are. :)

d: store "mystore" ; initialize your Store and 
                   ; specify where you want to store it 
                   ; (if the store already exists, it'll automatically load it)

d\name: "John"     ; and you can use it as any normal dictionary

:object

Object values are intimately related to custom types, as we have already seen above.

And while Arturo isn't properly speaking a primarily Object-oriented language, it offers more than enough functionality that will cover most OOP needs.

The normal way to create a new object, is by using to and a new custom type you have defined before:

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 its own fields and methods, from within - using this. But other than that, don't let them scare you out: it's just another tool in our toolkit! ;-)

:function

Functions are another important value type in Arturo - and yes, you heard right: functions a value too. You can assign them to a word/variable, pass them around, re-define them and whatever you want with them, pretty much as you would do with another value, let's say a number.

To define a function, all you have to do is call the 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.

multiply: function [x y][
     x * y
]

print multiply 2 3

; would print 6

addThemUp: $[x,y][x+y]

print addThemUp 2 3

; would print 5

:method

Methods in Arturo are pretty much like functions. With a couple of asterisks:

They are meant to be used only inside a custom type (in 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:

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:

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

:unit

Arturo has very advanced capabilities related to physical quantities, measurements and the related operations.

And everything begins with the concept of units.

To declare a Unit value, all you have to do is use a backtick, followed by the unit in question:

Meters: `m 
SquareMeters: `m2
Becquerels: `Bq

The list of builtin, supported Units is quite... long:

m, s, K, g, A, mol, cd, USD, B, rad, sr, in, ft, yd, ftm, rod, mi, fur, nmi, ang, au, ly, px, pt, pc, sqin, sqft, ac, are, ha, barn, L, gal, bbl, qt, p, cup, floz, tbsp, tsp, bu, cord, min, h, day, wk, mo, yr, lb, slug, oz, ct, t, ton, lt, st, Da, gr, dwt, ozt, lbt, mps, kph, mph, kn, fps, mach, Gal, N, dyn, lbf, kgf, pdl, Pa, atm, bar, pz, Ba, mmHg, psi, Torr, J, Wh, cal, BTU, eV, erg, th, thm, W, hp, statA, abA, Bi, V, statV, abV, Ohm, statOhm, abOhm, S, C, statC, abC, Fr, F, Daraf, H, abH, Wb, Mx, T, G, degC, degF, degR, b, KiB, MiB, GiB, TiB, PiB, EiB, deg, grad, arcmin, arcsec, kat, Hz, Bq, Ci, Gy, Sv, R, P, St, rpm, clo, bps, lx, Lb, lm

We also support most world currencies, with their ISO 3-letter code, e.g. USD, EUR, etc.

Compound units:

If you want to define compound units, Arturo actually supports that natively:

squareMeters: `m2
kilometersPerHours: `km/h

newtonDefinition: `kg.m/s2    ; yes, that's actually a N(ewton)

:quantity

Now, as we've seen, Arturo's Unit values are quite powerful. So, how can we express a Quantity using units?

Very simple: just add a number (a Rational literal works too) just in front of a unit:

twoMeters: 2`m    ; yes, we've just expressed the notion of "2 meters"
                  ; as a native Arturo value

And we can obviously use them in operations as every other value:

print 3`m + 4`yd    ; 6.6576 m

And, yes, no need to worry about compatibility: Arturo actually understands dimensional analysis! ;-)

:color

Colors can be easily defined using the #xxxxxx syntax, where xxxxxx is either the RGB value of the color in hex, or its common-name alias, like #red, #green or #blue:

color1: #red
color2: #0077BB

print color1 + color2

:date

Dates in Arturo are a distinct type of value. If you want to create one, you'll have to use one of the corresponding functions. For example, the function now returns a :date object, representing the current point in time. And it can be handled pretty much like you would handle a :dictionary.

print now

; would print 2020-10-26T10:27:14+01:00

print now\year

; would print 2020

:database

Database values cannot be constructed literally. However, using the function open, you can create a database value and then use it to query the database in question and much more.

db: open.sqlite "my.db"

print query db "SELECT * FROM users"

print type db   ; would print: :database

:socket

Another not-literally constructible (but still powerful) value type is the Socket.

To use Socket values properly, just have a look into the Sockets library module.

If you want to create one, just have a look at the quick example below, using listen:

; start a server listening on port 18966
server: listen 18966    ; and, yes, that's a socket!

:binary

Binary values are used to represent binary data, that is: an array of bytes. You cannot define them directly, however, you can sure convert other data to binary.

print to :binary "Hello world!"

; would print 4865 6C6C 6F20 776F 726C 6421

:bytecode

Bytecode values cannot be constructed literally. However, you can create them indirectly, e.g. using the function to.

; 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
; ]

Important concepts

Here we are going to analyze a few aspects that make Arturo rather unique; or that - in any case - you should study a bit more in order to become a real... Arturo guru, in no time.

So, let's get started...

Precedence and Evaluation

The easiest way to explain precedence rules in Arturo is pretty much like it happened with our introduction: there are no precedence rules whatsoever.

So, in an expression like 2 * 3 + 4, if you'd normally expect to get a result of 10, you would be wrong: the result is 14.

But in order to understand why, you'd have to understand how evaluation in Arturo works.

The right-to-left rule

The main expression evaluation order of Arturo is right-to-left. But with a tiny asterisk: Your code will be evaluated from left to right, it is the expressions passed to your function calls that will be evaluated from right-to-left.

Let's take a very simple example:

print add 1 2 
print "Done"

As you would expect, the first function to be executed is the first 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:

2 * 3 + 4

💡 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):

* 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 intended, then the right way in Arturo would be, either:

4 + 2 * 3

or (giving precedence to the multiplication, artificially, using parentheses):

(2 * 3) + 4

Another example:

Let's say we want to concatenate a number and a string into a new string.

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:

(to :string 3) ++ " <-- this is our number"

Scope and rules

Contrary to what you might expect, Arturo doesn't feature a traditional concept of scope. There are no real local or global variables, no local or global functions, no local or global blocks, no local or global anything.

Generally, if a variable has been previously declared at the moment and location of its usage, then it is available. Otherwise, it is not.

But let's see a couple of concrete cases to make this clearer.

Blocks

Arturo doesn't have a block scope.

In a few words, this means:

A variable declared inside a block is available outside of it
A variable previously declared outside of a block is available inside
The changes of an existing variable, inside a block, persist after the block

x: 1    ; here, we declare a variable x
        ; and set it to 1
do [
    x: 2      ; here, we re-assign the value of x
              ; to 2
    print x   ; prints 2
    y: 3      ; here, we declare a variable y
              ; and set it to 3
]
print x     ; prints 2 (the value of x has been changed)
print y     ; prints 3 (the value of y is still available)

Iterators

Iterators (such as loop, map, etc) always work with a block as well. But in a special way.

Basically, the logic is identical to the one 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

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)

Functions

Functions are totally different. Why? Because they do have their own scope.

The general idea is:

A variable declared inside a function is available only inside the function
A variable previously declared outside of a function is available inside
The changes of an existing variable, inside a function, do not persist after the function

If we want to export a specific symbol to the outer scope, that is, make it available outside the function, we can use the .export: attribute.

If we want to export all of the symbols - thus, practically making the function scope-less, we may use the .inline attribute.

In-place variable modification

In Arturo, every time you pass a parameter to a function, you can rest assured that the value of that parameter won't change (unless it's a string, block or dictionary and you - consciously - decided to use set on it, in which case it does alter its inner structure).

So, basically, you when do this...

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:

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!

Using literals

As we've already said, "literals" ('i 'am 'a 'literal) are nothing but string representations of a word, that is... the word itself. For that reason, they may come in very handy when you want to modify a variable in-place.

Let's revisit the above example and what the syntax of sort is:

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:

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!
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

Syntactic sugar

As you have hopefully seen so far, Arturo is rather simple, with fairly simple rules and that's pretty much it.

However, we also have some "syntactic sugar": a fancy way of referring to syntactic constructs, so that something more complicated will look better, or easier-to-write, or more readable.

Here you'll learn about some useful examples of syntactic sugar supported in Arturo.

Right-arrow operator: `->`

The function of the right operator is rather straightforward: basically, it wraps the following terminal value inside a block.

Let's take a simple example.

x: -> 2

This is 100% equivalent to:

x: [2]

You can also use the right-arrow operator to make many common constructs far more readable.

For example:

if x=2 -> print "x was 2!"

is the same as writing:

if x=2 [ print "x was 2!" ]

As you can see, it can be pretty handy. Just remember that -> can wrap only one terminal value.

For example:

x: -> 2 3

This doesn't result in x: [2 3] but in x: [2] 3

Another interesting way of making use of the power of the right-arrow operator:

loop 1..10 'x -> print x

which is the same as writing (only much more elegant):

loop 1..10 'x [ print x ]

Fat right-arrow operator: `=>`

The fat right-arrow operator is like a super-charged simple right arrow operator (->) as described above.

If -> was used to wrap the following terminal into a block, the => operator does even more.

Let's take this simple example:

x: $ => add

This is equivalent to writing:

x: $[x,y][add x y]

Basically, it reads the following word, and if it's a function, pushes all its needed arguments as anonymous variables.

The same could work with a block argument, where & can be used as a placeholder for the needed anonymous variables:

x: $ => [add & &]

(The first & will pop the first argument, and the second the next one - and so on...)

As you can already imagine, this is perfect for easily defining functions or action blocks that take exactly one parameter.

For example, to print an array of the even numbers between 1 and 10:

print select 1..10 'x [even? x]

This could be easily written as (using the -> operator):

print select 1..10 'x -> even? x

But pushing the limits more, we can also use the => operator:

print select 1..10 => even?

That's surely much more readable, isn't it?

Double-colon operator: `::`

The double-colon operator does something very simple: it wraps everything in a block - until the end of... the current block:

do [
    print :: 
        "This is a number:"
        123
]

Is equivalent to:

do [
    print ["This is a number:" 123]
]

Exclamation-mark operator: `!`

Explaining the exclamation-mark can be a bit tricky, but if you want the short version: it wraps everything that follows in a 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... !.

💡 Technically we could achieve the same thing without the ! sugar:
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! ;-)

Pipe operator: `|`

⚠️ This is experimental and may still not be stable enough for use in production scripts

The pipe operator is an easy way of reversing the default prefix notation of function calls and simulating what in OOP languages is called function chain.

Let's take this simple example:

1..10 | print

This equivalent to:

print 1..10

Or a bit more elaborate example (using pipes and the ->/=> operators):

1..10 | map => [2 * &]
      | select 'x -> even? x
      | print

which would be like writing:

print select map 1..10 'x [2*x] 'x [even? x]

Conclusion

If you made it here, then I can assure you: you've already learned more than you need in order to be fully proficient in Arturo.

Just head to the Library Reference and have a look at the built-in functions (with explanations and example code) and see what's already available for you or - if you want to see the language in action - just browse through the Examples: there are many (many!) working examples, to get more than just an idea.

Welcome on board! :)

Example program

This section is inspired by Learn X in Y minutes and its goal is to present the most basic features of Arturo, in a concise way, so that you can get started fast.

So... With X = Arturo and Y = ~15 minutes, here you are:

; this is a comment
; this is another comment

;---------------------------------
; VARIABLES & VALUES
;---------------------------------

; numbers
a1: 2
a2: 3.14
a3: to :complex [1 2.0]     ; 1.0+2.0i

; strings
c1: "this is a string"
c2: {
    this is a multiline string
    that is indentation-agnostic
}
c3: {:
    this is 
        a verbatim
            multiline string
                which will remain exactly
                    as the original
:}

; characters
ch: 'c'

; blocks/arrays
d: [1 2 3]

; dictionaries
e: #[
    name: "John"
    surname: "Doe"
    age: 34
    likes: [pizza spaghetti]
]

; yes, functions are values too
f: function [x][
    2 * x
]

; colors - right, you can directly define them as well!
g1: #red
g2: #0077BF

; dates
h: now              ; 2021-05-03T17:10:48+02:00

; versions

currentVersion: 3.2.10-beta ; SemVer compatible :)

; logical values
i1: true
i2: false
i3: maybe

; units
meters: `m
kilograms: `kg

; quantities
height: 3`yd
width: 4`m

;---------------------------------
; BASIC OPERATORS
;---------------------------------

; simple arithmetic
1 + 1       ; => 2
8 - 1       ; => 7
4.2 - 1.1   ; => 3.1
10 * 2      ; => 20
35 / 4      ; => 8
35 // 4     ; => 8.75
2 ^ 5       ; => 32
5 % 3       ; => 2

; bitwise operators
and 3 5     ; => 1
or 3 5      ; => 7
xor 3 5     ; => 6

; pre-defined constants
pi          ; => 3.141592653589793
epsilon     ; => 2.718281828459045
null        ; => null
true        ; => true
false       ; => false

;---------------------------------
; COMPARISON OPERATORS
;---------------------------------

; equality
1 = 1       ; => true
2 = 1       ; => false

; inequality
1 <> 1      ; => false
2 <> 1      ; => true

; more comparisons
1 < 10      ; => true
1 =< 10     ; => true
10 =< 10    ; => true
1 > 10      ; => false
1 >= 10     ; => false
11 >= 10    ; => true

;---------------------------------
; CONDITIONALS
;---------------------------------

; logical operators
and? true true      ; => true
and? true false     ; => false
or? true false      ; => true
or? false false     ; => false

and? [1=2][2<3]     ; => false 
                    ; (the second block will not be evaluated)

; simple if statements
if 2 > 1 [ print "yes!"]    ; yes!
if 3 <> 2 -> print "true!"  ; true!

; switch statements
switch 2 > 3 -> print "2 is greater than 3"
             -> print "2 is not greater than 3" ; 2 is not greater than 3

a: (2 > 3)?["yes"]["no"]         ; a: "no"
a: (2 > 3)? -> "yes" -> "no"     ; a: "no" (exactly the same as above)

; case statements
key: "one"

case key [ ; the main block is always evaluated!
    "one"   -> print "key is one!"
    "two"   -> print "key is two!"
    any     -> print "key is none of the above"
]

; when statements
when [ ; the main block is always evaluated!
    prime? 4 -> print "yes, 4 is prime - wait, what?!"
    prime? 5 -> print "yes, 5 is prime
    prime? 7 -> print "yes, 6 is prime
    true     -> print "none of the above was true"
]
; yes, 5 is prime

when.any [ ; cascade-style checking (without breaking)
    prime? 4 -> print "yes, 4 is prime - wait, what?!"
    prime? 5 -> print "yes, 5 is prime"
    prime? 7 -> print "yes, 7 is prime"
]
; yes, 5 is prime
; yes, 7 is prime

x: 2
when.has: x [ ; prepends passed parameter to each block/condition
    [=0] -> print "x is zero!"
    [<1] -> print "x is less than 1"
    [<4] -> print "x is less than 4"
    true -> print "x is >= 4"
]
; x is less than 4

;---------------------------------
; LOOPS
;---------------------------------

; with `loop`
arr: [1 4 5 3]
loop arr 'x [
    print ["x =" x]
]
; x = 1
; x = 4
; x = 5
; x = 3

; with loop and custom index
loop.with:'i arr 'x [
    print ["item at position" i "=>" x]
]
; item at position 0 => 1
; item at position 1 => 4
; item at position 2 => 5
; item at position 3 => 3

; using ranges
loop 1..3 'x ->         ; since it's a single statement
    print x             ; there's no need for [block] notation
                        ; we can wrap it up using the `->` syntactic sugar

loop 'a'..'c' 'ch ->
    print ch
; a
; b
; c

; picking multiple items
loop 1..10 [x y] ->
    print ["x =" x ", y =" y]
; x = 1 , y = 2 
; x = 3 , y = 4 
; x = 5 , y = 6 
; x = 7 , y = 8 
; x = 9 , y = 10 

; looping through a dictionary
dict: #[name: "John", surname: "Doe", age: 34]
loop dict [key value][
    print [key "->" value]
]
; name -> John 
; surname -> Doe 
; age -> 34 
                    
; while loops
i: 0
while [i<3][
    print ["i =" i]
    inc 'i
]
; i = 0
; i = 1
; i = 2
 
;---------------------------------
; STRINGS
;---------------------------------

; case
a: "tHis Is a stRinG"
print upper a               ; THIS IS A STRING
print lower a               ; this is a string
print capitalize a          ; THis Is a stRinG

; concatenation
a: "Hello " ++ "World!"     ; a: "Hello World!"

; strings as an array
split "hello"               ; => [h e l l o]
split.words "hello world"   ; => [hello world]

print first "hello"         ; h
print last "hello"          ; o

; conversion
to :string 123              ; => "123"
to :integer "123"           ; => 123

; joining strings together
join ["hello" "world"]              ; => "helloworld"
join.with:"-" ["hello" "world"]     ; => "hello-world"

; string interpolation
x: 2
print ~"x = |x|"            ; x = 2

; interpolation with `print`
print ["x =" x]             ; x = 2
                            ; (`print` works by calculating the given block
                            ;  and joining the different values as strings
                            ;  with a single space between them)

; templates
print render.template {
    <||= switch x=2 [ ||>
        Yes, x = 2
    <||][||>
        No, x is not 2
    <||]||> 
} ; Yes, x = 2

; matching
prefix? "hello" "he"        ; => true
suffix? "hello" "he"        ; => false

contains? "hello" "ll"      ; => true
contains? "hello" "he"      ; => true
contains? "hello" "x"       ; => false

in? "ll" "hello"            ; => true 
in? "x" "hello"             ; => false

;---------------------------------
; BLOCKS
;---------------------------------

; calculate a block
arr: [1 1+1 1+1+1]
@arr                        ; => [1 2 3]

; execute a block
sth: [print "Hello world"]  ; this is perfectly valid,
                            ; could contain *anything*
                            ; and will not be executed...

do sth                      ; Hello world
                            ; (...until we tell it to)

; array indexing
arr: ["zero" "one" "two" "three"]
print first arr             ; zero
print arr\0                 ; zero
print last arr              ; three
print arr\3                 ; three

x: 2
print get arr x             ; two
print arr\[x]               ; two

; setting an array element
arr\0: "nada"
set arr 2 "dos"
print arr                   ; nada one dos three

z: 2
arr\[z]: "dos"              ; would have the same effect

; adding elements to an array
arr: []
'arr ++ "one"
'arr ++ "two"
print arr                   ; one two

; remove elements from an array
arr: ["one" "two" "three" "four"]
'arr -- "two"               ; arr: ["one" "three" "four"]
remove 'arr .index 0        ; arr: ["three" "four"]

; getting the size of an array
arr: ["one" 2 "three" 4]
print size arr              ; 4

; getting a slice of an array
print slice ["one" "two" "three" "four"] 0 1        ; one two

; check if array contains a specific element
print contains? arr "one"   ; true
print contains? arr "five"  ; false

; sorting array
arr: [1 5 3 2 4]
sort arr                    ; => [1 2 3 4 5]
sort.descending arr         ; => [5 4 3 2 1]

; mapping values
map 1..10 [x][2*x]          ; => [2 4 6 8 10 12 14 16 18 20]
map 1..10 'x -> 2*x         ; same as above
map 1..10 => [2 * &]        ; same as above
map 1..10 => [2*]           ; same as above

; selecting/filtering array values
select 1..10 [x][odd? x]    ; => [1 3 5 7 9]
select 1..10 => odd?        ; same as above

filter 1..10 => odd?        ; => [2 4 6 8 10]
                            ; (now, we leave out all odd numbers - 
                            ;  while select keeps them)

; misc operations
arr: ["one" 2 "three" 4]
reverse arr                 ; => [4 "three" 2 "one"]
shuffle arr                 ; => [2 4 "three" "one"]
unique [1 2 3 2 3 1]        ; => [1 2 3]
permutate [1 2 3]           ; => [[1 2 3] [1 3 2] [3 1 2] [2 1 3] [2 3 1] [3 2 1]]
take 1..10 3                ; => [1 2 3]
repeat [1 2] 3              ; => [1 2 1 2 1 2]

;---------------------------------
; FUNCTIONS
;---------------------------------

; declaring a function
f: function [x][ 2*x ]
f: function [x]-> 2*x       ; same as above
f: $[x]->2*x                ; same as above (only using the `$` alias 
                            ;  for the `function`... function)

; calling a function
f 10                        ; => 20

; returning a value
g: function [x][
    if x < 2 -> return 0

    res: 0
    loop 0..x 'z [
        res: res + z
    ]
    return res
]

;---------------------------------
; CUSTOM TYPES
;---------------------------------

; defining a custom type
define :person [
    ; define a new custom type "Person"
    ; with fields: name, surname, age
    init: method [name surname age][
        \name: capitalize name
        \surname: surname
        \age: age
    ]

    ; custom print function
    string: method [][
        render "NAME: |\name|, SURNAME: |\surname|, AGE: |\age|"
    ]

    ; custom comparison operator
    compare: sortable 'age
]

; create a method for our custom type
sayHello: function [this :person][
    print ["Hello" this\name]
]

; create new objects of our custom type
a: to :person ["John" "Doe" 34]!                ; let's create 2 "Person"s
b: to :person ["jane" "Doe" 33]!                ; and another one

; call pseudo-inner method
sayHello a                                      ; Hello John                       
sayHello b                                      ; Hello Jane

; access object fields
print ["The first person's name is:" a\name]    ; The first person's name is: John
print ["The second person's name is:" b\name]   ; The second person's name is: Jane

; changing object fields
a\name: "Bob"                                   
sayHello a                                      ; Hello Bob

; verifying object type
print type a                                    ; :person
print is? :person a                             ; true

; printing objects
print a                                         ; NAME: Bob, SURNAME: Doe, AGE: 34

; sorting user objects (using custom comparator)
print sort @[a b]                                     ; Jane..., Bob...
print sort.descending @[a b]                          ; Bob..., Jane...

calculate the binary AND for the given values

Arguments

valueA (:integer,:literal,:pathliteral,:binary)
valueB (:integer,:binary)

Returns

:integer,:binary,:nothing

`nand`

calculate the binary NAND for the given values

Arguments

valueA (:integer,:literal,:pathliteral,:binary)
valueB (:integer,:binary)

Returns

:integer,:binary,:nothing

`nor`

calculate the binary NOR for the given values

Arguments

valueA (:integer,:literal,:pathliteral,:binary)
valueB (:integer,:binary)

Returns

:integer,:binary,:nothing

`not`

calculate the binary complement the given value

Arguments

value (:integer,:literal,:pathliteral,:binary)

Returns

:integer,:binary,:nothing

`or`

calculate the binary OR for the given values

Arguments

valueA (:integer,:literal,:pathliteral,:binary)
valueB (:integer,:binary)

Returns

:integer,:binary,:nothing

`shl`

shift-left first value bits by second value

Arguments

value (:integer,:literal,:pathliteral)
bits (:integer)

Options

safe (:logical): check for overflows

Returns

:integer,:nothing

`shr`

shift-right first value bits by second value

Arguments

value (:integer,:literal,:pathliteral)
bits (:integer)

Returns

:integer,:nothing

`xnor`

calculate the binary XNOR for the given values

Arguments

valueA (:integer,:literal,:pathliteral,:binary)
valueB (:integer,:binary)

Returns

:integer,:binary,:nothing

`xor`

calculate the binary XOR for the given values

Arguments

valueA (:integer,:literal,:pathliteral,:binary)
valueB (:integer,:binary)

Returns

:integer,:binary,:nothing

Collections

Functions and helpers for manipulating and dealing with different types of collections (blocks, dictionaries, and strings)

`append` (alias: `++` - infix: true)

append value to given collection

Arguments

collection (:char,:string,:literal,:pathliteral,:binary,:object,:block)
value (:any)

Returns

:string,:binary,:object,:block,:nothing

`array` (alias: `@` - infix: false)

create array from given block, by reducing/calculating all internal values

Arguments

source (:any)

Options

of (:integer,:block): initialize an empty n-dimensional array with given dimensions

Returns

:block

`chop`

remove last item from given collection

Arguments

collection (:string,:literal,:pathliteral,:block)

Options

times (:integer): remove multiple items

Returns

:string,:block,:nothing

`combine`

get all possible combinations of the elements in given collection

Arguments

collection (:block)

Options

by (:integer): define size of each set
repeated (:logical): allow for combinations with repeated elements
count (:logical): just count the number of combinations

Returns

:integer,:block

`contains?`

check if collection contains given value

Arguments

collection (:string,:dictionary,:object,:block,:range)
value (:any)

Options

at (:integer): check at given location within collection
deep (:logical): searches recursively in deep for a value.

Returns

:logical

`couple`

get combination of elements in given collections as array of tuples

Arguments

collectionA (:block)
collectionB (:block)

Returns

:block

`decouple`

get tuple of collections from a coupled collection of tuples

Arguments

collection (:literal,:pathliteral,:block)

Returns

:block

`dictionary` (alias: `#` - infix: false)

create dictionary from given block or file, by getting all internal symbols

Arguments

source (:string,:block)

Options

with (:block): embed given symbols
raw (:logical): create dictionary from raw block
lower (:logical): automatically convert all keys to lowercase

Returns

:dictionary

`drop`

remove first item from given collection

Arguments

collection (:string,:literal,:pathliteral,:block)

Options

times (:integer): remove multiple items

Returns

:string,:block,:nothing

`empty`

empty given collection

Arguments

collection (:literal,:pathliteral)

Returns

:nothing

`empty?`

check if given collection is empty

Arguments

collection (:null,:string,:dictionary,:block)

Returns

:logical

`extend`

get new dictionary by merging given ones

Arguments

parent (:literal,:pathliteral,:dictionary)
additional (:dictionary)

Returns

:dictionary

`first`

return the first item of the given collection

Arguments

collection (:string,:block,:range)

Options

n (:integer): get first n items

Returns

:null,:any

`flatten`

flatten given collection by eliminating nested blocks

Arguments

collection (:literal,:pathliteral,:block)

Options

once (:logical): do not perform recursive flattening

Returns

:block

`get`

get collection's item by given index

Arguments

collection (:complex,:string,:error,:errorkind,:date,:binary,:dictionary,:object,:store,:block,:range,:bytecode)
index (:any)

Returns

:any

`in?` (alias: `∈` - infix: true)

check if value exists in given collection

Arguments

value (:any)
collection (:string,:dictionary,:object,:block,:range)

Options

at (:integer): check at given location within collection
deep (:logical): searches recursively in deep for a value.

Returns

:logical

`index`

return first index of value in given collection

Arguments

collection (:string,:dictionary,:block,:range)
value (:any)

Returns

:null,:integer,:string

`insert`

insert value in collection at given index

Arguments

collection (:string,:literal,:pathliteral,:dictionary,:block)
index (:integer,:string)
value (:any)

Returns

:string,:dictionary,:block,:nothing

`key?`

check if collection contains given key

Arguments

collection (:dictionary,:object)
key (:any)

Returns

:logical

`keys`

get list of keys for given collection

Arguments

dictionary (:dictionary,:object)

Returns

:block

`last`

return the last item of the given collection

Arguments

collection (:string,:block,:range)

Options

n (:integer): get last n items

Returns

:null,:any

`max`

get maximum element in given collection

Arguments

collection (:block,:range)

Options

index (:logical): retrieve index of maximum element

Returns

:null,:any

`min`

get minimum element in given collection

Arguments

collection (:block,:range)

Options

index (:logical): retrieve index of minimum element

Returns

:null,:any

`one?`

check if given number or collection size is one

Arguments

number (:null,:integer,:floating,:string,:dictionary,:block,:range)

Returns

:logical

`permutate`

get all possible permutations of the elements in given collection

Arguments

collection (:block)

Options

by (:integer): define size of each set
repeated (:logical): allow for permutations with repeated elements
count (:logical): just count the number of permutations

Returns

:block

`pop`

remove and return the last item from given collection

Arguments

collection (:literal,:pathliteral)

Options

n (:integer): remove multiple items. (Must be greater than 0.)

Returns

:any

`prepend`

prepend value to given collection

Arguments

collection (:char,:string,:literal,:pathliteral,:binary,:block)
value (:any)

Returns

:string,:binary,:block,:nothing

`range` (alias: `..` - infix: true)

get list of values in given range (inclusive)

Arguments

from (:integer,:char)
to (:integer,:floating,:char)

Options

step (:integer): use step between range values

Returns

:range

`remove` (alias: `--` - infix: true)

remove value from given collection

Arguments

collection (:string,:literal,:pathliteral,:dictionary,:object,:block)
value (:any)

Options

key (:logical): remove dictionary key
once (:logical): remove only first occurence
index (:logical): remove specific index
prefix (:logical): remove first matching prefix from string
suffix (:logical): remove first matching suffix from string
instance (:logical): remove an instance of a block, instead of its elements.

Returns

:string,:dictionary,:block,:nothing

`repeat`

repeat value the given number of times and return new one

Arguments

value (:literal,:pathliteral,:any)
times (:integer)

Returns

:string,:block

`reverse`

reverse given collection

Arguments

collection (:string,:literal,:pathliteral,:block,:range)

Options

exact (:logical): make sure the reverse range contains the same elements

Returns

:string,:block,:nothing

`rotate`

right-rotate collection by given distance

Arguments

collection (:string,:literal,:pathliteral,:block)
distance (:integer)

Options

left (:logical): left rotation

Returns

:string,:block,:nothing

`sample`

get a random element from given collection

Arguments

collection (:block,:range)

Returns

:null,:any

`set`

set collection's item at index to given value

Arguments

collection (:string,:binary,:dictionary,:object,:store,:block,:bytecode)
index (:any)
value (:any)

Returns

:nothing

`shuffle`

get given collection shuffled

Arguments

collection (:literal,:pathliteral,:block)

Returns

:block,:nothing

`size`

get size/length of given collection

Arguments

collection (:null,:string,:binary,:dictionary,:object,:block,:range)

Returns

:integer,:floating

`slice`

get a slice of collection between given indices

Arguments

collection (:string,:literal,:pathliteral,:block)
from (:integer)
to (:integer)

Returns

:string,:block

`sort`

sort given block in ascending order

Arguments

collection (:literal,:pathliteral,:dictionary,:block)

Options

as (:literal): localized by ISO 639-1 language code
sensitive (:logical): case-sensitive sorting
descending (:logical): sort in descending order
values (:logical): sort dictionary by values
by (:string,:literal): sort array of dictionaries by given key

Returns

:block,:nothing

`sorted?`

check if given collection is already sorted

Arguments

collection (:block)

Options

descending (:logical): check for sorting in ascending order

Returns

:logical

`split`

split collection to components

Arguments

collection (:string,:literal,:pathliteral,:block)

Options

words (:logical): split string by whitespace
lines (:logical): split string by lines
by (:string,:regex,:block): split using given separator
at (:integer): split collection at given position
every (:integer): split collection every n elements
path (:logical): split path components in string

Returns

:block,:nothing

`squeeze`

reduce adjacent elements in given collection

Arguments

collection (:string,:literal,:pathliteral,:block)

Returns

:string,:block,:nothing

`take`

keep first of elements from given collection and return the remaining ones

Arguments

collection (:string,:literal,:pathliteral,:block,:range)
number (:integer)

Returns

:string,:block,:nothing

`tally`

find number of occurences of each value within given block and return as dictionary

Arguments

collection (:string,:block)

Returns

:dictionary

`unique`

get given collection without duplicates

Arguments

collection (:string,:literal,:pathliteral,:block)

Options

id (:logical): generate unique id using given prefix

Returns

:block,:nothing

`values`

get list of values for given collection

Arguments

dictionary (:dictionary,:object,:block,:range)

Returns

:block

`zero?`

check if given number or collection size is zero

Arguments

number (:null,:integer,:floating,:string,:dictionary,:block,:range)

Returns

:logical

Colors

Functions and helpers for manipulating color values

`blend`

blend given colors and get result

Arguments

colorA (:literal,:pathliteral,:color)
colorB (:color)

Options

balance (:floating): use different mix of color (0.0-1.0, default:0.5)

Returns

:color

`darken`

darken color by given percentage (0.0-1.0)

Arguments

color (:literal,:pathliteral,:color)
percent (:floating)

Returns

:color

`desaturate`

desaturate color by given percentage (0.0-1.0)

Arguments

color (:literal,:pathliteral,:color)
percent (:floating)

Returns

:color

`grayscale`

convert color to grayscale

Arguments

color (:literal,:pathliteral,:color)

Returns

:color

`invert`

get complement for given color

Arguments

color (:literal,:pathliteral,:color)

Returns

:color

`lighten`

lighten color by given percentage (0.0-1.0)

Arguments

color (:literal,:pathliteral,:color)
percent (:floating)

Returns

:color

`palette`

create palette using given base color

Arguments

color (:color)

Options

triad (:logical): generate a triad palette
tetrad (:logical): generate a tetrad palette
split (:logical): generate a split complement palette
analogous (:logical): generate an analogous palette
monochrome (:logical): generate a monochromatic palette
random (:logical): generate random palette based on color triads
size (:integer): specify the size of the generated palette

Returns

:block

`saturate`

saturate color by given percentage (0.0-1.0)

Arguments

color (:literal,:pathliteral,:color)
percent (:floating)

Returns

:color

`spin`

spin color around the hue wheel by given amount

Arguments

color (:literal,:pathliteral,:color)
amount (:integer)

`as`

format given value as implied type

Arguments

value (:any)

Options

binary (:logical): format integer as binary
hex (:logical): format integer as hexadecimal
octal (:logical): format integer as octal
agnostic (:logical): convert words in block to literals, if not in context
data (:logical): parse input as Arturo data block
code (:logical): convert value to valid Arturo code
pretty (:logical): prettify generated code
unwrapped (:logical): omit external block notation

Returns

:any

`from`

get value from string, using given representation

Arguments

value (:string,:literal)

Options

binary (:logical): get integer from binary representation
hex (:logical): get integer from hexadecimal representation
octal (:logical): get integer from octal representation
opcode (:logical): get opcode by from opcode literal

Returns

:any

Core

Basic functions and constants that make up the very core of the language

`alias`

assign symbol to given function

Arguments

symbol (:string,:symbol,:symbolliteral,:block)
function (:string,:word,:literal)

Options

infix (:logical): use infix precedence

Arguments

condition (:block)

Options

that (:string): prints a custom message when ensure fails

Returns

:nothing

`export`

export given container children to current scope

Arguments

module (:dictionary,:object,:module)

Options

all (:logical): export everything, regardless of whether it's been marked as public (makes sense only for modules)

Returns

:nothing

`function` (alias: `$` - infix: false)

create function with given arguments and body

Arguments

arguments (:literal,:block)
body (:block)

Options

import (:block): import/embed given list of symbols from current environment
export (:block): export given symbols to parent
memoize (:logical): store results of function calls
inline (:logical): execute function without scope

Returns

:function

`if`

perform action, if given condition is not false or null

Arguments

condition (:any)
action (:block,:bytecode)

Returns

:nothing

`if?`

perform action, if given condition is not false or null and return condition result

Arguments

condition (:any)
action (:block)

Returns

:logical

`import`

import given package

Arguments

package (:string,:literal,:block)

Options

version (:version): specify package version
min (:logical): get any version >= the specified one
branch (:string,:literal): use specific branch for repository url (default: main)
latest (:logical): always check for the latest version available
lean (:logical): return as a dictionary, instead of importing in main namespace
only (:block): import only selected symbols, if available
verbose (:logical): output extra information

Returns

:dictionary,:block,:nothing

`let` (alias: `:` - infix: true)

set symbol to given value

Arguments

symbol (:string,:word,:literal,:block)
value (:any)

Returns

:nothing

`method`

create type method with given arguments and body

Arguments

arguments (:literal,:block)
body (:block)

Options

distinct (:logical): shouldn't be treated as a magic method
public (:logical): make method public (relevant only in modules!)

Returns

:method

`module`

create new module with given contents

Arguments

contents (:dictionary,:block)

Options

with (:block): use given initialization parameters

Returns

:module

`new`

create new value by cloning given one

Arguments

value (:any)

Arguments

number (:integer)

Options

discard (:logical): do not return anything

Returns

:any

`until`

execute action until the given condition is not false or null

Arguments

action (:block,:bytecode)
condition (:block,:bytecode)

Returns

:nothing

`var`

get symbol value by given name

Arguments

symbol (:string,:word,:literal,:pathliteral)

Returns

:any

`when`

check conditions one by one and execute corresponding block accordingly

Arguments

conditions (:block)

Options

any (:logical): check all conditions, without breaking, regardless of success
has (:any): prepend given value to each of the conditions

Returns

:logical

`when?`

check if a specific condition is fulfilled and, if so, execute given action

Arguments

condition (:block)
action (:block)

Returns

:logical

`while`

execute action while the given condition is is not false or null

Arguments

condition (:null,:block,:bytecode)
action (:block,:bytecode)

Returns

:nothing

`with`

create closure-style block by embedding given words

Arguments

embed (:string,:word,:literal,:dictionary,:block)
body (:block)

Returns

:block

Crypto

Cryptography- or encoding-related functions

`crc`

calculate the CRC32 polynomial of given string

Arguments

value (:string,:literal,:pathliteral)

Returns

:string,:nothing

`decode`

decode given value (default: base-64)

Arguments

value (:string,:literal,:pathliteral)

Options

url (:logical): decode URL based on RFC3986

Returns

:string,:nothing

`digest`

get digest for given value (default: MD5)

Arguments

value (:string,:literal,:pathliteral)

Options

sha (:logical): use SHA1

Returns

:string,:nothing

`encode`

encode given value (default: base-64)

Arguments

value (:string,:literal,:pathliteral)

Options

url (:logical): encode URL based on RFC3986
spaces (:logical): also encode spaces
slashes (:logical): also encode slashes
from (:string): source character encoding (default: CP1252)
to (:string): target character encoding (default: UTF-8)

Returns

:string,:nothing

`hash`

get hash for given value

Arguments

value (:any)

Options

string (:logical): get as a string

Returns

:integer,:string

Databases

Functions for creating and query databases

`close`

close given database

Arguments

database (:database)

Returns

:nothing

`open`

opens a new database connection and returns database

Arguments

name (:string)

Options

sqlite (:logical): support for SQLite databases
mysql (:logical): support for MySQL databases

Returns

:database

`query`

execute command or block of commands in given database and get returned rows

Arguments

database (:database)
commands (:string,:block)

Options

id (:logical): return last INSERT id
with (:block): use arguments for parametrized statement

Returns

:null,:integer,:block

`store`

create or load a persistent store on disk

Arguments

path (:string,:literal)

Options

deferred (:logical): save to disk only on program termination
global (:logical): save as global store
native (:logical): force native/Arturo format
json (:logical): force Json format
db (:logical): force database/SQlite format

Returns

:range

Dates

Functions for manipulating dates

`after`

get date after given one using interval

Arguments

date (:literal,:pathliteral,:date)

Options

nanoseconds (:integer): add given number of nanoseconds
milliseconds (:integer): add given number of milliseconds
seconds (:integer): add given number of seconds
minutes (:integer): add given number of minutes
hours (:integer): add given number of hours
days (:integer): add given number of days
weeks (:integer): add given number of weeks
months (:integer): add given number of months
years (:integer): add given number of years

Returns

:date

`before`

get date before given one using interval

Arguments

date (:literal,:pathliteral,:date)

Options

nanoseconds (:integer): subtract given number of nanoseconds
milliseconds (:integer): subtract given number of milliseconds
seconds (:integer): subtract given number of seconds
minutes (:integer): subtract given number of minutes
hours (:integer): subtract given number of hours
days (:integer): subtract given number of days
weeks (:integer): subtract given number of weeks
months (:integer): subtract given number of months
years (:integer): subtract given number of years

Returns

:date

`friday?`

check if given date is a Friday

Arguments

date (:date)

Returns

:logical

`future?`

check if given date is in the future

Arguments

date (:date)

Returns

:logical

`leap?`

check if given year is a leap year

Arguments

year (:integer,:date)

Returns

:logical

`monday?`

check if given date is a Monday

Arguments

date (:date)

Returns

:logical

`now`

get date/time now

Returns

:date

`past?`

check if given date is in the past

Arguments

date (:date)

Returns

:logical

`saturday?`

check if given date is a Saturday

Arguments

date (:date)

Returns

:logical

`sunday?`

check if given date is a Sunday

Arguments

date (:date)

Returns

:logical

`thursday?`

check if given date is a Thursday

Arguments

date (:date)

Returns

:logical

`today?`

check if given date is today

Arguments

date (:date)

Returns

:logical

`tuesday?`

check if given date is a Tuesday

Arguments

date (:date)

Returns

:logical

`wednesday?`

check if given date is a Wednesday

Arguments

date (:date)

Returns

:logical

Exceptions

Exceptions and error handling

`arithmeticError`

an arithmetic error

`assertionError`

an assertion error

`conversionError`

a conversion error

`indexError`

an index error

`libraryError`

a library error

`nameError`

a name error

`packageError`

a package error

`runtimeError`

a generic runtime error

`syntaxError`

a syntax error

`systemError`

a system error

`throw`

throw an error with given message

Arguments

message (:string,:errorkind)

Options

as (:errorkind): consider the error as one of given subtype

Returns

:nothing

`throws?`

perform action, and return true if errors were thrown

Arguments

action (:block,:bytecode)

Returns

:logical

`try`

perform action and catch possible errors

Arguments

action (:block,:bytecode)

Options

verbose (:logical): print all error messages as usual

Returns

:null,:error

`typeError`

a type error

`uiError`

a UI error

`valueError`

a value error

`vmError`

a VM error

Files

Functions for reading, writing, and manipulating files

`copy`

copy file at path to given destination

Arguments

file (:string)
destination (:string)

Options

directory (:logical): path is a directory

Returns

:nothing

`delete`

delete file at given path

Arguments

file (:string)

Options

directory (:logical): path is a directory

Returns

:nothing

`directory?`

check if given path exists and corresponds to a directory

Arguments

path (:string)

Returns

:logical

`exists?`

check if file/directory at given path exists

Arguments

path (:string)

Returns

:logical

`file?`

check if given path exists and corresponds to a file

Arguments

path (:string)

Returns

:logical

`hidden?`

check if file/folder at given path is hidden

Arguments

file (:string)

Returns

:logical

`move`

move file at path to given destination

Arguments

file (:string)
destination (:string)

Options

directory (:logical): path is a directory

Returns

:nothing

`permissions`

check permissions of given file

Arguments

file (:string)

Options

set (:dictionary): set using given file permissions

Returns

:null,:dictionary

`read` (alias: `<<` - infix: false)

read file from given path

Arguments

file (:string)

Options

lines (:logical): read file lines into block
json (:logical): read Json into value
csv (:logical): read CSV file into a block of rows
delimiter (:char): read CSV file with a specific delimiter
withHeaders (:logical): read CSV headers
html (:logical): read HTML into node dictionary
xml (:logical): read XML into node dictionary
markdown (:logical): read Markdown and convert to HTML
toml (:logical): read TOML into value
bytecode (:logical): read file as Arturo bytecode
binary (:logical): read as binary
file (:logical): read as file (throws an error if not valid)

Returns

:string,:binary,:block

`rename`

rename file at path using given new path name

Arguments

file (:string)
name (:string)

Options

directory (:logical): path is a directory

Returns

:nothing

`symlink`

create symbolic link of file to given destination

Arguments

file (:string)
destination (:string)

Options

hard (:logical): create a hard link

Returns

:nothing

`symlink?`

check if given path exists and corresponds to a symlink

Arguments

path (:string)

Returns

:logical

`timestamp`

get file timestamps

Arguments

file (:string)

Returns

:null,:dictionary

`unzip`

unzip given archive to destination

Arguments

destination (:string)
original (:string)

Returns

:nothing

`volume`

get file size for given path

Arguments

file (:string)

Returns

:quantity

`write` (alias: `>>` - infix: false)

write content to file at given path

Arguments

file (:null,:string)
content (:any)

Options

append (:logical): append to given file
directory (:logical): create directory at path
json (:logical): write value as Json
compact (:logical): produce compact, non-prettified Json code
binary (:logical): write as binary

Returns

:nothing

`zip`

zip given files to file at destination

Arguments

destination (:string)
files (:block)

Arguments

prompt (:null,:string)

Options

repl (:logical): get input as if in a REPL
history (:string): set path for saving history
complete (:block): use given array for auto-completions
hint (:dictionary): use given dictionary for typing hints

Returns

:char,:string

`print`

print given value to screen with newline

Arguments

value (:any)

Options

lines (:logical): print each value in block in a new line

Returns

:nothing

`prints`

print given value to screen

Arguments

value (:any)

Arguments

collection (:integer,:string,:literal,:dictionary,:object,:inline,:block,:range)
params (:null,:literal,:block)
condition (:block,:bytecode)

Options

with (:literal): use given index
value (:logical): also include condition values

Returns

:block,:nothing

`cluster`

group together items in collection that abide by given predicate

Arguments

collection (:integer,:string,:literal,:dictionary,:object,:inline,:block,:range)
params (:null,:literal,:block)
condition (:block,:bytecode)

Options

with (:literal): use given index
value (:logical): also include condition values

Returns

:block,:nothing

`collect`

collect items from given collection condition while is true

Arguments

collection (:integer,:string,:literal,:dictionary,:object,:inline,:block,:range)
params (:null,:literal,:block)
condition (:block,:bytecode)

Options

with (:literal): use given index
after (:logical): start collecting after given condition becomes true

Returns

:block,:nothing

`enumerate`

calculate the number of given collection's items that satisfy condition

Arguments

collection (:integer,:string,:dictionary,:object,:inline,:block,:range)
params (:null,:literal,:block)
condition (:block,:bytecode)

Options

with (:literal): use given index

Returns

:integer

`every?`

check if every item in collection satisfies given condition

Arguments

collection (:integer,:string,:dictionary,:object,:inline,:block,:range)
params (:null,:literal,:block)
condition (:block,:bytecode)

Options

with (:literal): use given index

Returns

:logical

`filter`

get collection's items by filtering those that do not fulfil given condition

Arguments

collection (:integer,:string,:literal,:dictionary,:object,:inline,:block,:range)
params (:null,:literal,:block)
condition (:block,:bytecode)

Options

with (:literal): use given index
first (:logical,:integer): only filter first element/s
last (:logical,:integer): only filter last element/s

Returns

:block,:nothing,:any

`fold`

left-fold given collection returning accumulator

Arguments

collection (:integer,:string,:dictionary,:object,:inline,:block,:range)
params (:null,:block)
action (:block,:bytecode)

Options

with (:literal): use given index
seed (:any): use specific seed value
right (:logical): perform right folding

Returns

:null,:block,:nothing

`gather`

group items in collection by block result and return as dictionary

Arguments

collection (:integer,:string,:literal,:dictionary,:object,:inline,:block,:range)
params (:null,:literal,:block)
condition (:block,:bytecode)

Options

with (:literal): use given index

Returns

:dictionary,:nothing

`loop`

loop through collection, using given iterator and block

Arguments

collection (:integer,:string,:dictionary,:object,:inline,:block,:range)
params (:null,:literal,:block)
action (:block,:bytecode)

Options

with (:literal): use given index
forever (:logical): cycle through collection infinitely

Returns

:nothing

`map`

map collection's items by applying given action

Arguments

collection (:integer,:string,:literal,:dictionary,:object,:inline,:block,:range)
params (:null,:literal,:block)
condition (:block,:bytecode)

Options

with (:literal): use given index

Returns

:block,:nothing

`maximum`

get maximum item from collection based on given predicate

Arguments

collection (:integer,:string,:literal,:dictionary,:object,:inline,:block,:range)
params (:null,:literal,:block)
condition (:block,:bytecode)

Options

with (:literal): use given index
value (:logical): also include predicate values

Returns

:block,:nothing

`minimum`

get minimum item from collection based on given predicate

Arguments

collection (:integer,:string,:literal,:dictionary,:object,:inline,:block,:range)
params (:null,:literal,:block)
condition (:block,:bytecode)

Options

with (:literal): use given index
value (:logical): also include predicate values

Returns

:block,:nothing

`select`

get collection's items that fulfil given condition

Arguments

collection (:integer,:string,:literal,:dictionary,:object,:inline,:block,:range)
params (:null,:literal,:block)
condition (:block,:bytecode)

Options

with (:literal): use given index
first (:logical,:integer): only return first element/s
last (:logical,:integer): only return last element/s
n (:integer): only return n-th element

Returns

:block,:nothing,:any

`some?`

check if any of collection's items satisfy given condition

Arguments

collection (:integer,:string,:dictionary,:object,:inline,:block,:range)
params (:null,:literal,:block)
condition (:block,:bytecode)

Options

with (:literal): use given index

Returns

:logical

Logic

Logical operations (AND, OR, XOR, etc), helpers and constants for boolean values

`all?`

check if all values in given block are true

Arguments

conditions (:block)

Returns

:logical

`and?` (alias: `∧` - infix: true)

return the logical AND for the given values

Arguments

valueA (:logical,:block)
valueB (:logical,:block)

Returns

:logical

`any?`

check if any of the values in given block is true

Arguments

conditions (:block)

Returns

:logical

`false`

the FALSE logical constant

`false?`

returns true if given value is false; otherwise, it returns false

Arguments

value (:any)

Returns

:logical

`maybe`

the MAYBE logical constant

`nand?` (alias: `⊼` - infix: true)

return the logical NAND for the given values

Arguments

valueA (:logical,:block)
valueB (:logical,:block)

Returns

:logical

`nor?`

return the logical NOR for the given values

Arguments

valueA (:logical,:block)
valueB (:logical,:block)

Returns

:logical

`not?` (alias: `¬` - infix: false)

return the logical complement of the given value

Arguments

value (:logical,:block)

Returns

:logical

`or?` (alias: `∨` - infix: true)

return the logical OR for the given values

Arguments

valueA (:logical,:block)
valueB (:logical,:block)

Returns

:logical

`true`

the TRUE logical constant

`true?`

returns true if given value is true; otherwise, it returns false

Arguments

value (:any)

Returns

:logical

`xnor?`

return the logical XNOR for the given values

Arguments

valueA (:logical,:block)
valueB (:logical,:block)

Returns

:logical

`xor?` (alias: `⊻` - infix: true)

return the logical XOR for the given values

Arguments

valueA (:logical,:block)
valueB (:logical,:block)

Returns

:logical

Net

Network-related functions and helpers

`browse`

open given URL with default browser

Arguments

url (:string)

Returns

:nothing

`download`

download file from url to disk

Arguments

url (:string)

Options

as (:string): set target file

Returns

:nothing

`mail`

send mail using given title and message to selected recipient

Arguments

recipient (:string)
title (:string)
message (:string)

Options

using (:dictionary): use given configuration

Returns

:nothing

`request`

perform HTTP request to url with given data and get response

Arguments

url (:string)
data (:null,:string,:dictionary)

Options

get (:logical): perform a GET request (default)
post (:logical): perform a POST request
patch (:logical): perform a PATCH request
put (:logical): perform a PUT request
delete (:logical): perform a DELETE request
json (:logical): send data as Json
headers (:dictionary): send custom HTTP headers
agent (:string): use given user agent
timeout (:integer): set a timeout
proxy (:string): use given proxy url
certificate (:string): use SSL certificate at given path
raw (:logical): return raw response without processing

Returns

:null,:dictionary

`serve`

start web server using given routes

Arguments

routes (:block)

Options

port (:integer): use given port
verbose (:logical): print info log
chrome (:logical): open in Chrome windows as an app

Arguments

number (:integer,:block)

Options

base (:integer): use given based (default: 10)

Arguments

number (:integer)

Options

prime (:logical): prime factorization

Returns

:block

`floor`

calculate the largest integer not greater than given value

Arguments

value (:integer,:floating,:rational)

Returns

:integer

`gamma`

calculate the gamma function for given value

Arguments

value (:integer,:floating,:rational)

Returns

:floating

`gcd`

calculate greatest common divisor for given collection of integers

Arguments

numbers (:block)

Returns

:integer

`hypot`

calculate the hypotenuse of a right-angle triangle with given base and height

Arguments

base (:integer,:floating,:rational)
height (:integer,:floating,:rational)

`product` (alias: `∏` - infix: false)

calculate the product of all values in given list

Arguments

collection (:block,:range)

Options

cartesian (:logical): return the cartesian product of given sublists

Returns

:integer,:floating,:rational

`random`

get a random integer between given limits

Arguments

lowerLimit (:integer,:floating,:rational)
upperLimit (:integer,:floating,:rational)

Returns

:integer,:floating

`reciprocal`

calculate the reciprocal of given number

Arguments

value (:integer,:floating,:rational)

Returns

:rational

`round`

round given value

Arguments

value (:integer,:floating,:rational)

Options

to (:integer): round to given decimal places

Returns

:floating

`sec`

calculate the secant of given angle

Arguments

angle (:integer,:floating,:complex,:rational,:quantity)

Returns

:floating,:complex

`sech`

calculate the hyperbolic secant of given angle

Arguments

angle (:integer,:floating,:complex,:rational,:quantity)

Returns

:floating,:complex

`sin`

calculate the sine of given angle

Arguments

angle (:integer,:floating,:complex,:rational,:quantity)

Returns

:floating,:complex

`sinh`

calculate the hyperbolic sine of given angle

Arguments

angle (:integer,:floating,:complex,:rational,:quantity)

Returns

:floating,:complex

`sqrt`

get square root of given value

Arguments

value (:integer,:floating,:complex,:rational)

Options

integer (:logical): get the integer square root

Returns

:floating

`sum` (alias: `∑` - infix: false)

calculate the sum of all values in given list

Arguments

collection (:block,:range)

Returns

:integer,:floating,:rational

`tan`

calculate the tangent of given angle

Arguments

angle (:integer,:floating,:complex,:rational,:quantity)

Returns

:floating,:complex

`tanh`

calculate the hyperbolic tangent of given angle

Arguments

angle (:integer,:floating,:complex,:rational,:quantity)

Returns

:floating,:complex

`tau`

the number tau, mathematical constant

Paths

Functions for path manipulation and information retrieval

`absolute?`

check if given path is an absolute path

Arguments

path (:string)

Returns

:logical

`extract`

extract components from path

Arguments

path (:string,:color)

Options

directory (:logical): get path directory
basename (:logical): get path basename (filename+extension)
filename (:logical): get path filename
extension (:logical): get path extension
scheme (:logical): get scheme field from URL
host (:logical): get host field from URL
port (:logical): get port field from URL
user (:logical): get user field from URL
password (:logical): get password field from URL
path (:logical): get path field from URL
query (:logical): get query field from URL
anchor (:logical): get anchor field from URL
red (:logical): get red component from color
green (:logical): get green component from color
blue (:logical): get blue component from color
alpha (:logical): get alpha component from color
hsl (:logical): get HSL representation from color
hsv (:logical): get HSV representation from color
hue (:logical): get hue component from color
saturation (:logical): get saturation component from color
luminosity (:logical): get luminosity component from color

Returns

:string,:dictionary

`list`

get files in given path

Arguments

path (:string)

Options

recursive (:logical): perform recursive search
relative (:logical): get relative paths

Returns

:block

`normalize`

get normalized version of given path

Arguments

path (:string,:literal,:pathliteral)

Options

executable (:logical): treat path as executable
tilde (:logical): expand tildes in path

Returns

:string,:nothing

`relative` (alias: `./` - infix: false)

get relative path for given path, based on current script's location

Arguments

path (:string)

Returns

:string

Quantities

Functions related to Quantities, physical units and constants

`alphaParticleMass`

the mass of an alpha particle

`angstromStar`

one ten-billionth of a meter

`atomicMass`

the mass of an atomic mass unit

`avogadroConstant`

the number of atoms in 12 grams of carbon-12

`bohrRadius`

the radius of the first Bohr orbit of the hydrogen atom

`boltzmannConstant`

the ratio of the universal gas constant to Avogadro's number

`classicalElectronRadius`

the radius of an electron

`conductanceQuantum`

the conductance of a superconductor

`conforms?` (alias: `:=` - infix: true)

check if given quantities/units are compatible

Arguments

a (:unit,:quantity)
b (:unit,:quantity)

Returns

:logical

`convert` (alias: `-->` - infix: true)

convert quantity to given unit

Arguments

value (:integer,:floating,:rational,:quantity)
unit (:string,:word,:literal,:unit)

Returns

:quantity

`deuteronMass`

the mass of a deuteron

`electronCharge`

the charge of an electron

`electronMass`

the mass of an electron

`electronMassEnergy`

the energy equivalent of the mass of an electron

`gravitationalConstant`

the gravitational constant

`hartreeEnergy`

the energy of the ground state of the hydrogen atom

`helionMass`

the mass of a helion

`impedanceOfVacuum`

the impedance of free space

`in`

convert quantity to given unit

Arguments

unit (:string,:word,:literal,:unit)
value (:integer,:floating,:rational,:quantity)

Returns

:quantity

`inverseConductanceQuantum`

the inverse of the conductance of a superconductor

`josephsonConstant`

The inverse of the flux quantum

`magneticFluxQuantum`

the magnetic flux of a superconductor

`molarGasConstant`

the universal gas constant

`muonMass`

the mass of a muon

`neutronMass`

the mass of a neutron

`planckConstant`

the ratio of the energy of a photon to its frequency

`planckLength`

the length of the Planck scale

`planckMass`

the mass of the Planck scale

`planckTemperature`

the temperature of the Planck scale

`planckTime`

the time of the Planck scale

`property`

get the described property of given quantity or unit

Arguments

quantity (:unit,:quantity)

Options

hash (:logical): get property as a hash

Returns

:integer,:literal

`protonMass`

the mass of a proton

`protonMassEnergy`

the energy equivalent of the mass of a proton

`reducedPlanckConstant`

the ratio of the energy of a photon to its frequency

`rydbergConstant`

the Rydberg constant

`scalar`

get quantity value in the appropriate numeric type

Arguments

value (:quantity)

Returns

:integer,:floating,:rational

`specify`

define new user unit

Arguments

name (:string,:literal)
value (:unit,:quantity)

Options

symbol (:string): define main unit symbol
describes (:string): set corresponding property for new unit
property (:logical): define a new property

Returns

:literal

`speedOfLight`

the speed of light in a vacuum

`standardGasVolume`

the volume of one mole of an ideal gas at standard temperature and pressure

`standardPressure`

the standard pressure

`standardTemperature`

the standard temperature

`tauMass`

the mass of a tau

`thomsonCrossSection`

the cross section of an electron

`tritonMass`

the mass of a triton

`units`

get the units of given quantity

Arguments

value (:unit,:quantity)

Options

base (:logical): get base units

`benchmark`

benchmark given code

Arguments

action (:block,:bytecode)

Options

get (:logical): get benchmark time

Returns

:floating,:nothing

`info`

print info for given symbol

Arguments

symbol (:string,:word,:literal,:pathliteral,:symbolliteral)

Options

get (:logical): get information as dictionary

Returns

:dictionary,:nothing

`inspect`

print full dump of given value to screen

Arguments

value (:any)

Options

muted (:logical): don't use color output

Returns

:nothing

`methods`

get list of methods for given object or module

Arguments

object (:object,:module)

Arguments

setA (:literal,:pathliteral,:block)
setB (:block)

Options

symmetric (:logical): get the symmetric difference

Returns

:block,:nothing

`disjoint?`

check if given sets are disjoint (they have no common elements)

Arguments

setA (:block)
setB (:block)

Returns

:logical

`intersect?`

check if given sets intersect (they have at least one common element)

Arguments

setA (:block)
setB (:block)

Returns

:logical

`intersection` (alias: `∩` - infix: true)

return the intersection of given sets

Arguments

setA (:literal,:pathliteral,:block)
setB (:block)

Returns

:block,:nothing

`powerset`

return the powerset of given set

Arguments

set (:literal,:pathliteral,:block)

Returns

:block,:nothing

`subset?` (alias: `⊆` - infix: true)

check if given set is a subset of second set

Arguments

setA (:block)
setB (:block)

Options

proper (:logical): check if proper subset

Returns

:logical

`superset?` (alias: `⊇` - infix: true)

check if given set is a superset of second set

Arguments

setA (:block)
setB (:block)

Options

proper (:logical): check if proper superset

Returns

:logical

`union` (alias: `∪` - infix: true)

return the union of given sets

Arguments

setA (:literal,:pathliteral,:block)
setB (:block)

Returns

:block,:nothing

Sockets

High-level socket interface and relevant socket communication methods

`accept`

accept incoming connection and return corresponding socket

Arguments

server (:socket)

Returns

:socket

`connect`

create new socket connection to given server port

Arguments

port (:integer)

Options

to (:string): set socket address
udp (:logical): use UDP instead of TCP

Returns

:socket

`listen`

start listening on given port and return new socket

Arguments

port (:integer)

Options

blocking (:logical): set blocking mode (default: false)
udp (:logical): use UDP instead of TCP

Returns

:socket

`receive`

receive line of data from selected socket

Arguments

origin (:socket)

Options

size (:integer): set maximum size of received data
timeout (:integer): set timeout (in milliseconds)

Returns

:string

`send`

send given message to selected socket

Arguments

destination (:socket)
message (:string)

Options

chunk (:logical): don't send data as a line of data

Returns

:nothing

`send?`

send given message to selected socket and return true if successful

Arguments

destination (:socket)
message (:string)

Returns

:logical

`unplug`

close given socket

Arguments

socket (:socket)

Returns

:nothing

Statistics

Functions and helpers for working with statistics and samples

`average`

get average from given collection of numbers

Arguments

collection (:block,:range)

Returns

:floating

`deviation`

get population standard deviation of given collection of numbers

Arguments

collection (:block)

Options

sample (:logical): calculate the sample standard deviation

Returns

:floating

`kurtosis`

get population kurtosis of given collection of numbers

Arguments

collection (:block)

Options

sample (:logical): calculate the sample kurtosis

Returns

:floating

`median`

get median from given collection of numbers

Arguments

collection (:block)

Returns

:null,:integer,:floating

`skewness`

get population skewness of given collection of numbers

Arguments

collection (:block)

Options

sample (:logical): calculate the sample skewness

Returns

:floating

`variance`

get population variance of given collection of numbers

Arguments

collection (:block)

Options

sample (:logical): calculate the sample variance

Returns

:floating

Strings

Functions and helpers for manipulating and dealing with strings or character blocks

`alphabet`

get dictionary-index charset for given locale

Arguments

locale (:string,:literal)

Options

lower (:logical): return lowercase characters (default)
upper (:logical): return uppercase characters
all (:logical): also return non-dictionary characters

Returns

:null,:block

`ascii?`

check if given character/string is in ASCII

Arguments

string (:char,:string)

Returns

:logical

`capitalize`

convert given string to capitalized

Arguments

string (:char,:string,:literal,:pathliteral)

Returns

:char,:string,:nothing

`escape`

escape given string

Arguments

string (:string,:literal,:pathliteral)

Options

json (:logical): for literal use in JSON strings
regex (:logical): for literal use in regular expression
shell (:logical): for use in a shell command
xml (:logical): for use in an XML document

Returns

:string,:nothing

`indent`

indent each line of given text

Arguments

text (:string,:literal,:pathliteral)

Options

n (:integer): pad by given number of spaces (default: 4)
with (:string): use given padding

Returns

:string,:nothing

`jaro`

calculate Jaro distance/similarity between given strings

Arguments

stringA (:string)
stringB (:string)

Returns

:floating

`join`

join collection of values into string

Arguments

collection (:literal,:pathliteral,:block)

Options

with (:char,:string): use given separator
path (:logical): join as path components

Returns

:string,:nothing

`levenshtein`

calculate Levenshtein distance/similarity between given strings

Arguments

stringA (:string)
stringB (:string)

Options

align (:logical): return aligned strings
with (:char): use given filler for alignment (default: -)

Returns

:integer,:block

`lower`

convert given string to lowercase

Arguments

string (:char,:string,:literal,:pathliteral)

Returns

:char,:string,:nothing

`lower?`

check if given string is lowercase

Arguments

string (:char,:string)

Returns

:logical

`match`

get matches within string, using given regular expression

Arguments

string (:string)
regex (:char,:string,:regex)

Options

once (:logical): get just the first match
count (:logical): just get number of matches
capture (:logical): get capture groups only
named (:logical): get named capture groups as a dictionary
bounds (:logical): get match bounds only
in (:range): get matches within given range
full (:logical): get results as an array of match results

Returns

:integer,:dictionary,:block

`match?`

check if string matches given regular expression

Arguments

string (:string)
regex (:string,:regex)

Options

in (:range): get matches within given range

Returns

:logical

`numeric?`

check if given string is numeric

Arguments

string (:char,:string)

Returns

:logical

`outdent`

outdent each line of given text, by using minimum shared indentation

Arguments

text (:string,:literal,:pathliteral)

Options

n (:integer): unpad by given number of spaces
with (:string): use given padding

Returns

:string,:nothing

`pad`

align string by adding given padding

Arguments

string (:string,:literal,:pathliteral)
padding (:integer)

Options

center (:logical): add padding to both sides
right (:logical): add right padding
with (:char): pad with given character

Returns

:string

`prefix?`

check if string starts with given prefix

Arguments

string (:string)
prefix (:string,:regex)

Returns

:logical

`render` (alias: `~` - infix: false)

render template with |string| interpolation

Arguments

template (:string,:literal,:pathliteral)

Options

once (:logical): don't render recursively
template (:logical): render as a template

Returns

:string,:nothing

`replace`

replace every matched substring/s by given replacement string and return result

Arguments

string (:string,:literal,:pathliteral)
match (:string,:regex,:block)
replacement (:string,:block)

Returns

:string,:nothing

`strip`

strip whitespace from given string

Arguments

string (:string,:literal,:pathliteral)

Options

start (:logical): strip leading whitespace
end (:logical): strip trailing whitespace

Returns

:string,:nothing

`suffix?`

check if string ends with given suffix

Arguments

string (:string)
suffix (:string,:regex)

Returns

:logical

`translate`

takes a dictionary of translations and replaces each instance sequentially

Arguments

string (:string,:literal,:pathliteral)
translations (:dictionary)

Returns

:string,:nothing

`truncate`

truncate string at given length

Arguments

string (:string,:literal,:pathliteral)
cutoff (:integer)

Options

with (:string): use given filler
preserve (:logical): preserve word boundaries

Returns

:string,:nothing

`upper`

convert given string to uppercase

Arguments

string (:char,:string,:literal,:pathliteral)

Returns

:char,:string,:nothing

`upper?`

check if given string is uppercase

Arguments

string (:char,:string)

Returns

:logical

`whitespace?`

check if given string consists only of whitespace

Arguments

string (:string)

Returns

:logical

`wordwrap`

word wrap a given string

Arguments

string (:string,:literal,:pathliteral)

Options

at (:integer): use given max line width (default: 80)

Arguments

value (:any)

Options

builtin (:logical): check if, internally, it's a built-in

Returns

:logical

`inline?`

checks if given value is of type :inline

Arguments

value (:any)

Returns

:logical

`integer?`

checks if given value is of type :integer

Arguments

value (:any)

Options

big (:logical): check if, internally, it's a bignum

Returns

:logical

`is`

get derivative type with given prototype

Arguments

type (:type)
prototype (:dictionary,:block)

Returns

:type

`is?`

check whether value is of given type

Arguments

type (:type,:block)
value (:any)

Returns

:logical

`label?`

checks if given value is of type :label

Arguments

value (:any)

Returns

:logical

`literal?`

checks if given value is of type :literal

Arguments

value (:any)

Returns

:logical

`logical?`

checks if given value is of type :logical

Arguments

value (:any)

Returns

:logical

`method?`

checks if given value is of type :method

Arguments

value (:any)

Returns

:logical

`null?`

checks if given value is of type :null

Arguments

value (:any)

Returns

:logical

`object?`

checks if given value is a custom-type object

Arguments

value (:any)

Returns

:logical

`path?`

checks if given value is of type :path

Arguments

value (:any)

Returns

:logical

`pathLabel?`

checks if given value is of type :pathLabel

Arguments

value (:any)

Returns

:logical

`pathLiteral?`

checks if given value is of type :pathLiteral

Arguments

value (:any)

Returns

:logical

`quantity?`

checks if given value is of type :quantity

Arguments

value (:any)

Options

big (:logical): check if, internally, it's a bignum

Returns

:logical

`range?`

checks if given value is of type :range

Arguments

value (:any)

Returns

:logical

`rational?`

checks if given value is of type :rational

Arguments

value (:any)

Options

big (:logical): check if, internally, it's a bignum

Returns

:logical

`regex?`

checks if given value is of type :regex

Arguments

value (:any)

Returns

:logical

`socket?`

checks if given value is of type :socket

Arguments

value (:any)

Returns

:logical

`sortable`

create a sort descriptor method automatically using given type field

Arguments

field (:literal)

Returns

:method

`store?`

checks if given value is of type :store

Arguments

value (:any)

Returns

:logical

`string?`

checks if given value is of type :string

Arguments

value (:any)

Returns

:logical

`symbol?`

checks if given value is of type :symbol

Arguments

value (:any)

Returns

:logical

`symbolLiteral?`

checks if given value is of type :symbolLiteral

Arguments

value (:any)

Returns

:logical

`to`

convert value to given type

Arguments

type (:type,:block)
value (:any)

Options

format (:string): use given format (for dates or floating-point numbers)
unit (:string,:literal): use given unit (for quantities)
intrepid (:logical): convert to bytecode without error-line tracking
hsl (:logical): convert HSL block to color
hsv (:logical): convert HSV block to color

Returns

:any

`type`

get type of given value

Arguments

value (:any)

Returns

:type

`type?`

checks if given value is of type :type

Arguments

value (:any)

Returns

:logical

`unit?`

checks if given value is of type :unit

Arguments

value (:any)

Returns

:logical

`version?`

checks if given value is of type :version

Arguments

value (:any)

Returns

:logical

`word?`

checks if given value is of type :word

Arguments

value (:any)

Returns

:logical

Ui

UI- and webview-related helpers

`alert`

show notification with given title and message

Arguments

title (:string)
message (:string)

Options

info (:logical): show informational notification
warning (:logical): show notification as a warning
error (:logical): show notification as an error

Returns

:nothing

`clip`

set clipboard content to given text

Arguments

content (:string)

Returns

:nothing

`dialog`

show a file selection dialog and return selection

Arguments

title (:string)

Options

folder (:logical): select folders instead of files
path (:string): use given starting path

Returns

:string

`popup`

show popup dialog with given title and message and return result

Arguments

title (:string)
message (:string)

Options

info (:logical): show informational popup
warning (:logical): show popup as a warning
error (:logical): show popup as an error
question (:logical): show popup as a question
ok (:logical): show an OK dialog (default)
okCancel (:logical): show an OK/Cancel dialog
yesNo (:logical): show a Yes/No dialog
yesNoCancel (:logical): show a Yes/No/Cancel dialog
retryCancel (:logical): show a Retry/Cancel dialog
retryAbortIgnore (:logical): show an Abort/Retry/Ignore dialog
literal (:logical): return the literal value of the pressed button

Returns

:logical,:literal

`unclip`

get clipboard content

Returns

:string

`webview`

show webview window with given url or html source

Arguments

content (:string,:literal)

Options

title (:string): set window title
width (:integer): set window width
height (:integer): set window height
fixed (:logical): window shouldn't be resizable
maximized (:logical): start in maximized mode
fullscreen (:logical): start in fullscreen mode
borderless (:logical): show as borderless window
topmost (:logical): set window as always-on-top
debug (:logical): add inspector console
on (:dictionary): execute code on specific events
inject (:string): inject JS code on webview initialization

Returns

:nothing

drkameleon/arturo-ai-training.md

Arturo Programming language

Language overview

Introduction

The basics

Words

Labels

Symbols

Attributes

:attribute

:attributeLabel

More Values

:null

:logical

:integer

:floating

:complex

:rational

:version

:type

:char

:string

:range

:regex

:path

:pathLabel

:literal

:symbolLiteral

:pathLiteral

:inline

:block

:dictionary

:store

:object

:function

:method

:unit

:quantity

:color

:date

:database

:socket

:binary

:bytecode

Important concepts

Precedence and Evaluation

The right-to-left rule

Scope and rules

Blocks

Iterators

Functions

In-place variable modification

Using literals

Syntactic sugar

Right-arrow operator: `->`

Fat right-arrow operator: `=>`

Double-colon operator: `::`

Exclamation-mark operator: `!`

Pipe operator: `|`

Conclusion

Example program

Standard library

Arithmetic

add (alias: + - infix: true)

Arguments

Returns

dec

Arguments

Returns

div (alias: / - infix: true)

Arguments

Returns

divmod (alias: /% - infix: true)

Arguments

Returns

fdiv (alias: // - infix: true)

Arguments

Returns

inc

Arguments

`add` (alias: `+` - infix: true)

`dec`

`div` (alias: `/` - infix: true)

`divmod` (alias: `/%` - infix: true)

`fdiv` (alias: `//` - infix: true)

`inc`

`mod` (alias: `%` - infix: true)

`mul` (alias: `*` - infix: true)

`neg`

`pow` (alias: `^` - infix: true)

`sub` (alias: `-` - infix: true)

`and`

`nand`

`nor`

`not`

`or`

`shl`

`shr`

`xnor`

`xor`

`append` (alias: `++` - infix: true)

`array` (alias: `@` - infix: false)

`chop`

`combine`

`contains?`

`couple`