From 2d00f7fd9f9098f45c53b5174d26246bae23d364 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yanis=20Zafir=C3=B3pulos?= <1265028+drkameleon@users.noreply.github.com> Date: Sat, 23 Nov 2024 11:33:21 +0100 Subject: [PATCH 01/24] Core\when?: added deprecation notice --- src/library/Core.nim | 1 + 1 file changed, 1 insertion(+) diff --git a/src/library/Core.nim b/src/library/Core.nim index bf00cc0974..c14795c2a4 100644 --- a/src/library/Core.nim +++ b/src/library/Core.nim @@ -1738,6 +1738,7 @@ proc defineLibrary*() = attrs = NoAttrs, returns = {Logical}, example = """ + ; DEPRECATED! a: 2 case [a] when? [<2] -> print "a is less than 2" From 19e37fafccba3d0087f799d5a10ac59202e3ce2c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yanis=20Zafir=C3=B3pulos?= <1265028+drkameleon@users.noreply.github.com> Date: Sat, 23 Nov 2024 11:33:45 +0100 Subject: [PATCH 02/24] fixed In a nutshell guide --- .../pages/documentation/in a nutshell.art | 77 ++++++++++++++----- 1 file changed, 58 insertions(+), 19 deletions(-) diff --git a/docs/website/pages/documentation/in a nutshell.art b/docs/website/pages/documentation/in a nutshell.art index ebad301eb5..9f9e78bd92 100644 --- a/docs/website/pages/documentation/in a nutshell.art +++ b/docs/website/pages/documentation/in a nutshell.art @@ -34,7 +34,7 @@ c3: {: :} ; characters -ch: `c` +ch: 'c' ; blocks/arrays d: [1 2 3] @@ -59,11 +59,23 @@ 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 ;--------------------------------- @@ -127,23 +139,47 @@ and? [1=2][2<3] ; => false if 2 > 1 [ print "yes!"] ; yes! if 3 <> 2 -> print "true!" ; true! -; if/else statements -; note it's 'if?' not 'if' -if? 2 > 3 -> print "2 is greater than 3" -else -> print "2 is not greater than 3" ; 2 is not greater than 3 - ; 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) +a: (2 > 3)? -> "yes" -> "no" ; a: "no" (exactly the same as above) + +; case statements +key: "one" -; case/when statements -case [1] - when? [>2] -> print "1 is greater than 2. what?!" - when? [<0] -> print "1 is less than 0. nope..." - else -> print "here we are!" ; here we are! +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 @@ -173,7 +209,7 @@ 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 -> +loop 'a'..'c' 'ch -> print ch ; a ; b @@ -198,7 +234,7 @@ loop dict [key value][ ; age -> 34 ; while loops -i: new 0 +i: 0 while [i<3][ print ["i =" i] inc 'i @@ -297,14 +333,17 @@ 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: new [] +arr: [] 'arr ++ "one" 'arr ++ "two" print arr ; one two ; remove elements from an array -arr: new ["one" "two" "three" "four"] +arr: ["one" "two" "three" "four"] 'arr -- "two" ; arr: ["one" "three" "four"] remove 'arr .index 0 ; arr: ["three" "four"] @@ -327,7 +366,7 @@ 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 map 1..10 => [2*] ; same as above ; selecting/filtering array values @@ -400,8 +439,8 @@ sayHello: function [this :person][ ] ; 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 +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 From 0090613a28d38644c7242461180816ba2584f91d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yanis=20Zafir=C3=B3pulos?= <1265028+drkameleon@users.noreply.github.com> Date: Sat, 23 Nov 2024 11:37:57 +0100 Subject: [PATCH 03/24] update syntax for character literals --- docs/website/pages/documentation/language.art | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/website/pages/documentation/language.art b/docs/website/pages/documentation/language.art index 5482fabb04..f8d0ebfd26 100644 --- a/docs/website/pages/documentation/language.art +++ b/docs/website/pages/documentation/language.art @@ -237,7 +237,7 @@ if (type x) = :integer [ print "it's an integer!" ] Characters in Arturo can be declared using backticks: `` `\w` `` ```red -ch: `a` +ch: 'a' ```

:string

From fc3cbfd5ba0ac0e51e9bf395ec1659ab28a5176d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yanis=20Zafir=C3=B3pulos?= <1265028+drkameleon@users.noreply.github.com> Date: Sat, 23 Nov 2024 11:43:40 +0100 Subject: [PATCH 04/24] minor fixes re: Paths + more examples for PathLabels --- docs/website/pages/documentation/language.art | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/website/pages/documentation/language.art b/docs/website/pages/documentation/language.art index f8d0ebfd26..3c58b905a9 100644 --- a/docs/website/pages/documentation/language.art +++ b/docs/website/pages/documentation/language.art @@ -357,7 +357,7 @@ or ```red x: "name" -print user\(x) +print user\[x] ``` or @@ -383,6 +383,10 @@ 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" ``` From e66472a4630b9b06f4803c977b518e3a3c0a35af Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yanis=20Zafir=C3=B3pulos?= <1265028+drkameleon@users.noreply.github.com> Date: Sat, 23 Nov 2024 11:49:14 +0100 Subject: [PATCH 05/24] added better example for right-to-left evaluation rules --- docs/website/pages/documentation/language.art | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/website/pages/documentation/language.art b/docs/website/pages/documentation/language.art index 3c58b905a9..db211a21d1 100644 --- a/docs/website/pages/documentation/language.art +++ b/docs/website/pages/documentation/language.art @@ -647,6 +647,23 @@ 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. + +```red +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: + +```red +(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. From e7cd5ff31af2334cc44cd7ea2747af4136353dba Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yanis=20Zafir=C3=B3pulos?= <1265028+drkameleon@users.noreply.github.com> Date: Sat, 23 Nov 2024 11:50:25 +0100 Subject: [PATCH 06/24] update function scope explanation --- docs/website/pages/documentation/language.art | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/website/pages/documentation/language.art b/docs/website/pages/documentation/language.art index db211a21d1..f38195c4bb 100644 --- a/docs/website/pages/documentation/language.art +++ b/docs/website/pages/documentation/language.art @@ -725,9 +725,9 @@ The general idea is: - 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 of the function, we can use the `.export` option. +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 `.exportable` option. +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

From 3f7a25eaca15d102fde3ddf711061fb78bec01ad Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yanis=20Zafir=C3=B3pulos?= <1265028+drkameleon@users.noreply.github.com> Date: Sat, 23 Nov 2024 11:52:27 +0100 Subject: [PATCH 07/24] fixed documentation re: syntax sugar --- docs/website/pages/documentation/language.art | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/website/pages/documentation/language.art b/docs/website/pages/documentation/language.art index f38195c4bb..5bf94febf7 100644 --- a/docs/website/pages/documentation/language.art +++ b/docs/website/pages/documentation/language.art @@ -917,11 +917,11 @@ This equivalent to: ```red print 1..10 ``` -Or a bit more elaborate example (using *pipes* and the `=>` operator): +Or a bit more elaborate example (using *pipes* and the `->`/`=>` operators): ```red -1..10 | map => 2* - | select => even? +1..10 | map => [2 * &] + | select 'x -> even? x | print ``` From 41e5fe849100eb635a92d6b1be9f9bedd0bac14d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yanis=20Zafir=C3=B3pulos?= <1265028+drkameleon@users.noreply.github.com> Date: Sat, 23 Nov 2024 11:55:04 +0100 Subject: [PATCH 08/24] added extra example for custom types --- docs/website/pages/documentation/language.art | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/website/pages/documentation/language.art b/docs/website/pages/documentation/language.art index 5bf94febf7..55d3f81d89 100644 --- a/docs/website/pages/documentation/language.art +++ b/docs/website/pages/documentation/language.art @@ -232,6 +232,17 @@ or 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. +> ```red +> define :person [ +> init: method [name :string][ +> \name: name +> ] +> ] +> p: to :person ["John"]! +> print p\name ; John +> ``` +

:char

Characters in Arturo can be declared using backticks: `` `\w` `` From 9b7e41b747fd9d5f49b5e0b41c6eec2311e9c00e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yanis=20Zafir=C3=B3pulos?= <1265028+drkameleon@users.noreply.github.com> Date: Sat, 23 Nov 2024 11:58:42 +0100 Subject: [PATCH 09/24] added documentation for `\shortcut` labels --- docs/website/pages/documentation/language.art | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/website/pages/documentation/language.art b/docs/website/pages/documentation/language.art index 55d3f81d89..5edbf2e218 100644 --- a/docs/website/pages/documentation/language.art +++ b/docs/website/pages/documentation/language.art @@ -401,6 +401,17 @@ 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. +> ```red +> 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. :) +

:inline

*Inline*s 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). From e570f2f12951174a9ba3fac3d9244f043c1a55a1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yanis=20Zafir=C3=B3pulos?= <1265028+drkameleon@users.noreply.github.com> Date: Sat, 23 Nov 2024 12:01:45 +0100 Subject: [PATCH 10/24] added example for Rational literals --- docs/website/pages/documentation/language.art | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/website/pages/documentation/language.art b/docs/website/pages/documentation/language.art index 5edbf2e218..897e940635 100644 --- a/docs/website/pages/documentation/language.art +++ b/docs/website/pages/documentation/language.art @@ -194,7 +194,14 @@ print a + b

:rational

-As with complex numbers, rationals can be defined using `to`. And again, Arturo comes with full support for rational numbers and all the associated operations. +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). + +```red +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. ```red a: to :rational [1 2] ; 1/2 From c3fc2d3a93616d85bd50c74d09533e091f827440 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yanis=20Zafir=C3=B3pulos?= <1265028+drkameleon@users.noreply.github.com> Date: Sat, 23 Nov 2024 12:06:31 +0100 Subject: [PATCH 11/24] added section for Range values --- docs/website/pages/documentation/language.art | 22 +++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/docs/website/pages/documentation/language.art b/docs/website/pages/documentation/language.art index 897e940635..e4bdcd4509 100644 --- a/docs/website/pages/documentation/language.art +++ b/docs/website/pages/documentation/language.art @@ -21,6 +21,7 @@ Here, you'll find everything you may need to know about the language (and perhap - [:type](#type) - [:char](#char) - [:string](#string) + - [:range](#range) - [:regex](#regex) - [:literal](#literal) - [:symbolLiteral](#symbolLiteral) @@ -317,6 +318,27 @@ A string is nothing but a series of characters, seen as one unit. In Arturo, to > ; 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): + +```red +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: + +```red +@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). From 745cc2885582b1970c32b14f934000ba6e652951 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yanis=20Zafir=C3=B3pulos?= <1265028+drkameleon@users.noreply.github.com> Date: Sat, 23 Nov 2024 12:25:25 +0100 Subject: [PATCH 12/24] added documentation for methods, including Magic methods --- docs/website/pages/documentation/language.art | 91 +++++++++++++++++++ 1 file changed, 91 insertions(+) diff --git a/docs/website/pages/documentation/language.art b/docs/website/pages/documentation/language.art index e4bdcd4509..2860437771 100644 --- a/docs/website/pages/documentation/language.art +++ b/docs/website/pages/documentation/language.art @@ -31,6 +31,7 @@ Here, you'll find everything you may need to know about the language (and perhap - [:block](#block) - [:dictionary](#dictionary) - [:function](#function) + - [:method](#method) - [:color](#color) - [:date](#date) - [:database](#database) @@ -530,6 +531,96 @@ 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: + +```red +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: + +``` +```red +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 +``` +

: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`: From 202e997ffb8982e658c1268b56697ef752a62ca2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yanis=20Zafir=C3=B3pulos?= <1265028+drkameleon@users.noreply.github.com> Date: Sat, 23 Nov 2024 12:30:20 +0100 Subject: [PATCH 13/24] added complete list of recognized symbols --- docs/website/pages/documentation/language.art | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/website/pages/documentation/language.art b/docs/website/pages/documentation/language.art index 2860437771..2b6c64da28 100644 --- a/docs/website/pages/documentation/language.art +++ b/docs/website/pages/documentation/language.art @@ -135,6 +135,12 @@ Some of the existing *aliases* in the built-in dictionary: %ALIAS_LIST% +**All valid symbols**: + +``` +<=, =>, <=>, <<=, =>>, <<=>>, <-, ->, <->, <<-, ->>, <<->>, -<, >-, >-<, -<<, >>-, >>-<<, <<, >>, <<<, >>>, <--, -->, <-->, <==, ==>, <==>, <~, ~>, <~>, |>, <|, <|>, =<, >=, <>, <:, -:, >:, ~, !, !!, ?, ??, @, #, ##, ###, ####, #####, ######, $, %, ^, &, *, **, -, --, =, ==, =~, +, ++, <, >, /, /%, //, \\, \\\\, |, |-, |=, .., ..., ./, :, ::, :=, ||, ∅, ∞, ∑, ∏, ∩, ∪, ⊂, ⊃, ⊆, ⊇, ∈, ∉, ∧, ∨, ⊻, ⊼, ¬ +``` + > 💡 For the complete of recognized symbols in Arturo, you may have a look at here.

Values

From 1838758a97da078abb7a3a2be79782d6337a89ec Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yanis=20Zafir=C3=B3pulos?= <1265028+drkameleon@users.noreply.github.com> Date: Sat, 23 Nov 2024 12:34:02 +0100 Subject: [PATCH 14/24] added better example for Bytecode --- docs/website/pages/documentation/language.art | 35 ++++++++++++++++--- 1 file changed, 30 insertions(+), 5 deletions(-) diff --git a/docs/website/pages/documentation/language.art b/docs/website/pages/documentation/language.art index 2b6c64da28..c9b1b5dd0a 100644 --- a/docs/website/pages/documentation/language.art +++ b/docs/website/pages/documentation/language.art @@ -680,14 +680,39 @@ Bytecode values cannot be constructed literally. However, you can create them in ```red ; let's create some Arturo bytecode from scratch -x: to :bytecode [ - ["print"] ; first block contains our constants - [1 112 155] ; second block contains the opcodes to be executed, - ; in this case: ConstI1 (0x01), Call (0x70), End (0x9B) +bcode: to :bytecode [ + loop 1..10 'x [ + print x + ] ] ; and execute it! -do x ; this will simply print... 1 +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 +; ] ```

Attributes

From b2440e1592574b547da297e601ac9bcbc09cb800 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yanis=20Zafir=C3=B3pulos?= <1265028+drkameleon@users.noreply.github.com> Date: Sat, 23 Nov 2024 12:35:22 +0100 Subject: [PATCH 15/24] minor fix --- docs/website/pages/documentation/language.art | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/website/pages/documentation/language.art b/docs/website/pages/documentation/language.art index c9b1b5dd0a..99ee1e0657 100644 --- a/docs/website/pages/documentation/language.art +++ b/docs/website/pages/documentation/language.art @@ -260,7 +260,7 @@ if (type x) = :integer [ print "it's an integer!" ]

:char

-Characters in Arturo can be declared using backticks: `` `\w` `` +Characters in Arturo can be declared using single quotes: `'\w'` ```red ch: 'a' From b3e06e0f4aa164746d78ca1e1ab48d37879f94a0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yanis=20Zafir=C3=B3pulos?= <1265028+drkameleon@users.noreply.github.com> Date: Sat, 23 Nov 2024 12:51:14 +0100 Subject: [PATCH 16/24] added documentation for Unit & Quantity values --- docs/website/pages/documentation/language.art | 54 +++++++++++++++++++ 1 file changed, 54 insertions(+) diff --git a/docs/website/pages/documentation/language.art b/docs/website/pages/documentation/language.art index 99ee1e0657..a1ebcb1edc 100644 --- a/docs/website/pages/documentation/language.art +++ b/docs/website/pages/documentation/language.art @@ -32,6 +32,8 @@ Here, you'll find everything you may need to know about the language (and perhap - [:dictionary](#dictionary) - [:function](#function) - [:method](#method) + - [:unit](#unit) + - [:quantity](#quantity) - [:color](#color) - [:date](#date) - [:database](#database) @@ -627,6 +629,58 @@ 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: + +```red +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: + +```red +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: + +```red +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`: From dc1fec3a77dea70dbf685f2a97d1119f5fef8263 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yanis=20Zafir=C3=B3pulos?= <1265028+drkameleon@users.noreply.github.com> Date: Sat, 23 Nov 2024 13:12:11 +0100 Subject: [PATCH 17/24] added documentation for Exclamation-mark operator --- docs/website/pages/documentation/language.art | 49 +++++++++++++++++++ 1 file changed, 49 insertions(+) diff --git a/docs/website/pages/documentation/language.art b/docs/website/pages/documentation/language.art index a1ebcb1edc..267b56e0e5 100644 --- a/docs/website/pages/documentation/language.art +++ b/docs/website/pages/documentation/language.art @@ -53,6 +53,8 @@ Here, you'll find everything you may need to know about the language (and perhap - [Syntactic sugar](#syntactic-sugar) * [Right-arrow operator: `->`](#right-arrow-operator) * [Fat right-arrow operator: `=>`](#fat-right-arrow-operator) + * [Double-colon operator: `::`](#double-colon-operator) + * [Exclamation-mark operator: `!`](#exclamation-mark-operator) * [Pipe operator: `|`](#pipe-operator) - [Conclusion](#conclusion) @@ -1126,6 +1128,53 @@ 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: + +```red +do [ + print :: + "This is a number:" + 123 +] +``` + +Is equivalent to: + +```red +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: `|`

From 89e7eff57177c89452cdeb04a7e980eb43e7db87 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yanis=20Zafir=C3=B3pulos?= <1265028+drkameleon@users.noreply.github.com> Date: Sat, 23 Nov 2024 13:22:55 +0100 Subject: [PATCH 18/24] restructured the whole document --- docs/website/pages/documentation/language.art | 139 +++++++++--------- 1 file changed, 72 insertions(+), 67 deletions(-) diff --git a/docs/website/pages/documentation/language.art b/docs/website/pages/documentation/language.art index 267b56e0e5..0b76a5f356 100644 --- a/docs/website/pages/documentation/language.art +++ b/docs/website/pages/documentation/language.art @@ -6,11 +6,14 @@ Here, you'll find everything you may need to know about the language (and perhap --- - [Introduction](#introduction) -- [The main components](#the-main-components) +- [The basics](#the-basics) * [Words](#words) * [Labels](#labels) * [Symbols](#symbols) - * [Values](#values) + * [Attributes](#attributes) + - [:attribute](#attribute) + - [:attributeLabel](#attributeLabel) + * [More values](#more-values) - [:null](#null) - [:logical](#logical) - [:integer](#integer) @@ -39,17 +42,15 @@ Here, you'll find everything you may need to know about the language (and perhap - [:database](#database) - [:binary](#binary) - [:bytecode](#bytecode) - * [Attributes](#attributes) - - [:attribute](#attribute) - - [:attributeLabel](#attributeLabel) -- [Precedence and evaluation](#precedence-and-evaluation) - * [The right-to-left rule](#the-right-to-left-rule) -- [Scope and rules](#scope-and-rules) - * [Blocks](#blocks) - * [Iterators](#iterators) - * [Functions](#functions) -- [In-place variable modification](#in-place-variable-modification) - * [Using literals](#using-literals) +- [Important concepts](#important-concepts) + * [Precedence and evaluation](#precedence-and-evaluation) + - [The right-to-left rule](#the-right-to-left-rule) + * [Scope and rules](#scope-and-rules) + - [Blocks](#blocks) + - [Iterators](#iterators) + - [Functions](#functions) + * [In-place variable modification](#in-place-variable-modification) + - [Using literals](#using-literals) - [Syntactic sugar](#syntactic-sugar) * [Right-arrow operator: `->`](#right-arrow-operator) * [Fat right-arrow operator: `=>`](#fat-right-arrow-operator) @@ -75,11 +76,11 @@ Let's try to resume some key points of Arturo's no-syntax: As you can see, there is not much to learn from scratch here: -Once you learn what the language [**main components**](#the-main-components) are & a few details about **[precedence and evaluation](#precedence-and-evaluation)**, then only with the [**Library Reference**](../library/) at hand (the built-in functions that are already there for you, available to use), you're pretty much ready to write *any* program. ;-) +Once you learn what the language [**building blocks**](#the-basics) are & a few details about **[precedence and evaluation](#precedence-and-evaluation)**, then only with the [**Library Reference**](../library/) 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 main components

+

The basics

Words

@@ -145,9 +146,51 @@ Some of the existing *aliases* in the built-in dictionary: <=, =>, <=>, <<=, =>>, <<=>>, <-, ->, <->, <<-, ->>, <<->>, -<, >-, >-<, -<<, >>-, >>-<<, <<, >>, <<<, >>>, <--, -->, <-->, <==, ==>, <==>, <~, ~>, <~>, |>, <|, <|>, =<, >=, <>, <:, -:, >:, ~, !, !!, ?, ??, @, #, ##, ###, ####, #####, ######, $, %, ^, &, *, **, -, --, =, ==, =~, +, ++, <, >, /, /%, //, \\, \\\\, |, |-, |=, .., ..., ./, :, ::, :=, ||, ∅, ∞, ∑, ∏, ∩, ∪, ⊂, ⊃, ⊆, ⊇, ∈, ∉, ∧, ∨, ⊻, ⊼, ¬ ``` -> 💡 For the complete of recognized symbols in Arturo, you may have a look at here. +

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: +```red +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 `:char`s. + +What if we want for example to split the string into words? For that, there is the `.words` attribute for the function `split`. So: + +```red +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: + +```red +split .every: 2 "hello world" + +; => ["he" "ll" "ow" "or" "ld"] +``` -

Values

+

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. @@ -155,7 +198,7 @@ Values are the very core of Arturo and are used to refer to pretty much all the 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 complete list follows: +The (hopefully) complete list follows:

:null

@@ -771,51 +814,13 @@ inspect bcode ; ] ``` -

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. +

Important concepts

-There are two types: +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. - 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: -```red -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 `:char`s. - -What if we want for example to split the string into words? For that, there is the `.words` attribute for the function `split`. So: - -```red -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: - -```red -split .every: 2 "hello world" - -; => ["he" "ll" "ow" "or" "ld"] -``` +So, let's get started... -

Precedence and Evaluation

+

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. @@ -823,7 +828,7 @@ So, in an expression like `2 * 3 + 4`, if you'd normally expect to get a result But in order to understand why, you'd have to understand how evaluation in Arturo works. -

The right-to-left rule

+

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. @@ -893,7 +898,7 @@ The correct code in that case would be: (to :string 3) ++ " <-- this is our number" ``` -

Scope and rules

+

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. @@ -901,7 +906,7 @@ Generally, if a variable has been previously declared at the moment and location But let's see a couple of concrete cases to make this clearer. -

Blocks

+

Blocks

Arturo doesn't have a block scope. @@ -925,7 +930,7 @@ print x ; prints 2 (the value of x has been changed) print y ; prints 3 (the value of y is still available) ``` -

Iterators

+

Iterators

Iterators (such as `loop`, `map`, etc) always work with a block as well. But in a special way. @@ -944,7 +949,7 @@ print i ; ERROR: variable not found ; (i is not available anymore) ``` -

Functions

+

Functions

Functions are totally different. Why? Because they do have their own scope. @@ -958,7 +963,7 @@ If we want to *export* a specific symbol to the outer scope, that is, make it av 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-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). @@ -984,7 +989,7 @@ 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

+

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. From 89428d7aaca93f98f38809b62f53eaadf201f8c0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yanis=20Zafir=C3=B3pulos?= <1265028+drkameleon@users.noreply.github.com> Date: Sat, 23 Nov 2024 13:29:17 +0100 Subject: [PATCH 19/24] added documentation for Object values --- docs/website/pages/documentation/language.art | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/docs/website/pages/documentation/language.art b/docs/website/pages/documentation/language.art index 0b76a5f356..46e01cab10 100644 --- a/docs/website/pages/documentation/language.art +++ b/docs/website/pages/documentation/language.art @@ -33,6 +33,7 @@ Here, you'll find everything you may need to know about the language (and perhap - [:inline](#inline) - [:block](#block) - [:dictionary](#dictionary) + - [:object](#object) - [:function](#function) - [:method](#method) - [:unit](#unit) @@ -198,7 +199,7 @@ Values are the very core of Arturo and are used to refer to pretty much all the 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: +The (hopefully) complete list follows.

:null

@@ -557,6 +558,22 @@ What the `#` function here does is: > 💡 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 +

: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: + +```red +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. From 28cb1fc1b088c0a16b65bd4383f0bfb97534d886 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yanis=20Zafir=C3=B3pulos?= <1265028+drkameleon@users.noreply.github.com> Date: Sat, 23 Nov 2024 13:32:31 +0100 Subject: [PATCH 20/24] added documentation for Socket values --- docs/website/pages/documentation/language.art | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/docs/website/pages/documentation/language.art b/docs/website/pages/documentation/language.art index 46e01cab10..254b8f2eaa 100644 --- a/docs/website/pages/documentation/language.art +++ b/docs/website/pages/documentation/language.art @@ -41,6 +41,7 @@ Here, you'll find everything you may need to know about the language (and perhap - [:color](#color) - [:date](#date) - [:database](#database) + - [:socket](#socket) - [:binary](#binary) - [:bytecode](#bytecode) - [Important concepts](#important-concepts) @@ -780,6 +781,19 @@ 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`: + +```red +; 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. From 54a0dc920b73ce1e30b2629fa944758b5fa9e38b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yanis=20Zafir=C3=B3pulos?= <1265028+drkameleon@users.noreply.github.com> Date: Sat, 23 Nov 2024 13:37:44 +0100 Subject: [PATCH 21/24] added documentation for Store values --- docs/website/pages/documentation/language.art | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/docs/website/pages/documentation/language.art b/docs/website/pages/documentation/language.art index 254b8f2eaa..611113b155 100644 --- a/docs/website/pages/documentation/language.art +++ b/docs/website/pages/documentation/language.art @@ -33,6 +33,7 @@ Here, you'll find everything you may need to know about the language (and perhap - [:inline](#inline) - [:block](#block) - [:dictionary](#dictionary) + - [:store](#store) - [:object](#object) - [:function](#function) - [:method](#method) @@ -542,7 +543,8 @@ x: [

:dictionary

-Dictionaries in Arturo as what in other languages you'd call an *associative array* or *hash table*. 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. +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. ```red user: #[ @@ -559,6 +561,21 @@ What the `#` function here does is: > 💡 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. :) + +```red +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. From 3202aa4aeaa2491fafe24d08a9d0d1fa286aec26 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yanis=20Zafir=C3=B3pulos?= <1265028+drkameleon@users.noreply.github.com> Date: Sat, 23 Nov 2024 13:40:32 +0100 Subject: [PATCH 22/24] minor edits + added documentatin for Path literals --- docs/website/pages/documentation/language.art | 61 +++++++++++-------- 1 file changed, 36 insertions(+), 25 deletions(-) diff --git a/docs/website/pages/documentation/language.art b/docs/website/pages/documentation/language.art index 611113b155..8cbc4eaaef 100644 --- a/docs/website/pages/documentation/language.art +++ b/docs/website/pages/documentation/language.art @@ -26,10 +26,11 @@ Here, you'll find everything you may need to know about the language (and perhap - [:string](#string) - [:range](#range) - [:regex](#regex) - - [:literal](#literal) - - [:symbolLiteral](#symbolLiteral) - [:path](#path) - [:pathLabel](#pathLabel) + - [:literal](#literal) + - [:symbolLiteral](#symbolLiteral) + - [:pathLiteral](#pathLiteral) - [:inline](#inline) - [:block](#block) - [:dictionary](#dictionary) @@ -419,29 +420,6 @@ While we may - optionally - use any of the supported PCRE-compliant flags: match "Hello" {/he/i} ; => ["He"] ``` -

: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+]` - -```red -func: 'print -info func -``` - -However, literals may be used for much more - e.g. modifying a passed parameter in-place, without having to re-assign the result of an operation to a new variable. To learn more, have a look at **[In-place variable modification](#in-place-variable-modification)**. - -

: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: - -```red -type '++ ; => :symbolliteral -``` -

: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. @@ -498,6 +476,39 @@ print user\name ; ok, now it should print "Jane" > ``` > 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+]` + +```red +func: 'print +info func +``` + +However, literals may be used for much more - e.g. modifying a passed parameter in-place, without having to re-assign the result of an operation to a new variable. To learn more, have a look at **[In-place variable modification](#in-place-variable-modification)**. + +

: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: + +```red +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: + +```red +type 'this\is\a\path ; => :pathliteral +``` +

:inline

*Inline*s 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). From 335f7b4cf31cedb5be4c89c25d675c85b2fb4505 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yanis=20Zafir=C3=B3pulos?= <1265028+drkameleon@users.noreply.github.com> Date: Sat, 23 Nov 2024 13:48:51 +0100 Subject: [PATCH 23/24] updated package-related documentation --- .../pages/documentation/command line.art | 58 ++++++++----------- 1 file changed, 24 insertions(+), 34 deletions(-) diff --git a/docs/website/pages/documentation/command line.art b/docs/website/pages/documentation/command line.art index 112d93cd62..29d2d2f6ae 100644 --- a/docs/website/pages/documentation/command line.art +++ b/docs/website/pages/documentation/command line.art @@ -11,12 +11,11 @@ The command line is where the whole journey starts: whether you want to try out * [Start the interactive console](#start-the-interactive-console) * [Working with bytecode](#working-with-bytecode) - [Package manager](#package-manager) - * [List available modules](#list-available-modules) - * [List remote modules](#list-remote-modules) - * [Get module info](#get-module-info) - * [Install a new module](#install-a-new-module) - * [Uninstall a module](#uninstall-a-module) - * [Update existing modules](#update-existing-modules) + * [List available packages](#list-available-packages) + * [List remote packages](#list-remote-packages) + * [Install a new package](#install-a-new-package) + * [Uninstall a package](#uninstall-a-package) + * [Update all packages](#update-all-packages) --- @@ -66,63 +65,54 @@ This will output a `path/to/your/script.art.bcode` file. arturo -x path/to/your/script.art.bcode ``` -

Package manager Experimental

+

Package manager

Although Arturo's philosophy is batteries-included - so you'll most likely need nothing that is not already included - Arturo also comes with a ready-to-use package manager, to make your life even easier. -

List available modules

+

List available packages

-To list all available modules, just type: +To list all available packages, just type: ```bash -arturo -m list +arturo -p list ``` -This will show you all the modules you have installed locally. +This will show you all the packages you have installed locally.) -It looks like this: +

List remote packages

-![Module listing](https://arturo-lang.io/resources/images/module_list.png) - -

List remote modules

- -If you want to fetch a list of *all* modules available to download from the [official repository](https://github.com/arturo-lang/art-modules), just type: +If you want to fetch a list of *all* packages available to download from the [official repository](https://pkgr.art), just type: ```bash -arturo -m remote +arturo -p remote ``` -

Get module info

+

Install a new package

-Have you spotted a module you like and want to know more about it? That's easy: +To install a package ```bash -arturo -m info html +arturo -p install grafito ``` -

Install a new module

- -When you have finally decided you want to install a module, it's also easy: +> 💡 If you do e.g. `import 'grafito!` from within the REPL or your Arturo script, if the package isn't already installed, it'll automatically be taken care of - so, nothing to worry about! ;-) -```bash -arturo -m install html -``` -

Uninstall a module

+

Uninstall a package

-In order to uninstall a module you have previously, you just have to type: +In order to uninstall a package you have previously, you just have to type: ```bash -arturo -m uninstall html +arturo -p uninstall grafito ``` -

Update existing modules

+

Update all packages

-If you want to update all of your local modules, there's no reason to uninstall/reinstall anything. Just type: +If you want to update all of your local packages, there's no reason to uninstall/reinstall anything. Just type: ```bash -arturo -m update +arturo -p update ``` -And *all* of your modules will be automatically up-to-date. +And *all* of your packages will be automatically up-to-date. } \ No newline at end of file From 9954cda40fe43f635b447768ab44f398dbc84a53 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yanis=20Zafir=C3=B3pulos?= <1265028+drkameleon@users.noreply.github.com> Date: Sat, 23 Nov 2024 13:51:18 +0100 Subject: [PATCH 24/24] minor edit --- docs/website/pages/documentation/language.art | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/website/pages/documentation/language.art b/docs/website/pages/documentation/language.art index 8cbc4eaaef..243d5dd119 100644 --- a/docs/website/pages/documentation/language.art +++ b/docs/website/pages/documentation/language.art @@ -97,7 +97,7 @@ As with a real (spoken) language, every word has a specific meaning. And if you 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 close to 150 already defined such words/functions +- 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