mn Language Developer Guide

• • About mn
    • Why?
    • How?
    • Who?
    • When?
  • Get Started
    • Building from source
    • Running the mn REPL
    • Executing an mn Program
  • Learning the mn Language
    • Data Types
    • Operators
    • Definitions
      • Lexical scoping and binding
    • Control Flow
      • Conditionals
      • Loops
  • Extending mn
    • Implementing new mn symbols using mn itself
    • Embedding mn in your Nim program
  • Reference
    • Notation
      • Types and Values
      • Suffixes
    • Symbols

About mn

mn 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 mn are actually written using quotations, i.e. lists.
• It comes with map, filter, find, and loads of other functional goodies.
• It is probably slower than the average production-ready programming language.

Why?

mn is min’s little brother. When I started implementing min, I wanted to create a small but practical programming language you could use for shell scripting and perform common tasks. As more feature requests piled in, I noticed it slowly became more and more comprehensive and batteries-included: I slowly swapped small, less-unknown and somewhat quirky libraries used for regular expressions, compression etc. with more complete and well-known ones, added HTTPS support (and OpenSSL), improved runtime checks when creating symbols, enhanced the type system, and so on. While min can now be used on its own to create quite complex programs, it became less minimal than originally intended.

I tried to add compilation variants to reduce the modules to include but that made it more difficult to maintain and still included complex constructs like dictionaries and the full type system, so one day I decided to… fork it! And that’s how mn was born.

Is mn the successor of min? No! As I said, it is min’s little brother, and it has its own (somewhat more minimalist) life. If you want to create a quick script to glue some shell commands together, then mn is definitely the fastest way to do so. If you want to use the concatenative paradigm to create more complex applications, then min comes with a much bigger toolbox.

How?

mn is developed entirely in Nim and started off as a fork of the min programming language. I took the v0.35.0 codebase and started removing stuff, including the only vowel used in the language name. What else was removed you ask? Let’s see… compared to min, mn:

• does not have dictionaries
• does not have modules
• does not have require, include, etc.
• does not support compilation via Nim
• does not have sigils
• does not have an operator symbol, only lambda
• does not have any dependency from third-party code
• does not have type classes or type expressions, except for unions of basic types
• does not have JSON interoperability
• does not have error handling, i.e. a try/catch mechanism
• does not have any built-in support for networking, cryptography, etc.
• does not have a fancy REPL with autocompletion

What does it have then? Well, mn provides:

• exactly 72 symbols, nearly all of which are borrowed from min
• file reading/writing (via the read and write symbols)
• stdin reading (gets) and writing (puts)
• external command execution via run and automatic command expansion for all strings wrapped in square brackets
• string evaluation via eval
• string interpolation via interpolate
• a basic REPL

Who?

mn was created and implemented by Fabio Cevasco.

When?

mn source code repository was created on March 23^rd 2021.

Get Started

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

• mn v0.4.0 for macOS (x64)
• mn v0.4.0 for Windows (x64)
• mn v0.4.0 for Linux (x64)

Building from source

Alternatively, you can build mn from source as follows:

1. Download and install Nim.
2. Clone the mn repository.
3. Navigate to the mn repository local folder.
4. Run ./build.sh.

Running the mn REPL

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

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

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

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

Executing an mn Program

To execute a mn script, you can:

• Run mn -e:"... program ..." to execute a program inline.
• Run mn myfile.mn to execute a program contained in a file.

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

Learning the mn Language

mn 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 mn will look somewhat familiar to you.

If not, well, here’s how a short mn 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:

1. First, a list containing the first five integers is pushed on the stack.
2. 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.
3. 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 symbols that consume elements that are placed in order on top of a stack.

Data Types

The following data types are availanle in mn (with the corresponding shorthand symbols used in symbol 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]

Operators

Every mn program needs operators to:

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

An mn symbol is a single word that is either provided by mn like dup or defined by the user. User-defined symbols must:

• Start with a letter
• Contain zero or more letters, numbers and/or underscores.

