@devaloop/devalang 0.0.1-alpha.1 → 0.0.1-alpha.10

package/.devalang

@@ -0,0 +1,4 @@
+[defaults]
+entry = "./examples"
+output = "./output"
+watch = false

package/Cargo.toml

@@ -1,45 +1,49 @@
-[package]
-name = "devalang"
-version = "0.0.1-alpha.1"
-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"
-repository = "https://github.com/devaloop-labs/devalang"
-keywords = ["music", "dsl", "audio", "cli"]
-categories = ["command-line-utilities", "audio", "development-tools"]
-readme = "README.md"
-homepage = "https://devaloop.com"
-documentation = "https://docs.rs/devalang"
-edition = "2024"
-
-[[bin]]
-name = "devalang"
-path = "rust/main.rs"
-
-[lib]
-path = "rust/lib.rs"
-crate-type = ["cdylib"]
-
-[profile.release]
-opt-level = "s"
-
-[features]
-default = ["cli"]
-cli = ["crossterm"]
-
-[dependencies]
-clap = { version = "4.5", features = ["derive"] }
-serde = { version = "1.0", features = ["derive"] }
-serde_json = "1.0"
-rodio = "0.17"
-hound = "3.4.0"
-toml = "0.8"
-notify = "6.1"
-fs_extra = "1.3"
-include_dir = "0.7"
-wasm-bindgen = "0.2"
-serde-wasm-bindgen = "0.4"
-nom_locate = "4.0.0"
-chrono = "0.4"
-crossterm =  { version = "0.27", optional = true }
-indicatif = "0.17"
+[package]
+name = "devalang"
+version = "0.0.1-alpha.10"
+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"
+repository = "https://github.com/devaloop-labs/devalang"
+keywords = ["music", "dsl", "audio", "cli"]
+categories = ["command-line-utilities", "development-tools", "parser-implementations"]
+readme = "README.md"
+homepage = "https://devalang.com"
+documentation = "https://docs.devalang.com/"
+license-file = "LICENSE"
+edition = "2024"
+
+[[bin]]
+name = "devalang"
+path = "rust/main.rs"
+required-features = ["cli"]
+
+[lib]
+path = "rust/lib.rs"
+crate-type = ["cdylib"]
+
+[profile.release]
+opt-level = "s"
+
+[features]
+default = ["cli"]
+cli = ["crossterm", "indicatif", "inquire"]
+
+[dependencies]
+clap = { version = "4.5", features = ["derive"] }
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"
+rodio = "0.17"
+hound = "3.4.0"
+toml = "0.8"
+notify = "6.1"
+fs_extra = "1.3"
+include_dir = "0.7"
+wasm-bindgen = "0.2"
+serde-wasm-bindgen = "0.4"
+nom_locate = "4.0.0"
+chrono = "0.4"
+crossterm =  { version = "0.27", optional = true }
+indicatif = { version = "0.17", optional = true }
+inquire = { version = "0.7.5", optional = true }
+js-sys = "0.3"

package/README.md

