all repos — min @ ac51420051e5f7bdd6c66d24024a237f70df2a02

A small but practical concatenative programming language.

Changed link macros.
h3rald h3rald@h3rald.com
Sun, 29 Sep 2024 11:53:34 +0200
commit

ac51420051e5f7bdd6c66d24024a237f70df2a02

parent

15996fe6d2635272cc1ff55aa0a6a556a5cd0a3f

M site/contents/_defs_.mdsite/contents/_defs_.md

@@ -100,7 +100,9 @@ {# link-page => [$2](/$1/) #}

{# link-module => [`$1` Module](/reference-$1/) #} -{# link-operator => [`$2`](/reference-$1#op-$2) #} +{# link-operator => [$1.$2`](/reference-$1#op-$2) #} + +{# link-global-operator => [`$1`](/reference-global#op-$1) #} {# link-learn => → Continue to [*$2*](/learn-$1) #}
M site/contents/get-started.mdsite/contents/get-started.md

@@ -72,11 +72,11 @@ #### -d:nopcre

If the **-d:nopcre** is specified when compiling, min will be built _without_ PCRE support, so it will not be possible to use regular expressions and the following symbols will _not_ be exposed by the {#link-module||global#}: -* {#link-operator||global||search#} -* {#link-operator||global||match?#} -* {#link-operator||global||search-all#} -* {#link-operator||global||replace#} -* {#link-operator||global||replace-apply#} +* {#link-global-operator||search#} +* {#link-global-operator||match?#} +* {#link-global-operator||search-all#} +* {#link-global-operator||replace#} +* {#link-global-operator||replace-apply#} ## Building a docker image

@@ -158,7 +158,7 @@ > %min-terminal%

> > [$](class:prompt) min compile myfile.min -n:&quot;-d:release --threadAnalysis:off --mm:refc&quot; -Additionally, you can also use `-m:<path>` (or `--module-path`) to specify one path containing [.min](class:ext) files which will be compiled as well (but not executed) along with the specified file. Whenever a {#link-operator||global||load#} or a {#link-operator||global||require#} symbol is used to load/require an external [.min](class:ext) file, it will attempt to retrieve its contents from the pre-loaded files first before searching the filesystem. +Additionally, you can also use `-m:<path>` (or `--module-path`) to specify one path containing [.min](class:ext) files which will be compiled as well (but not executed) along with the specified file. Whenever a {#link-global-operator||load#} or a {#link-global-operator||require#} symbol is used to load/require an external [.min](class:ext) file, it will attempt to retrieve its contents from the pre-loaded files first before searching the filesystem. For example, the following command executed in the root folder of the min project will compile [run.min](class:file) along with all [.min](class:ext) files included in the [tasks](class:dir) folder and its subfolders:

@@ -175,7 +175,7 @@ > In order to successfully compile [.min](class.ext) files, Nim must be installed on your system and min must be installed via nimble.

## Getting help on a min symbol -min comes with a built-in `help` command that can be used to print information on a specific symbol. Essentially, this is equivalent to use the {#link-operator||global||help#} symbol within the min REPL. +min comes with a built-in `help` command that can be used to print information on a specific symbol. Essentially, this is equivalent to use the {#link-global-operator||help#} symbol within the min REPL. > %min-terminal% >
M site/contents/learn-control-flow.mdsite/contents/learn-control-flow.md

@@ -12,10 +12,10 @@ ## Conditionals

The following symbols provide ways to implement common conditional statements: -* {#link-operator||global||case#} -* {#link-operator||global||if#} -* {#link-operator||global||unless#} -* {#link-operator||global||when#} +* {#link-global-operator||case#} +* {#link-global-operator||if#} +* {#link-global-operator||unless#} +* {#link-global-operator||when#} For example, consider the following program:

@@ -38,9 +38,9 @@ ## Loops

The following symbols provide ways to implement common loops: -* {#link-operator||global||foreach#} -* {#link-operator||global||times#} -* {#link-operator||global||while#} +* {#link-global-operator||foreach#} +* {#link-global-operator||times#} +* {#link-global-operator||while#} For example, consider the following program:

@@ -57,15 +57,15 @@ ) while

f ) ^factorial -This program defines a symbol `factorial` that calculates the factorial of an integer iteratively using the symbol {#link-operator||global||while#}. +This program defines a symbol `factorial` that calculates the factorial of an integer iteratively using the symbol {#link-global-operator||while#}. ## Error handling The following symbols provide ways to manage errors in min: -* {#link-operator||global||format-error#} -* {#link-operator||global||raise#} -* {#link-operator||global||try#} +* {#link-global-operator||format-error#} +* {#link-global-operator||raise#} +* {#link-global-operator||try#} For example, consider the following program:
M site/contents/learn-data-types.mdsite/contents/learn-data-types.md

@@ -54,7 +54,7 @@ > The {#link-operator||dict||dtype#} operator can be used to set the type of a dictionary.

The {#link-module||global#} provides predicate operators to check if an element belongs to a particular data type or pseudo-type (`boolean?`, `number?`, `integer?`, `float?`, ...). -Additionally, the {#link-module||global#} provides operators to convert values from a data type to another (e.g. {#link-operator||global||integer#}, {#link-operator||global||string#}, and so on). +Additionally, the {#link-module||global#} provides operators to convert values from a data type to another (e.g. {#link-global-operator||integer#}, {#link-global-operator||string#}, and so on). > %note% > Note
M site/contents/learn-definitions.mdsite/contents/learn-definitions.md

@@ -14,7 +14,7 @@ swap fs.mtime now 3600 - >

This program takes a single string corresponding to a file path and returns true if it's a .zip file bigger than 1MB that was modified in the last hour. Sure, it is remarkable that no variables are needed for such a program, but it is not very readable: because no variables are used, it is often necessary to make copies of elements and push them to the end of the stack -- that's what the {#link-operator||stack||dup#} and {#link-operator||stack||swap#} are used for. -The good news is that you can use the {#link-operator||global||define#} operator and the `:` sigil to define new symbols, and symbols can also be set to fixed values (literals). +The good news is that you can use the {#link-global-operator||define#} operator and the `:` sigil to define new symbols, and symbols can also be set to fixed values (literals). Consider the following program:

@@ -24,7 +24,7 @@ filepath fs.size 1000000 >

filepath fs.mtime now 3600 - > and and -In this case, the `filepath` symbol is defined and then used on the following three lines, each of which defines a condition to be evaluated. The last line contains just two {#link-operator||global||and#} symbols necessary to compare the three conditions. +In this case, the `filepath` symbol is defined and then used on the following three lines, each of which defines a condition to be evaluated. The last line contains just two {#link-global-operator||and#} symbols necessary to compare the three conditions. ## Lexical scoping and binding

@@ -47,7 +47,7 @@ ...What is the value of the symbol `a` after executing it?

Simple: `4`. Every quotation defines its own scope, and in each scope, a new variable called `a` is defined. In the innermost scope containing the quotation `(a dup * :a)` the value of `a` is set to `64`, but this value is not propagated to the outer scopes. Note also that the value of `a` in the innermost scope is first retrieved from the outer scope (8). -If we want to change the value of the original `a` symbol defined in the outermost scope, we have to use the {#link-operator||global||bind#} or its shorthand sigil `@`, so that the program becomes the following: +If we want to change the value of the original `a` symbol defined in the outermost scope, we have to use the {#link-global-operator||bind#} or its shorthand sigil `@`, so that the program becomes the following: 4 :a ;First definition of the symbol a (

@@ -70,12 +70,12 @@ (5 :quote quote dup *) -> ;returns 25

...because the `quote` symbol is only defined in the root scope and can therefore be redefined in child scopes. -If you want, you can {#link-operator||global||seal#} your own symbols so that they may not be redefined using the {#link-operator||global||bind#} operator or deleted using the {#link-operator||global||delete#}. +If you want, you can {#link-global-operator||seal#} your own symbols so that they may not be redefined using the {#link-global-operator||bind#} operator or deleted using the {#link-global-operator||delete#}. > %note% > Note > -> The {#link-operator||global||unseal-symbol#} operator can be used to effectively un-seal a previously-sealed symbol. Use with caution! +> The {#link-global-operator||unseal-symbol#} operator can be used to effectively un-seal a previously-sealed symbol. Use with caution! {#link-learn||scopes||Scopes#}
M site/contents/learn-extending.mdsite/contents/learn-extending.md

@@ -16,7 +16,7 @@ ## Implementing new min modules using min itself

When you just want to create more high-level min operator using functionalities that are already available in min, the easiest way is to create your own reusable min modules. -To create a new module, simply create a file containing your operator definitions implemented using either the {#link-operator||global||operator#} operator or the {#link-operator||global||lambda#} operator +To create a new module, simply create a file containing your operator definitions implemented using either the {#link-global-operator||operator#} operator or the {#link-global-operator||lambda#} operator ``` (dup *) ^pow2

@@ -25,7 +25,7 @@ (dup * dup *) ^pow4

``` -Save your code to a file (e.g. *quickpows.min*) and you can use it in other Nim files using the {#link-operator||global||require#} operator and the {#link-operator||global||import#} (if you want to import the operators in the current scope): +Save your code to a file (e.g. *quickpows.min*) and you can use it in other Nim files using the {#link-global-operator||require#} operator and the {#link-global-operator||import#} (if you want to import the operators in the current scope): ``` 'quickpows require :qp

@@ -53,7 +53,7 @@ ; Unseal prompt symbol

'prompt unseal-symbol ``` -Essentially, this causes min to import *all* the modules and unseals the {#link-operator||global||prompt#} symbol so that it can be customized. If you want, you can provide your own prelude file to specify your custom behaviors, selectively import modules, and define your own symbols, like this: +Essentially, this causes min to import *all* the modules and unseals the {#link-global-operator||prompt#} symbol so that it can be customized. If you want, you can provide your own prelude file to specify your custom behaviors, selectively import modules, and define your own symbols, like this: > %min-terminal% > [$](class:prompt) min -i -p:myfile.min
M site/contents/learn-mmm.mdsite/contents/learn-mmm.md

@@ -28,7 +28,7 @@ The registry contains the metadata of all public managed modules and it is queried when running every mmm command (see below).

### Module lookup -When requiring a module in your min file using the {{#link-operator||global||require}} symbol, min will attempt to lookup the module (for example **module1**) checking the following files (in order): +When requiring a module in your min file using the {{#link-global-operator||require}} symbol, min will attempt to lookup the module (for example **module1**) checking the following files (in order): - module1.min - mmm/module1/*/index.min
M site/contents/learn-operators.mdsite/contents/learn-operators.md

@@ -21,7 +21,7 @@ * Contain zero or more letters, numbers and/or any of the following characters: `/ ! ? + * _ -`

If a symbol contains a dot (`.`) then it is namespaced by its containing module or dictionary. For example, `fs.dirname` identifies the {{#link-operator||fs||dirname}} operator defined in the {{#link-module||fs}} module. -It is possible to define operator symbols using the {#link-operator||global||operator#} symbol. The following min program defines a new symbol called square that duplicates the first element on the stack and multiplies the two elements: +It is possible to define operator symbols using the {#link-global-operator||operator#} symbol. The following min program defines a new symbol called square that duplicates the first element on the stack and multiplies the two elements: ( symbol square

@@ -30,23 +30,23 @@ (n dup * @result)

) operator ;; Calculates the square of n. - The {#link-operator||global||operator#} symbol provides way to: + The {#link-global-operator||operator#} symbol provides way to: * Specify the name of the symbol operator (**square** in this case) * Specify a signature to identify the type of the input and output values (in this case, the operator takes a numeric input value and produces a numeric output value). Also, note how inputs and outputs are captured into the `n` and `result` symbols in the signature quotation and then referenced in the body quotation. * Specify a quotation containing the code that the operator will execute. -Also, symbol operator definitions can be annotated with documentation comments (starting with `;;` or wrapped in `#|| ... ||#`)) so that a help text can be displayed using the {#link-operator||global||help#} symbol. +Also, symbol operator definitions can be annotated with documentation comments (starting with `;;` or wrapped in `#|| ... ||#`)) so that a help text can be displayed using the {#link-global-operator||help#} symbol. ### Using the lambda operator -Sometimes you just want to bind a piece of code to a symbol to reuse it later, typically something simple and easy-to-read. In these cases, you can use the {#link-operator||global||lambda#} operator (or the `^` sigil). For example, the previous `square` operator definition could be rewritten simply as the following. +Sometimes you just want to bind a piece of code to a symbol to reuse it later, typically something simple and easy-to-read. In these cases, you can use the {#link-global-operator||lambda#} operator (or the `^` sigil). For example, the previous `square` operator definition could be rewritten simply as the following. (dup *) ^square -Note that this feels like using {#link-operator||global||define#}, but the main difference between {#link-operator||global||lambda#} and {#link-operator||global||define#} is that `lambda` only works on quotations doesn't auto-quote them, so that they are immediately evaluated when the corresponding symbol is pushed on the stack. +Note that this feels like using {#link-global-operator||define#}, but the main difference between {#link-global-operator||lambda#} and {#link-global-operator||define#} is that `lambda` only works on quotations doesn't auto-quote them, so that they are immediately evaluated when the corresponding symbol is pushed on the stack. -Also note that unlike with {#link-operator||global||operator#}, symbols defined with {#link-operator||global||lambda#}: +Also note that unlike with {#link-global-operator||operator#}, symbols defined with {#link-global-operator||lambda#}: * have no built-in validation of input and output values. * do not support the `return` symbol to immediately end their execution.

@@ -55,7 +55,7 @@

> %tip% > Tip > -> You can use {#link-operator||global||lambda-bind#} to re-set a previously set lambda. +> You can use {#link-global-operator||lambda-bind#} to re-set a previously set lambda. ## Sigils

@@ -70,25 +70,25 @@

Currently min provides the following sigils: ' -: Alias for {#link-operator||global||quote#}. +: Alias for {#link-global-operator||quote#}. \: -: Alias for {#link-operator||global||define#}. +: Alias for {#link-global-operator||define#}. @ -: Alias for {#link-operator||global||bind#}. +: Alias for {#link-global-operator||bind#}. ^ -: Alias for {#link-operator||global||lambda#}. +: Alias for {#link-global-operator||lambda#}. ~ -: Alias for {#link-operator||global||lambda-bind#}. +: Alias for {#link-global-operator||lambda-bind#}. > -: Alias for {#link-operator||global||save-symbol#}. +: Alias for {#link-global-operator||save-symbol#}. < -: Alias for {#link-operator||global||load-symbol#}. +: Alias for {#link-global-operator||load-symbol#}. / : Alias for {#link-operator||dict||dget#}. % : Alias for {#link-operator||dict||dset#}. ? -: Alias for {#link-operator||global||help#}. +: Alias for {#link-global-operator||help#}. ! : Alias for {#link-operator||sys||system#}. &

@@ -104,7 +104,7 @@ * can be unsealed, deleted, redefined, and sealed.

Sigils can be a very powerful construct and a way to reduce boilerplate code: you can define a sigil to use as you would use any symbol which requires a single string or quoted symbol on the stack. -Like symbols, sigils can be defined with the {#link-operator||global||operator#} operator, like this: +Like symbols, sigils can be defined with the {#link-global-operator||operator#} operator, like this: ( sigil j

@@ -120,18 +120,18 @@ ...will push the following dictionary on the stack:

{true :test} -Also, sigil definitions can be annotated with documentation comments (starting with `;;` or wrapped in `#|| ... ||#`) so that a help text can be displayed using the {#link-operator||global||help#} symbol. +Also, sigil definitions can be annotated with documentation comments (starting with `;;` or wrapped in `#|| ... ||#`) so that a help text can be displayed using the {#link-global-operator||help#} symbol. ## Auto-popping -Typically, but not always, operators push one or more value to the stack. While this is typically the desired behavior, in some cases you may want to keep the stack clear so in these cases you can append a `!` character to any symbol to cause the symbol {#link-operator||global||pop#} to be pushed on the stack immediately afterwards. +Typically, but not always, operators push one or more value to the stack. While this is typically the desired behavior, in some cases you may want to keep the stack clear so in these cases you can append a `!` character to any symbol to cause the symbol {#link-global-operator||pop#} to be pushed on the stack immediately afterwards. "test" puts ;Prints "test" and pushes "test" on the stack. "test" puts! ;Prints "test" without pushing anything on the stack. ## Operator signatures -When defining symbols and sigils with the {#link-operator||global||operator#} operator, you must specify a *signature* that will be used to validate and capture input and output values: +When defining symbols and sigils with the {#link-global-operator||operator#} operator, you must specify a *signature* that will be used to validate and capture input and output values: ( symbol square

@@ -151,7 +151,7 @@

> %note% > Note > -> If the operator you are defining doesn't require any input value or doesn't leave ang output value on the stack, simply don't put anything before or after the `==>` separator, respectively. For example, the signature of the {#link-operator||global||puts!#} operator could be written like `(a ==>)`. +> If the operator you are defining doesn't require any input value or doesn't leave ang output value on the stack, simply don't put anything before or after the `==>` separator, respectively. For example, the signature of the {#link-global-operator||puts!#} operator could be written like `(a ==>)`. ### Type classes

@@ -165,7 +165,7 @@ (quot :q ==> bool :o)

(q (string?) all? @o) ) :: -The {#link-operator||global||operator#} operator can be used to define a symbol prefixed with `typeclass:` (`typeclass:strquot` in this case) corresponding to a type class that can be used in operator signatures in place of a type, like this: +The {#link-global-operator||operator#} operator can be used to define a symbol prefixed with `typeclass:` (`typeclass:strquot` in this case) corresponding to a type class that can be used in operator signatures in place of a type, like this: ( symbol join-strings

@@ -198,13 +198,13 @@ Essentially, this allows you to push a lambda on the stack from an operator.

Note that: -* Lambdas must be captured using the `^` sigil in signatures and bound using {#link-operator||global||lambda-bind#} in the operator body. +* Lambdas must be captured using the `^` sigil in signatures and bound using {#link-global-operator||lambda-bind#} in the operator body. * Lambdas cannot be captured in input values (they have already been pushed on the stack). * Requiring a lambda as an output value effectively bypasses stack pollution checks. While this can be useful at times, use with caution! ### Type expressions -When specifying types in operator signatures or through the {#link-operator||global||expect#} operator, you can specify a logical expression containing types and type classes joined with one of the following operators: +When specifying types in operator signatures or through the {#link-global-operator||expect#} operator, you can specify a logical expression containing types and type classes joined with one of the following operators: * `|` (or) * `&` (and)

@@ -251,7 +251,7 @@ ```

### Type aliases -As you can see, type expressions can quickly become quite long and complex. To avoid this, you can define *type aliases* using the {#link-operator||global||typealias#} operator. +As you can see, type expressions can quickly become quite long and complex. To avoid this, you can define *type aliases* using the {#link-global-operator||typealias#} operator. For example, you can create an alias of part of the type expression used in the previous example, like this:

@@ -270,7 +270,7 @@ Note that:

* Type aliases be used to create an alias for any type expression. * Aliased type expressions can contain standard {{m}} types, dictionary types, type classes, and even other type aliases. -* The {#link-operator||global||typealias#} operator actually creates lexically-scoped, `typealias:`-prefixed symbols that can be sealed, unsealed, and deleted exactly like other symbols. +* The {#link-global-operator||typealias#} operator actually creates lexically-scoped, `typealias:`-prefixed symbols that can be sealed, unsealed, and deleted exactly like other symbols. ### Generics

@@ -314,7 +314,7 @@ > By contrast, using the same type union several times within the same signature allows different types to be used in the same call, and that is probably something you don't want!

### Constructors -The {#link-operator||global||operator#} operator can also be used to create *constructor* symbols. A constructor is a particular type of operator that is used to create a new typed dictionary. +The {#link-global-operator||operator#} operator can also be used to create *constructor* symbols. A constructor is a particular type of operator that is used to create a new typed dictionary. Consider the following example:

@@ -336,6 +336,6 @@

> %note% > Tip > -> Except for some native symbols, constructors represent the only way to create new typed dictionaries. The more validations you perform in a constructor, the most effective checking for a specific type using the {#link-operator||global||type?#} operator will be, as `type?` only checks if a specific type annotation is present on a typed dictionary, nothing else. +> Except for some native symbols, constructors represent the only way to create new typed dictionaries. The more validations you perform in a constructor, the most effective checking for a specific type using the {#link-global-operator||type?#} operator will be, as `type?` only checks if a specific type annotation is present on a typed dictionary, nothing else. {#link-learn||quotations||Quotations#}
M site/contents/learn-quotations.mdsite/contents/learn-quotations.md

@@ -42,13 +42,13 @@ This program returns a new quotation containing all odd numbers contained in quotation `(1 2 3 4 5 6 7)`.

In this case, the second quotation is used to _quote_ the symbol `odd?` so that instead of being executed immediately, it will be executed by the symbol `filter` on each element of the first quotation. In this way, we may say that `(odd?)` is _dequoted_ by the symbol `filter`. -The symbol {#link-operator||global||dequote#} or its alias `->` can be used to dequote a quotation by pushing all its elements on the main stack. Essentially, this *executes* the quotation in the current context. +The symbol {#link-global-operator||dequote#} or its alias `->` can be used to dequote a quotation by pushing all its elements on the main stack. Essentially, this *executes* the quotation in the current context. For example, the following program leaves the elements `1` and `-1` on the stack: (1 2 3 -) -> -Alternatively, the symbol {#link-operator||global||apply#} or its alias `=>` can also be used to dequote a quotation but in this case it will not push its elements on the main stack, instead it will: +Alternatively, the symbol {#link-global-operator||apply#} or its alias `=>` can also be used to dequote a quotation but in this case it will not push its elements on the main stack, instead it will: 1. Create a temporary empty stack. 2. Push all elements on it, one by one.
M site/contents/learn-scopes.mdsite/contents/learn-scopes.md

@@ -30,7 +30,7 @@ > &lt;native&gt; values cannot be retrieved using the {#link-operator||dict||dget#} operator.

## Accessing the current scope -You can access the current scope using the {#link-operator||global||scope#} operator, which pushes a module on the stack that references the current scope. +You can access the current scope using the {#link-global-operator||scope#} operator, which pushes a module on the stack that references the current scope. Consider the following program:

@@ -40,13 +40,13 @@ In this case:

1. A new variable called `innerscope` is defined on the global scope. 2. A quotation is dequoted, but its scope is retrieved using the `scope` operator and bound to `innerscope`. -3. After the quotation is dequoted, myscope is accessed and its symbols (`test` in this case) are pushed on the stack using the {#link-operator||global||scope-symbols#} operator. +3. After the quotation is dequoted, myscope is accessed and its symbols (`test` in this case) are pushed on the stack using the {#link-global-operator||scope-symbols#} operator. Note that scopes can only be accessed if they are bound to a dictionary, hence the `global` and `scope` operators push a module on the stack, and a module is nothing but a typed dictionary. ## Dequoting a quotation within the context of a specific scope -The {#link-operator||global||with#} operator can be used to dequote a quotation within a specific scope instead of the current one. +The {#link-global-operator||with#} operator can be used to dequote a quotation within a specific scope instead of the current one. Consider the following program, which leaves `2` on the stack:

@@ -56,6 +56,6 @@ In this case, when `with` is pushed on the stack, it will dequote `(4 2 minus)`. Note that the symbol `minus` is defined in the dictionary that will be used by `with` as the current scope, so after `with` is pushed on the stack, the stack contents are:

4 2 (-) -At this point, the {#link-operator||global||dequote#} operator is pushed on the stack and the subtraction is executed leaving `2` on the stack. +At this point, the {#link-global-operator||dequote#} operator is pushed on the stack and the subtraction is executed leaving `2` on the stack. {#link-learn||control-flow||Control Flow#}
M site/contents/learn-shell.mdsite/contents/learn-shell.md

@@ -64,6 +64,6 @@ This file is used to persist all commands entered in the min shell, and it is loaded in memory at startup to provide line history support.

### .min\_symbols -This files contains all symbol definitions in JSON format that were previously-saved using the {#link-operator||global||save-symbol#} symbol. Symbols can be loaded using the {#link-operator||global||load-symbol#} symbol. +This files contains all symbol definitions in JSON format that were previously-saved using the {#link-global-operator||save-symbol#} symbol. Symbols can be loaded using the {#link-global-operator||load-symbol#} symbol. {#link-learn||extending||Extending min#}
M site/contents/news/v0.43.0.mdsite/contents/news/v0.43.0.md

@@ -27,5 +27,5 @@

## Fixes and Improvements - Added check to prevent installing local managed modules in the HOME directory or $HOME/mmm. -- Changed {#link-operator||global||tokenize#} symbol so that it returns the full token, including delimiters (for strings and comments). +- Changed {#link-global-operator||tokenize#} symbol so that it returns the full token, including delimiters (for strings and comments). - Fixed regression in `min compile` command introduced in the previews version due to parses changes.