all repos — min @ null

A small but practical concatenative programming language.

site/contents/get-started.md

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
 100
 101
 102
 103
 104
 105
 106
 107
 108
 109
 110
 111
 112
 113
 114
 115
 116
 117
 118
 119
 120
 121
 122
 123
 124
 125
 126
 127
 128
 129
 130
 131
 132
 133
 134
 135
 136
 137
 138
 139
 140
 141
 142
 143
 144
 145
 146
 147
 148
 149
 150
 151
 152
 153
 154
 155
 156
 157
 158
 159
 160
 161
 162
 163
 164
 165
 166
 167
 168
 169
 170
 171
 172
 173
 174
 175
 176
 177
 178
 179
 180
 181
 182
 183
-----
content-type: "page"
title: "Get Started"
-----
{@ _defs_.md || 0 @}


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

* {#release||{{$version}}||macosx||macOS||x64#} <small>[{#lite-release||{{$version}}||macosx||macOS||x64#}, {#mini-release||{{$version}}||macosx||macOS||x64#}]</small>
* {#release||{{$version}}||windows||Windows||x64#} <small>[{#lite-release||{{$version}}||windows||Windows||x64#}, {#mini-release||{{$version}}||windows||Windows||x64#}]</small>
* {#release||{{$version}}||linux||Linux||x64#} <small>[{#lite-release||{{$version}}||linux||Linux||x64#}, {#mini-release||{{$version}}||linux||Linux||x64#}]</small>

{#release -> [min v$1 for $3 ($4)](https://github.com/h3rald/min/releases/download/v$1/min\_v$1\_$2\_$4.zip) #}
{#lite-release -> [lite](https://github.com/h3rald/min/releases/download/v$1/litemin\_v$1\_$2\_$4.zip) #}
{#mini-release -> [mini](https://github.com/h3rald/min/releases/download/v$1/minimin\_v$1\_$2\_$4.zip) #}

{{guide-download}}

## Building from Source

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

### Using nimble

If you already installed [nim](https://nim-lang.org), you probably already have the [nimble](https://github.com/nim-lang/nimble) package manager installed.

If that's the case, simply run **nimble install min**. This will actually install and run [nifty](https://github.com/h3rald/nifty) which will download min dependencies for you before compiling. 

### Without using nimble

1. Download and install [nim](https://nim-lang.org).
2. Download and build [nifty](https://github.com/h3rald/nifty), and put the nifty executable somewhere in your [$PATH](class:kwd).
3. Clone the min [repository](https://github.com/h3rald/min).
4. Navigate to the min repository local folder.
5. Run **nifty install** to download min’s dependencies.
7. Run **nim c -d:release min.nim**.

### 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 {#link-module||http#}.
* use the cryptographic symbols defined in the {#link-module||crypto#}.

> %note%
> Note
> 
> By default, this flag is enabled when compiling the executable files included with official releases.

#### -d:lite

If the **d:lite** flag is specified, a more minimal executable file will be generated (typically, it should be called "litemin"), however the following functionalities will not be available:

* The {#link-module||crypto#}
* The {#link-module||net#}
* The {#link-module||http#}
* The {#link-module||math#}
* The {#link-operator||sys||zip#} and {#link-operator||sys||unzip#} operators.

#### -d:mini

If the **d:mini** flag is specified, an even more minimal executable file will be generated (typically, it should be called "minimin"), however the following functionalities will not be available:

* The {#link-module||crypto#}
* The {#link-module||net#}
* The {#link-module||http#}
* The {#link-module||math#}
* The {#link-module||io#}
* The {#link-module||fs#}
* The {#link-module||sys#}
* The following operators:
  * {#link-operator||lang||load#}
  * {#link-operator||lang||require#}
  * {#link-operator||lang||read#}
  * {#link-operator||lang||to-json#}
  * {#link-operator||lang||from-json#}
  * {#link-operator||lang||raw-args#}
  * {#link-operator||lang||save-symbol#}
  * {#link-operator||lang||load-symbol#}
  * {#link-operator||lang||saved-symbol#}
  * {#link-operator||lang||loaded-symbol#}
  * {#link-operator||str||search#}
  * {#link-operator||str||match#}
  * {#link-operator||str||replace#}
  * {#link-operator||str||regex#}
  * {#link-operator||str||semver?#}
  * {#link-operator||str||from-semver#}
  * {#link-operator||str||parse-url#}
  * {#link-operator||str||decode-url#}
  * {#link-operator||str||encode-url#}
  * {#link-operator||sys||zip#}
  * {#link-operator||sys||unzip#}

Additionally:

* No checks will be performed when defining symbols.
* Only the simple REPL will be available.
* There will be no support for dynamic libraries.
* The **-m, \-\-module-path** and **-a, \-\-asset-path** options have no effect.
* No environment configuration files ([.minrc](class:file), [.min_symbols](class:file)) are used.

## Running the min Shell

To start min shell, run [min -i](class:cmd). You will be presented with a prompt displaying the path to the current directory:

> %min-terminal%
> [[/Users/h3rald/test]$](class:prompt)

You can type min code and press [ENTER](class:kbd) to evaluate it immediately:

> %min-terminal%
> [[/Users/h3rald/test]$](class:prompt) 2 2 +
>  4 
> [[/Users/h3rald/test]$](class:prompt)

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

> %min-terminal%
> [[/Users/h3rald/test]$](class:prompt) dup *
>  16
> [[/Users/h3rald/test]$](class:prompt)

To exit min shell, press [CTRL+C](class:kbd) or type [0 exit](class:cmd) and press [ENTER](class:kbd).

> %tip%
> 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](class:cmd) instead, and run min shell with a bare-bones REPL. 

## Executing a min Program

To execute a min script, you can:

* Run `min -e:"... program ..."` to execute a program inline.
* Run `min myfile.min` to execute a program contained in a file.

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](class:file):

> %min-terminal%
> 
> [$](class:prompt) cat myfile.min | min

## Compiling a min Program

min programs can be compiled to a single executable simply by specifying the `-c` (or `--compile`) flag when executing a min file:

> %min-terminal%
> 
> [$](class:prompt) min -c myfile.min

Essentially, this will:

1. Generate a [myfile.nim](class:file) containing the equivalent Nim code of your min program.
2. 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-terminal%
> 
> [$](class:prompt) min -c myfile.min -n:-d:release

Additionally, you can also use `-m:<path>` (or `--module-path`) to specify one path containing [.min](class:ext) files which will be compiled as well (but not executed) along with the specified file. Whenever a {#link-operator||lang||load#} symbol is used to load an external [.min](class:ext) file, it will attempt to load from the pre-loaded files first before searching the filesystem.

For example, the following command executed in the root folder of the min project will compile [run.min](class:file) along with all [.min](class:ext) files included in the [task](class:dir) and its subfolders:

> %min-terminal%
> 
> [$](class:prompt) min -c 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%
> Note
> 
> In order to successfully compile [.min](class.ext) files, Nim must be installed on your system and min must be installed via nimble.

## Syntax Highlighting

* If you are using [Visual Studio Code](https://code.visualstudio.com/), you can install the official [min extension](https://marketplace.visualstudio.com/items?itemName=h3rald.vscode-min-lang) which provides syntax highlighting support, code folding, and auto-indentation.
* If you are using [Vim](https://www.vim.org), a [min.vim](https://github.com/h3rald/min/blob/master/min.vim) syntax definition file is available in the min repo.
* If you are using [Sublime Text 3](https://www.sublimetext.com/3), Rafael Carrasco created a min syntax definition file that is available [here](https://github.com/rscarrasco/min-sublime-syntax).