To define a new operator symbol, you can use the lambda symbol. For example, the following symbol defines a quotation that can be used to calculate the square value of a number.

 (dup *) (square) lambda

Note that this feels like using let, but the main difference between lambda and let is that lambda only works on quotations and it doesn’t auto-quote them, so that they are immediately evaluated when the corresponding symbol is pushed on the stack.

Definitions

Being a concatenative language, mn 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
 () cons "Compiling in $# mode..." swap interpolate puts pop
 () cons "nim -d:$# c test.nim" swap interpolate run

This program takes an string containing either “release” or “development” and attempts to build the file test.nim for it. 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 let symbol to define new symbols, and symbols can also be set to literals of course.

Consider the following program:

 (mode) let
 "Compiling in $# mode..." (mode) interpolate puts pop
 "nim -d:$# c test.nim" (mode) interpolate run

In this case, the first element on the stack is saved to a symbol called mode, which is then used whenever needed in the rest of the program.

Lexical scoping and binding

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

Consider the following program:

 4 (a) let
 ( 
   a 3 + (a) let
   (
      a 1 + (a) let
      (a dup * (a) let) 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) let) 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, so that the program becomes the following:

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

Control Flow

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

Conditionals

The when symbol can be used to implement conditional statements.

For example, consider the following program:

 (
   "Unknown" (system) let 
    [uname] (uname) let
    (uname "MINGW" indexof -1 !=)
      ("Windows" (system) bind)  
    when
    (uname "Linux" indexof -1 !=)
      ("Linux" (system) bind)  
    when
    (uname "Darwin" indexof -1 !=)
      ("macOS" (system) bind)  
    when
   "The current OS is $#" (system) interpolate puts
 ) (display-os) lambda

This program defines a symbol display-os that execute the uname system command to discover the operating system and outputs a message.

Loops

The following symbols provide ways to implement common loops:

• foreach
• while

For example, consider the following program:

 (
   (n) let
   1 (i) let
   1 (f) let
   (i n <=)
   (
     f i * (f) bind 
     i 1 + (i) bind
   ) while
   f
 ) (factorial) lambda

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

Extending mn

mn provides a fairly very basic standard library. If you want to extend it, you basically have the following options:

• Implementing new mn symbols using mn itself
• Embedding mn in your Nim program

Implementing new mn symbols using mn itself

When you just want to create more high-level mn symbol using functionalities that are already available in mn, the easiest way is to create your own reusable mn symbols in separate files.

(dup *)             (pow2) lambda
(dup dup * *)       (pow3) lambda
(dup dup dup * * *) (pow4) lambda

Save your code to a file (e.g. quickpows.mn) and you can use it in other nim files using the read symbol to read it and then the eval to evaluate the program in the current scope:

"quickpows.mn" read eval

2 pow3 pow2 puts ;prints 64

Embedding mn in your Nim program

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

To do so:

1. Download and install Nim
2. Import it in your Nim file.
3. Implement a new proc to define the module.

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

import mn

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:

1. Instantiate a new mn interpreter using the newMnInterpreter proc.
2. Run the proc used to define the module.
3. Call the interpret method to interpret a mn file or string:

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

Reference

Notation

The following notation is used in the signature of all mn symbols:

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

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

Symbols

>

>=

<

<=

==

!=

&&

||

!

+

-

-inf

*

/

+inf

nan

append

apply

args

bind

concat

cons

cpu

dip

dup

dequote

eval

exit

expect

filter

(1 37 34 2 6 8 12 21)
(2 / 0 ==) filter

foreach

get

gets

getstack

indexof

interpolate

join

lambda

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

lambdabind

length

let

map

os

pop

print

puts

quote

quotesym

quotecmd

read

replace

run

setstack

swap

size

slice

(1 2 3 4 5 6)
2 4 slice

split

strip

substr

symbols

timestamp

type

when

which

while

0 (count) let
(count 10 <=) 
(count puts 1 + (count) bind) while

write

Fabio Cevasco – December 2, 2023

Powered by