Viyal Language Specification

This is the authoritative MVP specification for the Viyal programming language (Phase M0).

1. Installation & Usage

You can download the pre-compiled binaries for your operating system directly from our GitHub releases page.

Download Links

Setup Instructions

For Windows:

  1. Download and extract the .zip file to a folder (e.g., C:\viyal).
  2. Add the extracted folder to your system's PATH environment variable.
  3. Open a new command prompt or PowerShell window and verify the installation by running viyal --version.

For Linux:

  1. Download the .tar.gz archive.
  2. Extract the archive: tar -xzf viyal-linux.tar.gz
  3. Move the binary to your local bin directory: sudo mv viyal /usr/local/bin/
  4. Verify the installation by running viyal --version.

Executing a Script

Create a file named hello.vyl with the following content:

void main() {
    print("Hello from Viyal!");
}

Run the script using the Viyal compiler:

viyal hello.vyl

2. Syntax Overview

The language uses a strict C-style syntax with expression-oriented capabilities where appropriate, maintaining a balance between familiarity and modern ergonomics.

class Person(String name, int age) {
    void greet() {
        print("Hello $name");
    }
}

void main() {
    final person = Person("Raja", 25);
    person.greet();
}

3. Variables and Declarations

  • final: Immutable reference (value cannot be reassigned).
  • var: Mutable reference (type inferred).
  • Type annotations can precede the variable name.
String name = "Raja";
var age = 25;
final score = 98.5;

4. Core Types

  • int: 64-bit signed integer.
  • double: 64-bit floating point.
  • bool: true or false.
  • String: UTF-8 encoded string.
  • Collections: List<T>, Set<T>, Map<K, V>.

5. Null Safety

Null safety is baked into the type system. Types are non-nullable by default.

  • T is non-nullable.
  • T? is nullable.
String name = "Raja"; // Valid
String? nickname = null; // Valid
// String invalid = null; // Compiler Error

Control flow analysis performs smart casting:

if (nickname != null) {
    print(nickname.length); // nickname is treated as String here
}

6. Functions

Functions support positional, named, default, and optional parameters.

int add(int a, int b) {
    return a + b;
}

final multiply = (int a, int b) => a * b;

7. Object-Oriented Features

  • Classes with primary constructors (e.g., class Point(int x, int y)).
  • Interfaces declared explicitly (interface Logger { ... }).
  • Abstract classes for partial implementations.
  • No implicit interfaces (unlike Dart).

8. Control Flow

Standard C-style constructs:

  • if / else
  • for (C-style and for-in)
  • while / do-while
  • switch (exhaustive by default on enums and sealed classes)

9. Examples

Here are a few quick examples demonstrating Viyal's syntax and features in action.

Working with Arrays

class Main {
    void run() {
        var arr = [10, 20, 30];
        print(arr[0]);
        print(arr[1]);
        
        arr[1] = 99;
        print(arr[1]); // 99
    }
}

Working with Maps

class Main {
    void run() {
        var myMap = {"name": "Viyal", "version": "1.0"};
        print(myMap["name"]);
        
        myMap["version"] = "1.1";
        myMap["new_key"] = "hello";
        
        print(myMap["new_key"]);
    }
}

Classes and Methods

class Animal {
    void speak() {
        print("Roar!");
    }
}

class Main {
    void run() {
        new Animal().speak();
    }
}

10. Standard Library

Viyal includes a comprehensive standard library out of the box, optimized for performance and ease of use.

fs (File System)

Read and write files synchronously or asynchronously.

import { readFile } from "fs";
var content = await readFile("data.txt");

http (Networking)

Build web servers or make HTTP requests effortlessly.

import { get } from "http";
var response = await get("https://api.github.com");

json

Native JSON parsing and serialization.

var data = json.parse('{"key": "value"}');

math & str

Extensive utilities for mathematical operations and string manipulations (like regex matching, splitting, formatting).

11. Concurrency Model

Viyal features Structured Concurrency, inspired by Kotlin and Swift, avoiding the pitfalls of unstructured Futures/Promises.

Hierarchical Scopes

Async tasks are strictly bound to a hierarchical scope. A task cannot outlive its parent scope, ensuring no leaked coroutines.

async void fetchAll() {
    scope {
        task { fetchUsers(); }
        task { fetchProducts(); }
    } // Blocks until all tasks complete.
}
  • Cancellation: If a parent scope is cancelled, all child tasks are automatically cancelled.
  • Error Propagation: If a child task fails, the error bubbles up, cancelling siblings automatically to prevent wasted work.
  • Channels: Go-style channels are available for safe communication between concurrent tasks.

12. Compiler Architecture

The Viyal compiler is written in Rust to leverage its performance, memory safety, and mature compiler toolchain.

Pipeline Overview

Source Code
     ↓ (Lexer)
Tokens
     ↓ (Parser)
AST (Abstract Syntax Tree)
     ↓ (Resolver)
Resolved AST
     ↓ (Type Checker)
Typed AST
     ↓ (Lowering)
HIR (High-Level Intermediate Representation)
     ↓ (Optimization / Lowering)
MIR (Mid-Level Intermediate Representation)
     ↓
 ┌───────────────┬───────────────┐
 │               │               │
Bytecode IR      LLVM IR       WASM IR
 │               │               │
 VM            Native Executable   Browser

Components

  • Lexer: Converts raw source text into a stream of Tokens. Handles whitespace, comments, and string interpolation boundaries.
  • Parser: Consumes Tokens to produce an Abstract Syntax Tree (AST). Recovers from errors gracefully to support IDE features (LSP).
  • Resolver & Type Checker: Binds identifiers to declarations, enforces null safety and type rules, and performs type inference.
  • HIR & MIR: High-level concepts (classes, async/await) are lowered into simpler representations (structs, state machines). Enables optimizations independent of the final target (Bytecode vs Native).

13. Contributing

Viyal is an open-source project and we welcome contributions from the community! Whether you're interested in compiler design, standard library development, or writing documentation, there's a place for you.

How to Contribute

  • Report Bugs: Open an issue on our GitHub repository with a clear description and steps to reproduce.
  • Suggest Features: We are currently in Phase M0 (Research). Feel free to open a discussion for language features.
  • Submit Pull Requests:
    1. Fork the repository.
    2. Create a new branch for your feature or bug fix.
    3. Write tests for your changes.
    4. Ensure all existing tests pass.
    5. Submit your PR with a detailed description of the changes.

Development Environment

Since the compiler is written in Rust, you will need the standard Rust toolchain (cargo and rustc). Detailed instructions on building the compiler from source can be found in the repository's README.

14. Compiler Setup Guide

Follow these steps to build the Viyal compiler from source and start contributing.

Prerequisites

  • Rust Toolchain: You need rustc and cargo. The easiest way to install them is via rustup.
  • Git: To clone the repository.

Build Instructions

1. Clone the repository:

git clone https://github.com/bytebunkers/viyal.git
cd viyal

2. Build the compiler:

cargo build --release

3. Run the test suite to ensure everything is working correctly:

cargo test

4. Run the compiler against a Viyal source file:

cargo run -- hello.vyl