From 58780b5530637923b57a22f7a8faa5609f65bf21 Mon Sep 17 00:00:00 2001 From: Jeff Date: Tue, 13 Aug 2024 22:25:33 -0400 Subject: [PATCH] Write docs and clean up --- README.md | 107 +++++++++++------- dust-lang/src/parser.rs | 5 - {dust_examples => examples}/assets/data.json | 0 .../assets/jq_data.json | 0 .../assets/seaCreatures.json | 0 {dust_examples => examples}/async_count.ds | 0 {dust_examples => examples}/fizzbuzz.ds | 0 {dust_examples => examples}/guessing_game.ds | 0 {dust_examples => examples}/hello_world.ds | 0 {dust_examples => examples}/json_length.ds | 0 {dust_examples => examples}/type_inference.ds | 0 11 files changed, 67 insertions(+), 45 deletions(-) rename {dust_examples => examples}/assets/data.json (100%) rename {dust_examples => examples}/assets/jq_data.json (100%) rename {dust_examples => examples}/assets/seaCreatures.json (100%) rename {dust_examples => examples}/async_count.ds (100%) rename {dust_examples => examples}/fizzbuzz.ds (100%) rename {dust_examples => examples}/guessing_game.ds (100%) rename {dust_examples => examples}/hello_world.ds (100%) rename {dust_examples => examples}/json_length.ds (100%) rename {dust_examples => examples}/type_inference.ds (100%) diff --git a/README.md b/README.md index 9ad0557..0744997 100644 --- a/README.md +++ b/README.md @@ -3,57 +3,84 @@ High-level programming language with effortless concurrency, automatic memory management and type safety. -## Concepts +Dust is a work in progress. Because it aims to deliver a high level of safety, extensive testing +is required. The language is still in the design phase, and the syntax is subject to change. -Dust is heavily influenced by Rust, but aims to be more high-level and easier to use. Its approach -to safety is similar in that it will refuse to run programs with issues that can be caught by -static analysis. However, Dust is not compiled and while performance is a concern, it is less -important than safety and ease of use. +## Usage + +The Dust command line tool can be used to run Dust programs. It is not yet available outside of +this repository. + +```sh +cargo run --package dust-shell -- examples/hello_world.ds +``` + +```sh +cargo run --package dust-shell -- -c "'Hello my name is ' + read_line() + '!'" +``` + +Dust is easily embedded in another program. You can run a dust program of any size or complexity +with a single function. + +```rust +use dust_lang::{run, Value}; + +fn main() { + let code = " + x = 'Dust' + y = ' is awesome!' + + write_line(x + y) + + 42 + "; + + let result = dust.run(code).unwrap(); + + assert_eq!(result, Ok(Some(Value::integer(42)))); +} +``` + +## Concepts ### Effortless Concurrency -Rust promises *fearless* concurrency, and Dust takes it a step further by making concurrency as -*effortless* as possible. Dust is organized into **statements**, and any sequence of statements can -be run concurrently by simply adding the `async` keyword before the block of statements. +Dust takes it a step further by making concurrency as effortless as possible. Dust is organized +into **statements**, and any sequence of statements can be run concurrently by simply adding the +`async` keyword before the block of statements. -```dust -# This function will count from 0 to 9, sleeping for an increasing amount of -# time between each number. -count_slowly = fn ( - multiplier: int, -) { - i = 0 +```rust +// Counts from 0 to 9, sleeping for an increasing amount of time between each. +count_slowly = fn (multiplier: int) { + i = 0 - while i < 10 { - sleep_time = i * multiplier; + while i < 10 { + sleep(i * multiplier) + write_line(i.to_string()) - thread.sleep(sleep_time) - io.write_line(i as str) - - i += 1 - } + i += 1 + } } async { - count_slowly(200) # Finishes last - count_slowly(100) # Finishes second - count_slowly(50) # Finishes first + count_slowly(200) // Finishes last + count_slowly(100) // Finishes second + count_slowly(50) // Finishes first } ``` ### Automatic Memory Management -Dust uses a garbage collector to automatically manage memory. During the analysis phase, Dust will -determine the number of references to each value. During execution, the intepreter will check the -context after each statement and remove values that will not be used again. +Dust uses a garbage collector to automatically manage memory. During the analysiys phase, Dust +will determine when a value is no longer needed. It can then be removed from memory at runtime. -```dust -x = 0 # x is assigned but never used - # x is removed from memory +```rust +x = 0 // x is assigned but never used + // x is removed from memory -y = 41 # y is assigned -y + 1 # y is kept alive for this statement - # y is removed from memory +y = 41 // y is assigned +y + 1 // y is kept alive for this statement + // y is removed from memory ``` ### Type Safety @@ -62,19 +89,19 @@ Dust is statically typed and null-free, but the type of a value can usually be i usage. Dust will refuse to run programs with type errors, but will usually not require type annotations. -```dust -# These two statements are identical to Dust +```rust +// These two statements are identical to Dust x = 1 x: int = 1 -# Numbers with decimals are floats +// Numbers with decimals are floats y = 10.0 y: float = 10.0 -# Strings are enclosed in single or double quotes and are guaranteed to be valid UTF-8 +// Strings are enclosed in single or double quotes and are guaranteed to be valid UTF-8 z = "Hello, world!" z: string = "Hello, world!" ``` -Aside from the ubiqutous `bool`, `int`, `float`, and `string` types, Dust also has `list`, `map`, -`range`, structures, enums and functions. +Aside from the ubiqutous `bool`, `int`, `float`, and `string` types, Dust also has list, maps, +ranges, structures, enums and functions. diff --git a/dust-lang/src/parser.rs b/dust-lang/src/parser.rs index 358846d..f96b615 100644 --- a/dust-lang/src/parser.rs +++ b/dust-lang/src/parser.rs @@ -1183,11 +1183,6 @@ mod tests { #[test] fn tuple_struct_access() { let input = "Foo(42, 'bar').0"; - let mut tree = AbstractSyntaxTree::new(); - - if parse_into(input, &mut tree).is_err() { - println!("{:?}", tree); - } assert_eq!( parse(input), diff --git a/dust_examples/assets/data.json b/examples/assets/data.json similarity index 100% rename from dust_examples/assets/data.json rename to examples/assets/data.json diff --git a/dust_examples/assets/jq_data.json b/examples/assets/jq_data.json similarity index 100% rename from dust_examples/assets/jq_data.json rename to examples/assets/jq_data.json diff --git a/dust_examples/assets/seaCreatures.json b/examples/assets/seaCreatures.json similarity index 100% rename from dust_examples/assets/seaCreatures.json rename to examples/assets/seaCreatures.json diff --git a/dust_examples/async_count.ds b/examples/async_count.ds similarity index 100% rename from dust_examples/async_count.ds rename to examples/async_count.ds diff --git a/dust_examples/fizzbuzz.ds b/examples/fizzbuzz.ds similarity index 100% rename from dust_examples/fizzbuzz.ds rename to examples/fizzbuzz.ds diff --git a/dust_examples/guessing_game.ds b/examples/guessing_game.ds similarity index 100% rename from dust_examples/guessing_game.ds rename to examples/guessing_game.ds diff --git a/dust_examples/hello_world.ds b/examples/hello_world.ds similarity index 100% rename from dust_examples/hello_world.ds rename to examples/hello_world.ds diff --git a/dust_examples/json_length.ds b/examples/json_length.ds similarity index 100% rename from dust_examples/json_length.ds rename to examples/json_length.ds diff --git a/dust_examples/type_inference.ds b/examples/type_inference.ds similarity index 100% rename from dust_examples/type_inference.ds rename to examples/type_inference.ds