min Language Developer Guide

About min

min is a concatenative, fully-homoiconic, functional, interpreted programming language.

This basically means that:

It is based on a somewhat obscure and slightly unintuitive programming paradigm, think of Forth, Factor and Joy but with parentheses for an extra Lispy flavor.
Programs written in min are actually written using quotations, i.e. lists.
It comes with map, filter, find, map-reduce, and loads of other functional goodies. See the seq Module for more.
It is probably slower than the average production-ready programming language.

Why?

Because creating a programming language is something that every programmer needs to do, at some point in life. And also because there are way too few concatenative programming language out there – so people are likely to be less pissed off than if I made a yet another Lisp instead.

I always wanted to build a minimalist language, but that could also be used for real work and provided a standard library for common tasks and functionalities like regular expression support, cryptography, execution of external programs, shell-like operators, and keywords to work with files, and more.

Additionally, I wanted it to be fully self-contained, cross-platform, and small. Not stupidly small, but I feel it’s a good compromise compared to the alternatives out there, considering that you only need one file to run any min program.

I also created a static site generator called HastySite, which also powers https://min-lang.org. HastySite internally uses min as the language to write the rules to process the source files of the site, and also all its scripts.

Finally, I think more and more people should get to know concatenative programming languages, because concatenative programming matters.

How?

min is developed entirely in Nim – the name is (almost) entirely a coincidence. I wanted to call it minim but then shortened it for more… minimalism.

min’s parser started off as a fork of Nim’s JSON parser – adapted to process a concatenative programming language with less primitive types than JSON. It is interpreted in the traditional sense: no bytecode, no JIT, just plain read, parse, and run.

Who?

min was created and implemented by Fabio Cevasco, with contributions by Peter Munch-Ellingsen, Yanis Zafirópulos, and baykus871.

Special thanks to mwgkgk for contributing to the design of native dictionaries.

When?

min source code repository was created on November 8^th 2014. This only means that I’ve been very slowly developing something that was actually made public at the end of July 2017.

Get Started

You can download one of the following pre-built min binaries:

Building from source

Alternatively, you can build min from source in one of the following ways:

Using nimble

If you already installed nim, you probably already have the nimble package manager installed.

If that’s the case, simply run nimble install min.

Building from source for additional platforms

By default, min is released as a pre-built binary executable for Windows x64, macOS x64 and Linux x64. However, it should run without issues on any platform supported by the Nim programming language.

To build on a different operating system and architecture from the default ones, you also need to get or build the following static libraries:

libssl (OpenSSL)
libcrypto (OpenSSL)
libpcre (PCRE)

and also specify the following additional flag when compiling:

--passL:"-static -L<dir> -lpcre -lssl -lcrypto"

Where <dir> is the directory containing the *.a files for the static libraries listed above.

Alternatively, if you can also opt out from OpenSSL and PCRE support by:

Specifying -d:nossl
Specifying -d:nopcre

Additional build options

-d:ssl

If the -d:ssl flag is specified when compiling, min will be built with SSL support, so it will be possible to:

perform HTTPS requests with the http Module.
use all the cryptographic symbols defined in the crypto Module.

If this flag is not specified:

It will not be possible to perform HTTPS requests
Only the following symbols will be exposed by the crypto Module:
- md5
- sha1
- encode
- decode
- aes

-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 str Module:

search
match?
search-all
replace
replace-apply

Building a docker image

Yanis Zafirópulos contributed a Dockerfile that you can use to create your own Docker image for min based on Alpine Linux.

To build the image locally, execute the following command from the repository root directory:

docker build -t mindocker .

To run it, execute:

docker run -it mindocker

Running the min shell

To start the min shell, run min with no arguments. You will be presented with a prompt displaying the path to the current directory:

min shell v0.43.0 [/Users/h3rald/test]$

You can type min code and press ENTER to evaluate it immediately:

[/Users/h3rald/test]$ 2 2 + 4 [/Users/h3rald/test]$

The result of each operation will be placed on top of the stack, and it will be available to subsequent operation

[/Users/h3rald/test]$ dup * 16 [/Users/h3rald/test]$

To exit min shell, press CTRL+C or type 0 exit and press ENTER.

Tip

By default, the min shell provides advanced features like tab-completion, history, etc. If however, you run into problems, you can disable these features by running min -j instead, and run min shell with a bare-bones REPL.

Executing a min program

To execute a min script, you can:

Run min eval "... program..." to execute a program inline.
Run min myfile.min to execute a program contained in a file.
Run min run <mmm> to execute the main symbol of the specified min managed module. If the managed module is not installed globally, it will be downloaded and installed automatically.

min also supports running programs from standard input, so the following command can also be used (on Unix-like system) to run a program saved in myfile.min:

$ cat myfile.min | min

You can enable development mode (runtime checks and validations) by specifying -d (--dev) when running a min program. If development mode is not enabled, min programs run faster.

Compiling a min program

min programs can be compiled to a single executable simply by using the built-in compile command:

$ min compile myfile.min

Essentially, this will:

Generate a myfile.nim containing the equivalent Nim code of your min program.
Call the Nim compiler to do the rest ;)

If you want to pass any options to the Nim compiler (like -d:release for example) you can do so by using the -n (or --passN) option:

$ min compile myfile.min -n:"-d:release –threadAnalysis:off –mm:refc"

Additionally, you can also use -m:<path> (or --module-path) to specify one path containing .min files which will be compiled as well (but not executed) along with the specified file. Whenever a load or a require symbol is used to load/require an external .min 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 along with all .min files included in the tasks folder and its subfolders:

$ min compile run.min -m:tasks

Similarly, you can also bundle additional files in the executable by specifying the -a:<path> (or --asset-path) option. At runtime, the compiled min program will attempt to lookup bundled asset files before checking the filesystem.

Note

In order to successfully compile .min 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 help symbol within the min REPL.

$ min help dup

Syntax highlighting

If you are using Visual Studio Code, you can install the official min extension which provides syntax highlighting support, code folding, and auto-indentation.
If you are using Vim, a min.vim syntax definition file is available in the min repo.
If you are using Sublime Text 3, Rafael Carrasco created a min syntax definition file that is available here.
If you are using Notepad++, a Notepad++ language file contributed by baykus871 is available in the repo.

Learning the min Language

min is a stack-based, concatenative programming language that uses postfix notation. If you already know Forth, Factor or Joy, or if you ever used an RPN calculator, then min will look somewhat familiar to you.

If not, well, here’s how a short min program looks like:

; This is a comment
(1 2 3 4 5) (dup *) map
#| This is a...
...multiline comment |#

This program returns a list containing the square values of the first five integer numbers:

(1 4 9 16 25)

Let’s see how it works:

First, a list containing the first five integers is pushed on the stack.
Then, another list containing two symbols (dup and *) is pushed on the stack. This constitutes a quoted program which, when executed duplicates the first element on the stack — this is done by dup— and then multiplies — with *— the two elements together.
Finally, the symbol map is pushed on the stack. Map takes a list of elements and a quoted program and applies the program to each element.

Note that:

There are no variable assignments.
elements are pushed on the stack one by one.
Parentheses are used to group one or more elements together so that they are treated as a single element and they are not evaluated immediately.
Symbols (typically single words, or several words joined by dashes) are used to execute code that performs operations on the whole stack.

Unlike more traditional programming languages, in a concatenative programming language, there is no inherent need for variables or named parameters, as symbols act as stack operators that consume elements that are placed in order on top of a stack.

Data Types

The following data types are availanle in min (with the corresponding shorthand symbols used in operator signatures in brackets):

null (null)

null value.

boolean (bool)

true or false.

integer (int)

A 64-bit integer number like 1, 27, or -15.

float (flt)

A 64-bit floating-point number like 3.14 or -56.9876.

string (str)

A series of characters wrapped in double quotes: “Hello, World!”.

quotation (quot)

A list of elements, which may also contain symbols. Quotations can be used to create heterogenous lists of elements of any data type, and also to create a block of code that will be evaluated later on (quoted program). Example: (1 2 3 + *)

command (cmd)

A command string wrapped in square brackets that will be immediately executed on the current shell and converted into the command standard output. Example: [ls -a]

dictionary (dict)

A key/value table. Dictionaries are implemented as an immediately-dequoted quotation, are enclosed in curly braces, and are represented by their symbol definitions. Note that dictionary keys must start with :and be followed by a double-quoted string, or a single word (which can be written without double quotes). The dict Module provides some operators on dictionaries.

Example

The following is a simple dictionary containing three keys: name, paradigm, and first-release-year:

{
    "min" :name
    "concatenative" :paradigm
    2017 :"first release year"
}

Additionally, dictionaries can also be typed to denote complex objects like sockets, errors, etc. For example, the following dictionary defines an error:

  {
   "MyError" :error
   "An error occurred" :message
   "symbol1" :symbol
   "dir1/file1.min" :filename
   3 :line
   13 :column
   ;error
  }

Tip

The dtype operator can be used to set the type of a dictionary.

The logic Module provides predicate operators to check if an element belongs to a particular data type or pseudo-type (boolean?, number?, integer?, float?, …).

Additionally, the global Module provides operators to convert values from a data type to another (e.g. integer, string, and so on).

Note

Most of the operators defined in the num Module are able to operate on both integers and floats.

Quotations

Quotations are the most important thing to understand in min. Besides being the data type used for lists, they are also used to delimit blocks of min code that is not going to be immediately executed.

Consider for example the following min code which returns all the files present in the current folder sorted by name:

 . ls (ftype "file" ==) filter '> sort

The symbol filter takes two quotations as arguments – the first quotation on the stack is applied to all the elements of the second quotation on the stack, to determine which elements of the second quotation will be part of the resulting quotation. This is an example of how quotations can be used both as lists and programs.

Let’s examine this program step-by-step:

The . symbol is pushed on the stack, and it is immediately evaluated to the full path to the current directory.
The ls symbol is pushed on the stack, it consumes the string already on the stack and returns a quotation containing all files and directories within the current directory.
The quotation (ftype 'file ==) is pushed on the stack. It is treated exactly like a list of data and it is not evaluated.
The filter symbol is pushed on the stack. This symbol takes two quotations as input, and applies the result of the first quotation on the stack ((ftype "file" ==)) to all elements of the second quotation of the stack (the list of files and directories), returning a new quotation containing only those elements of the second quotation on the stack that satisfy the result of the first quotation. In this case, it returns a new quotation containing only files.
'> is pushed on the stack. The ' sigil can be used instead of the quote symbol to quote a single symbol, > in this case. In other words, it is instantly evaluated to the quotation (>).
The symbol sort is pushed on the stack. This symbol, like filter, takes two quotations as input, and applies the first quotation to each element of the second quotation, effectively sorting each element of the second quotation using the predicate expressed by the first quotation. In this case, all files are sorted by name in ascending order.

Tip

The seq Module provides several symbols to work with quotations in a functional way.

Quoting, dequoting, and applying

When a quotation is created, it is treated as data, no matter what it contains: it is placed on the stack, like an integer or a string would. However, unlike other data types, a quotation can be evaluated in certain situations and when it happens its contents are pushed on the stack.

Consider the following program:

 (1 2 3 4 5 6 7) (odd?) filter

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

Create a temporary empty stack.
Push all elements on it, one by one.
Push the entire temporary stack as a quotation back on the main stack.

For example, the following program leaves the element (1 -1) on the stack:

 (1 2 3 -) =>

Operators

Every min program needs operators to:

Manipulate elements on the stack
Perform operations on data
Provide side effects (read/print to standard input/output/files, etc.)

There are two types of operators: symbols and sigils.

Symbols

Symbols are the most common type of operator. A min symbol is a single word that is either provided by one of the predefined min modules like dup or . or defined by the user. User-defined symbols must:

Start with a letter or an underscore (_).
Contain zero or more letters, numbers and/or any of the following characters: / ! ? + * . _ -

It is possible to define operator symbols using the 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
   (num :n ==> num :result)
   (n dup * @result)
 ) operator
 ;; Calculates the square of n.