@@ -11,97 +11,164 @@
 ![License: MIT](https://img.shields.io/badge/license-MIT-green)
 ![Platform](https://img.shields.io/badge/platform-Windows-blue)
 
-![npm](https://img.shields.io/npm/dm/@devaloop/devalang)
+![npm](https://img.shields.io/npm/dt/@devaloop/devalang)
+![crates](https://img.shields.io/crates/d/devalang)
+
+[![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, and automate parameters — all in clean, readable text.
+Compose loops, control samples, render and play audio — all in clean, readable text.
 
 🦊 Whether you're building a track, shaping textures, or performing live, Devalang helps you think in rhythms. It’s designed to be simple, expressive, and fast — because your ideas shouldn’t wait.
 
 From studio sketches to live sets, Devalang gives you rhythmic control — with the elegance of code.
 
-> 🚧 **v0.0.1-alpha.1 Notice** 🚧
+> 🚧 **v0.0.1-alpha.10 Notice** 🚧
 >
-> Devalang is still in early development. This version does not yet include **sound rendering**.
+> NEW: Online documentation is now available at [docs.devalang.com](https://docs.devalang.com).
 >
-> You can parse code, generate the AST, and validate syntax — all essential building blocks for the upcoming audio engine.
+> NEW: Devalang VSCode extension is now available !
+> [Get it here](https://marketplace.visualstudio.com/items?itemName=devaloop.devalang-vscode).
 >
-> Currently, only `.kick` is included as a built-in trigger.
-> Custom instruments can be defined with `@load`, allowing any sound sample to be triggered with the same syntax.
+> Includes synthesis, playback, and rendering features, but is still in early development.
 >
 > Currently, Devalang CLI is only available for **Windows**.  
 > Linux and macOS binaries will be added in future releases via cross-platform builds.
 
+---
+
+## 📚 Quick Access
+
+- [📖 Documentation](https://docs.devalang.com)
+- [💡 Examples](./examples/)
+- [🧩 VSCode Extension](https://marketplace.visualstudio.com/items?itemName=devaloop.devalang-vscode)
+- [🎨 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
 
-- 🧩 Module system for importing and exporting variables between files (`@import`, `@export`)
-- 📜 Structured AST generation for debugging and future compilation
-- 🔢 Basic data types: strings, numbers, booleans, maps, arrays
-- ⏱️ `bpm` assignment for setting tempo
-- 🧱 `bank` declaration to define the instrument set
-- 🔁 Looping system with fixed repetitions (`loop 4:`)
-- 🧪 Instruction calls with parameters (e.g. `.kick auto {reverb:10, decay:20}`) for testing pattern syntax
-- 📄 `let` assignments for storing reusable values
-- 🔄 `@load` assignment to load a sample (.mp3, .wav) to use it as a value
-- 🛠️ CLI tools for syntax checking (`check`), AST output (`build`)
+- 🎵 **Audio Engine**: Integrated audio playback and rendering
+- 🧩 **Module system** for importing and exporting variables between files
+- 📜 **Structured AST** generation for debugging and future compilation
+- 🔢 **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
 
 ### For users
 
-> - ⚠️ Requires [Node.js 18+](https://nodejs.org/en/download)
+> ⚠️ Requires [Node.js 18+](https://nodejs.org/en/download)
 
-Install the package globally (NPM)
+For Node users (NPM)
 
 ```bash
-npm install -g @devaloop/devalang
+npm install -g @devaloop/devalang@latest
 ```
 
-Usage without install (NPX)
+> ⚠️ Requires [Rust 1.70+](https://www.rust-lang.org/learn/get-started#installing-rust)
+
+For Rust users (Cargo)
 
 ```bash
-npx @devaloop/devalang <command>
+cargo install devalang
 ```
 
 ### For contributors
 
-> - ⚠️ Requires [Node.js 18+](https://nodejs.org/en/download)
-> - ⚠️ Requires [Rust 1.70+](https://www.rust-lang.org/learn/get-started#installing-rust)
+> ⚠️ Requires [Node.js 18+](https://nodejs.org/en/download)
+
+> ⚠️ 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
 ```
 
-Usage for development (feel free to change arguments in package.json)
+Development usage (you can customize arguments in package.json)
 
 ```bash
 # For syntax checking test
-npm run rust:dev <command>
+npm run rust:dev:check
+
+# For building test
+npm run rust:dev:build
 ```
 
 ## ❔ Usage
 
+NOTE: Commands are available via `devalang` or `npx @devaloop/devalang`.
+
+NOTE: Arguments can be passed to commands using `--<argument>` syntax. You can also use a configuration file to set default values for various settings, making it easier to manage your Devalang project.
+
+NOTE: Some commands require a mandatory `--entry` argument to specify the input folder, and a `--output` argument to specify the output folder. If not specified, they default to `./src` and `./output` respectively.
+
 For more examples, see [docs/COMMANDS.md](./docs/COMMANDS.md)
 
-Checking syntax only and output debug files
+### Initialize a new project
+
+In the current directory
 
 ```bash
-devalang check --entry <entry-directory> --output <output-directory>
+devalang init
 ```
 
-Building output file(s) (AST generation for the moment)
+Or use optional arguments to specify a directory name and a template
 
 ```bash
-devalang build --entry <entry-directory> --output <output-directory>
+devalang init --name <project-name> --template <template-name>
 ```
 
+### Checking syntax only
+
+```bash
+devalang check --watch
+```
+
+### Building output files
+
+```bash
+devalang build --watch
+```
+
+### Playing audio files (once by file change)
+
+```bash
+devalang play --watch
+```
+
+### Playing audio files (continuous playback, even without file changes)
+
+```bash
+devalang play --repeat
+```
+
+## ⚙️ Configuration
+
+You can use a configuration file to set default values for various settings, making it easier to manage your Devalang project.
+
+To do this, create a `.devalang` file in the root of your project directory.
+
+See [docs/CONFIG.md](./docs/CONFIG.md) for more information.
+
 ## 📄 Syntax example
 
 For more examples, see [docs/SYNTAX.md](./docs/SYNTAX.md)
@@ -111,6 +178,8 @@ For more examples, see [docs/SYNTAX.md](./docs/SYNTAX.md)
 
 @import { globalBpm, globalBank, kickDuration } from "global.deva"
 
+@load "./examples/samples/kick-808.wav" as customKick
+
 bpm globalBpm
 # Will declare the tempo at the globalBpm variable beats per minute
 
@@ -118,34 +187,46 @@ bank globalBank
 # Will declare a custom instrument bank using the globalBank variable
 
 loop 5:
-    .kick kickDuration {reverb=50, drive=25}
-    # Will play 5 times a kick for the duration of the kickDuration variable with reverb and drive effects
+    .customKick kickDuration {reverb=50, drive=25}
+    # Will play 5 times a custom sample for 500ms with reverb and overdrive effects
+
+group myGroup:
+    .customKick kickDuration {reverb=50, drive=25}
+    # Will play the same sample in a group, allowing for more complex patterns
+
+call myGroup
+# Will be executed line by line (sequentially)
+
+# spawn 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.
 ```
 
+> 🧠 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
-let kickDuration = 500 
+let kickDuration = 500
 
 @export { globalBpm, globalBank, kickDuration }
 ```
 
 ## 🧯 Known issues
 
-- No support yet for Audio Engine
-- No support yet for `if`, `else`, `else if` statements
-- No support yet for `@group`, `@pattern`, `@function` statements
-- Nested loops and conditions may not be fully tested
+- 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)
 
-- ⏳ Audio engine integration
-- ⏳ Other statements (e.g `if`, `@group`, ...)
-- ⏳ Watch mode for automatic rebuilds
+- ⏳ Other statements (e.g `function`, `pattern`, ...)
+- ⏳ Cross-platform support (Linux, macOS)
+- ⏳ More built-in instruments (e.g. snare, hi-hat, etc.)
 
 ## 🛡️ License
 

package/docs/CHANGELOG.md

@@ -0,0 +1,172 @@
+<div align="center">
+    <img src="https://firebasestorage.googleapis.com/v0/b/devaloop-labs.firebasestorage.app/o/devalang-teal-logo.svg?alt=media&token=d2a5705a-1eba-4b49-88e6-895a761fb7f7" alt="Devalang Logo">
+</div>
+
+# Changelog
+
+## Version 0.0.1-alpha.10 (2025-07-19)
+
+### 📖 Documentation
+
+- Updated [new documentation website](https://docs.devalang.com) with new features and examples.
+
+### 🧠 Core Engine
+
+- Patched `call`, `spawn` to handle correct cursor time.
+- Patched `advance_char` to handle correct indentation and dedentation.
+- Patched `bank` resolver to handle numbers in bank names.
+- Patched `spawn` calls that was not calling a variable.
+
+### 🧩 Web Assembly
+
+- Added `load_wasm_module` function to the WASM module to load Devalang modules dynamically.
+- Added `render_audio` function to the WASM module to render audio files.
+
+## Version 0.0.1-alpha.9 (2025-07-14)
+
+### ✨ Syntax
+
+- Added support for `synth` directives to define synthesizer sounds directly in code  
+  → Example:
+
+  ```deva
+  let mySynth = synth sine
+  ```
+
+### 🧠 Core Engine
+
+- ✅ **Major refactor** of the resolution layer:
+
+  - `condition`, `loop`, `group`, `trigger`, `call`, `spawn`, and `driver` were fully rewritten
+  - Ensures **correct variable scoping**, **cross-module references**, and **imported symbol resolution**
+
+- ✅ Audio interpreter updated:
+  - `call` and `spawn` now execute correctly in parallel, preserving **temporal alignment** across groups
+
+### 🧩 Language Features
+
+- Improved `@import` behavior:
+  - Modules can now be imported using **relative paths only**
+  - No need for absolute or root-based imports
+
+## 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
+
+- Fixed block parsing issues caused by missing or incorrect `Indent` / `Dedent` token detection.
+- Indentation handling now triggers correctly at each newline.
+- Improved reliability of nested blocks (e.g., inside `loop`) with consistent `Dedent` termination.
+
+### Core Components
+
+- Added full **WebAssembly (WASM)** support — Devalang can now be compiled for browser or Node.js environments.
+- Prepared the ground for future IDE integrations (e.g., VSCode extension) by stabilizing core syntax parsing.
+
+## Version 0.0.1-alpha.4 (2025-07-03)
+
+### Audio Engine
+
+- Integrated Audio Engine to handle audio playback and rendering.
+- Implemented Audio Player to play audio files.
+- Added support for audio playback with the `play` command.
+
+### Commands
+
+- Implemented `play` command to play Devalang files.
+
+  - Added `--watch` option to watch for changes in files and automatically rebuild and play them. (once)
+  - Added `--repeat` option to repeat the playback of the audio file. (infinite)
+
+  Note : You cannot use `--watch` and `--repeat` options together. Use `--repeat` instead.
+
+## Version 0.0.1-alpha.3 (2025-07-01)
+
+- /!\ Major refactor of the project structure and module system /!\
+- Refactored module system to support multiple modules and submodules.
+- Patched all directives to be compatible with the new project structure.
+- Prepared for the upcoming audio engine integration and sound rendering capabilities.
+- Updated documentation to reflect the new project structure and features.
+
+## Version 0.0.1-alpha.2 (2025-06-26)
+
+### Commands
+
+- Implemented `init` command to initialize a new Devalang project.
+- Implemented `template` command to manage templates.
+  - Added `list` subcommand to list available templates.
+  - Added `info` subcommand to show information about a specific template.
+- Implemented `watch` subcommand for the `build` and `check` command to watch for changes in files and automatically rebuild or check them.
+
+### Core Components
+
+- Implemented Config manager to handle configuration files.
+  - Added support for `.devalang` configuration file as a TOML file.
+- Implemented File System watcher to monitor file changes.
+- Implemented Template manager to handle templates and their metadata.
+
+### Syntax
+
+- Added support for built-in triggers for `.snare`, `.hihat`, `.clap`, `.tom`, `.crash`, `.ride`, `.synth`, `.bass`, and `.pad`.
+
+## Version 0.0.1-alpha.1 (2025-06-25)
+
+### Syntax
+
+- Added support for `@import` directive to import other Devalang files.
+- Added support for `@export` directive to export variables and functions.
+- Added support for `@load` directive to load external resources.
+- Added support for `bpm` directive to set the beats per minute.
+- Added support for `bank` directive to define a bank of sounds.
+- Added support for `loop` directive to define loops in the code.
+
+### Commands
+
+- Implemented `check` command to check the syntax of Devalang files.
+- Implemented `build` command to build the Abstract Syntax Tree (AST) of Devalang files.
+
+### Core Components
+
+- Implemented Lexer to tokenize Devalang source code.
+- Implemented Parser to parse the tokens and build the AST.
+- Implemented Preprocessor to handle directives and preprocess the source code.
+- Implemented Debugger to debug Devalang code.
+- Implemented Builder to build the final output from the AST.

package/docs/COMMANDS.md

@@ -4,28 +4,82 @@
 
 # Devalang Commands Guide
 
+## Initialization
+
+Initialize a new Devalang project (current folder)
+
+```bash
+devalang init
+```
+
+Initialize a new Devalang project (new folder)
+
+```bash
+devalang init --name <project-name> --template <template-name>
+```
+
+Available arguments:
+
+- `--name`: The name of the project (cannot be empty)
+- `--template`: The template to use for the project (default to `welcome`)
+
 ## Checking
 
 Checking syntax of .deva file(s)
 
 ```bash
-devalang check --entry ./examples --output ./output
+devalang check --entry ./examples --output ./output --watch
 ```
 
 Available arguments :
 
-- `entry`: The input folder (default to `./src`)
-- `output`: The output folder (default to `./output`)
+- `--no-config`: Whether to ignore the configuration file (default to `false`)
+- `--entry`: The input folder (default to `./src`)
+- `--output`: The output folder (default to `./output`)
+- `--watch`: Whether to watch for changes and re-analyze (default to `false`)
 
 ## Building
 
 Building AST of .deva file(s)
 
 ```bash
-devalang build --entry ./examples --output ./output
+devalang build --entry ./examples --output ./output --watch
 ```
 
 Available arguments :
 
-- `entry`: The input folder (default to `./src`)
-- `output`: The output folder (default to `./output`)
+- `--no-config`: Whether to ignore the configuration file (default to `false`)
+- `--entry`: The input folder (default to `./src`)
+- `--output`: The output folder (default to `./output`)
+- `--watch`: Whether to watch for changes and rebuild (default to `false`)
+
+
+## Playing
+
+Playing .deva file(s) without audio playback (once)
+
+```bash
+devalang play --entry ./examples --output ./output
+```
+
+Playing .deva file(s) with audio playback (once by file change)
+
+```bash
+devalang play --entry ./examples --output ./output --watch
+```
+
+Playing .deva file(s) with audio playback (infinite loop)
+
+```bash
+devalang play --entry ./examples --output ./output --repeat
+```
+
+Note : You cannot use `--watch` and `--repeat` options together. Use `--repeat` instead.
+
+Available arguments :
+
+- `--no-config`: Whether to ignore the configuration file (default to `false`)
+- `--entry`: The input folder (default to `./src`)
+- `--output`: The output folder (default to `./output`)
+- `--watch`: Whether to watch for changes and rebuild + play (default to `false`)
+- `--repeat`: Whether to repeat the playback of the audio file (default to `false`)

package/docs/CONFIG.md

@@ -0,0 +1,30 @@
+<div align="center">
+    <img src="https://firebasestorage.googleapis.com/v0/b/devaloop-labs.firebasestorage.app/o/devalang-teal-logo.svg?alt=media&token=d2a5705a-1eba-4b49-88e6-895a761fb7f7" alt="Devalang Logo">
+</div>
+
+# Devalang Configuration File
+
+Use a configuration file if you don't want to pass command-line arguments every time you run a command. The configuration file allows you to set default values for various settings, making it easier to manage your Devalang project.
+
+## Ignoring the Configuration File
+
+If you prefer not to use a configuration file, you can ignore it by passing the `--no-config` flag when running Devalang commands. This will bypass any settings defined in the configuration file and use only the command-line arguments you provide.
+
+## Structure of the Configuration File
+
+The configuration file is a TOML (Tom's Obvious, Minimal Language) file that contains key-value pairs to define various settings for your Devalang project. Below is a sample configuration file:
+
+```toml
+[defaults]
+entry = "./src"
+output = "./output"
+watch = false
+repeat = true
+```
+
+### Available Settings
+
+- `entry`: (String) The entry point for your Devalang project (default to `./src`)
+- `output`: (String) The output directory for generated files (default to `./output`)
+- `watch`: (Boolean) Whether to watch for changes in files and automatically rebuild or check them (default to `false`)
+- `repeat`: (Boolean) Whether to repeat the playback of audio files (default to `false`)