jeff/dust
1
0
Fork 0
Code Issues

Write docs

Browse Source
This commit is contained in:
Jeff 2024-01-30 01:38:19 -05:00
parent 5adfa716fd
commit 281732924c
2 changed files with 39 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
README.md
View File

@ -19,7 +19,7 @@ async {
}
```
You can use Dust to run complex operations simply and safely, you can even invoke other programs, run them at the same time, capture their output, and pipe them together.
You can use Dust to run complex operations simply and safely. You can even invoke other programs, run them at the same time, capture their output, and pipe them together.
```dust
# Run each statment in this block in its own thread.
@ -46,7 +46,7 @@ async {
}
```
Dust is an interpreted, strictly typed language with first class functions. It emphasises concurrency by allowing any group of statements to be executed in parallel. Dust includes built-in tooling to import and export data in a variety of formats, including JSON, TOML, YAML and CSV.
Dust is an interpreted, strictly typed language with first class functions, embracing concurrency by allowing any group of statements to be executed in parallel. Dust includes built-in tooling to import and export data in a variety of formats, including JSON, TOML, YAML and CSV. Dust aims to be panic-free. That means that the interpreter will only fail to run a program due to an intended error, such as a type error or syntax error. If your program passes the these checks, it will run correctly.
<!--toc:start-->
- [Dust](#dust)
@ -69,20 +69,35 @@ Dust is an interpreted, strictly typed language with first class functions. It e
## Installation
### Cargo
You must have the default rust toolchain installed and up-to-date. Install [rustup] if it is not already installed. Run `cargo install dust-lang` then run `dust` to start the interactive shell.
To build from source, clone the repository and build the parser. To do so, enter the `tree-sitter-dust` directory and run `tree-sitter-generate`. In the project root, run `cargo run` to start the shell. To see other command line options, use `cargo run -- --help`.
### Build From Source
To build from source, clone the repository and build the parser. To do so, enter the `tree-sitter-dust` directory and run `tree-sitter-generate`. In the project root, run `cargo run` to start the shell. If you get errors about a linking with C, read them carefully to determine which prerequisites are needed.
On Fedora, you can install these prerequisites with:
```sh
sudo dnf group install -y 'C Development Tools and Libraries' && sudo dnf install -y cmake
```
## Usage
After installation, the command line interpreter can be given source code to run or it can launch the command-line shell.
After installation, the command line interpreter can be given source code to run or it can launch the command-line shell. As with intepreters like `sh` and `bash`, you can use the `-c` flag to pass source code directly.
```sh
cargo install dust-lang
dust -c "output('Hello world!')"
# Output: Hello world!
```
Or just provide a path to the source file.
```sh
dust examples/hello_world.ds
```
Run `dust --help` to see the available commands and options.
```txt

28
docs/language.md
View File

@ -2,6 +2,12 @@
!!! This is a **work in progress** and has incomplete information. !!!
This is an in-depth description of the syntax and abstractions used by the Dust language. It is not necessary to read or understand all of it before you start using Dust. Instead, refer to it when you need help with the syntax or understanding how the code is run.
Each section of this document corresponds to a node in the concrete syntax tree. Creating this tree is the first step in interpreting Dust code. Second, the syntax tree is traversed and an abstract tree is generated. Each node in the syntax tree corresponds to a node in the abstract tree. Third, the abstract tree is verified to ensure that it will not generate any values that violate the type restrictions. Finally, the abstract tree is run, beginning at the [root](#root).
You may reference the [grammar file](tree-sitter-dust/grammar.js) and the [Tree Sitter docs](https://tree-sitter.github.io/) while reading this guide to understand how the language is parsed.
<!--toc:start-->
- [Dust Language Reference](#dust-language-reference)
- [Values](#values)
@ -22,9 +28,10 @@
- [None](#none)
- [List and List Contents](#list-and-list-contents)
- [Unstructured Map](#unstructured-map)
- [Collection](#collection)
- [Function Types](#function-types)
- [Option Type](#option-type)
- [Structures](#structures)
- [Custom Types](#custom-types)
- [Statements](#statements)
- [Assignment](#assignment)
- [Blocks](#blocks)
@ -46,12 +53,9 @@
- [New](#new)
- [Command](#command)
- [Built-In Values](#built-in-values)
- [Comments](#comments)
<!--toc:end-->
Dust is a general purpose, interpreted and strictly typed language with first-class functions. This guide is an in-depth description of the abstractions and concepts that are used to implement the language.
Dust aims to be panic-free. That means that the interpreter will only fail to run a program due to an intended error, such as a type error or a syntax error.
## Values
There are ten kinds of value in Dust. Some are very simple and are parsed directly from the source code, some are collections and others are used in special ways, like functions and structures. All values can be assinged to an [identifier](#identifiers).
@ -168,7 +172,7 @@ Dust includes built-in functions to work with option values: `is_none`, `is_some
### Structure
A structure is an **concrete type value**. It is a value, like any other, and can be [assigned](#assignment) to an [identifier](). It can also be instantiated as a [map]() that will only allow the variables present in the structure. Default values may be provided for each variable in the structure, which will be propagated to the map it creates. Values without defaults must be given a value during instantiation.
A structure is an **concrete type value**. It is a value, like any other, and can be [assigned](#assignment) to an [identifier](#identifier). It can also be instantiated as a [map](#map) that will only allow the variables present in the structure. Default values may be provided for each variable in the structure, which will be propagated to the map it creates. Values without defaults must be given a value during instantiation.
```dust
struct User {
@ -185,7 +189,7 @@ bob = new User {
# The variable "bob" is a structured map.
```
A map created by using [new]() is called a **structured map**. In other languages it may be called a "homomorphic mapped type". Dust will generate errors if you try to set any values on the structured map that are not allowed by the structure.
A map created by using [new](#new) is called a **structured map**. In other languages it may be called a "homomorphic mapped type". Dust will generate errors if you try to set any values on the structured map that are not allowed by the structure.
## Types
@ -208,7 +212,7 @@ The simple types, and their notation are:
### Number
The `number` type may represent a value of type `int` or `float`.
The `num` type may represent a value of type `int` or `float`.
### Any
@ -222,6 +226,8 @@ The `none` type indicates that no value should be found after executing the stat
### Unstructured Map
### Collection
### Function Types
A function's type specification is more complex than other types. A function value must always have its arguments and return type specified when the **function value** is created.
@ -266,7 +272,7 @@ stdout_message = new Message {
TODO
### Structures
### Custom Types
TODO
@ -391,3 +397,7 @@ TODO
## Built-In Values
TODO
## Comments
TODO