The 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 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 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 define, but the main difference between lambda and 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 operator, symbols defined with lambda:

have no built-in validation of input and output values.
do not support the return symbol to immediately end their execution.
have no built-in stack pollution checks.

Tip

You can use lambda-bind to re-set a previously set lambda.

Sigils

Besides symbols, you can also define sigils. min provides a set of predefined sigils as abbreviations for commonly used symbols.

A sigil can be prepended to a double-quoted string or a single word (with no spaces) which will be treated as a string instead of using the corresponding symbol.

For example, the following executes the command ls -al and pushes the command return code on the stack:

 !"ls -al"

Currently min provides the following sigils:

': Alias for quote.
:: Alias for define.
*: Alias for invoke.
@: Alias for bind.
^: Alias for lambda.
~: Alias for lambda-bind.
>: Alias for save-symbol.
<: Alias for load-symbol.
/: Alias for dget.
%: Alias for dset.
?: Alias for help.
!: Alias for system.
&: Alias for run.
$: Alias for get-env.

Besides system sigils, you can also create your own sigils. Unlike system sigils however, user defined sigils:

have the same character restrictions as symbols
can only be prepended to double-quoted strings
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 operator operator, like this:

 (
   sigil j
   (string :json ==> a :result)
   (json from-json @result)
 ) operator

This definition will add a j sigil that will process the following string as JSON code, so for example:

 j"{\"test\": true}"

…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 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 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 operator operator, you must specify a signature that will be used to validate and capture input and output values:

 (
   symbol square
   (num :n ==> num :result)
   (n dup * @result)
 ) operator

In this case for example the square symbol expects a number on the stack, which will be captured to the symbol n and it will place a number on the stack which needs to be bound in the operator body to the symbol result.

In a signature, a type expression must precede the capturing symbol. Such type expression can be:

One of the following shorthand symbols identifying a well-known min base type (see the reference section for more information): a, bool, null, str, int, num, flt, 'sym, quot, or dict.
A typed dictionary like dict:module or dict:datastore.
A type class (see below).
a type expression like str|int.

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 puts! operator could be written like (a ==>).

Type classes

Besides standard base types, you can define your own type classes to express custom constraints/validations for operator input and output values.

Consider the following type class definition validating a quotation containing strings:

 (
   typeclass strquot
   (quot :q ==> bool :o)
   (q (string?) all? @o)
 ) ::

The 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
   (strquot :q ==> str :result)
   ( 
      q "" (suffix) reduce @result
   )
 )

This operator will raise an error if anything other than a quotation of strings is found on the stack.

Tip

typeclass:-prefixed symbols are just like ordinary symbols: they are lexically scoped, they can be sealed, unsealed and deleted.

Capturing lambdas

You can also specify a lambda to be captured to an output value, like this:

 (
   symbol square
   (==> quot ^o)
   (
     (dup *) ~o
   )
 ) ::

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 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 expect operator, you can specify a logical expression containing types and type classes joined with one of the following operators:

| (or)
& (and)
! (not)

Suppose for example you defined the following type classes:

(typeclass fiveplus
    (int :n ==> bool :o)
    (
      n 5 > @o
    )
) ::

(typeclass tenminus
    (int :n ==> bool :o)
    (
      n 10 < @o
    )
) ::

(typeclass even
    (int :n ==> bool :o)
    (
      n 2 mod 0 == @o
    )
) ::

You can combine them in a type expression as following:

(symbol test
    (!even|tenminus&fiveplus :n ==> bool :o)
    (
      true @o
    )
) ::
4 test  ; error
6 test  ; true
11 test ; true

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 typealias operator.

For example, you can create an alias of part of the type expression used in the previous example, like this:

'tenminus&fiveplus 'five-to-ten typealias

(symbol test
    (!even|five-to-ten :n ==> bool :o)
    (
      true @o
    )
) ::

Note that:

Type aliases be used to create an alias for any type expression.
Aliased type expressions can contain standard min types, dictionary types, type classes, and even other type aliases.
The typealias operator actually creates lexically-scoped, typealias:-prefixed symbols that can be sealed, unsealed, and deleted exactly like other symbols.

Generics

min supports generics in operator signatures. in other words, you can define a custom type alias on-the-fly directly in an operator signature, like this:

