Language Specification

VelinScript Language Specification

Version 3.1.0

Übersicht

VelinScript ist eine moderne Programmiersprache für KI-APIs. Sie kombiniert die Einfachheit von modernen Sprachen mit leistungsstarken Features für API-Entwicklung, Security und KI/ML-Integration.

Neu in Version 2.5:

13 neue Standard Library Module mit 117+ Funktionen
VelinAutoDoc für automatische Dokumentationsgenerierung
VelinPipeline für automatische Performance-Optimierung
VelinFlow Runtime für transaktionales Flow-Management

Neu in Version 2.6:

5 neue kritische Standard Library Module mit 50+ Funktionen
path, url, stream, redis, tracing Module hinzugefügt
Alle Mock-Funktionen durch echte Implementierungen ersetzt
Verbesserte Pipeline-Optimierung mit echter Dependency-Tracking

Neu in Version 3.0:

KI-Compiler-Passes für automatische Code-Analyse und -Generierung
System-Generierung für boilerplate-freie Systeme
Automatische Parallelisierung (Multithreading, GPU, Async, SIMD)

Neu in Version 3.0.1:

IR-Repräsentation (SSA-Format) für optimierte Code-Generierung
Borrow Checker (Ownership & Borrowing System)
Prompt Optimizer (90%+ Token-Ersparnis)

Neu in Version 3.1.0:

Multi-Target Compilation (Rust, PHP, Python, TypeScript, JavaScript, Go, Java, C#)
Erweiterte GPU-Acceleration und SIMD Vectorization

Design-Prinzipien

Einfachheit - Klare, lesbare Syntax
Type Safety - Starke Typisierung mit Type Inference
API-First - Built-in Support für REST APIs
Security - Security-Features von Anfang an
KI/ML Ready - Native Unterstützung für KI/ML-Integration

Lexikalische Struktur

Kommentare

// Single-line Kommentar

/*
 * Multi-line Kommentar
 * Kann mehrere Zeilen umfassen
 */

/// Doc-Comment (für @VelinAutoDoc)
/// Diese Kommentare werden vom Compiler erfasst
/// und für automatische Dokumentationsgenerierung verwendet
/// 
/// @param name - Der Name des Parameters
/// @returns Eine Beschreibung des Rückgabewerts
@VelinAutoDoc
fn example(name: string): string {
    // ...
}

Doc-Comments (///):

Neu in Version 2.5 ✅
Werden als First-Class-Citizens im AST erfasst
Werden für automatische Dokumentationsgenerierung mit @VelinAutoDoc verwendet
Unterstützen Markdown-Formatierung
Können Parameter und Rückgabewerte dokumentieren

Keywords

fn - Funktion definieren
let - Variable definieren
return - Wert zurückgeben
if, else - Bedingte Ausführung
for, while - Schleifen
match - Pattern Matching
try, catch, finally - Fehlerbehandlung (Syntaktischer Zucker, Version 3.0.1)
struct - Struktur definieren
enum - Enumeration definieren
type - Type Alias
pub - Public Visibility
use - Import
mod - Modul
const, static - Konstanten
async, await - Asynchrone Programmierung
in - For-Loop Iterator
trait - Trait definieren (Rust-ähnlich)
interface - Interface definieren (TypeScript-ähnlich)
impl - Trait/Interface Implementierung

Identifikatoren

Beginnen mit Buchstabe oder _
Können Buchstaben, Zahlen und _ enthalten
Case-sensitive
Beispiele: user, getUser, UserService, _private

Literale

String Literale

"Hello, World!"
'Hello, World!'
"String mit \"Escapes\""

Format-Strings (String Interpolation)

Format-Strings ermöglichen die Interpolation von Ausdrücken innerhalb von String-Literalen:

let name = "John";
let message = "Hello, {name}!";
// Ergebnis: "Hello, John!"

let x = 10;
let y = 20;
let result = "Sum: {x + y}";
// Ergebnis: "Sum: 30"

Syntax:

Format-Strings verwenden geschweifte Klammern {} für Interpolation
Beliebige Ausdrücke können innerhalb der Klammern verwendet werden
Escaping: \{ für literal {, \} für literal }

Number Literale

42
3.14
0.5

Boolean Literale

true
false

Null Literal

null

Operatoren

Arithmetische Operatoren

+ - Addition
- - Subtraktion
* - Multiplikation
/ - Division
% - Modulo

Vergleichsoperatoren

== - Gleich
!= - Ungleich
< - Kleiner
> - Größer
<= - Kleiner oder gleich
>= - Größer oder gleich

Logische Operatoren

&& - Und
|| - Oder
! - Nicht

Membership Operator

in - Prüft, ob ein Element in einer Collection enthalten ist

Unterstützte Typen für rechten Operanden:

List<T> - Listenelemente
Map<K, V> - Schlüssel
string - Teilstrings

Beispiele:

// Mit Liste
let colors = ["rot", "grün", "blau"]
if "rot" in colors { print("Farbe gefunden") }

// Mit Map
let users = { "alice": 25, "bob": 30 }
if "alice" in users { print("Benutzer existiert") }

// Mit String
if "ll" in "Hallo" { print("Substring gefunden") }

// Mit Try-Catch
try {
    let value = getUserValue()
    if value in validValues { print("Gültig") }
} catch err { print("Fehler") }

Code-Generierung:

Rust: .contains(&value)
Python: in
PHP: in_array()
JavaScript: in

Zuweisungsoperatoren

= - Zuweisung

Typen

Primitive Typen

string - Zeichenkette
number - Fließkommazahl (f64)
boolean - Wahrheitswert
void - Kein Rückgabewert
null - Null-Typ

Collection Typen

List<T> - Liste von Elementen
Map<K, V> - Schlüssel-Wert-Paarung
Optional<T> - Optionaler Wert (kann null sein)
Result<T, E> - Result Type für explizite Fehlerbehandlung

Funktionstypen

fn(string, number) -> string

Tuple Typen

(string, number, boolean)

Named Typen

Benutzerdefinierte Typen (Structs, Enums, Type Aliases)

Deklarationen

Funktionen

fn functionName(param1: type1, param2: type2): returnType {
    // Body
}

Beispiele:

// Einfache Funktion
fn greet(name: string): string {
    return "Hello, " + name;
}

// Funktion ohne Parameter
fn getVersion(): string {
    return "0.1.0";
}

// Funktion ohne Rückgabewert
fn printMessage(msg: string): void {
    // ...
}

// Async Funktion
async fn fetchData(url: string): Data {
    // ...
}

Variablen

let variableName: type = value;
let mutableVariable: type = value; // mit mut für mutable

Type Inference:

let name = "John"; // Typ: string (inferiert)
let age = 30;      // Typ: number (inferiert)
let active = true; // Typ: boolean (inferiert)

Structs

struct StructName {
    field1: type1,
    field2: type2,
}

Beispiel:

struct User {
    id: string,
    name: string,
    email: string,
    age: number,
}

Enums

enum EnumName {
    Variant1,
    Variant2(data: type),
    Variant3(type1, type2),
}

Beispiel:

enum Status {
    Pending,
    Active,
    Inactive,
}

enum Status {
    Pending,
    Active,
    Inactive,
}

Ownership & Borrowing Types (Neu in 3.0.1)

VelinScript unterstützt ein Ownership-System ähnlich Rust für Memory-Safety:

// Owned (Standard - Move Semantics)
fn take_ownership(data: string) {
    // data wird moved (owned)
    // Nach dem Aufruf ist data nicht mehr gültig
}

// Immutable Borrow (&T)
fn process(data: &string) {
    // data ist eine immutable Referenz
    // data kann nicht modifiziert werden
}

// Mutable Borrow (&mut T)
fn modify(data: &mut string) {
    // data ist eine mutable Referenz
    // data kann modifiziert werden
}

// Shared Ownership (Arc<T> / Rc<T>)
fn shared_data(data: shared<string>) {
    // data wird geteilt (Arc/Rc)
    // Mehrere Referenzen möglich
}

// Copy Semantics (primitive types)
fn copy_value(x: number) {
    // number ist Copy, wird kopiert
    // x bleibt nach dem Aufruf gültig
}

Ownership-Typen:

Owned (Standard) - Variable besitzt den Wert (move semantics)
&T - Immutable Referenz (Borrow)
&mut T - Mutable Referenz (Mutable Borrow)
shared - Shared Ownership (Arc/Rc)
Copy - Copy-Semantik (primitive types: number, boolean)

Borrow-Regeln:

Nur eine mutable Referenz (&mut T) gleichzeitig
Mehrere immutable Referenzen (&T) gleichzeitig möglich
Keine mutable und immutable Referenzen gleichzeitig
Use-After-Move wird erkannt

Siehe: Borrow Checker Dokumentation

Result Type

Der Result<T, E> Type ermöglicht explizite Fehlerbehandlung:

fn parseNumber(input: string): Result<number, string> {
    // ... Parsing-Logik
    if (isValid) {
        return Result::Ok(parsedValue);
    } else {
        return Result::Error("Invalid number");
    }
}

// Result verwenden
let result = parseNumber("42");
if (result.isOk()) {
    let value = result.unwrap();
} else {
    let error = result.unwrapErr();
}

Result Methoden:

isOk() - Prüft ob Result Ok ist
isErr() - Prüft ob Result Error ist
unwrap() - Extrahiert Ok-Wert (panics bei Error)
unwrapOr(default) - Extrahiert Ok-Wert oder gibt Default zurück
map(fn) - Transformiert Ok-Wert
mapErr(fn) - Transformiert Error-Wert

try-catch-finally (Syntaktischer Zucker) ✅ (Version 3.0.1)

try-catch-finally ist syntaktischer Zucker, der automatisch in Result-basiertes Error-Handling desugared wird. Dies ermöglicht eine vertraute, exception-basierte Syntax, während die Typsicherheit von Result<T, E> erhalten bleibt.

Einfacher try-catch

try {
    let result = db.query("SELECT * FROM users");
    return result;
} catch (err) {
    log.error("Database error: " + err.message);
    return [];
}

Mehrere catch-Blöcke mit Typ-Dispatch

try {
    return processData(data);
} catch (err: ValidationError) {
    return Result.err("Validation failed");
} catch (err: NetworkError) {
    return Result.err("Network failed");
} catch (err) {
    return Result.err("Unknown error");
}

try-catch mit finally

try {
    return openFile(path);
} catch (err) {
    log.error(err.message);
} finally {
    closeResources();
}

Wichtige Hinweise:

Explizites return erforderlich: Jedes return im try-Block wird automatisch in Result.ok(...) gewrappt
Typ-Dispatch: Mehrere catch-Blöcke mit spezifischen Fehlertypen werden zu match-Statements desugared
finally immer ausgeführt: Der finally-Block wird immer ausgeführt, unabhängig von Erfolg oder Fehler
Desugaring: Die Transformation erfolgt automatisch während der Kompilierung, der generierte Code nutzt Result<T, E>

Traits

Traits definieren Verträge für Typen (ähnlich wie Interfaces in anderen Sprachen):

trait Serialize {
    fn toJson(): string;
    fn fromJson(json: string): Self;
}

trait Clone {
    fn clone(): Self;
}

// Trait mit generischen Parametern
trait Comparable<T> {
    fn compare(other: T): number;
}

Trait Implementierungen

impl Serialize for User {
    fn toJson(): string {
        // ... Implementation
    }
    
    fn fromJson(json: string): User {
        // ... Implementation
    }
}

// Trait für mehrere Typen implementieren
impl Clone for User {
    fn clone(): User {
        // ... Implementation
    }
}

Interfaces

Interfaces sind syntaktisch identisch zu Traits, bieten aber TypeScript-ähnliche Semantik:

interface IUserService {
    fn getUser(id: string): User;
    fn createUser(user: User): User;
}

// Interface implementieren
impl IUserService for UserService {
    fn getUser(id: string): User {
        // ... Implementation
    }
    
    fn createUser(user: User): User {
        // ... Implementation
    }
}

Generics mit Constraints

Generics ermöglichen wiederverwendbaren Code mit Type Safety:

// Einfaches Generic
fn identity<T>(value: T): T {
    return value;
}

// Generic mit Constraint (T muss Serialize implementieren)
fn serialize<T: Serialize>(item: T): string {
    return item.toJson();
}

// Multiple Constraints
fn process<T: Serialize & Clone>(item: T): string {
    let cloned = item.clone();
    return cloned.toJson();
}

// Generic Struct
struct Container<T> {
    value: T,
}

// Generic mit Constraints in Struct
struct Cache<T: Clone> {
    data: T,
}

Type Aliases

type AliasName = ExistingType;

Beispiel:

type UserId = string;
type UserList = List<User>;

Decorators

Decorators sind Metadaten, die Funktionen, Structs oder andere Items annotieren.

HTTP Decorators

@GET("/api/users")
@POST("/api/users")
@PUT("/api/users/:id")
@DELETE("/api/users/:id")
@PATCH("/api/users/:id")

Security Decorators

@Auth
@Role("admin")

Performance Decorators

@Cache(ttl: "5m", key: "user:{id}")

SEO Decorators

@SEO(title: "Product: {name}", description: "{description}")

AI/ML Decorators

@AI(model: "sentiment")

Testing Decorators

@test
@describe("Test Suite Name")
@fixture("fixture-name")
@mock("TraitName")

Beispiel:

@GET("/api/users/:id")
@Auth
@Role("user")
fn getUser(id: string): User {
    return db.find(User, id);
}

Statements

Let Statement

let name: string = "John";
let age = 30; // Type Inference
let mut counter = 0; // Mutable

Return Statement

return value;
return; // void

If Statement

if (condition) {
    // then block
} else {
    // else block
}

For Statement

for (item in collection) {
    // body
}

While Statement

while (condition) {
    // body
}

Match Statement

match (value) {
    pattern1 => {
        // body
    },
    pattern2 if condition => {
        // body with guard
    },
    pattern3 | pattern4 => {
        // or pattern
    },
    _ => {
        // wildcard
    }
}

Pattern Types

Literal Patterns: "hello", 42, true
Identifier Patterns: value (bindet Wert an Variable)
Wildcard Pattern: _ (matched alles)
Range Patterns: 0..10 (exclusive), 0..=10 (inclusive)
Tuple Patterns: (a, b, c)
Struct Patterns: User { name, email }
Enum Variant Patterns: Result::Ok(value), Result::Error(err)
Or Patterns: pattern1 | pattern2

Pattern Guards

Pattern Guards erlauben zusätzliche Bedingungen:

match (value) {
    Ok(x) if x > 0 => "positive",
    Ok(x) if x < 0 => "negative",
    Ok(0) => "zero",

Try Statement ✅ (Version 3.0.1)

Der try-catch-finally Statement ist syntaktischer Zucker für Result-basiertes Error-Handling:

// Einfacher try-catch
try {
    let result = someFunction();
    return result;
} catch (err) {
    handleError(err);
}

// Mehrere catch-Blöcke mit Typ-Dispatch
try {
    return processData(data);
} catch (err: ValidationError) {
    handleValidationError(err);
} catch (err: NetworkError) {
    handleNetworkError(err);
} catch (err) {
    handleGenericError(err);
}

// Mit finally-Block
try {
    return openFile(path);
} catch (err) {
    log.error(err.message);
} finally {
    closeResources(); // Wird immer ausgeführt
}

Wichtige Hinweise:

Jedes return im try-Block wird automatisch in Result.ok(...) gewrappt
Mehrere catch-Blöcke mit spezifischen Fehlertypen werden zu match-Statements desugared
Der finally-Block wird immer ausgeführt, unabhängig von Erfolg oder Fehler
Die Transformation erfolgt automatisch während der Kompilierung

match (value) {
    Ok(x) if x > 0 => "positive",
    Ok(x) if x < 0 => "negative",
    Ok(0) => "zero",
    _ => "unknown"
}

Expressions

Literal Expressions

"string"
42
3.14
true
false
null

Identifier Expressions

variableName
functionName

Binary Operations

a + b
a - b
a * b
a / b
a % b
a == b
a != b
a < b
a > b
a <= b
a >= b
a && b
a || b

Unary Operations

!condition
-number

Function Calls

functionName(arg1, arg2)
db.find(User, id)

Member Access

object.member
user.name

Index Access

array[index]
list[0]

Conditional Expressions

condition ? thenExpr : elseExpr

Block Expressions

{
    let x = 1;
    x + 1
}

Lambda Expressions

// Lambda mit Expression Body
let add = (a: number, b: number) => a + b;

// Lambda mit Block Body
let multiply = (a: number, b: number) => {
    let result = a * b;
    return result;
};

// Lambda mit Type Inference
let square = (x) => x * x;

LLM-Call Expressions (Neu in 3.0.1)

Kompakte Syntax für LLM-Aufrufe mit automatischer Prompt-Optimierung (90%+ Token-Ersparnis):

// Kompakte LLM-Syntax
let result = await @llm.analyze(text);
let summary = await @llm.summarize(long_text);
let sentiment = await @llm.sentiment(comment);
let translated = await @llm.translate(text, "en");
let extracted = await @llm.extract(text, "email addresses");
let evaluation = await @llm.evaluate(review_text);

Syntax:

@llm.<method>(args...) - Kompakte LLM-Call Syntax
Unterstützte Methoden: analyze, summarize, extract, evaluate, translate, sentiment
Automatische Prompt-Optimierung durch Prompt Optimizer
90-95% Token-Ersparnis im Vergleich zu klassischen Prompts

Vorteile:

Deutlich weniger Tokens (5-10 statt 100+)
Automatische Prompt-Optimierung
System-Prompt-Caching
Einfache, lesbare Syntax

Siehe: Prompt Optimizer Dokumentation

Standard Library

Database Funktionen

db.find(Entity, id)        // Findet ein Entity
db.findAll(Entity)         // Findet alle Entities
db.save(entity)            // Speichert ein Entity
db.delete(Entity, id)      // Löscht ein Entity

Collections Library

List

let list = List<number>([1, 2, 3, 4, 5]);

// Transformation
let doubled = list.map((x: number) => x * 2);
let evens = list.filter((x: number) => x % 2 == 0);
let sum = list.reduce((acc: number, x: number) => acc + x, 0);

// Suche
let found = list.find((x: number) => x > 3);
let hasFive = list.contains(5);
let index = list.indexOf(3);

// Sortierung
let sorted = list.sort();
let reversed = list.reverse();

// Chunking & Slicing
let chunks = list.chunk(2);
let slice = list.slice(1, 3);

Map<K, V>

let map = Map<string, number>();

map.set("one", 1);
let value = map.get("one");
let has = map.has("one");
let keys = map.keys();
let values = map.values();
let entries = map.entries();
map.delete("one");
let size = map.size();

Set

let set = Set<number>();

set.add(1);
set.remove(1);
let has = set.has(1);
let size = set.size();
let union = set1.union(set2);
let intersection = set1.intersection(set2);
let difference = set1.difference(set2);

HTTP Client Library

let client = HttpClient.new();

// GET Request
let response = await client.get("https://api.example.com/users");
let data = response.json();

// POST Request
let response = await client.post(
    "https://api.example.com/users",
    { name: "John", email: "john@example.com" }
);

// PUT, DELETE, PATCH
let response = await client.put(url, body);
let response = await client.delete(url);
let response = await client.patch(url, body);

// Response Handling
let json = response.json();
let text = response.text();
let status = response.status();

Rate Limiting Library

@RateLimit(
    requests: 100,
    window: "1m",
    strategy: "sliding-window",
    key: "user:{userId}"
)
@GET("/api/users")
fn getUsers(): List<User> {
    // ...
}

Assert Funktionen

assert(condition)
assert(left == right)      // Wird zu assert_eq!()
assert(left != right)      // Wird zu assert_ne!()

Module System

Module Definition

mod moduleName {
    // Items
}

Use Statements

use module::item;
use module::item as alias;

Visibility

pub - Public (exportiert)
(kein Modifier) - Private (standard)

Type System

Type Inference

VelinScript unterstützt Type Inference für Variablen:

let name = "John"; // Typ: string
let age = 30;      // Typ: number

Type Checking

Alle Typen werden zur Compile-Zeit geprüft:

fn add(a: number, b: number): number {
    return a + b;
}

let result = add(2, 3); // OK
let error = add("2", 3); // Type Error!

Generic Types

List<User>
Map<string, number>
Optional<User>

Beispiele

Hello World

@GET("/api/hello")
fn hello(): string {
    return "Hello, VelinScript! 🚀";
}

API Endpoint

struct User {
    id: string,
    name: string,
    email: string,
}

@GET("/api/users/:id")
fn getUser(id: string): User {
    return db.find(User, id);
}

Security

@Auth
@Role("admin")
@GET("/api/admin/users")
fn getAdminUsers(): List<User> {
    return db.findAll(User);
}

Testing

@test
fn testGetUser() {
    let user = getUser("123");
    assert(user.name == "John");
}

Compilation

VelinScript wird zu Rust Code kompiliert:

VelinScript:

@GET("/api/users/:id")
fn getUser(id: string): User {
    return db.find(User, id);
}

Rust Output:

#[get("/api/users/:id")]
fn get_user(id: String) -> User {
    db.find::<User>(id).await
}

Syntax-Zusammenfassung

Funktion

[Decorators]
[pub] [async] fn name(params): returnType {
    statements
}

Variable

let [mut] name[: type] = value;

Struct

[pub] struct Name {
    [pub] field: type,
}

Enum

[pub] enum Name {
    Variant1,
    Variant2(type),
}

Bekannte Einschränkungen (v0.1.0)

Module System: Basis-Implementierung
Pattern Matching: Vereinfacht
Async/Await: Basis-Implementierung
Macros: Noch nicht implementiert

Implementierte Features (v0.1.0)

✅ Result<T, E> Type - Explizite Fehlerbehandlung mit Result Type ✅ try-catch-finally (Version 3.0.1) - Syntaktischer Zucker für Result-basiertes Error-Handling ✅ Traits/Interfaces - Polymorphismus durch Traits und Interfaces ✅ Generics mit Constraints - Type-safe generische Programmierung mit Trait Constraints ✅ Erweiterte Test-Features - @describe, @fixture, @mock Decorators ✅ Package Manager (velin-pkg) - Dependency Management mit velin.toml ✅ Security Scanner (velin-security) - Automatische Security-Vulnerability-Erkennung ✅ LSP Server - Language Server Protocol für IDE-Integration ✅ VS Code Extension - Vollständige IDE-Unterstützung