@devaloop/devalang 0.0.1-alpha.5 → 0.0.1-alpha.8

package/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "devalang"
-version = "0.0.1-alpha.5"
+version = "0.0.1-alpha.8"
 authors = ["Devaloop <contact@devaloop.com>"]
 description = "Write music like code. Devalang is a domain-specific language (DSL) for sound designers and music hackers. Compose, automate, and control sound — in plain text."
 license = "MIT"

package/README.md

@@ -16,10 +16,9 @@
 
 [![VSCode Extension](https://img.shields.io/visual-studio-marketplace/v/devaloop.devalang-vscode?label=VSCode%20Extension)](https://marketplace.visualstudio.com/items?itemName=devaloop.devalang-vscode)
 
-
 ## 🎼 Devalang, by **Devaloop Labs**
 
-🎶 Compose music with code — simple, structured, sonic.
+🎶 Compose music with code — structured, expressive, and fast.
 
 Devalang is a tiny domain-specific language (DSL) for music makers, sound designers, and audio hackers.
 Compose loops, control samples, render and play audio — all in clean, readable text.
@@ -28,11 +27,13 @@ Compose loops, control samples, render and play audio — all in clean, readable
 
 From studio sketches to live sets, Devalang gives you rhythmic control — with the elegance of code.
 
-> 🚧 **v0.0.1-alpha.5 Notice** 🚧
+> 🚧 **v0.0.1-alpha.8 Notice** 🚧
 >
 > NEW: Devalang VSCode extension is now available !
 > [Get it here](https://marketplace.visualstudio.com/items?itemName=devaloop.devalang-vscode).
 >
+> NEW: Devalang supports conditional statements (`if`, `else`, `else if`) for more dynamic compositions !
+>
 > Currently, Devalang CLI is only available for **Windows**.  
 > Linux and macOS binaries will be added in future releases via cross-platform builds.
 
@@ -46,6 +47,15 @@ From studio sketches to live sets, Devalang gives you rhythmic control — with
 - [🎨 Prettier Plugin](https://www.npmjs.com/package/@devaloop/prettier-plugin-devalang)
 - [🌐 Project Website](https://devalang.com)
 
+## ❓ Why Devalang?
+
+- 🎹 Prototype audio ideas without opening a DAW
+- 💻 Integrate sound into code-based workflows
+- 🎛️ Control audio parameters through readable syntax
+- 🧪 Build musical logic with variables and conditions
+
+> Producer, coder, or both — Devalang gives you musical structure, instantly.
+
 ## 🚀 Features
 
 - 🎵 **Audio Engine**: Integrated audio playback and rendering
@@ -54,6 +64,8 @@ From studio sketches to live sets, Devalang gives you rhythmic control — with
 - 🔢 **Basic data types**: strings, numbers, booleans, maps, arrays
 - 👁️ **Watch mode** for `build`, `check` and `play` commands
 - 📂 **Project templates** for quick setup
+- 🎛️ **Custom samples**: easily load and trigger your own audio files
+- 🔄 **Looping and grouping**: create complex patterns with ease
 
 ## 📆 Installation
 
@@ -64,13 +76,13 @@ From studio sketches to live sets, Devalang gives you rhythmic control — with
 Install the package globally (NPM)
 
 ```bash
-npm install -g @devaloop/devalang
+npm install -g @devaloop/devalang@latest
 ```
 
 Usage without install (NPX)
 
 ```bash
-npx @devaloop/devalang <command>
+npx @devaloop/devalang@latest
 ```
 
 ### For contributors
@@ -79,10 +91,11 @@ npx @devaloop/devalang <command>
 > - ⚠️ Requires [Rust 1.70+](https://www.rust-lang.org/learn/get-started#installing-rust)
 
 ```bash
-> git clone https://github.com/devaloop-labs/devalang.git
-> cd devalang
-> npm install
-> cargo install --path .
+git clone https://github.com/devaloop-labs/devalang.git
+
+cd devalang
+
+npm install
 ```
 
 Development usage (you can customize arguments in package.json)
@@ -90,6 +103,7 @@ Development usage (you can customize arguments in package.json)
 ```bash
 # For syntax checking test
 npm run rust:dev:check
+
 # For building test
 npm run rust:dev:build
 ```
@@ -167,13 +181,30 @@ bpm globalBpm
 bank globalBank
 # Will declare a custom instrument bank using the globalBank variable
 
+# Loops
+
 loop 5:
     .customKick kickDuration {reverb=50, drive=25}
-    # Will play 5 times a kick for the duration of the kickDuration variable with reverb and drive effects
+    # Will play 5 times a custom sample for 500ms with reverb and overdrive effects
+
+# Groups
+
+group myGroup:
+    .customKick kickDuration {reverb=50, drive=25}
+    # Will play the same sample in a group, allowing for more complex patterns
+
+# Will be executed line by line (sequentially)
+call myGroup
+
+# Will be executed in parallel (concurrently)
+# ⚠️ Note: `spawn` runs the entire group in parallel, but the group’s internal logic remains sequential unless it uses `spawn` internally.
+# spawn myGroup
 ```
 
+> 🧠 Note: `call` and `spawn` only work with `group` blocks. They do not apply to individual samples or other statements.
+
 ```deva
-# global.deva
+# variables.deva
 
 let globalBpm = 120
 let globalBank = 808
@@ -184,15 +215,15 @@ let kickDuration = 500
 
 ## 🧯 Known issues
 
-- No support yet for `if`, `else`, `else if` statements
-- No support yet for `@group`, `@pattern`, `@function` statements
+- No smart modules yet, all groups, variables, and samples must be explicitly imported where used
+- No support yet for `pattern`, `function`, ... statements
 - No support yet for cross-platform builds (Linux, macOS)
 
 ## 🧪 Roadmap Highlights
 
 For more info, see [docs/ROADMAP.md](./docs/ROADMAP.md)
 
-- ⏳ Other statements (e.g `if`, `@group`, ...)
+- ⏳ Other statements (e.g `function`, `pattern`, ...)
 - ⏳ Cross-platform support (Linux, macOS)
 - ⏳ More built-in instruments (e.g. snare, hi-hat, etc.)
 

package/docs/CHANGELOG.md

@@ -4,6 +4,45 @@
 
 # Changelog
 
+## Version 0.0.1-alpha.8 (2025-07-12)
+
+### Syntax
+
+- Implemented `if` directive to conditionally execute blocks of code.
+- Implemented `else` directive to provide an alternative block of code when the `if` condition is not met.
+- Implemented `else if` directive to provide additional conditions for the `if` directive.
+
+### Core Components
+
+- Implemented evaluator for audio statements, to execute conditional statements.
+- Fixed `group` resolution and export issues.
+- Implemented `Global Store` debugger to inspect variables by module for build command.
+- Organized `TokenKind` and `StatementKind` enums for better clarity and maintainability.
+- Refactored audio interpreter to handle the new syntax and directives.
+- Refactored lexer to handle new directives and improve tokenization.
+- Refactored parser to handle new directives and improve parsing logic.
+- Added support for `call` and `spawn` execution of imported groups.
+- Enforced scoped resolution of groups in `spawn` and `call` (must be imported in current module).
+
+## Version 0.0.1-alpha.7 (2025-07-11)
+
+## Examples
+
+- Added examples in `examples` folder (group, loop, variables, index).
+
+## Structure
+
+- Moved `rust/audio` folder to `rust/core/audio` to better organize the project structure.
+
+### Core Components
+
+- Implemented `group` directive to define groups of sounds.
+- Implemented `call` directive to call a group of sounds.
+- Implemented `spawn` directive to spawn a group of sounds in parallel.
+- Implemented `sleep` directive to pause execution for a specified duration.
+- Patched line and column tracking in the lexer to ensure correct indentation handling.
+- Patched string lexing advancing to handle first character correctly.
+
 ## Version 0.0.1-alpha.5 (2025-07-05)
 
 ### Syntax

package/docs/ROADMAP.md

@@ -24,8 +24,8 @@ Devalang is a work in progress. Here’s what we’re planning next:
 
 ## Upcoming
 
+- ⏳ **Smart modules**: Let Devalang detect and use groups, samples, and variables without needing to import them manually.
 - ⏳ **VSCode extension**: Create a VSCode extension for syntax highlighting and code completion.
-- ⏳ **Other statements**: Implement `if`, `else`, and other control structures.
-- ⏳ **Pattern and group statements**: Add support for `@pattern` and `@group` to organize code.
+- ⏳ **Other statements**: Implement `pattern`, `function`, and other control structures.
 - ⏳ **Functions**: Add support for defining and calling functions.
 - ⏳ **Testing**: Expand test coverage for all features.

package/docs/SYNTAX.md

@@ -17,6 +17,18 @@ The engine uses indentation to define blocks, similar to Python. Each block must
 <details>
 <summary>Show available types</summary>
 
+### Duration
+
+Duration is defined using a number. It represents the length of a sound in milliseconds.
+
+```deva
+let duration = 1000
+```
+
+Will play a sound for 1000 milliseconds (1 second).
+
+NOTE: Other time units like seconds or beats are not supported yet, but will be in the future.
+
 ### String
 
 Strings are defined using double quotes.
@@ -46,7 +58,7 @@ let boolean = false
 Maps are key-value pairs defined using curly braces. Keys are strings, and values can be of any type (string, number, boolean, map, or array).
 
 ```deva
-let map = {myKey: 99}
+let map = { myKey: 99 }
 ```
 
 ### Array
@@ -81,13 +93,17 @@ bank 808
 
 Modules can be imported and exported to share variables between different files.
 
+> ⚠️ The import/export system is still experimental and may change in the future.
+>
+> You must explicitly declare imports and exports in each file — Devalang does not automatically detect or resolve them.
+
 Exporting variables from a module :
 
 ```deva
 # exported.deva
 
 let exportedIterator = 10
-let exportedParams = {drive: 50, decay: 30}
+let exportedParams = { drive: 50, decay: 30 }
 
 @export { exportedIterator, exportedParams }
 ```
@@ -103,22 +119,13 @@ loop exportedIterator:
     .kick auto exportedParams
 ```
 
-### Built-in triggers
-
-Usage : `.<trigger-name> <duration> <effects-map>`
+### Loading Samples
 
-Other triggers will be added in future releases (e.g. `.snare`, `.hihat`, `.tom`, `.clap`, `.crash`, `.ride`, `.synth`, `.bass`, `.pad`).
-You can also create custom triggers using the `@load` directive.
-
-```deva
-.kick
-.kick 1/4
-.kick auto {reverb: 50, decay: 30}
-```
+You can load your own samples and use them in your music.
 
-### Custom triggers
+Load usage : `@load <path> as <name>`
 
-Same usage as built-in triggers, but with custom audio files or effects.
+Trigger usage : `.<name> <duration> <params>`
 
 ```deva
 @load "./path/to/instrument.mp3" as mySample
@@ -126,7 +133,7 @@ Same usage as built-in triggers, but with custom audio files or effects.
 .mySample auto {reverb: 50, drive: 25}
 ```
 
-### Let variables
+### Variables
 
 Variables are defined using the `let` keyword, followed by the variable name and its value. The value can be of any type (string, number, boolean, map, or array).
 
@@ -134,11 +141,11 @@ Variables are defined using the `let` keyword, followed by the variable name and
 let number = 0
 let boolean = true
 let string = "string"
-let map = {myKey: 200}
+let map = { myKey: 200 }
 let array = [0, 1, 2]
 ```
 
-### Basic loops
+### Loops
 
 Loops are defined using the `loop` keyword, followed by the number of iterations. The body of the loop is indented.
 
@@ -146,3 +153,58 @@ Loops are defined using the `loop` keyword, followed by the number of iterations
 loop 10:
     # ...
 ```
+
+### Groups
+
+Groups are defined using the `group` keyword, followed by the group name. The body of the group is indented.
+
+Groups allow you to organize your code into reusable blocks. They can be called or spawned later in the code.
+
+```deva
+group myGroup:
+    # ...
+```
+
+### Conditions
+
+Conditions are defined using the `if` keyword, followed by a condition. The body of the condition is indented.
+
+```deva
+if myCondition:
+    # ...
+```
+
+You can also use `else` and `else if` for alternative branches:
+
+```deva
+if myCondition:
+    # ...
+else if anotherCondition:
+    # ...
+else:
+    # ...
+```
+
+### Calling Groups (Sequential Execution)
+
+Groups can be called using the `call` keyword, which executes only the group in sequence.
+
+> ⚠️ `call` only works on `group` declarations. It does not apply to other statements.
+
+This executes the entire group in the current execution thread, following a sequential order.
+
+```deva
+call myGroup
+```
+
+### Spawning Groups (Parallel Execution)
+
+Groups can be spawned using the `spawn` keyword, which executes only the group in parallel.
+
+> ⚠️ spawn also only works on group declarations. It does not make the group’s content parallel unless it explicitly uses spawn inside.
+
+This runs the entire group in a separate execution thread, allowing it to play alongside other actions.
+
+```deva
+spawn myGroup
+```

package/docs/TODO.md

@@ -42,18 +42,21 @@ This is a list of tasks and features to be implemented in Devalang. Note that th
 - [x] #
 - [x] @import
 - [x] @export
-- [ ] @group
-- [ ] @pattern
-- [ ] @function
 - [x] @load
 - [ ] @include
+- [ ] function
+- [ ] pattern
+- [x] group
+- [x] call
+- [x] spawn
+- [x] sleep
 - [x] bpm
 - [x] bank
 - [x] loop
 - [x] let
-- [ ] if
-- [ ] else
-- [ ] else if
+- [x] if
+- [x] else
+- [x] else if
 
 ## Triggers
 
@@ -62,8 +65,6 @@ This is a list of tasks and features to be implemented in Devalang. Note that th
 
 ## Other TODOs
 
-- [x] Implement a more robust error handling system
-- [x] Replace eprintln & println with `log_message` function
-- [x] Implement a more comprehensive logging system
-- [ ] Add unit tests for all core components
-- [ ] Comment all core components
+- [ ] Patch path handling to support relative paths
+- [ ] Comment all core components
+- [ ] Add unit tests for all core components

package/examples/condition.deva

@@ -0,0 +1,24 @@
+# This file demonstrates the use of conditional blocks in Devalang.
+
+@import { myGroup } from "./examples/group.deva"
+
+@load "./examples/samples/kick-808.wav" as kickCustom
+@load "./examples/samples/hat-808.wav" as hatCustom
+
+group conditionBlock:
+    if tempo > 120:
+        # Will be executed if the condition is true
+        .kickCustom
+    else if tempo > 155:
+        # Will be executed if the condition is false
+        .hatCustom
+    else:
+        # Following lines will be executed if the condition is neither true or false
+        
+        # This will call myGroup sequentially (in the main thread)
+        call myGroup
+
+        # This will spawn a group in parallel to the main thread (kick + hat simultaneously)
+        # spawn myGroup
+
+@export { conditionBlock }

package/examples/group.deva

@@ -0,0 +1,12 @@
+# This file demonstrates the use of grouping in Devalang.
+
+@import { duration, default_bank, params, loopCount, tempo } from "./examples/variables.deva"
+
+@load "./examples/samples/kick-808.wav" as kickCustom
+@load "./examples/samples/hat-808.wav" as hatCustom
+
+group myGroup:
+    .kickCustom duration params
+    .hatCustom duration params
+
+@export { myGroup }

package/examples/index.deva

@@ -1,4 +1,9 @@
-@import { duration, default_bank, params, loopCount, tempo } from "./examples/exported.deva"
+# This file demonstrates the use of main features in Devalang.
+
+@import { duration, default_bank, params, loopCount, tempo } from "./examples/variables.deva"
+@import { conditionBlock } from "./examples/condition.deva"
+@import { myGroup } from "./examples/group.deva"
+
 
 @load "./examples/samples/kick-808.wav" as kickCustom
 @load "./examples/samples/hat-808.wav" as hatCustom
@@ -7,11 +12,5 @@ bpm tempo
 
 bank default_bank
 
-loop loopCount:
-    .kickCustom duration params
-
-    # Uncomment the next line (.hat) while executing "play" command 
-    # with `--repeat` option to see magic happen !
-
-    # .hatCustom duration params
-    
+# This will call the group sequentially (line by line)
+call conditionBlock

package/examples/loop.deva

@@ -0,0 +1,15 @@
+# This file demonstrates the use of a loop in Devalang.
+
+@import { duration, default_bank, params, loopCount, tempo } from "./examples/variables.deva"
+
+@load "./examples/samples/kick-808.wav" as kickCustom
+@load "./examples/samples/hat-808.wav" as hatCustom
+
+loop loopCount:
+    .kickCustom duration params
+
+    # Uncomment the next line (.hat) while executing "play" command
+    # with `--repeat` option to see magic happen !
+
+    .hatCustom duration params
+

package/examples/variables.deva

@@ -0,0 +1,9 @@
+# This file only exports variables for use in other files.
+
+let duration = auto
+let default_bank = 808
+let params = {decay:10, delay:30}
+let loopCount = 5
+let tempo = 115
+
+@export { duration, default_bank, params, loopCount, tempo }

package/package.json

@@ -1,44 +1,44 @@
-{
-  "name": "@devaloop/devalang",
-  "private": false,
-  "version": "0.0.1-alpha.5",
-  "description": "Write music like code. Devalang is a domain-specific language (DSL) for sound designers and music hackers. Compose, automate, and control sound — in plain text.",
-  "main": "out-tsc/index.js",
-  "bin": {
-    "devalang": "./out-tsc/bin/index.js"
-  },
-  "scripts": {
-    "prepublish": "cargo build --release && npm run script:postbuild",
-    "rust:dev:build": "cargo run build --entry examples --output output",
-    "rust:dev:check": "cargo run check --entry examples --output output",
-    "rust:wasm:web": "wasm-pack build --target=web --no-default-features",
-    "rust:wasm:node": "wasm-pack build --target=nodejs --no-default-features",
-    "script:postbuild": "tsc && node out-tsc/scripts/postbuild.js",
-    "script:version:bump": "tsc && node out-tsc/scripts/version/index.js"
-  },
-  "homepage": "https://devalang.com",
-  "keywords": [
-    "devalang",
-    "music",
-    "sound",
-    "domain-specific language",
-    "dsl",
-    "programming language",
-    "sound design",
-    "music hacking",
-    "audio",
-    "synthesis",
-    "scripting",
-    "sound synthesis",
-    "music programming"
-  ],
-  "author": "Devaloop",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/devaloop-labs/devalang.git"
-  },
-  "dependencies": {
-    "@types/node": "^24.0.3"
-  }
-}
+{
+  "name": "@devaloop/devalang",
+  "private": false,
+  "version": "0.0.1-alpha.8",
+  "description": "Write music like code. Devalang is a domain-specific language (DSL) for sound designers and music hackers. Compose, automate, and control sound — in plain text.",
+  "main": "out-tsc/index.js",
+  "bin": {
+    "devalang": "./out-tsc/bin/index.js"
+  },
+  "scripts": {
+    "prepublish": "cargo build --release && npm run script:postbuild",
+    "rust:dev:build": "cargo run build --entry examples --output output",
+    "rust:dev:check": "cargo run check --entry examples --output output",
+    "rust:wasm:web": "wasm-pack build --target=web --no-default-features",
+    "rust:wasm:node": "wasm-pack build --target=nodejs --no-default-features",
+    "script:postbuild": "tsc && node out-tsc/scripts/postbuild.js",
+    "script:version:bump": "tsc && node out-tsc/scripts/version/index.js"
+  },
+  "homepage": "https://devalang.com",
+  "keywords": [
+    "devalang",
+    "music",
+    "sound",
+    "domain-specific language",
+    "dsl",
+    "programming language",
+    "sound design",
+    "music hacking",
+    "audio",
+    "synthesis",
+    "scripting",
+    "sound synthesis",
+    "music programming"
+  ],
+  "author": "Devaloop",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/devaloop-labs/devalang.git"
+  },
+  "dependencies": {
+    "@types/node": "^24.0.3"
+  }
+}

package/project-version.json

@@ -1,6 +1,6 @@
-{
-  "version": "0.0.1-alpha.5",
-  "channel": "alpha",
-  "lastCommit": "1df08dbb62484586f67fbf42d34d6011cf019a12",
-  "build": 4
+{
+  "version": "0.0.1-alpha.8",
+  "channel": "alpha",
+  "lastCommit": "fdb440173acc82227067864903aabc83e1d1570c",
+  "build": 7
 }

package/rust/cli/build.rs

@@ -1,9 +1,12 @@
 use crate::{
-    audio::render::render_audio_with_modules,
     config::Config,
     core::{
         builder::Builder,
-        debugger::{ lexer::write_lexer_log_file, preprocessor::write_preprocessor_log_file },
+        debugger::{
+            lexer::write_lexer_log_file,
+            preprocessor::write_preprocessor_log_file,
+            store::write_store_log_file,
+        },
         preprocessor::loader::ModuleLoader,
         store::global::GlobalStore,
         utils::path::{ find_entry_file, normalize_path },
@@ -114,6 +117,7 @@ fn begin_build(entry: String, output: String) {
         "resolved_statements.log",
         modules_statements.clone()
     );
+    write_store_log_file(&normalized_output_dir, "global_store.log", global_store.modules.clone());
 
     // SECTION Building AST and Audio
     let builder = Builder::new();

package/rust/cli/play.rs

@@ -1,5 +1,4 @@
 use crate::{
-    audio::player::AudioPlayer,
     config::Config,
     core::{
         builder::Builder,
@@ -23,6 +22,8 @@ pub fn handle_play_command(
     watch: bool,
     repeat: bool
 ) {
+    use crate::core::audio::player::AudioPlayer;
+
     let logger = Logger::new();
 
     let entry_path = entry

package/rust/core/audio/evaluator.rs

@@ -0,0 +1,31 @@
+use crate::core::{ shared::value::Value, store::variable::VariableTable };
+
+pub fn evaluate_condition_string(expr: &str, vars: &VariableTable) -> bool {
+    let tokens: Vec<&str> = expr.split_whitespace().collect();
+    if tokens.len() != 3 {
+        return false;
+    }
+
+    let left = tokens[0];
+    let op = tokens[1];
+    let right = tokens[2];
+
+    let left_val = match vars.get(left) {
+        Some(Value::Number(n)) => *n,
+        _ => {
+            return false;
+        }
+    };
+
+    let right_val: f32 = right.parse().unwrap_or(0.0);
+
+    match op {
+        ">" => left_val > right_val,
+        "<" => left_val < right_val,
+        ">=" => left_val >= right_val,
+        "<=" => left_val <= right_val,
+        "==" => (left_val - right_val).abs() < f32::EPSILON,
+        "!=" => (left_val - right_val).abs() > f32::EPSILON,
+        _ => false,
+    }
+}