(
  symbol add
  ((str|num|quot :t) :a t :b ==> t :result)
  (
   (a type "str" ==)
     (a b suffix @result return)
   when
   (a type "num" ==)
     (a b + @result return)
   when
   (a type "quot" ==)
     (a b concat #result return)
   when
  )
) ::

In this case, t is set to the type union stribg|num|quot, and the add method above can be used to sum two numbers or join two strings or quotations.

Note that the value of t is evaluated to the type of the first value that is processed. In other words, the following programs will work as expected:

 3 5 add ;outputs 8

 "hello, " "world" ;outputs "hello, world"

while the following will raise an error, because the value of t from num to quot within the same operator use:

 12 "test" add ;raises an error

Constructors

The 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:

 (
   constructor point
   (num :x num :y ==> dict :out)
   (
     {}
       x %x
       y %y
     @out
   )
 ) ::

The operator above creates a point constructor symbol that can be used to create a new dict:point typed dictionary by popping two numbers from the stack:

 2 3 point ; {2 :x 3 :y ;point}

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 type? operator will be, as type? only checks if a specific type annotation is present on a typed dictionary, nothing else.

Definitions

Being a concatenative language, min does not really need named parameters or variables: symbols just pop elements off the main stack in order, and that’s normally enough. There is however one small problem with the traditional concatenative paradigm; consider the following program for example:

 dup dup
 "\.zip$" match?
 swap fsize 1000000 > and 
 swap 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 dup and swap are used for.

The good news is that you can use the define operator and the : sigil to define new symbols, and symbols can also be set to fixed values (literals).

Consider the following program:

 :filepath
 filepath "\.zip$" match?
 filepath fsize 1000000 >
 filepath 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 and symbols necessary to compare the three conditions.

Lexical scoping and binding

min, like many other programming languages, uses lexical scoping to resolve symbols.

Consider the following program:

 4 :a
 ( 
   a 3 + :a
   (
      a 1 + :a
      (a dup * :a) dequote
   ) dequote
 ) dequote

…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 bind or its shorthand sigil @, so that the program becomes the following:

 4 :a ;First definition of the symbol a
 (
   a 3 + @a ;The value of a is updated to 7.
   (
     a 1 + @a ;The value of a is updated to 8
     (a dup * @a) dequote ;The value of a is now 64
   ) dequote
 ) dequote

Sealing symbols

Finally, symbols can be sealed to prevent accidental updates or deletions. By default, all symbols defined in the core min modules are sealed, so the following code if run in min shell will result in an error:

 5 :quote

…because the symbol quote is already defined in the root scope. However, note that the following code will not return an error:

 (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 seal your own symbols so that they may not be redefined using the bind operator or deleted using the delete.

Note

The unseal-symbol operator can be used to effectively un-seal a previously-sealed symbol. Use with caution!

Scopes

As explained in Definitions, min uses lexical scoping to resolve symbols and sigils. A scope is an execution context (a symbol table really) that:

is created while a new quotation is being dequoted or a dictionary is created.
is destroyed after a quotation has been dequoted.
is attached to a dictionary.

The main, root-level scope in min can be accessed using the global Module symbol and it typically contains all symbols and sigils imported from all the standard library modules. The global symbol pushes a module on the stack that references the global scope:

[/Users/h3rald/test]$ global { <native> :! <native> :!= … <native> :xor <native> :zip ;module }

Note

<native> values cannot be retrieved using the dget operator.

Accessing the current scope

You can access the current scope using the scope operator, which pushes a module on the stack that references the current scope.

Consider the following program:

 {} :innerscope ("This is a test" :test scope @myscope) -> myscope scope-symbols

In this case:

A new variable called innerscope is defined on the global scope.
A quotation is dequoted, but its scope is retrieved using the scope operator and bound to innerscope.
After the quotation is dequoted, myscope is accessed and its symbols (test in this case) are pushed on the stack using the 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 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:

 (4 2 minus) {'- :minus} with ->

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 dequote operator is pushed on the stack and the subtraction is executed leaving 2 on the stack.

Control Flow

The global Module provide some symbols that can be used for the most common control flow statements. Unlike most programming languages, min does not differentiate between functions and statements – control flow statements are just ordinary symbols that manipulate the main stack.

Conditionals

The following symbols provide ways to implement common conditional statements:

case
if
{#link-operator||global||unless#}
when

For example, consider the following program:

 (
   (  
     "" :type
     (("\.(md|markdown)$") ("markdown" @type))
     (("\.txt$") ("text" @type))
     (("\.min$") ("min" @type))
     (("\.html?$") ("HTML" @type))
     ((true) ("unknown" @type))
   ) case 
   "This is a $1 file." (type) % echo
 ) ^display-file-info

This program defines a symbol display-file-info that takes a file name and outputs a message displaying its type if known.

Loops

The following symbols provide ways to implement common loops:

foreach
times
while

For example, consider the following program:

 (
   :n
   1 :i
   1 :f
   (i n <=)
   (
     f i * @f 
     i succ @i
   ) while
   f
 ) ^factorial

This program defines a symbol factorial that calculates the factorial of an integer iteratively using the symbol while.

Error handling

The following symbols provide ways to manage errors in min:

format-error
raise
try

For example, consider the following program:

 . ls
 (
   (
     (fsize) 
     (pop 0)
   ) try
 ) map 
 1 (+) reduce

This program calculates the size in bytes of all files included in the current directory. Because the fsize symbol throws an error if the argument provided is not a file (for example, if it is a directory), the try symbol is used to remove the error from the stack and push 0 on the stack instead.

Using the min Shell

The min executable also provide an interactive REPL (Read-Eval-Print Loop) when launched with no arguments:

$ min [/Users/h3rald/Development/min]$

Although not as advanced, the min REPL is not dissimilar from an OS system shell like Bash, and as a matter of fact, it provides many functionalities that are found in other shells or command prompts, such as:

Auto-completion
Persistent line history
A customizable prompt
Access to environment variables

…plus in can obviously leverage the entire min language for complex scripting.

Autocompletion and shortcuts

The min shell features smart tab autocompletion and keyboard shortcut implemented using the minline library.

The following behaviors are implemented when pressing the TAB key within:

Context	Result
…a string	Auto-completes the current word using file and directory names.
…a word starting with `$`	Auto-completes the current word using environment variable names.
…a word starting with `'`, `@`, `#`, `>`, `<`, `(`, `?`	Auto-completes the current word using symbol names.
…a word starting with `*` and optionally containing `/`s	Auto-completes the current word using dictionaries and their symbol (nested invocation)

Additionally, the following common shortcuts are also available:

Key	Effect
`INSERT`	Switches between insert and replace mode.
`UP`	Displays the previous history entry.
`DOWN`	Displays the next history entry.
`CTRL+d`	Terminates the min shell.
`CTRL+u`	Clears the current line.
`CTRL+b`	Goes to the beginning of the line.
`CTRL+e`	Goes to the end of the line.

Tip

If you want, you can define your own keyboard shortcuts using the mapkey operator.

Shell configuration files

When the min interpreter is first launched, the following files are created automatically in the $HOME directory (%USERPROFILE% on Windows).

.minrc

This file is interpreted first every time min is run. By default it is empty, but it can be used to define code to execute at startup.

.min_history

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 save-symbol symbol. Symbols can be loaded using the load-symbol symbol.

Extending min

min provides a fairly complete standard library with many useful modules. However, you may feel the need to extend min in order to perform more specialized tasks.

In such situations, you basically have the following options:

Implementing new min modules using min itself
Specifying your custom prelude program
Embedding min in your Nim program

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 operator operator or the lambda operator

(dup *)       ^pow2
(dup dup * *) ^pow3
(dup * dup *) ^pow4

Save your code to a file (e.g. quickpows.min) and you can use it in other Nim files using the require operator and the import (if you want to import the operators in the current scope):

'quickpows require :qp

2 *qp/pow3 *qp/pow2 puts ;prints 64

Specifying your custom prelude program

By default, when min is started it loads the following prelude.min program:

; Imports
'str       import
'io        import
'logic     import
'num       import
'sys       import
'stack     import
'seq       import
'dict      import
'time      import
'fs        import
'crypto    import
'math      import
'net       import
'http      import
; Unseal prompt symbol
'prompt    unseal-symbol

Essentially, this causes min to import all the modules and unseals the 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 -i -p:myfile.min

Embedding min in your Nim program

If you’d like to use min as a scripting language within your own program, and maybe extend it by implementing additional operators, you can use min as a Nim library.

To do so:

Install min sources using Nifty as explained in the Download section.
Import it in your Nim file.
Implement a new proc to define the module.

The following code is taken from HastySite and shows how to define a new hastysite module containing some symbols (preprocess, postprocess, process-rules, …):

import min

proc hastysite_module*(i: In, hs1: HastySite) =
  var hs = hs1
  let def = i.define()

  def.symbol("preprocess") do (i: In):
    hs.preprocess()

   def.symbol("postprocess") do (i: In):
    hs.postprocess()

  def.symbol("process-rules") do (i: In):
    hs.interpret(hs.files.rules)

  # ...

  def.finalize("hastysite")

Then you need to:

Instantiate a new min interpreter using the newMinInterpreter proc.
Run the proc used to define the module.
Call the interpret method to interpret a min file or string:

proc interpret(hs: HastySite, file: string) =
  var i = newMinInterpreter(file, file.parentDir)
  i.hastysite_module(hs)
  i.interpret(newFileStream(file, fmRead))

Tip

For more information on how to create new modules with Nim, have a look in the lib folder of the min repository, which contains all the min modules included in the standard library.

Module Management

The min executable includes a minimal but practical package manager that can be used to initialize, install, uninstall, update, list and search managed min modules stored in remote git repositories.

The min commands that make up this module management functionality is often referred to as mmm, for min module management.

How mmm works

mmm borrows most of its design from Nim’s Nimble, but it is mcuh simpler. Here are the basics:

mmm is not a standalone program, it is built-in into the min executable
mmm has a central registry (a single JSON file really, and distributed storage (managed modules are hosted in remote github repositorues).
managed modules can be installed both locally to a specific folder (another managed module) or globally, in the $HOME/mmm folder.
each managed module relies on an mmm.json for its metadata, including dependencies on other managed modules.
the version (git branch or tag) of a managed module must be always specified when installing or specifying a dependency. There is no concept of semantic versioning support, and that’s deliberate: it makes things simpler and leas error prone.

The registry

The registry of mmm is a single JSON file accessible here:

https://min-lang.org/mmm.json

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 {[require}} symbol, min will attempt to lookup the module (for example module1) checking the following files (in order):

module1.min
mmm/module1/*/index.min
$HOME/mmm/module1/*/index.min

Commands

The following sections explain how to use the mmm-related commands that are built-in into tbe min executable.

min init

Initializes a new managed min module in tbe current directory by creating a sample mmm.json file in the current folder.

min install [name version | name@version] [-g]

Install the specified managed module by specifying its name and version. By default, the module is installed in the mmm/<name>/<version> folder; if -g is specified, it is installed in $HOME/mmm/<name>/<version>.

If no version is specified, the version will be set to the HEAD branch of the git repository of the module.

If no name and no version are specified, all the managed modules (and their dependencies) specified as dependencies for the current managed module will be installed.

If the installation of one dependency fails, the installation of the module will be rolled back.

min uninstall [name version | name@version] [-g]

Uninstall the module specified by name and version either locally or globally (if -g is specified).

If no version is specified, the version will be set to the HEAD branch of the git repository of the module.

If no version is specified, all version of the module will be uninstalled (if the module is installed globally).

If no name and no version are specified, all dependencies of the current managed module (and their dependencies) will be uninstalled.

min update [name version | name@version] [-g]

Update the module specified by name and version either locally or globally (if -g is specified).

If no version is specified, the version will be set to the HEAD branch of the git repository of the module.

If no name and no version are specified, all dependencies of the current managed module (and their dependencies) will be updated.

min list

List all the installed dependencies of the current module, and their dependencies, recursively.

min search [arg1 arg2 … argN]

Search for a managed module matching the specified arguments. if no argument is specified, the metadata of all public managed modules will be printed.

Creating a managed min module

Creating a managed min module is easy. As a minimum, you need to create three files:

an index.min file containing your code
a license file
an mmm.json file containing the module metadata

See min-highlight as an example.

Metadata

The mmm.json file of a managed min module must contain at least the following metadata:

name
description
private set to true for private modules, or, if public:
- method set to git
- url set to the URL of the git repository containing the module
license
deps set to an object with the keys corresponding to module names and the values to their respective versions

Publishing

If you want to publish your module, just create a PR on the min git repository and modify this file by adding the metadata for your module.

Reference

min includes a small but powerful standard library organized into the following modules:

global Module: Defines the basic language constructs, such as control flow, type conversions, symbol definition and binding, exception handling, etc. {#link-module](#min-operator-id-require}} symbol, min will attempt to lookup the module (for example module1) checking the following files (in order):

module1.min
mmm/module1/*/index.min
$HOME/mmm/module1/*/index.min

Commands

The following sections explain how to use the mmm-related commands that are built-in into tbe min executable.

min init

Initializes a new managed min module in tbe current directory by creating a sample mmm.json file in the current folder.

min install [name version | name@version] [-g]

If no version is specified, the version will be set to the HEAD branch of the git repository of the module.

If no name and no version are specified, all the managed modules (and their dependencies) specified as dependencies for the current managed module will be installed.

If the installation of one dependency fails, the installation of the module will be rolled back.

min uninstall [name version | name@version] [-g]

Uninstall the module specified by name and version either locally or globally (if -g is specified).

If no version is specified, the version will be set to the HEAD branch of the git repository of the module.

If no version is specified, all version of the module will be uninstalled (if the module is installed globally).

If no name and no version are specified, all dependencies of the current managed module (and their dependencies) will be uninstalled.

min update [name version | name@version] [-g]

Update the module specified by name and version either locally or globally (if -g is specified).

If no version is specified, the version will be set to the HEAD branch of the git repository of the module.

If no name and no version are specified, all dependencies of the current managed module (and their dependencies) will be updated.

min list

List all the installed dependencies of the current module, and their dependencies, recursively.

min search [arg1 arg2 … argN]

Search for a managed module matching the specified arguments. if no argument is specified, the metadata of all public managed modules will be printed.

Creating a managed min module

Creating a managed min module is easy. As a minimum, you need to create three files:

an index.min file containing your code
a license file
an mmm.json file containing the module metadata

See min-highlight as an example.

Metadata

The mmm.json file of a managed min module must contain at least the following metadata:

name
description
private set to true for private modules, or, if public:
- method set to git
- url set to the URL of the git repository containing the module
license
deps set to an object with the keys corresponding to module names and the values to their respective versions

Publishing

If you want to publish your module, just create a PR on the min git repository and modify this file by adding the metadata for your module.

Reference

min includes a small but powerful standard library organized into the following modules:

global Module: Defines the basic language constructs, such as control flow, type conversions, symbol definition and binding, exception handling, etc.
{#link-module): Defines combinators and stack-shufflers like dip, dup, swap, cons, etc.
seq Module: Defines operators for quotations, like map, filter, reduce, etc.
dict Module: Defines operators for dictionaries, like dget, ddup, dset, etc.
dstore Module: Provides support for simple, persistent, in-memory JSON stores.
io Module: Provides operators for reading and writing files as well as printing to STDOUT and reading from STDIN.
fs Module: Provides operators for accessing file information and properties.
logic Module: Provides comparison operators for all min data types and other boolean logic operators.
str Module: Provides operators to perform operations on strings, use regular expressions, interpolation, etc..
sys Module: Provides operators to use as basic shell commands, access environment variables, and execute external commands.
num Module: Provides operators to perform simple mathematical operations on integer and floating point numbers.
time Module: Provides a few basic operators to manage dates, times, and timestamps.
crypto Module: Provides operators to compute hashes (MD4, MD5, SHA1, SHA224, SHA256, SHA384, sha512), base64 encoding/decoding, and AES encryption/decryption.
math Module: Provides many mathematical operators and constants such as trigonometric functions, square root, logarithms, etc.
net Module: Provides basic supports for sockets (some features are not supported on Windows systems).
http Module: Provides operators to perform HTTP requests, download files and create basic HTTP servers.
xml Module: Provides operators for parsing, creating and querying XML/HTML code using CSS selectors.

Notation

The following notation is used in the signature of all min operators:

Types and Values

∅

No value.

null

null value

a

A value of any type.

bool

A boolean value

int

An integer value.

flt

A float value.

num

A numeric (integer or float) value.

str

A string value.

'sym

A string-like value (string or quoted symbol).

quot

A quotation (also expressed as parenthesis enclosing other values).

dict

A dictionary value.

dict:help

A help dictionary:

{
 "puts" :name
 "symbol" :kind
 "a ==>" :signature
 "Prints a and a new line to STDOUT." :description
 ;help
}

dict:url

An URL dictionary:

{
 "http" :scheme
 "h3rald" :hostname
 "" :port
 "" :username
 "" :password
 "/min" :path
 "" :anchor
 "" :query
 ;url
}

dict:timeinfo

A timeinfo dictionary:

{
 2017 :year
 7 :month
 8 :day
 6 :weekday
 188 :yearday
 15 :hour
 16 :minute
 25 :second
 true :dst
 -3600 :timezone ;UTC offset
 ;timeinfo
}

dict:error

An error dictionary:

{
 "MyError" :error
 "An error occurred" :message
 "symbol1" :symbol
 "dir1/file1.min" :filename
 3 :line
 13 :column
 ;error
}

dict:socket

A socket dictionary that must be created through the socket operator:

{
 "ipv4" :domain
 "stream" :type
 "tcp" :protocol
 ;socket
}

dict:rawval

A raw value dictionary obtained via the get-raw or dget-raw operators:

{
 "sym" :type
 "my-symbol" :str
 my-symbol :val
 ;rawval
}

dict:datastore

A datastore dictionary that must be created through the dsinit or dsread operator:

{
 {} :data
 "path/to/file.json" :path
 ;datastore
}

dict:http-request

A request dictionary, representing an HTTP request to be performed through the operators exposed by the http Module:

{
 "http://httpbin.org/put" :url
 "PUT" :method
 "1.1" :version         ;optional
 "h3rald.com" :hostname ;optional
 {                      
  "it-id" :Accept-Language
  "httpbin.org" :Host
 } :headers             ;optional
 "test body" :body      ;optional
 ;http-request
}

dict:http-response

A response dictionary, representing an HTTP response returned by some of the operators exposed by the http Module:

{
  "1.1" :version ;optional
  200 :status    ;optional
  {
    "application/json" :Content-Type
  } :headers     ;optional
  "{\"test\": \"This is a test\"}" :body
  ;http-response
}

dict:xml-element

A dictionary representing an XML or HTML element, exposed by the xml Module

{
  {"https://min-lang.org" :href} :attributes
  ({"min web site" :text}) :children
  "a" :tag
  ;xml-element
}

dict:xml-comment

A dictionary representing an XML comment.

{
  "This is a comment" :text
  ;xml-comment
}

dict:xml-cdata

A dictionary representing XML CDATA text.

{
  "This is some text" :text
  ;xml-cdata
}

dict:xml-entity

A dictionary representing an XML entity.

{
  "amp" :text
  ;xml-entity
}

dict:xml-text

A dictionary representing XML text.

{
  "This is some text" :text
  ;xml-text
}

xml-node

A typealias to identify all XML dictionary types.

dict:xml-element||dict:xml-text||dict:xml-comment||dict:xml-entity||dict:xml-cdata

Suffixes

The following suffixes can be placed at the end of a value or type to indicate ordering or quantities.

₁: The first value of the specified type.
₂: The second value of the specified type.
₃: The third value of the specified type.
₄: The fourth value of the specified type.
_?: Zero or one.
_*: Zero or more.
₊: One or more

`global` Module

'str ⇒ str quotesym

See quotesym.

' ⇒ quotesym

See quotesym.

:str ⇒ str define

See define.

: ⇒ define

See define.

:: ⇒ operator

See operator.

?str ⇒ str help

See help.

? ⇒ help

See help.

~str ⇒ str lambda-bind

See lambda-bind.

~ ⇒ lambda-bind

See lambda-bind.

*str ⇒ str invoke

See invoke.

@str ⇒ str bind

See bind.

@ ⇒ bind

See bind.

>str ⇒ str save-symbol

See save-symbol.

<str ⇒ str load-symbol

See load-symbol.

-> ⇒ dequote

See dequote.

>> ⇒ prefix-dequote

See prefix-dequote.

>< ⇒ infix-dequote

See infix-dequote.

=> ⇒ apply

See apply.

==>

∅ ⇒ ∅

Symbol used to separate input and output values in operator signatures.

=-=

=-= ⇒ expect-empty-stack

See expect-empty-stack.

^str ⇒ str lambda

See lambda.

^ ⇒ lambda

See lambda.

apply

quot ⇒ (a_*)

Returns a new quotation obtained by evaluating each element of quot in a separate stack.

args

∅ ⇒ quot

Returns a list of all arguments passed to the current program.

bind

a 'sym ⇒ ∅

Binds the specified value (auto-quoted) to an existing symbol 'sym.

bool

a ⇒ bool

Converts a to a boolean value based on the following rules:

If a is a boolean value, no conversion is performed.
If a is null, it is converted to false.
If a is a numeric value, zero is converted to false, otherwise it is converted to true.
If a is a quotation or a dictionary, the empty quotation or dictionary is converted to false, otherwise it is converted to true.
If a is a string, the empty string, and "false" are converted to false, otherwise it is converted to true.

case

((quot₁ quot₂)_*) ⇒ a_*

This operator takes a quotation containing n different conditional branches.

Each branch must be a quotation containing two quotations, and it is processed as follows:

if quot₁ evaluates to true, then the quot₂ is executed.
if quot₁ evaluates to false, then the following branch is processed (if any).

Example

The following program prints “Smaller than 3”:

(
   ((2 > 3) ("Greater than 3" put!))
   ((2 < 3) ("Smaller than 3" put!))
   ((true) ("Exactly 3" put!))
) case

compiled?

∅ ⇒ bool

Returns true if the current program has been compiled.

define

a 'sym ⇒ ∅

Defines a new symbol 'sym, containing the specified value.

define-sigil

a 'sym ⇒ ∅

Defines a new sigil 'sym, containing the specified value (auto-quoted if not already a quotation).

defined-symbol?

'sym ⇒ bool

Returns true if the symbol 'sym is defined, false otherwise.

defined-sigil?

'sym ⇒ bool

Returns true if the symbol 'sym is defined, false otherwise.

delete-sigil

'sym ⇒ ∅

Deletes the specified symbol 'sym.

delete-sigil

'sym ⇒ ∅

Deletes the specified user-defined sigil 'sym.

dequote

quot ⇒ a_*

Pushes the contents of quotation quot on the stack.

Each element is pushed on the stack one by one. If any error occurs, quot is restored on the stack.

dev

∅ ⇒ ∅

Toggles development mode.

dev?

∅ ⇒ bool

Returns true if the current program is being executed in development mode.

eval

str ⇒ a_*

Parses and interprets str.

exit

int ⇒ ∅

Exits the program or shell with int as return code.

expect

quot₁ ⇒ quot₂

If the -d (--dev) flag is specified when running the program, validates the first n elements of the stack against the type descriptions specified in quot₁ (n is quot₁’s length) and if all the elements are valid returns them wrapped in quot₂ (in reverse order). If the -d (--dev) flag is not specified when running the program, no validation is performed and all elements are just returned in a quotation in reverse order.

Tips

You can specify a typed dictionary by prepending the type name with dict:. Example: dict:socket
You can specify two or more matching types by separating combined together in a logical type expression, e.g.: string|quot

expect-empty-stack

∅ ⇒ ∅

Raises an error if the stack is not empty.

float

a ⇒ flt

Converts a to a float value based on the following rules:

If a is true, it is converted to 1.0.
If a is false, it is converted to 0.0.
If a is null, it is converted to 0.0.
If a is a integer, it is converted to float value.
If a is a float, no conversion is performed.
If a is a string, it is parsed as a float value.

foreach

quot₁ quot₂ ⇒ a_*

Applies the quotation quot₂ to each element of quot₁.

format-error

dict:error ⇒ str

Formats the error dict:error as a string.

Example

The following code:

 (
   (
      {"MyError" :error "This is a test error" :message} raise
   ) 
   (format-error)
 ) try

produces: "This is a test error"

from-json

str ⇒ a

Converts a JSON string into min data.

from-yaml

str ⇒ a

Converts a YAML string into min data.

Note

At present, only YAML objects containing string values are supported.

gets

∅ ⇒ str

Reads a line from STDIN and places it on top of the stack as a string.

help

'sym ⇒ ∅

Prints the help text for 'sym, if available.

quot₁ quot₂ quot₃ ⇒ a_*

If quot₁ evaluates to true then evaluates quot₂, otherwise evaluates quot₃.

import

'sym ⇒ ∅

Imports the a previously-loaded module 'sym, defining all its symbols in the current scope.

infix-dequote

quot ⇒ a

Dequotes quot using infix notation.

Note that no special operator preference is defined, symbols precedence is always left-to-right. However, you can use parentheses (quotes) to evaluate expressions before others.

Example

The following program leaves 17 on the stack:

 (2 + (3 * 5)) infix-dequote

while this program leaves 25 on the stack:

 (2 + 3 * 5) infix-dequote

integer

a ⇒ int

Converts a to an integer value based on the following rules:

If a is true, it is converted to 1.
If a is false, it is converted to 0.
If a is null, it is converted to 0.
If a is an integer, no conversion is performed.
If a is a float, it is converted to an integer value by truncating its decimal part.
If a is a string, it is parsed as an integer value.

invoke

'sym ⇒ a_*

Assuming that 'sym is a formatted like dictionary/symbol, calls symbol defined in dictionary (note that this also works for nested dictionaries.

Example

The following program leaves 100 on the stack:

{{100 :b} :a} :test *test/a/b

lambda

quot 'sym ⇒ ∅

Defines a new symbol 'sym, containing the specified quotation quot. Unlike with define, in this case quot will not be quoted, so its values will be pushed on the stack when the symbol 'sym is pushed on the stack.

Essentially, this symbol allows you to define an operator without any validation of constraints and bind it to a symbol.

lambdabind

lambdabind ⇒ lambda-bind

See lambda-bind.

lambda-bind

quot 'sym ⇒ ∅

Binds the specified quotation to an existing symbol 'sym which was previously-set via lambda.

line-info

∅ ⇒ dict

Returns a dictionary dict containing a filename, line, and column properties identifying the filename, line and column of the current symbol.

linrec

quot₁ quot₂ quot₃ quot₄ ⇒ a_*

Implements linear recursions as follows:

Evaluates quot₁.
- If quot₁ evaluates to true, then it evaluates quot₂.
- Otherwises it executes quot₃ and recurses using the same four quotations.
Finally, it executes quot₄.

Example

The following program leaves 120 on the stack, the factorial of 5:

 5 (dup 0 ==) 'succ (dup pred) '* linrec

load

'sym ⇒ a_*

Parses and interprets the specified min file 'sym, adding .min if not specified.

load-symbol

'sym ⇒ a_*

Loads the contents of symbol 'sym from the .min_symbols file.

loglevel

'sym ⇒ ∅

Sets the current logging level to 'sym. 'sym must be one of the following strings or quoted symbols:

debug
info
notice
warn
error
fatal

Note

The default logging level is notice.

loglevel?

∅ ⇒ str

Returns the current log level (debug, info, notice, warn, error or fatal).

operator

quot ⇒ a_*

Provides a way to define a new operator (symbol, sigil, or typeclass) on the current scope performing additional checks (compared to define and define-sigil), and automatically mapping inputs and outputs.

quot is a quotation containing:

A symbol identifying the type of operator to define (symbol, sigil, or typeclass).
A symbol identifying the name of the operator.
A quotation defining the signature of the operator, containing input and output values identified by their type and a capturing symbol, separated by the ==> symbol.
A quotation identifying the body of the operator.

The main additional features offered by this way of defining operators are the following:

If in development mode (-d or --dev flag specified at run time), both input and output values are checked against a type (like when using the expect operator and automatically captured in a symbol that can be referenced in the operator body quotation.
The full signature of the operator is declared, making the resulting code easier to understand at quick glance.
An exception is automatically raised if the operator body pollutes the stack by adding or removing elements from the stack (besides adding the declared output values).
It is possible to use the return symbol within the body quotation to immediately stop the evaluation of the body quotation and automatically push the output values on the stack.

Example

The following program defines a pow operator that calculates the power of a number providing its base and exponent, and handling some NaN results using the return symbol:

 (
   symbol pow
   (num :base int :exp ==> num :result)
   ( 
     (base 0 == exp 0 == and)
       (nan @result return)
     when
     (base 1 == exp inf == and)
       (nan @result return)
     when
     (base inf == exp 0 == and)
       (nan @result return)
     when
     exp 1 - :n
     base  (dup) n times (*) n times @result
   )
 ) ::

opts

∅ ⇒ dict

Returns a dictionary of all options passed to the current program, with their respective values.

parent-scope

dict₁ ⇒ dict₂

Returns a dictionary dict₂ holding a reference to the parent scope of dict₁ or null if dict₁ is global.

parse

str ⇒ quot

Parses str and returns a quoted program quot.

prefix-dequote

quot ⇒ a

Dequotes quot using prefix notation (essentially it reverses quot and dequotes it).

Example

The following program leaves 4 on the stack:

(* 8 4) prefix-dequote

prompt

∅ ⇒ str

This symbol is used to configure the prompt of the min shell. By default, it is set to the following quotation:

("[$1]$$ " (.) => %)

Unlike other predefined symbols, this symbol is unsealed, which means it can be modified.

publish

'sym dict ⇒ ∅

Publishes symbol 'sym to the scope of dict.

puts

a ⇒ a

Prints a and a new line to STDOUT.

quit

∅ ⇒ ∅

Exits the program or shell with 0 as return code.

quote

a ⇒ (a)

Wraps a in a quotation.

quotecmd

str ⇒ (sym)

Creates a command with the value of str and wraps it in a quotation.

quotesym

str ⇒ (sym)

Creates a symbol with the value of str and wraps it in a quotation.

raise

dict:error ⇒ ∅

Raises the error specified via the dictionary dict:error.

raw-args

∅ ⇒ quot

Returns a list of all arguments and (non-parsed) options passed to the current program.

remove-symbol

'sym ⇒ ∅

Removes the symbol 'sym from the .min_symbols file.

require

'sym ⇒ dict

Parses and interprets (in a separated interpreter) the specified min module, and returns a module dictionary dict containing all the symbols defined in 'sym.

This symbol will attempt to locate the specified module in this way. Given the following min program:

 'my-module require :my-module

Check for a file named my-module in the same folder as the current file (with our without a .min extension).
Check for a file named index.min in the mmm/my-module/*/index.min folder relative to the current file (locally-installed managed-module).
Check for a file named index.min in the $HOME/mmm/my-module/*/index.min folder (globally-installed managed-module). If multiple versions of the same module are present, the first one will be loaded.

return

∅ ⇒ ∅

If used within the body quotation of an operator definition, causes the interpreter to stop pushing further body elements on the stack and start pushing tbe operator output values on the stack.

If used outside of the body quotation of an operator definition, it raises an exception.

save-symbol

'sym ⇒ ∅

Saves the contents of symbol 'sym to the .min_symbols file.

scope

∅ ⇒ dict

Returns a dictionary dict holding a reference to the current scope.

This can be useful to save a reference to a given execution scope to access later on.

Example

The following program leaves {(2) :two ;module} on the stack:

{} :myscope (2 :two scope @myscope) ->

saved-symbols

∅ ⇒ (str_*)

Returns a quotation containing all symbols saved in the .min_symbols file.

scope-sigils

dict ⇒ (str_*)

Returns a list of all sigils defined in dictionary dict.

scope-symbols

dict ⇒ (str_*)

Returns a list of all symbols defined in dictionary dict.

seal-symbol

'sym ⇒ ∅

Seals symbol 'sym, so that it cannot be re-assigned.

seal-sigil

'sym ⇒ ∅

Seals the user-defined sigil 'sym, so that it cannot be re-defined.

sealed-symbol?

'sym ⇒ bool

Returns true if the symbol 'sym is sealed, false otherwise.

sealed-sigil?

'sym ⇒ bool

Returns true if the sigil 'sym is sealed, false otherwise.

sigil-help

'sym ⇒ dict:help|null

Returns the help dictionary for the sigil 'sym, if available, null otherwise.

sigils

∅ ⇒ (str_*)

Returns a list of all sigils defined in the global scope.

source

'sym ⇒ quot

Display the source code of symbol 'sym (if it has been implemented a min quotation).

string

a ⇒ str

Converts a to its string representation.

symbols

∅ ⇒ (str_*)

Returns a list of all symbols defined in the global scope.

symbol-help

'sym ⇒ dict:help|null

Returns the help dictionary for the symbol 'sym, if available, null otherwise.

tap

a quot ⇒ a

Performs the following operations:

Removes a from the stack.
For each quotation defined in quot (which is a quotation of quotations each requiring one argument and returning one argument):
1. Pushes a back to the stack.
2. Dequotes the quotation and saves the result as a.
Push the resulting a back on the stack.

Example

The following program:

{1 :a 2 :b 3 :c} (
  (dup /a  succ succ %a)
  (dup /b  succ %b)
) tap

Returns {3 :a 3 :b 3 :c}.

times

quot int ⇒ a_*

Applies the quotation quot int times.

tokenize

str ⇒ quot

Parses the min program str and returns a quotation quot containing dictionaries with a type symbol and a value symbol for each token.

to-json

a ⇒ str

Converts a into a JSON string.

to-yaml

a ⇒ str

Converts a into a YAML string.

Note

At present, only min dictionaries containing string values are supported.

try

(quot₁ quot₂_? quot₃_?) ⇒ a_*

Evaluates a quotation as a try/catch/finally block.

The must contain the following elements:

A quotation quot₁ containing the code to be evaluated (try block).
(optional) A quotation quot₂ containing the code to execute in case of error (catch block).
(optional) A quotation quot₃ containing the code to execute after the code has been evaluated, whether an error occurred or not (finally block).

Example

The following program executed on an empty stack prints the message “Insufficient items on the stack” and pushes 0 on the stack:

  (
    (pop)
    (format-error puts)
    (0)
  ) try

type

a ⇒ str

Returns the type of a.

typealias

'sym₁ 'sym₂ ⇒ ∅

Creates a type alias 'sym₁ for type expression 'sym₂.

unless

quot₁ quot₂ ⇒ a_*

If ₁ evaluates to false then evaluates ₂.

unseal-symbol

'sym ⇒ ∅

Unseals the user-defined symbol 'sym, so that it can be re-assigned.

unseal-sigil

'sym ⇒ ∅

Unseals sigil 'sym, so that it can be re-defined (system sigils cannot be unsealed).

version

∅ ⇒ str

Returns the current min version number.

when

quot₁ quot₂ ⇒ a_*

If quot₁ evaluates to true then evaluates quot₂.

while

quot₁ quot₂ ⇒ a_*

Executes quot₂ while quot₁ evaluates to true.

Example

The following program prints all natural numbers from 0 to 10:

0 :count
(count 10 <=) 
(count puts succ @count) while

with

quot₁ quot₂ ⇒ a_*

Pushes each item of quot₁ on the stack using the scope of quot₂ as scope.

`stack` Module

clear-stack

a ⇒ ∅

Empties the stack.

cleave

a₁ (quot_*) ⇒ a_*

Applies each quotation contained in the first element to the second element a₁.

cons

a₁ (a_*) ⇒ (a₁ a_*)

Prepends a₁ to the quotation on top of the stack.

dip

a₁ (a₂) ⇒ a_* a₁

Removes the first and second element from the stack, dequotes the first element, and restores the second element.

dup

a₁ ⇒ a₁ a₁

Duplicates the first element on the stack.

getstack

getstack ⇒ get-stack

See get-stack.

get-stack

∅ ⇒ (a_*)

Puts a quotation containing the contents of the stack on the stack.

∅ ⇒ ∅

Does nothing.

keep

a₁ quot ⇒ a_* a₁

Removes the first element from the stack, dequotes it, and restores the second element.

nip

a₁ a₂ ⇒ a₂

Removes the second element from the stack.

over

a₁ a₂ ⇒ a₁ a₂ a₁

Pushes a copy of the second element on top of the stack.

pick

a₁ a₂ a₃ ⇒ a₁ a₂ a₃ a₁

Pushes a copy of the third element on top of the stack.

pop

a ⇒ ∅

Removes the first element from the stack.

rolldown

a₁ a₂ a₃ ⇒ a₂ a₃ a₁

Moves the third element in first position, the second in third position and the the first in second position.

rollup

a₁ a₂ a₃ ⇒ a₃ a₂ a₁

Moves the third and second element into second and third position and moves the first element into third position.

setstack

setstack ⇒ set-stack

See set-stack.

set-stack

quot ⇒ a_*

Substitute the existing stack with the contents of quot.

sip

quot₁ quot₂ ⇒ a_* quot₁

Saves the quot₁, dequotes quot₂, and restores quot₁.

spread

a_* (quot_*) ⇒ a_*

Applies each quotation contained in the first element to each subsequent corresponding element.

swap

a₁ a₂ ⇒ a₂ a₁

Swaps the first two elements on the stack.

swons

(a_*) a₁ ⇒ (a₁ a_*)

Prepends a₁ to the quotation that follows it.

`seq` Module

all?

quot₁ quot₂ ⇒ bool

Applies predicate quot₂ to each element of quot₁ and returns true if all elements of quot₁ satisfy predicate quot₂, false otherwise.

any?

quot₁ quot₂ ⇒ bool

Applies predicate quot₂ to each element of quot₁ and returns true if at least one element of quot₁ satisfies predicate quot₂, false otherwise.

append

a quot ⇒ (a_* a)

Returns a new quotation containing the contents of quot with a appended.

get

quot int ⇒ a

Returns the n^th element of quot (zero-based).

concat

quot₁ quot₂ ⇒ quot₃

Concatenates quot₁ with quot₂.

difference

quot₁ quot₂ ⇒ quot₃

Calculates the difference quot₃ of quot₁ and quot₂.

Example

The following program leaves (2) on the stack:

(1 2 "test") ("test" "a" true 1) difference

drop

quot₁ int ⇒ quot₂

Returns a quotation quot₂ containing the remaining elements after the first n values of the input quotation quot₁, or an empty quotation if int is greater than the length of quot₁.

filter

quot₁ quot₂ ⇒ quot₃

Returns a new quotation quot₃ containing all elements of quot₁ that satisfy predicate quot₂.

Example

The following program leaves (2 6 8 12) on the stack:

(1 37 34 2 6 8 12 21)
(dup 20 < swap even? and) filter

find

quot₁ quot₂ ⇒ int

Returns the index of the first element within quot₁ that satisfies predicate quot₂, or -1 if no element satisfies it.

Example

The following program leaves 3 on the stack:

(1 2 4 8 16)
(5 >) find

first

quot ⇒ a

Returns the first element of quot.

flatten

quot₁ ⇒ quot₂

Flattens all quotations within quot₁ and returns the resulting sequence quot₂.

Example

The following program leaves (1 2 3 4 5 6 7 8) on the stack:

(1 (2 3 4) 5 (6 7) 8)
flatten

harvest

quot₁ ⇒ quot₂

Creates a new quotation quot₂ containing all elements of quot₁ except for empty quotations.

Example

The following program leaves (1 2 3) on the stack:

(1 () () () 2 () 3)
harvest

in?

quot a ⇒ bool

Returns true if a is contained in quot, false otherwise.

insert

quot₁ a int ⇒ quot₂

Inserts a as the value of the n^th element quot₁ (zero-based), and returns the modified copy of the quotation quot₂.

intersection

quot₁ quot₂ ⇒ quot₃

Calculates the intersection quot₃ of quot₁ and quot₂.

Example

The following program leaves (1 "test") on the stack:

(1 2 "test") ("test" "a" true 1) intersection

last

quot ⇒ a

Returns the last element of quot.

map

quot₁ quot₂ ⇒ quot₃

Returns a new quotation quot₃ obtained by applying quot₂ to each element of quot₁.

map-reduce

quot₁ quot₂ quot₃ ⇒ int

Applies quot₂ (map) to each element of quot₁ and then applies quot₃ (reduce) to each successive element of quot₁. quot₁ must have at least one element.

Example

The following program leaves 35 on the stack:

(1 3 5)
(dup *) (+) map-reduce

partition

quot₁ quot₂ ⇒ quot₃ quot₄

Partitions quot₁ into two quotations: quot₃ contains all elements of quot₁ that satisfy predicate quot₂, quot₄ all the others.

Example

The following program leaves (1 3 5) (2 4 6) on the stack:

(1 2 3 4 5 6)
(odd?) partition

one?

quot₁ quot₂ ⇒ bool

Applies predicate quot₂ to each element of quot₁ and returns true if only one element of quot₁ satisfies predicate quot₂, false otherwise.

prepend

a quot ⇒ (a a_*)

Returns a new quotation containing the contents of quot with a prepended.

quote-map

quot₁ ⇒ quot₂

Returns a new quotation quot₂ obtained by quoting each element of quot₁.

raw-get

quot int ⇒ dict:rawval

Returns the n^th element of quot (zero-based) wrapped in a dict:rawval.

reduce

quot₁ a₁ quot₂ ⇒ a₂

Combines each successive element of quot₁ using quot₂. On the first iteration, the first two inputs processed by quot₂ are a₁ and the first element of quot₁.

Example

The following program leaves 120 on the stack:

(1 2 3 4 5)
1 (*) reduce

reject

quot₁ quot₂ ⇒ quot₃

Returns a new quotatios quot₃ including all elements of quot₁ that do not satisfy predicate quot₂ (i.e. the opposite of filter)

remove

quot₁ int ⇒ quot₂

Returns the n^th element of quot₁ (zero-based), and returns the modified copy of the quotation quot₂.

rest

quot₁ ⇒ quot₂

Returns a new quotation quot₂ containing all elements of quot₁ quotation except for the first.

reverse

quot₁ ⇒ quot₂

Returns a new quotation quot₂ containing all elements of quot₁ in reverse order.

set

quot₁ a int ⇒ quot₂

Sets the value of the n^th element quot₁ (zero-based) to a, and returns the modified copy of the quotation quot₂.

set-sym

quot₁ 'sym int ⇒ quot₂

Sets the value of the n^th element quot₁ (zero-based) to 'sym (treating it as a symbol), and returns the modified copy of the quotation quot₂.

shorten

quot₁ int ⇒ quot₂

Returns a quotation quot₂ containing the first n values of the input quotation quot₁.

size

quot ⇒ int

Returns the length of quot.

slice

quot₁ int₁ int₂ ⇒ quot₂

Creates a new quotation quot₂ obtaining by selecting all elements of quot₁ between indexes int₁ and int₂.

Example

The following program leaves (3 4 5) on the stack:

(1 2 3 4 5 6)
2 4 slice

sort

quot₁ quot₂ ⇒ quot₃

Sorts all elements of quot₁ according to predicate quot₂.

Example

The following program leaves (1 3 5 7 9 13 16) on the stack:

(1 9 5 13 16 3 7) '> sort

symmetric-difference

quot₁ quot₂ ⇒ quot₃

Calculates the symmetric difference quot₃ of quot₁ and quot₂.

Example

The following program leaves (true "a" 2) on the stack:

(1 2 "test") ("test" "a" true 1) symmetric-difference

take

quot₁ int ⇒ quot₂

Returns a quotation quot₂ containing the first n values of the input quotation quot₁, or quot₁ itself if int is greater than the length of quot₁.

union

quot₁ quot₂ ⇒ quot₃

Calculates the union quot₃ of quot₁ and quot₂.

Example

The following program leaves (true 1 "test" "a" 2) on the stack:

(1 2 "test") ("test" "a" true 1) union

`dict` Module

/str ⇒ str dget

See dget.

%str ⇒ str dset

See dset.

ddup

dict₁ ⇒ dict₂

Returns a copy of dict₁.

ddel

dict 'sym ⇒ dict

Removes 'sym from dict₁ and returns dict₁.

dget

dict 'sym ⇒ a

Returns the value of key 'sym from dictionary dict.

dget-raw

dict 'sym ⇒ dict:rawval

Returns the value of key 'sym from dictionary dict, wrapped in a dict:rawval.

dhas?

dict 'sym ⇒ bool

Returns true if dictionary dict contains the key 'sym, false otherwise.

Example

The following program returns true:

{true :a1 "aaa" :a2 false :a3} 'a2 dhas?

dkeys

dict ⇒ (str_*)

Returns a quotation containing all the keys of dictionary dict.

dpick

dict₁ quot ⇒ dict₂

Returns a new dictionary dict₂ containing the elements of dict₁ whose keys are included in quot.

Example

The following program returns {4 :a 7 :d}:

{5 :q 4 :a 6 :c 7 :d "d" :a} ("a" "d") dpick

dpairs

dict ⇒ (a_*)

Returns a quotation containing a quotation for each value/key pair (value first, key second) of dictionary dict.

dset

dict a 'sym ⇒ dict

Sets the value of the 'sym of dict₁ to a, and returns the modified dictionary dict.

dset-sym

dict 'sym 'sym ⇒ dict

Sets the value of the 'sym of dict₁ to 'sym (treating it as a symbol), and returns the modified dictionary dict.

dtype

dict ⇒ str

Returns a string set to the type of dict (empty if the dictionary has no type).

dvalues

dict ⇒ (a_*)

Returns a quotation containing all the values of dictionary dict.

`dstore` Module

dsdelete

dict:datastore 'sym ⇒ dict:datastore

Removes an item from the datastore dict:datastore. The item is uniquely identified by 'sym, which contains the collection containing the item and the item id, separated by a forward slash (/). Puts the reference to the modified datastore back on tbe stack.

dsget

dict:datastore 'sym ⇒ dict

Retrieves item dict from datastore dict:datastore. dict is retrieved by specifying 'sym, which contains the collection containing the item and the item id, separated by a forward slash (/).

dsinit

'sym ⇒ dict:datastore

Initializes a bew datastore by creating the 'sym JSON file. Puts the datastore instance on the stack.

dspost

dict:datastore 'sym dict ⇒ dict:datastore

Adds the dictionary dict to the datastore dict:datastore inside collection 'sym, generating and adding a unique id field to dict. If the collection 'sym does not exist it is created. Puts the reference to the modified datastore back on tbe stack.

dsput

dict:datastore 'sym dict ⇒ dict:datastore

Adds the dictionary dict to the datastore dict:datastore. 'sym contains the collection where dict will be placed and the id of dict, separated by a forward slash (/). If the collection 'sym does not exist it is created. Puts the reference to the modified datastore back on tbe stack.

dsquery

dict:datastore 'sym quot ⇒ (dict_*)

Retrieves a quotation of dictionaries from the collection 'sym of datastore dict:datastore obtained by applying quot as a filter to each item of the collection, picking only the elements that match the filter.

Example

Assuming that ds is a datastore, the following program retrieves all elements of teh collection posts whose author field is set to “h3rald”:

 ds "posts" (/author "h3rald" ==) dsquery

dsread

'sym ⇒ dict:datastore

Reads the previously-created datastore from the file 'sym and puts the resulting datastore instance on the stack.

dswrite

dict:datastore ⇒ dict:datastore

Writes the contents of the datastore dict:datastore to the filesystem.

`io` Module

ask

str₁ ⇒ str₂

Prints str₁ (prompt), reads a line from STDIN and places it on top of the stack as a string.

choose

((str₁ quot₁)₊) str₂ ⇒ a_*

Prints str₂, then prints all str₁ included in the quotation prepended with a number, and waits from valid input from the user.

If the user enters a number that matches one of the choices, then the corresponding quotation quot₁ is executed, otherwise the choice menu is displayed again until a valid choice is made.

clear

∅ ⇒ ∅

Clears the screen.

column-print

quot int ⇒ a

Prints all elements of quot to STDOUT, in int columns.

confirm

str ⇒ bool

Prints str (prompt) appending " [yes/no]: ", reads a line from STDIN and:

if it matches /^y(es)?$/i, puts true on the stack.
if it matches /^no?$/i, puts false on the stack.
Otherwise, it prints Invalid answer. Please enter 'yes' or 'no': and waits for a new answer.

debug

a ⇒ a

Prints a and a new line to STDOUT, if logging level is set to debug or lower.

error

a ⇒ a

Prints a and a new line to STDERR, if logging level is set to error or lower.

fappend

str₁ str₂ ⇒ ∅

Appends str₁ to the end of file str₂.

fatal

a ⇒ a

Prints a and a new line to STDERR, and exists the program with error code 100.

fread

str ⇒ str

Reads the file str and puts its contents on the top of the stack as a string.

fwrite

str₁ str₂ ⇒ ∅

Writes str₁ to the file str₂, erasing all its contents first.

getchr

∅ ⇒ int

Reads single character from STDIN without waiting for ENTER key and places its ASCII code on top of the stack.

info

a ⇒ a

Prints a and a new line to STDOUT, if logging level is set to info or lower.

mapkey

quot 'sym ⇒ ∅

Maps the named key/key combination 'sym to the quotation quot, so that quot is executed when key 'sym is pressed.

Notes

At present, only the key names and sequences defined in the minline library are supported.
The quotation will be executed by a copy of the min interpreter created when the mapping was defined. In other words, quotations executed by key bindings will not affect the current stack.

Example

The following program:

(clear) 'ctrl+l mapkey

causes the CTRL+L key to clear the screen.

newline

∅ ⇒ ∅

Prints a new line to STDOUT.

notice

a ⇒ a

Prints a and a new line to STDOUT, if logging level is set to notice (default) or lower.

password

∅ ⇒ str

Reads a line from STDIN displaying * for each typed character, and places it on top of the stack as a string.

a ⇒ a

Prints a to STDOUT.

putchr

str ⇒ a

Prints str to STDOUT without printing a new line (str must contain only one character).

read

read ⇒ fread

See fread.

type

a ⇒ str

Puts the data type of a on the stack. In cased of typed dictionaries, the type name is prefixed by dict:, e.g. dict:module, dict:socket, etc.

unmapkey

'sym ⇒ ∅

Unmaps a previously-mapped key or key-combination 'sym, restoring the default mapping if available.

Notes

At present, only the key names and sequences defined in the minline library are supported.
At present, all the default mappings of min are those provided by the minline library.

warn

a ⇒ a

Prints a and a new line to STDERR, if logging level is set to warn or lower.

write

write ⇒ fwrite

See fwrite.

`fs` Module

absolute-path

'sym ⇒ str

Returns the absolute path to 'sym.

absolute-path?

'sym ⇒ bool

Returns true if 'sym is an absolute path.

atime

'sym ⇒ flt

Returns a timestamp corresponding to the time that file/directory 'sym was last accessed.

ctime

'sym ⇒ flt

Returns a timestamp corresponding to the time that file/directory 'sym was created.

dirname

'sym ⇒ str

Returns the path of the directory containing path 'sym.

dir?

'sym ⇒ bool

Returns true if the specified path 'sym exists and is a directory.

exists?

'sym ⇒ bool

Returns true if the specified file or directory 'sym exists.

expand-filename

'sym ⇒ str

Returns the absolute path to the file name 'sym.

expand-symlink

'sym ⇒ str

Returns the absolute path to the symlink 'sym (an error is raised if 'sym is not a symlink).

file?

'sym ⇒ bool

Returns true if the specified path 'sym exists and is a file.

filename

'sym ⇒ str

Returns the file name of path 'sym.

fperms

'sym ⇒ int

Returns the Unix permissions (expressed as a three-digit number) of file/directory 'sym.

fsize

'sym ⇒ int

Returns the size in bytes of file/directory 'sym.

fstats

'sym ⇒ dict

Returns a dictionary dict containing information on file/directory 'sym.

Example

Assuming that min is a file, the following:

"min" fstats

produces:

 {
   "min" :name
   16777220 :device
   50112479 :file
   "file" :type
   617068 :size
   755 :permissions
   1 :nlinks
   1496583112.0 :ctime
   1496584370.0 :atime
   1496583112.0 :mtime
 }

ftype

'sym ⇒ str

Returns the type of file/directory 'sym ("file" or "dir").

hidden?

'sym ⇒ bool

Returns true if file/directory 'sym is hidden, false otherwise.

join-path

quot ⇒ str

Joins the strings contained in quot with /.

normalized-path

'sym ⇒ str

Returns the normalized path to 'sym.

mtime

'sym ⇒ flt

Returns a timestamp corresponding to the time that file/directory 'sym was last modified.

relative-path

'sym₁ 'sym₂ ⇒ str

Returns the path of 'sym₁ relative to 'sym₂.

symlink?

'sym ⇒ bool

Returns true if the specified path 'sym exists and is a symbolic link.

unix-path

'sym ⇒ str

Converts all backslashes in 'sym to slashes.

windows-path

'sym ⇒ str

Converts all slashes in 'sym to backslashes.

`logic` Module

a₁ a₂ ⇒ bool

Returns true if a₁ is greater than a₂, false otherwise.

Note

Only comparisons among two numbers or two strings are supported.

a₁ a₂ ⇒ bool

Returns true if a₁ is greater than or equal to a₂, false otherwise.

Note

Only comparisons among two numbers or two strings are supported.

a₁ a₂ ⇒ bool

Returns true if a₁ is smaller than a₂, false otherwise.

Note

Only comparisons among two numbers or two strings are supported.

a₁ a₂ ⇒ bool

Returns true if a₁ is smaller than or equal to a₂, false otherwise.

Note

Only comparisons among two numbers or two strings are supported.

a₁ a₂ ⇒ bool

Returns true if a₁ is equal to a₂, false otherwise.

a₁ a₂ ⇒ bool

Returns true if a₁ is not equal to a₂, false otherwise.

|| ⇒ expect-any

See expect-any.

&& ⇒ expect-all

See expect-all.

and

bool₁ bool₂ ⇒ bool₃

Returns true if bool₁ is equal to bool₂, false otherwise.

boolean?

a ⇒ bool

Returns true if a is a boolean, false otherwise.

dictionary?

a ⇒ bool

Returns true if a is a dictionary, false otherwise.

expect-all

quot ⇒ bool

Assuming that quot is a quotation of quotations each evaluating to a boolean value, it pushes true on the stack if they all evaluate to true, false otherwise.

expect-any

quot ⇒ bool

Assuming that quot is a quotation of quotations each evaluating to a boolean value, it pushes true on the stack if any evaluates to true, false otherwise.

float?

a ⇒ bool

Returns true if a is a float, false otherwise.

bool₁ bool₂ ⇒ bool₃

Returns true if bool₁ or bool₂ is true, false otherwise.

integer?

a ⇒ bool

Returns true if a is an integer, false otherwise.

not

bool₁ ⇒ bool₂

Negates bool₁.

null?

a ⇒ bool

Returns true if a is null, false otherwise.

number?

a ⇒ bool

Returns true if a is a number, false otherwise.

quotation?

a ⇒ bool

Returns true if a is a quotation, false otherwise.

quoted-symbol?

a ⇒ bool

Returns true if a is a quoted symbol, false otherwise.

string?

a ⇒ bool

Returns true if a is a string, false otherwise.

stringlike?

a ⇒ bool

Returns true if a is a string or a quoted symbol, false otherwise.

type?

a 'sym ⇒ bool

Returns true if the data type of a satisfies the specified type expression 'sym, false otherwise.

xor

bool₁ bool₂ ⇒ bool₃

Returns true if bool₁ and bool₂ are different, false otherwise.

`str` Module

% ⇒ interpolate

See interpolate.

=% ⇒ apply-interpolate

See apply-interpolate.

apply-interpolate

str quot ⇒ str

The same as pushing apply and then interpolate on the stack.

capitalize

'sym ⇒ str

Returns a copy of 'sym with the first character capitalized.

chr

int ⇒ str

Returns the single character str obtained by interpreting int as an ASCII code.

escape

'sym ⇒ str

Returns a copy of 'sym with quotes and backslashes escaped with a backslash.

from-bin

'sym ⇒ int

Parses 'sym as a binary number.

from-dec

'sym ⇒ int

Parses 'sym as a decimal number.

from-hex

'sym ⇒ int

Parses 'sym as a hexadecimal number.

from-oct

'sym ⇒ int

Parses 'sym as a octal number.

from-semver

str ⇒ dict

Given a basic SemVer-compliant string (with no additional labels) str, it pushes a dictionary dict on the stack containing a major, minor, and patch key/value pairs.

indent

'sym int ⇒ str

Returns str containing 'sym indented with int spaces.

indexof

str₁ str₂ ⇒ int

If str₂ is contained in str₁, returns the index of the first match or -1 if no match is found.

interpolate

str quot ⇒ str

Substitutes the placeholders included in str with the values in quot.

Notes

If quot contains symbols or quotations, they are not interpreted. To do so, call apply before interpolating or use apply-interpolate instead.
You can use the $# placeholder to indicate the next placeholder that has not been already referenced in the string.
You can use named placeholders like $pwd, but in this case quot must contain a quotation containing both the placeholder names (odd items) and the values (even items).

join

quot 'sym ⇒ str

Joins the elements of quot using separator 'sym, producing str.

length

'sym ⇒ int

Returns the length of 'sym.

lowercase

'sym ⇒ str

Returns a copy of 'sym converted to lowercase.

match?

str₁ str₂ ⇒ bool

Returns true if str₂ matches str₁, false otherwise.

Tip

str₂ is a Perl Compatible Regular Expression.

ord

str ⇒ int

Returns the ASCII code int corresponding to the single character str.

parse-url

str ⇒ dict:url

Parses the url str into its components and stores them into dict:url.

prefix

'sym₁ 'sym₂ ⇒ str

Prepends 'sym₂ to 'sym₁.

repeat

'sym int ⇒ str

Returns str containing 'sym repeated int times.

replace

str₁ str₂ str₃ ⇒ str₄

Returns a copy of str₁ containing all occurrences of str₂ replaced by str₃

Tip

str₂ is a Perl Compatible Regular Expression.

replace-apply

str₁ str₂ quot ⇒ str₃

Returns a copy of str₁ containing all occurrences of str₂ replaced by applying quot to each quotation corresponding to each match.

Tip

str₂ is a Perl Compatible Regular Expression.

str₁ str₂ ⇒ quot

Returns a quotation containing the first occurrence of str₂ within str₁. Note that:

The first element of quot is the matching substring.
Other elements (if any) contain captured substrings.
If no matches are found, the quotation contains empty strings.

Tip

str₂ is a Perl Compatible Regular Expression.

search-all

str₁ str₂ ⇒ quot

Returns a quotation of quotations (like the one returned by the search operator) containing all occurrences of str₂ within str₁.

semver-inc-major

str₁ ⇒ str₂

Increments the major digit of the SemVer-compliant string (with no additional labels) str₁.

semver-inc-minor

str₁ ⇒ str₂

Increments the minor digit of the SemVer-compliant string (with no additional labels) str₁.

semver-inc-patch

str₁ ⇒ str₂

Increments the patch digit of the SemVer-compliant string (with no additional labels) str₁.

semver?

str ⇒ bool

Checks whether str is a SemVer-compliant version or not.

split

'sym₁ 'sym₂ ⇒ quot

Splits 'sym₁ using separator 'sym₂ (a Perl Compatible Regular Expression) and returns the resulting strings within the quotation quot.

strip

'sym ⇒ str

Returns str, which is set to 'sym with leading and trailing spaces removed.

substr

str₁ int₁ int₂ ⇒ str₂

Returns a substring str₂ obtained by retrieving int₂ characters starting from index int₁ within str₁.

suffix

'sym₁ 'sym₂ ⇒ str

Appends 'sym₂ to 'sym₁.

titleize

'sym ⇒ str

Returns a copy of 'sym in which the first character of each word is capitalized.

to-bin

int ⇒ str

Converts int to its binary representation.

to-dec

int ⇒ str

Converts int to its decimal representation.

to-hex

int ⇒ str

Converts int to its hexadecimal representation.

to-oct

int ⇒ str

Converts int to its octal representation.

to-semver

dict ⇒ str

Given a a dictionary dict containing a major, minor, and patch key/value pairs , it pushes a basic SemVer-compliant string (with no additional labels) str on the stack.

uppercase

'sym₁ ⇒ 'sym₂

Returns a copy of 'sym converted to uppercase.

`sys` Module

$str ⇒ str get-env

See get-env.

$ ⇒ get-env

See get-env.

!str ⇒ str system

See system.

! ⇒ system

See system.

&str ⇒ str run

See run.

& ⇒ run

See run.

∅ ⇒ str

Returns the full path to the current directory.

∅ ⇒ str

Returns the full path to the parent directory.

admin?

∅ ⇒ bool

Returns true if the program is being run with administrative privileges.

chmod

'sym int ⇒ ∅

Sets the permissions of file or directory 'sym to int. int is a three-digit representation of user, group and other permissions. See the Unix Permissions Calculator for examples and conversions.

'sym ⇒ ∅

Change the current directory to 'sym.

'sym₁ 'sym₂ ⇒ ∅

Copies the file or directory 'sym₁ to 'sym₂.

cpu

∅ ⇒ str

Returns the host CPU. It can be one of the following strings i386, alpha, powerpc, powerpc64, powerpc64el, sparc, amd64, mips, mipsel, arm, arm64.

env?

'sym ⇒ bool

Returns true if environment variable 'sym exists, false otherwise.

get-env

'sym ⇒ str

Returns environment variable 'sym.

hardlink

'sym₁ 'sym₂ ⇒ ∅

Creates hardlink 'sym₂ for file or directory 'sym₁.

'sym ⇒ quot

Returns a quotation quot containing all children (files and directories) of the directory 'sym.

ls-r

'sym ⇒ quot

Returns a quotation quot containing all children (files and directories) of the directory 'sym, recursively.

mkdir

'sym ⇒ ∅

Creates the specified directory 'sym.

'sym₁ 'sym₂ ⇒ ∅

Moves the file or directory 'sym₁ to 'sym₂.

∅ ⇒ str

Returns the host operating system. It can be one of the following strings: windows, macosx, linux, netbsd, freebsd, openbsd, solaris, aix, standalone.

put-env

'sym₁ 'sym₂ ⇒ str

Sets environment variable 'sym₂ to 'sym₁.

'sym ⇒ ∅

Deletes the specified file 'sym.

rmdir

'sym ⇒ ∅

Deletes the specified directory 'sym and all its subdirectories recursively.

run

'sym ⇒ dict

Executes the external command 'sym in the current directory without displaying its output. Returns a dictionary containing the command output and return code (in keys output and code respectively).

sleep

int ⇒ ∅

Halts program execution for int milliseconds.

symlink

'sym₁ 'sym₂ ⇒ ∅

Creates symlink 'sym₂ for file or directory 'sym₁.

system

'sym ⇒ int

Executes the external command 'sym in the current directory and pushes its return code on the stack.

unzip

'sym₁ 'sym₂ ⇒ ∅

Decompresses zip file 'sym₁ to directory 'sym₂ (created if not present).

which

'sym ⇒ str

Returns the full path to the directory containing executable 'sym, or an empty string if the executable is not found in $PATH.

zip

quot 'sym ⇒ ∅

Compresses files included in quotation quot into zip file 'sym.

`num` Module

num₁ num₂ ⇒ num₃

Sums num₁ and num₂.

num₁ num₂ ⇒ num₃

Subtracts num₂ from num₁.

-inf

∅ ⇒ num

Returns negative infinity.

num₁ num₂ ⇒ num₃

Multiplies num₁ by num₂.

num₁ num₂ ⇒ num₃

Divides num₁ by num₂.

avg

quot ⇒ num

Returns the average of the items of quot.

base

"dec"|"hex"|"oct"|"bin" ⇒ ∅

Sets the numeric base used to represent integers.

base?

∅ ⇒ "dec"|"hex"|"oct"|"bin"

Returns the numeric base currently used to represent integers (default: "dec").

bitand

int₁ int₂ ⇒ int₃

Computes the bitwise and of integer int₁ and int₂.

bitclear

int₁ quot ⇒ int₂

Sets the bytes specified via their position in int₁ through quot to 0.

bitflip

int₁ quot ⇒ int₂

Flips the bytes specified via their position in int₁ through quot.

bitnot

int₁ ⇒ int₂

Computes the bitwise complement of int₁.

bitor

int₁ int₂ ⇒ int₃

Computes the bitwise or of integers int₁ and int₂.

bitparity

int₁ ⇒ int₂

Calculate the bit parity in int₁. If the number of 1-bits is odd, the parity is 1, otherwise 0.

bitset

int₁ quot ⇒ int₂

Sets the bytes specified via their position in int₁ through quot to 0.

bitxor

int₁ int₂ ⇒ int₃

Computes the bitwise xor of integers int₁ and int₂.

even?

int ⇒ bool

Returns true if int is even, false otherwise.

div

int₁ int₂ ⇒ int₃

Divides int₁ by int₂ (integer division).

inf

∅ ⇒ num

Returns infinity.

med

quot ⇒ num

Returns the median of the items of quot.

mod

int₁ int₂ ⇒ int₃

Returns the integer module of int₁ divided by int₂.

nan

∅ ⇒ nan

Returns NaN (not a number).

odd?

int ⇒ bool

Returns true if int is odd, false otherwise.

pred

int₁ ⇒ int₂

Returns the predecessor of int₁.

product

quot ⇒ int

Returns the product of all items of quot. quot is a quotation of integers.

random

int₁ ⇒ int₂

Returns a random number int₂ between 0 and int₁-1.

Note

You must call randomize to initialize the random number generator, otherwise the same sequence of numbers will be returned.

randomize

∅ ⇒ {{null}

Initializes the random number generator using a seed based on the current timestamp.

range

quot₂ ⇒ quot₂

Takes a quotation quot₁ of two or three integers in the form of start, end and an optional step (1 if not specified) and generates the sequence and returns the resulting quotation of integers quot₂.

shl

int₁ int₂ ⇒ int₃

Computes the shift left operation of int₁ and int₂.

shr

int₁ int₂ ⇒ int₃

Computes the shift right operation of int₁ and int₂.

succ

int₁ ⇒ int₂

Returns the successor of int₁.

sum

quot ⇒ int

Returns the sum of all items of quot. quot is a quotation of integers.

`time` Module

now

∅ ⇒ flt

Returns the current time as Unix timestamp with microseconds.

timestamp

∅ ⇒ int

Returns the current time as Unix timestamp.

timeinfo

int ⇒ dict:timeinfo

Returns a timeinfo dictionary from timestamp int.

to-timestamp

dict:timeinfo ⇒ int

Converts the timeinfo dictionary dict:timeinfo to the corresponding Unix timestamp.

datetime

int ⇒ str

Returns an ISO 8601 string representing the combined date and time in UTC of timestamp int.

tformat

int str ⇒ str

Formats timestamp int using string str.

Tip

For information on special characters in the format string, see the format nim method.

`crypto` Module

aes

'sym₁ 'sym₂ ⇒ str

Encrypts or decrypts 'sym₁ using the Advanced Encryption Standard (AES) in CTR mode, using 'sym₂ as password.

decode

'sym ⇒ str

Decodes the Base64-encoded string 'sym.

encode

'sym ⇒ str

Base64-encodes 'sym.

md4

'sym ⇒ str

Returns the MD4 hash of 'sym.

md5

'sym ⇒ str

Returns the MD5 hash of 'sym.

sha1

'sym ⇒ str

Returns the SHA1 hash of 'sym.

sha224

'sym ⇒ str

Returns the SHA224 hash of 'sym.

sha256

'sym ⇒ str

Returns the SHA256 hash of 'sym.

sha384

'sym ⇒ str

Returns the SHA384 hash of 'sym.

sha512

'sym ⇒ str

Returns the SHA512 hash of 'sym.

`math` Module

abs

num₁ ⇒ num₂

Calculates tbe absolute value of num₁.

acos

num₁ ⇒ num₂

Calculates the arc cosine of num₁ (in radians).

asin

num₁ ⇒ num₂

Calculates the arc sine of num₁ (in radians).

atan

num₁ ⇒ num₂

Calculates the arc tangent of num₁ (in radians).

ceil

num ⇒ int

Returns the smallest integer int that is not smaller than num.

cos

num₁ ⇒ num₂

Calculates the cosine of num₁ (in radians).

cosh

num₁ ⇒ num₂

Calculates the hyperbolic cosine of num₁ (in radians).

d2r

num₁ ⇒ num₂

Converts num₁ from degrees to radians.

∅ ⇒ num

Returns the value of the e constant (Euler’s number).

floor

num ⇒ int

Returns the largest integer int that is not greater than num.

num₁ ⇒ num₂

Calculates the natural logarithm of num₁.

log10

num₁ ⇒ num₂

Calculates the common logarithm of num₁.

log2

num₁ ⇒ num₂

Calculates the binary logarithm of num₁.

∅ ⇒ num

Returns the value of the π constant.

pow

num₁ num₂ ⇒ num₃

Computes num₁ to power raised of num₂.

r2d

num₁ ⇒ num₂

Converts num₁ from radians to degrees.

round

num₁ int ⇒ num₂

Rounds num₁ to the int^th decimal place.

sin

num₁ ⇒ num₂

Calculates the sine of num₁ (in radians).

sinh

num₁ ⇒ num₂

Calculates the hyperbolic sine of num₁ (in radians).

sqrt

num₁ ⇒ num₂

Returns square root of num₁.

tan

num₁ ⇒ num₂

Calculates the tangent of num₁ (in radians).

tanh

num₁ ⇒ num₂

Calculates the hyperbolic tangent of num₁ (in radians).

tau

∅ ⇒ num

Returns the value of the τ constant (2π).

trunc

num₁ ⇒ num₂

Truncates num to the decimal point.

`net` Module

dict:socket₁ dict:socket₂ ⇒ dict:socket₁

Makes dict:socket₂ (server) accept a connection from dict:socket₁ (client). Returns the client socket dict:socket₁ from which it will be possible to receive data from.

dict:socket ⇒ ∅

Closes a previously-opened socket.

connect

dict:socket str int ⇒ dict:socket

Connects socket dict:socket to address str and port int.

Example

The following code shows how to send a message to a server running on localhost:7777. The message is passed as the first argument to the program.

{} socket "localhost" 7777 connect :cli

args 1 get :msg

"Sending message \"$1\" to localhost:7777..." (msg) => % puts!

cli "$1\n" (msg) => % send

"Done." puts!

cli close

listen

dict dict:socket₁ ⇒ dict:socket₂

Makes socket dict:socket₁ listen to the specified address and port. dict can be empty or contain any of the following properties, used to specify the address and port to listen to respectively.

address: The address to listen to (default: 0.0.0.0).
port: The port to listen to (default: 80).

Example

The following code shows how to create a simple server that listens on port 7777, prints data received from clients, and exits when it receives the string exit:

{} socket {"127.0.0.1" :address 7777 :port} listen :srv

"Server listening on localhost:7777" puts!

{} socket :cli
"" :line
(line "exit" !=)
(
  srv cli accept #cli
  cli recv-line @line
  "Received: $1" (line) => % puts!
) while

"Exiting..." puts!

srv close

recv

dict:socket int ⇒ str

Waits to receive int characters from dict:socket and returns the resulting data str.

recv-line

dict:socket ⇒ str

Waits to receive a line of data from dict:socket and returns the resulting data str. "" is returned if dict:socket is disconnected.

Example

The following code shows how to make a simple GET request to http://httpbin.org/uuid to receive a random UUID and display its response:

{} socket "httpbin.org" 80 connect :cli

cli "GET /uuid HTTP/1.1\r\nHost: httpbin.org\r\n\r\n" send

cli recv-line puts :line
(line "}" match not) 
(
  cli recv-line puts @line
) while

send

dict:socket str ⇒ ∅

Sends str to the connected socket dict:socket.

socket

dict ⇒ dict:socket

Opens a new socket.

dict can be empty or contain any of the following properties, used to specify the domain, type and protocol of the socket respectively.

domain

The socket domain. It can be set to one of the following values:

ipv4 (default): Internet Protocol version 4.
ipv6: Internet Protocol version 6.
unix: local Unix file (not supported on Windows systems).

type

The socket type. It can be set to one of the following values:

stream (default): Reliable stream-oriented service or Stream Socket.
dgram: Datagram service or Datagram Socket.
raw: Raw protocols atop the network layer.
seqpacket: Reliable sequenced packet service.

protocol

The socket protocol. It can be set to one of the following values:

tcp (default): Transmission Control Protocol.
udp: User Datagram Protocol.
ipv4: Internet Protocol version 4 (not supported on Windows systems).
ipv6: Internet Protocol version 6 (not supported on Windows systems).
raw: Raw IP Packets protocol (not supported on Windows systems).
icmp: Internet Control Message Protocol (not supported on Windows systems).

`http` Module

download

str₁ str₂ ⇒ ∅

Downloads the contents of URL str₁ to the local file str₂.

get-content

str₁ ⇒ str₂

Retrieves the contents of URL str₁ as str₂.

request

dict ⇒ dict:http-response

Performs an HTTP request. Note that dict is can be a standard (untyped) dictionary but its fields will be validated like if it was a dict:http-request.

Example

The following code constructs dict and passes it to the request operator to perform an HTTP GET request to http://httpbin.org/ip:

{}
  "GET" %method
  "http://httpbin.org/ip" %url
request

start-server

dict ⇒ ∅

Starts an HTTP server based on the configuration provided in dict.

dict is a dictionary containing the following keys:

address: The address to bind the server to (default: 127.0.0.1).
port: The port to bind the server to.
handler: A quotation with the following signature, used to handle all incoming requests: dict:http-request ⇒ dict:http-response

Example

The following program starts a very simple HTTP server that can display the current timestamp or date and time in ISO 8601 format:

; Define the request handler
(
  ; Assume there is a request on the stack, take it off and give it the name req
  :req
  ; Let's see what we got (print req to standard out)
  "THE REQUEST:" puts! req puts!
  ; The request is a dictionary, we retrieve the value for the key url, and give it the name url
  req /url :url
  "THE URL is '$1'." url quote % puts!
  ; Constuct response body
  (
    (("/datetime" url ==) (timestamp datetime))
    (("/timestamp" url ==) (timestamp string))
    (("/shutdown" url ==) ("Stopping server..." puts! stop-server))
    (("/" url ==) (
      ; this is a bit short, but works with Chrome, IE, Edge, Safari
      "<a href='/datetime'>datetime</a>, <a href='/timestamp'>timestamp</a>, <a href='/shutdown'>stop</a>"
    ))
    ((true) ("Invalid Request: $1" url quote %))
  ) case
  :body
  ; Prepare the response
  {} body %body
  dup puts!
)
; The request handler is ready, give it the name handler
:handler

; Create the parameter dictionary for the server
{}
handler %handler
5555 %port

; Start server
"Server started on port 5555." puts!
"Press Ctrl+C to stop." puts!
start-server

stop-server

∅ ⇒ ∅

Stops the currently-running HTTP server. This operator should be used within an HTTP server handler quotation.

`xml` Module

from-xml

'sym ⇒ xml-node

Returns an xml-node representing an XML string representing an element or fragment.

Example

The following program:

"<a href='https://min-lang.org'>min web site</a>" from-xml

returns the following:

{
  {"https://min-lang.org" :href} :attributes
 ({"min web site" :text}) :children
 "a" :tag
 ;xml-element
}

to-xml

xml-node ⇒ str

Returns a str representing an XML node.

xcdata

'sym ⇒ dict:xml-cdata

Returns a dict:xml-cdata representing an XML CDATA section.

xcomment

'sym ⇒ dict:xml-comment

Returns a dict:xml-comment representing an XML comment.

xelement

'sym ⇒ dict:xml-element

Returns a dict:xml-element representing an XML element (it will be an empty element with no attributes or children).

xentity

'sym ⇒ dict:xml-entity

Returns a dict:xml-entity representing an XML entity.

xquery

dict:xml-element 'sym ⇒ dict:xml-element

Returns an dict:xml-element representing the first element matching CSS the selector 'sym.

Example

The following program:

"<ul>
   <li class='test'>first</li>
   <li class='other'>second</li>
   <li class='test'>third</li>
</ul>" 
from-xml ".test" xquery

Returns the following:

{
  {"test" :class} :attributes 
  ({"first" :text}) :children 
  "li" :tag 
  ;xml-element
}

xqueryall

dict:xml-element 'sym ⇒ dict:xml-element

Returns a list of dict:xml-element dictionaries representing all the elements matching CSS the selector 'sym.

Example

The following program:

"<ul>
   <li class='test'>first</li>
   <li class='other'>second</li>
   <li class='test'>third</li>
</ul>" 
from-xml ".test" xqueryall

Returns the following:

({
  {"test" :class} :attributes 
  ({"first" :text}) :children 
  "li" :tag 
  ;xml-element
}
{
  {"test" :class} :attributes 
  ({"third" :text}) :children 
  "li" :tag 
  ;xml-element
})

xtext

'sym ⇒ dict:xml-text

Returns a dict:xml-text representing an XML text node.