Vais 프로그래밍 언어

Vais 0.1.0 (Vibe AI Language for Systems)

AI-optimized systems programming language with token-efficient syntax.

Vais is designed to minimize token usage while maximizing code expressiveness, making it ideal for AI-assisted development and LLM code generation.

Key Features

• Single-letter keywords - F (function), S (struct), E (enum/else), I (if), L (loop), M (match)
• Self-recursion operator @ - Call the current function recursively
• Expression-oriented - Everything is an expression
• LLVM backend - Native performance with LLVM 17
• Type inference - Minimal type annotations with full constraint solving
• Memory Safety - Borrow checker with Non-Lexical Lifetimes (NLL), --strict-borrow mode
• Slice Types - &[T] / &mut [T] with fat pointer implementation
• Parallel Compilation - DAG-based parallel type-check and codegen (2-4x speedup)
• Self-Hosting - 50,000+ LOC bootstrap compiler, 21/21 clang 100% success
• Rich Ecosystem - 29 crates, 74 stdlib modules, growing package ecosystem

Quick Example

# Fibonacci with self-recursion
F fib(n:i64)->i64 = n<2 ? n : @(n-1) + @(n-2)

# Struct definition
S Point { x:f64, y:f64 }

# Sum with loop
F sum(arr:[i64])->i64 {
    s := 0
    L x:arr { s += x }
    s
}

Syntax Overview

Project Structure

crates/
├── vais-ast/          # AST definitions
├── vais-lexer/        # Tokenizer (logos-based)
├── vais-parser/       # Recursive descent parser
├── vais-types/        # Type checker & inference
├── vais-codegen/      # LLVM IR code generator (inkwell/, advanced_opt/)
├── vais-codegen-js/   # JavaScript (ESM) code generator
├── vais-mir/          # Middle IR
├── vaisc/             # Main compiler CLI & REPL
├── vais-lsp/          # Language Server Protocol
├── vais-dap/          # Debug Adapter Protocol
├── vais-jit/          # Cranelift JIT compiler
├── vais-gc/           # Optional garbage collector
├── vais-gpu/          # GPU codegen (CUDA/Metal/OpenCL/WebGPU)
├── vais-i18n/         # Internationalized error messages
├── vais-plugin/       # Plugin system
├── vais-macro/        # Declarative macro system
├── vais-hotreload/    # Hot reloading
├── vais-dynload/      # Dynamic module loading & WASM sandbox
├── vais-bindgen/      # FFI binding generator (C/WASM-JS)
├── vais-query/        # Salsa-style query database
├── vais-profiler/     # Compiler profiler
├── vais-security/     # Security analysis & audit
├── vais-supply-chain/ # SBOM & dependency audit
├── vais-testgen/      # Property-based test generation
├── vais-tutorial/     # Interactive tutorials
├── vais-registry-server/    # Package registry (Axum/SQLite)
├── vais-playground-server/  # Web playground backend
├── vais-python/       # Python bindings (PyO3)
└── vais-node/         # Node.js bindings (NAPI)

std/               # Standard library (79 modules)
selfhost/          # Self-hosting compiler (50,000+ LOC)
vscode-vais/       # VSCode extension
intellij-vais/     # IntelliJ plugin
docs-site/         # mdBook documentation
examples/          # Example programs (174 .vais files)
benches/           # Benchmark suite (criterion + language comparison)
playground/        # Web playground frontend

Building

cargo build --release
cargo test                                     # Run all 9,300+ tests
cargo test -p vaisc                            # Run vaisc tests (1,620+ E2E tests)
cargo clippy --workspace --exclude vais-python --exclude vais-node

Test Coverage

This project uses cargo-llvm-cov to measure test coverage. Coverage reports are generated automatically in the CI pipeline.

Local Coverage Measurement

To generate coverage reports locally:

# Install cargo-tarpaulin (one-time setup)
cargo install cargo-tarpaulin

# Generate coverage reports (HTML and Lcov)
cargo tarpaulin --config tarpaulin.toml

# Or use the convenience alias
cargo coverage

# Generate HTML report only
cargo coverage-html

# Generate Lcov format for CI integration
cargo coverage-lcov

Coverage reports are saved to target/coverage/:

• index.html - Interactive HTML coverage report
• lcov.info - Lcov format for codecov integration

CI Integration

Coverage is measured automatically on every push and pull request to main and develop branches. Reports are:

• Uploaded as GitHub Actions artifacts
• Sent to Codecov for tracking trends
• Available for 30 days in the CI artifacts

Usage

# Compile a Vais file
./target/release/vaisc build hello.vais -o hello

# Run directly
./target/release/vaisc run hello.vais

# Start REPL
./target/release/vaisc repl

# Format code
./target/release/vaisc fmt src/

# Check for errors
./target/release/vaisc check hello.vais

Status

• Lexer (logos-based tokenizer)
• Parser (recursive descent)
• Type checker (generics, traits, type inference, GATs, object safety)
• Code generator (LLVM IR via inkwell, JavaScript ESM, WASM)
• Standard library (74 modules: Vec, HashMap, String, File, Net, Async, GPU, etc.)
• Borrow checker (Non-Lexical Lifetimes, CFG-based dataflow, --strict-borrow)
• Slice types (&[T] / &mut [T] with fat pointers)
• Parallel compilation (DAG-based dependency resolution, 2-4x speedup)
• Self-hosting compiler (50,000+ LOC, 21/21 clang success, Bootstrap Phase 56)
• LSP support (diagnostics, completion, hover, go-to-definition, references, rename)
• REPL (interactive environment)
• VSCode extension + IntelliJ plugin (syntax highlighting, LSP integration)
• Optimizer (constant folding, DCE, CSE, loop unrolling, LICM, alias analysis, vectorization)
• Formatter (vaisc fmt)
• Debugger (DWARF metadata, lldb/gdb support)
• Ecosystem packages (vais-aes, vais-base64, vais-crc32, vais-csv, vais-json, vais-lz4, vais-regex, vais-sha256, vais-uuid)

Performance

Vais is designed for both compilation speed and runtime performance.

Compilation Speed

Self-Hosting Bootstrap: 50,000+ LOC, 21/21 clang compilation success (100%)

Runtime Performance

Fibonacci(35) benchmark (Apple M-series ARM64, 2026-02-11):

Running Benchmarks

# Compile-time benchmarks
cargo bench -p vais-benches --bench compile_bench

# Runtime comparison benchmarks
cargo bench -p vais-benches --bench runtime_bench

Documentation

Official Documentation Site

The comprehensive documentation is available as an interactive mdBook site:

# Build and view the documentation
cd docs-site
./serve.sh

Visit the online documentation or browse the individual files:

• LANGUAGE_SPEC.md - Complete language specification
• STDLIB.md - Standard library reference
• TUTORIAL.md - Getting started tutorial
• Architecture.md - Compiler architecture and design
• INSTALLATION.md - Installation guide
• COVERAGE.md - Test coverage measurement guide
• MEMORY_SAFETY.md - Memory safety testing and guarantees
• ROADMAP.md - Project roadmap and progress

Memory Safety Testing

Vais ensures memory safety through Rust's ownership system and comprehensive testing:

# Run memory safety tests (without AddressSanitizer)
cargo test -p vaisc --test memory_safety_tests

# Run with AddressSanitizer (requires Rust nightly)
./scripts/asan-test.sh

# Run all sanitizers (ASan, UBSan, etc.)
./scripts/run-sanitizers.sh all

See MEMORY_SAFETY.md for detailed information on memory safety guarantees and testing.

Installation

Homebrew (macOS/Linux) - No Rust required

brew tap vaislang/tap
brew install vais

Pre-built Binaries

Download from Releases (Linux, macOS Intel/ARM, Windows):

# macOS ARM
curl -LO https://github.com/vaislang/vais/releases/download/v0.1.0/vais-v0.1.0-aarch64-apple-darwin.tar.gz
tar -xzf vais-v0.1.0-aarch64-apple-darwin.tar.gz
./vais/vaisc --version

From Source (requires Rust)

git clone https://github.com/vaislang/vais.git
cd vais && cargo build --release

Docker

docker run -it vaislang/vais:latest

Links

What's Next?

After installing Vais and running your first program, here's how to continue:

5-Minute Quickstart

# 1. Install
brew tap vaislang/tap && brew install vais

# 2. Write your first program
echo 'F main() { println("Hello, Vais!") }' > hello.vais

# 3. Run it
vaisc run hello.vais

# 4. Try the REPL
vaisc repl

Recommended Examples

Learning Path

Follow the structured learning path for a guided experience:

• Stage 1 (2hr): Variables, functions, control flow, structs, enums
• Stage 2 (4hr): Generics, traits, error handling, closures, stdlib
• Stage 3 (4hr): Macros, async, FFI, WASM, performance

Tutorials

Step-by-step project tutorials:

• CLI Tool - Build a word count tool
• HTTP Server - Create a REST API
• Data Pipeline - ETL data processing

Community

• GitHub Discussions - Questions, ideas, show & tell
• Blog - Technical articles and language design insights
• Contributing Guide - How to contribute
• CHANGELOG - Release history
• Discord - Real-time chat (coming soon)

Follow Us

• GitHub: @vaislang
• Twitter/X: @vaislang
• Instagram: @vaislang

Recent Blog Posts

• The Self-Hosting Journey: 50,000 Lines of Vais Compiling Itself
• Vais Performance: Compilation Speed and Runtime Benchmarks
• The Design Philosophy Behind Single-Character Keywords

Legacy

The prototype implementation is available on the proto branch.

License

MIT License

설치

Vais Compiler Installation Guide

Welcome to the Vais compiler installation guide. This document will walk you through setting up Vais on your system, from prerequisites to verification.

Quick Install (Recommended)

The fastest way to install Vais. No Rust required.

Homebrew (macOS / Linux)

brew tap vaislang/tap
brew install vais

Pre-built Binaries

Download from GitHub Releases:

# Example: macOS ARM
curl -LO https://github.com/vaislang/vais/releases/download/v1.0.0/vais-v1.0.0-aarch64-apple-darwin.tar.gz
tar -xzf vais-v1.0.0-aarch64-apple-darwin.tar.gz
sudo cp vais/vaisc /usr/local/bin/

Prerequisite: clang

Vais uses clang to compile generated LLVM IR to native binaries:

• macOS: xcode-select --install
• Linux: sudo apt install clang or sudo dnf install clang
• Windows: Install from https://releases.llvm.org

After installation, verify: vaisc --version

Build from Source

If you want to build from source or contribute to development.

System Requirements

Required Software

• Rust 1.70+ - The Vais compiler is written in Rust
• LLVM/Clang 17+ - For LLVM backend code generation
• Git - For cloning the repository
• CMake 3.15+ - Required by LLVM build tools

Hardware Requirements

• Minimum 2GB RAM
• At least 5GB disk space (for build artifacts and LLVM)
• Multi-core processor recommended

Supported Platforms

• macOS 11+ (Intel and Apple Silicon)
• Linux (Ubuntu 20.04+, Fedora 35+, Debian 11+)
• Windows 10+ (with MSVC or WSL2)

Installation by Platform

macOS

1. Install Rust

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

2. Install LLVM and Dependencies

Using Homebrew:

brew install llvm@17 clang cmake pkg-config

Set up environment variables:

# Add to ~/.zshrc or ~/.bash_profile
export LLVM_DIR=/usr/local/opt/llvm@17
export PATH="/usr/local/opt/llvm@17/bin:$PATH"

3. Clone and Build

git clone https://github.com/vaislang/vais.git
cd vais
cargo build --release

Linux (Ubuntu/Debian)

1. Install Rust

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

2. Install Dependencies

sudo apt-get update
sudo apt-get install -y \
    build-essential \
    cmake \
    pkg-config \
    llvm-17 \
    clang-17 \
    libllvm-17-ocaml-dev

3. Set Environment Variables

# Add to ~/.bashrc
export LLVM_DIR=/usr/lib/llvm-17
export PATH="/usr/lib/llvm-17/bin:$PATH"

4. Clone and Build

git clone https://github.com/vaislang/vais.git
cd vais
cargo build --release

Linux (Fedora/RHEL)

1. Install Rust

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

2. Install Dependencies

sudo dnf install -y \
    gcc-c++ \
    cmake \
    llvm-devel-17 \
    clang-tools-extra-17 \
    pkg-config

3. Set Environment Variables

# Add to ~/.bashrc
export LLVM_DIR=/usr/lib64/llvm-17
export PATH="/usr/lib64/llvm-17/bin:$PATH"

4. Clone and Build

git clone https://github.com/vaislang/vais.git
cd vais
cargo build --release

Windows

1. Install Rust

Download and run the installer from https://rustup.rs/

2. Install Visual Studio Build Tools

Download from: https://visualstudio.microsoft.com/visual-cpp-build-tools/

Select "Desktop development with C++"

3. Install LLVM 17

Download from: https://releases.llvm.org/download.html (LLVM-17.x.x-win64.exe)

During installation, add LLVM to PATH when prompted.

4. Install CMake

Download from: https://cmake.org/download/

Ensure CMake is added to PATH.

5. Clone and Build

git clone https://github.com/vaislang/vais.git
cd vais
cargo build --release

Building from Source

Development Build

For faster compilation during development:

cargo build

The compiler will be available at ./target/debug/vaisc

Release Build

For optimized production binary:

cargo build --release

The compiler will be available at ./target/release/vaisc

Build with Specific Features

# With LSP support (included by default)
cargo build --release --all-features

# Run all tests during build
cargo build --release --all-targets

Environment Setup

Add Vais to PATH

For easy access to the compiler from anywhere:

# For release build
export PATH="$PATH:$(pwd)/target/release"

# Or create a symlink
ln -s $(pwd)/target/release/vaisc /usr/local/bin/vaisc

Configure Standard Library Path

Set the VAIS_STD_PATH environment variable (optional, auto-detected by default):

export VAIS_STD_PATH=$(pwd)/std

LSP Configuration

The Vais Language Server is built into the compiler:

vaisc lsp

This starts the language server on stdio.

VSCode Extension Installation

From Marketplace

1. Open VSCode
2. Press Ctrl+Shift+X (Windows/Linux) or Cmd+Shift+X (macOS)
3. Search for "vais" or "vais-language"
4. Click Install

From Source

cd vscode-vais
npm install
npm run build
code --install-extension vais-language-server-0.0.1.vsix

Configure Extension

Add to .vscode/settings.json:

{
  "vais.compilerPath": "/path/to/vaisc",
  "vais.stdPath": "/path/to/vais/std",
  "vais.lsp.enable": true,
  "[vais]": {
    "editor.defaultFormatter": "vais.vais-language",
    "editor.formatOnSave": true
  }
}

Verification

Test the Installation

# Check compiler version
vaisc --version

# Run the test suite
cargo test --release

# Compile an example
vaisc build examples/hello.vais -o hello
./hello

Expected Output

$ ./hello
Hello, World!

Run Comprehensive Tests

# Unit tests
cargo test --lib

# Integration tests
cargo test --test '*'

# Benchmark tests
cargo bench

Troubleshooting

LLVM Not Found

Error: error: LLVM 17 not found

Solution:

• Verify LLVM 17 is installed: llvm-config-17 --version
• Set LLVM_DIR correctly
• On macOS: export LLVM_DIR=$(brew --prefix llvm@17)

Rust Compilation Errors

Error: error: could not compile vaisc

Solution:

• Update Rust: rustup update
• Clean build artifacts: cargo clean && cargo build --release
• Check Rust version: rustc --version (should be 1.70+)

Out of Memory During Build

Solution:

• Increase swap space or RAM
• Build without optimizations: cargo build (instead of --release)
• Close other applications

Missing Standard Library

Error: error: standard library not found

Solution:

• Verify std/ directory exists in project root
• Set VAIS_STD_PATH: export VAIS_STD_PATH=$(pwd)/std

VSCode Extension Not Working

Solution:

• Ensure compiler path in settings is correct
• Restart VSCode: Cmd+Shift+P → "Developer: Reload Window"
• Check LSP output: View → Output → select "Vais Language Server"

Platform-Specific Issues

macOS Apple Silicon (M1/M2):

• Use native ARM64 builds; Rosetta translation may cause issues
• Ensure Homebrew and dependencies are installed for ARM64

Windows Path Issues:

• Use full paths or add to system PATH environment variable
• Restart Command Prompt/PowerShell after modifying PATH

Linux GLIBC Compatibility:

• Error: GLIBC_2.XX not found
• Solution: Update glibc or compile with RUSTFLAGS="-C target-cpu=generic"

Next Steps

After successful installation:

1. Read the Tutorial: docs/TUTORIAL.md
2. Language Specification: docs/LANGUAGE_SPEC.md
3. Standard Library: docs/STDLIB.md
4. Example Programs: examples/ directory

Getting Help

• GitHub Issues: https://github.com/vaislang/vais/issues
• Documentation: https://github.com/vaislang/vais/tree/main/docs
• Contributing: See CONTRIBUTING.md

Version Information

• Vais Version: 0.0.1
• LLVM Requirement: 17.x
• Rust MSRV: 1.70
• License: MIT

빠른 시작

Vais 프로그래밍 언어를 빠르게 시작하는 방법입니다.

설치

# macOS / Linux (Homebrew)
brew tap vaislang/tap && brew install vais

# 또는 Cargo
cargo install vaisc

소스에서 직접 빌드하려면 Getting Started 가이드를 참고하세요.

첫 번째 프로그램

다음 코드를 hello.vais 파일로 저장합니다:

F main() {
    puts("Hello, Vais!")
}

컴파일 및 실행

# 컴파일
vaisc build hello.vais -o hello
./hello

# 또는 직접 실행
vaisc run hello.vais

출력:

Hello, Vais!

기본 문법

변수

F main() {
    x := 42              # i64 타입으로 추론됨
    y := 3.14            # f64 타입으로 추론됨
    name := "Alice"      # str 타입으로 추론됨
    flag := true         # bool 타입으로 추론됨

    puts("Variables declared!")
}

함수

F add(a: i64, b: i64) -> i64 {
    a + b  # 마지막 표현식이 반환값
}

F main() {
    result := add(10, 20)
    print_i64(result)  # 출력: 30
}

제어 흐름

F main() {
    x := 10

    # if 표현식
    msg := I x > 5 { "big" } E { "small" }
    puts(msg)

    # 반복문
    L i:0..5 {
        print_i64(i)
    }
}

자기 재귀

@를 사용하여 현재 함수를 호출합니다:

F factorial(n: i64) -> i64 {
    I n <= 1 { R 1 }
    n * @(n - 1)
}

F main() {
    print_i64(factorial(5))  # 출력: 120
}

다음 단계

• 튜토리얼 - Vais를 심도 있게 배우기
• 언어 사양 - 전체 문법 참조
• 예제 프로그램 - 코드 샘플 둘러보기

튜토리얼

Vais Programming Tutorial

Welcome to Vais! This tutorial will guide you through the basics of programming in Vais, from installation to writing your first programs.

Table of Contents

1. Installation
2. Hello World
3. Variables and Types
4. Functions
5. Control Flow
6. Structs and Enums
7. Pattern Matching
8. Traits and Methods
9. Generics
10. Standard Library Basics
11. Async Programming
12. Next Steps

Installation

Prerequisites

• Rust toolchain (for building the compiler)
• LLVM (for code generation)
• Clang (for compiling generated LLVM IR)

Building from Source

# Clone the repository
git clone https://github.com/vaislang/vais.git
cd vais

# Build the compiler
cargo build --release

# The compiler will be available at:
./target/release/vaisc

Verify Installation

./target/release/vaisc --version
# Should output: Vais 0.0.1

Hello World

Let's write your first Vais program!

Create a file hello.vais:

# Hello World example
F main()->i64 {
    puts("Hello, Vais!")
    0
}

Compile and run:

./target/release/vaisc hello.vais
./hello

Output:

Hello, Vais!

Understanding the code:

• F - Keyword for function definition
• main - Entry point function name
• ()->i64 - Function signature: no parameters, returns i64
• puts("Hello, Vais!") - Print a string
• 0 - Return value (convention: 0 for success)

Variables and Types

Type-Inferred Variables

Use := for automatic type inference:

F main()->i64 {
    x := 10          # i64 inferred
    y := 3.14        # f64 inferred
    name := "Alice"  # str inferred
    flag := true     # bool inferred

    puts("Variables declared!")
    0
}

Explicit Types

Specify types explicitly with ::

F main()->i64 {
    x: i64 = 100
    y: f64 = 2.5
    count: i32 = 42

    puts("Typed variables declared!")
    0
}

Primitive Types

Integers:

a: i8 = 127          # 8-bit signed
b: i16 = 32000       # 16-bit signed
c: i32 = 1000000     # 32-bit signed
d: i64 = 999999999   # 64-bit signed

ua: u8 = 255         # 8-bit unsigned
ub: u32 = 4294967295 # 32-bit unsigned

Floating-point:

x: f32 = 3.14        # 32-bit float
y: f64 = 2.718281828 # 64-bit float

Boolean:

is_ready := true
is_done := false

Using Variables

F main()->i64 {
    x := 10
    y := 20
    sum := x + y

    puts("Sum calculated!")
    0
}

Functions

Simple Functions

Expression form (single expression):

F add(a:i64, b:i64)->i64 = a + b

F square(x:i64)->i64 = x * x

F max(a:i64, b:i64)->i64 = a > b ? a : b

Block form (multiple statements):

F greet(name: str)->i64 {
    puts("Hello, ")
    puts(name)
    puts("!")
    0
}

Function Parameters

# Multiple parameters with different types
F calculate(x: i64, y: f64, multiplier: i64) -> f64 {
    result := x * multiplier
    result * y
}

Calling Functions

F main()->i64 {
    sum := add(10, 20)
    squared := square(5)
    maximum := max(100, 200)

    puts("Functions called!")
    0
}

Self-Recursion with @

The @ operator calls the current function recursively:

# Fibonacci using self-recursion
F fib(n:i64)->i64 = n<2 ? n : @(n-1) + @(n-2)

# Factorial
F factorial(n:i64)->i64 = n<2 ? 1 : n * @(n-1)

# Countdown
F countdown(n:i64)->i64 {
    I n <= 0 {
        puts("Done!")
        0
    } E {
        puts("Counting...")
        @(n-1)
    }
}

Why use @?

• More concise than writing the function name
• Fewer tokens for AI code generation
• Clear indicator of recursion

Control Flow

If-Else Expressions

Ternary form (single expression):

F abs(x:i64)->i64 = x < 0 ? -x : x

F sign(x:i64)->i64 = x < 0 ? -1 : x > 0 ? 1 : 0

Block form:

F classify(x:i64)->str {
    I x < 0 {
        "negative"
    } E I x == 0 {
        "zero"
    } E {
        "positive"
    }
}

Note: E is used for "else". Context determines whether E means "enum" or "else".

Loops

Infinite loop:

F loop_forever()->i64 {
    L {
        puts("Looping...")
        # Need break condition
    }
    0
}

Range loop:

F count_to_ten()->i64 {
    L i: 0..10 {
        puts("Number: ")
        print_i64(i)
        putchar(10)
    }
    0
}

With break and continue:

F find_first_even()->i64 {
    L i: 0..100 {
        I i % 2 == 0 {
            puts("Found even number:")
            print_i64(i)
            B  # Break
        }
        C  # Continue
    }
    0
}

Early Return

F validate(x: i64)->i64 {
    I x < 0 {
        puts("Error: negative value")
        R -1  # Early return
    }
    I x == 0 {
        puts("Error: zero value")
        R -1
    }

    # Process valid value
    puts("Valid!")
    x * 2
}

Structs and Enums

Defining Structs

S Point {
    x: f64,
    y: f64
}

S Person {
    name: str,
    age: i64
}

S Rectangle {
    top_left: Point,
    bottom_right: Point
}

Creating Struct Instances

F main()->i64 {
    # Create a Point
    p := Point { x: 10.0, y: 20.0 }

    # Create a Person
    person := Person { name: "Bob", age: 25 }

    # Nested structs
    rect := Rectangle {
        top_left: Point { x: 0.0, y: 10.0 },
        bottom_right: Point { x: 10.0, y: 0.0 }
    }

    0
}

Accessing Fields

F main()->i64 {
    p := Point { x: 5.0, y: 15.0 }

    x_coord := p.x
    y_coord := p.y

    puts("Point coordinates:")
    print_f64(x_coord)
    print_f64(y_coord)

    0
}

Defining Enums

Simple enum:

E Color {
    Red,
    Green,
    Blue
}

Enum with data:

E Option {
    None,
    Some(i64)
}

E Result {
    Ok(i64),
    Err(str)
}

E Message {
    Quit,
    Move(i64, i64),
    Write(str)
}

Using Enums

F main()->i64 {
    color := Red
    opt := Some(42)
    result := Ok(100)
    msg := Move(10, 20)

    puts("Enums created!")
    0
}

Pattern Matching

Pattern matching with M (match) is powerful for working with enums and values.

Basic Match

F describe_number(n: i64)->str {
    M n {
        0 => "zero",
        1 => "one",
        2 => "two",
        _ => "other"  # Wildcard: matches everything else
    }
}

Match with Binding

Extract values from matched patterns:

E Option {
    None,
    Some(i64)
}

F unwrap_or(opt: Option, default: i64) -> i64 {
    M opt {
        Some(x) => x,        # Bind value to 'x'
        None => default
    }
}

F main()->i64 {
    opt1 := Some(42)
    opt2 := None

    v1 := unwrap_or(opt1, 0)  # Returns 42
    v2 := unwrap_or(opt2, 99) # Returns 99

    print_i64(v1)
    print_i64(v2)
    0
}

Match with Result Types

E Result {
    Ok(i64),
    Err(str)
}

F handle_result(res: Result) -> i64 {
    M res {
        Ok(value) => value,
        Err(msg) => {
            puts("Error: ")
            puts(msg)
            0
        }
    }
}

Complete Example

E Color {
    Red,
    Green,
    Blue
}

F color_to_code(c: Color) -> i64 {
    M c {
        Red => 0xFF0000,
        Green => 0x00FF00,
        Blue => 0x0000FF
    }
}

F main()->i64 {
    red_code := color_to_code(Red)
    green_code := color_to_code(Green)

    puts("Color codes calculated!")
    0
}

Traits and Methods

Defining Traits

Traits define interfaces that types can implement:

W Printable {
    F print(&self) -> i64
}

W Comparable {
    F compare(&self, other: &Self) -> i64
}

Implementing Traits

S Counter {
    value: i64
}

# Implement Printable trait for Counter
X Counter: Printable {
    F print(&self) -> i64 {
        puts("Counter value: ")
        print_i64(self.value)
        putchar(10)
        0
    }
}

Adding Methods

Add methods without traits using X:

X Counter {
    F increment(&self) -> i64 {
        self.value + 1
    }

    F double(&self) -> i64 {
        self.value * 2
    }

    F reset() -> Counter {
        Counter { value: 0 }
    }
}

Using Methods

F main()->i64 {
    c := Counter { value: 10 }

    # Call trait method
    c.print()

    # Call impl methods
    inc := c.increment()
    dbl := c.double()

    puts("Incremented: ")
    print_i64(inc)
    puts("Doubled: ")
    print_i64(dbl)

    0
}

Complete Example

W Shape {
    F area(&self) -> f64
}

S Circle {
    radius: f64
}

S Rectangle {
    width: f64,
    height: f64
}

X Circle: Shape {
    F area(&self) -> f64 {
        pi := 3.14159
        pi * self.radius * self.radius
    }
}

X Rectangle: Shape {
    F area(&self) -> f64 {
        self.width * self.height
    }
}

F main()->i64 {
    circle := Circle { radius: 5.0 }
    rect := Rectangle { width: 4.0, height: 6.0 }

    circle_area := circle.area()
    rect_area := rect.area()

    puts("Circle area: ")
    print_f64(circle_area)

    puts("Rectangle area: ")
    print_f64(rect_area)

    0
}

Generics

Generics allow you to write code that works with multiple types.

Generic Functions

F identity<T>(x: T) -> T = x

F first<T>(a: T, b: T) -> T = a

F swap<A, B>(a: A, b: B) -> (B, A) {
    (b, a)
}

Generic Structs

S Pair<T> {
    first: T,
    second: T
}

S Box<T> {
    value: T
}

S Container<K, V> {
    key: K,
    value: V
}

Using Generic Structs

F main()->i64 {
    # Pair of integers
    int_pair := Pair { first: 10, second: 20 }

    # Pair of floats
    float_pair := Pair { first: 1.5, second: 2.5 }

    # Container with different types
    container := Container { key: 1, value: "hello" }

    0
}

Methods on Generic Types

S Pair<T> {
    first: T,
    second: T
}

X Pair {
    F sum(&self) -> i64 {
        self.first + self.second
    }

    F swap(&self) -> Pair {
        Pair { first: self.second, second: self.first }
    }
}

F main()->i64 {
    p := Pair { first: 10, second: 20 }
    total := p.sum()
    swapped := p.swap()

    print_i64(total)  # 30
    0
}

Generic Enums

E Option<T> {
    None,
    Some(T)
}

E Result<T, E> {
    Ok(T),
    Err(E)
}

F main()->i64 {
    # Option of i64
    opt_int := Some(42)

    # Option of str
    opt_str := Some("hello")

    # Result with i64 value and str error
    result := Ok(100)

    0
}

Standard Library Basics

Using the Math Library

U std/math

F main()->i64 {
    # Constants
    pi := PI
    e := E

    # Basic math
    x := abs(-10.0)          # Absolute value
    min_val := min(5.0, 10.0)
    max_val := max(5.0, 10.0)

    # Advanced math
    root := sqrt(16.0)       # Square root: 4.0
    power := pow(2.0, 8.0)   # 2^8 = 256.0

    # Trigonometry
    sine := sin(PI / 2.0)    # sin(90°) = 1.0
    cosine := cos(0.0)       # cos(0°) = 1.0

    # Logarithms
    natural_log := log(E)    # ln(e) = 1.0
    log_base_10 := log10(100.0)  # 2.0

    print_f64(root)
    0
}

Using the IO Library

U std/io

F main()->i64 {
    # Read an integer
    puts("Enter a number: ")
    num := read_i64()
    puts("You entered: ")
    print_i64(num)
    putchar(10)

    # Read a float
    puts("Enter a decimal: ")
    decimal := read_f64()
    puts("You entered: ")
    print_f64(decimal)
    putchar(10)

    # Prompt functions
    age := prompt_i64("Enter your age: ")
    height := prompt_f64("Enter your height: ")

    puts("Age: ")
    print_i64(age)
    puts("Height: ")
    print_f64(height)

    0
}

Using Option and Result

U std/option
U std/result

F divide(a: i64, b: i64) -> Option {
    I b == 0 {
        None
    } E {
        Some(a / b)
    }
}

F main()->i64 {
    result := divide(10, 2)
    value := result.unwrap_or(0)  # Returns 5

    error_result := divide(10, 0)
    default_value := error_result.unwrap_or(-1)  # Returns -1

    print_i64(value)
    print_i64(default_value)
    0
}

Async Programming

Vais supports async/await for concurrent programming.

Defining Async Functions

# Mark function as async with 'A'
A F compute(x: i64) -> i64 {
    x * 2
}

A F fetch_data(id: i64) -> str {
    # Simulate async operation
    "Data loaded"
}

Awaiting Async Functions

F main()->i64 {
    # Call async function and await the result
    result := compute(21).await

    puts("Result: ")
    print_i64(result)  # 42

    # Chain async calls
    data := fetch_data(1).await
    puts(data)

    0
}

Spawning Concurrent Tasks

A F task1() -> i64 {
    puts("Task 1 running")
    100
}

A F task2() -> i64 {
    puts("Task 2 running")
    200
}

F main()->i64 {
    # Spawn tasks to run concurrently
    t1 := spawn task1()
    t2 := spawn task2()

    # Await results
    r1 := t1.await
    r2 := t2.await

    total := r1 + r2
    print_i64(total)  # 300

    0
}

Next Steps

Complete Examples

Explore the examples/ directory for more complete programs:

• fib.vais - Fibonacci with self-recursion
• pattern_match_test.vais - Pattern matching examples
• trait_test.vais - Traits and implementations
• generic_struct_test.vais - Generic types
• async_test.vais - Async/await examples
• io_test.vais - Interactive I/O examples

Further Reading

• Language Specification: See LANGUAGE_SPEC.md for complete language reference
• Standard Library: See STDLIB.md for all available modules and functions
• REPL: Try the interactive REPL with vaisc repl

Practice Projects

1. Calculator: Build a simple calculator using the IO library
2. File Processor: Read and process files using std/file
3. Data Structures: Implement your own Vector or HashMap
4. Async Web Server: Build a simple server using async/await

Community

• GitHub: https://github.com/yourusername/vais
• Issues: Report bugs or request features
• Discussions: Ask questions and share projects

Quick Reference

Function Definition

F name(param: type)->return_type = expr
F name(param: type)->return_type { body }

Variables

x := value        # Type inferred
x: type = value   # Explicit type

Control Flow

I condition { then } E { else }
L { loop_body }
L var: range { body }
M value { pattern => expr, ... }

Self-Recursion

F fib(n:i64)->i64 = n<2 ? n : @(n-1) + @(n-2)

Struct

S Name { field: type, ... }
X Name { F method(&self)->type { body } }

Enum

E Name { Variant, Variant(type), ... }

Trait

W Trait { F method(&self)->type }
X Type: Trait { F method(&self)->type { body } }

Generics

F name<T>(x: T) -> T { body }
S Name<T> { field: T }

Async

A F name() -> type { body }
result := async_func().await

Happy coding with Vais!

Getting Started with Vais

Vais는 AI 최적화된 시스템 프로그래밍 언어입니다. 단일 문자 키워드, 완전한 타입 추론, LLVM 백엔드를 제공합니다. 이 가이드를 따라 Vais를 설치하고 첫 번째 프로그램을 작성해보세요.

설치

Homebrew (macOS / Linux) — 추천

brew tap vaislang/tap && brew install vais

Cargo

cargo install vaisc

바이너리 다운로드

GitHub Releases에서 플랫폼별 바이너리를 다운로드할 수 있습니다:

# macOS / Linux
curl -L https://github.com/vaislang/vais/releases/latest/download/vaisc-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m) -o vaisc
chmod +x vaisc
sudo mv vaisc /usr/local/bin/

Docker

docker run -it vaislang/vais:latest

소스에서 빌드 (개발자용)

컴파일러 개발에 참여하려면 소스에서 직접 빌드합니다:

git clone https://github.com/vaislang/vais.git
cd vais
cargo build --release
cargo install --path crates/vaisc

요구사항: Rust 1.70+, LLVM 17, Git

Hello World

첫 번째 프로그램 작성

hello.vais 파일을 생성합니다:

F main() {
    println("Hello, Vais!")
}

참고: main() 함수는 반환 타입을 생략할 수 있습니다. 생략 시 암시적으로 i64 반환 타입이 적용되며, 명시적 R(return) 없이 종료하면 0을 반환합니다. 명시적으로 F main() -> i64 { ... } 형태도 여전히 지원됩니다.

컴파일 및 실행

# 방법 1: 컴파일 후 실행
vaisc build hello.vais -o hello
./hello

# 방법 2: 직접 실행 (vaisc run 사용)
vaisc run hello.vais

# 방법 3: REPL에서 실행
vaisc repl
> puts("Hello, Vais!")

첫 번째 프로젝트

프로젝트 구조 만들기

# 새로운 프로젝트 초기화
mkdir my-vais-app
cd my-vais-app

# 기본 폴더 구조
mkdir src
mkdir bin
touch Vais.toml

Vais.toml 작성

프로젝트 메타데이터 파일을 작성합니다:

[package]
name = "my-vais-app"
version = "0.1.0"
edition = "2024"

[dependencies]

[dev-dependencies]

소스 코드 구조

my-vais-app/
├── Vais.toml
├── src/
│   ├── lib.vais       # 라이브러리 코드
│   └── main.vais      # 메인 엔트리 포인트
└── bin/
    └── cli.vais       # 추가 바이너리 (선택 사항)

프로젝트 컴파일 및 실행

# 프로젝트 빌드
vaisc build

# 최적화 빌드
vaisc build --release

# 프로젝트 실행
vaisc run

# 테스트 실행
vaisc test

기본 문법 투어

변수 선언

# 불변 변수
x := 42
name := "Vais"

# 가변 변수 (mut 키워드)
counter := mut 0
counter = counter + 1

# 가변 변수 예제
total := mut 0
total = total + 5

# 타입 명시 (선택 사항)
age: i64 = 25
pi: f64 = 3.14159

함수 정의

# 간단한 함수
F add(a: i64, b: i64) -> i64 = a + b

# 함수 본문 포함
F greet(name: str) -> str {
    message := "Hello, ~{name}!"
    message
}

# 반환값 명시
F factorial(n: i64) -> i64 {
    I n <= 1 {
        R 1
    }
    R n * factorial(n - 1)
}

# 기본값 없는 반환 (0 반환)
F print_info(msg: str) {
    puts(msg)
}

조건문

x := 42

# if/else 기본
I x > 0 {
    puts("positive")
} E {
    puts("not positive")
}

# if/else if/else
I x > 100 {
    puts("greater than 100")
} E I x > 50 {
    puts("greater than 50")
} E {
    puts("50 or less")
}

# 삼항 연산자
result := x > 0 ? "positive" : "non-positive"

반복문

# for 루프 (범위)
F print_range() {
    L i:0..5 {
        puts("~{i}")
    }
}

# 무한 루프
F infinite_loop_example() {
    count := mut 0
    L {
        I count >= 10 {
            B
        }
        puts("~{count}")
        count = count + 1
    }
}

# while 루프 (조건 기반)
F while_example() {
    x := mut 0
    L x < 10 {
        puts("~{x}")
        x = x + 2
    }
}

구조체

# 구조체 정의
S Point {
    x: i64
    y: i64
}

S Person {
    name: str
    age: i64
    email: str
}

# 구조체 인스턴스 생성
p := Point { x: 10, y: 20 }

# 필드 접근
puts("~{p.x}, ~{p.y}")

# 구조체 메서드 (impl 블록)
X Point {
    F distance_from_origin(&self) -> f64 {
        a := self.x as f64
        b := self.y as f64
        sqrt(a * a + b * b)
    }
}

# 메서드 호출
dist := p.distance_from_origin()

Enum (열거형)

# 간단한 Enum
E Color {
    Red,
    Green,
    Blue
}

# 데이터를 포함한 Enum
E Result<T> {
    Ok(T),
    Err(str)
}

# Enum 사용
color := Color.Red

M color {
    Color.Red => puts("Red color"),
    Color.Green => puts("Green color"),
    Color.Blue => puts("Blue color")
}

패턴 매칭

status := 200

# 기본 match
M status {
    200 => puts("OK"),
    404 => puts("Not Found"),
    500 => puts("Server Error"),
    _ => puts("Unknown status")
}

# Enum과 함께 사용
E Response {
    Success(str),
    Failure(str)
}

response := Response.Success("Done")

M response {
    Response.Success(msg) => puts("Success: ~{msg}"),
    Response.Failure(err) => puts("Error: ~{err}")
}

제네릭

# 제네릭 함수
F max<T>(a: T, b: T) -> T {
    I a > b { R a } E { R b }
}

# 제네릭 구조체
S Container<T> {
    value: T
}

X Container<T> {
    F get_value(&self) -> T = self.value
}

# 제네릭 사용
container := Container<i64> { value: 42 }
val := container.get_value()

Trait (특성)

# Trait 정의
W Drawable {
    F draw(&self) -> i64
}

# 구조체 정의
S Circle {
    radius: i64
}

# Trait 구현
X Circle: Drawable {
    F draw(&self) -> i64 {
        puts("Drawing circle with radius ~{self.radius}")
        0
    }
}

# Trait 메서드 호출
circle := Circle { radius: 5 }
circle.draw()

실제 예제

간단한 계산기

S Calculator {
    result: i64
}

X Calculator {
    F add(&self, n: i64) -> i64 = self.result + n
    F subtract(&self, n: i64) -> i64 = self.result - n
    F multiply(&self, n: i64) -> i64 = self.result * n
}

F main() -> i64 {
    calc := mut Calculator { result: 0 }
    calc.result = calc.add(10)
    calc.result = calc.multiply(2)
    calc.result = calc.subtract(5)
    puts("Result: ~{calc.result}")
    0
}

문자열 처리

F count_chars(s: str) -> i64 {
    # 문자열 길이 계산
    len := mut 0
    # (실제로는 s.len() 메서드 사용)
    len
}

F main() -> i64 {
    greeting := "Hello, Vais!"
    puts(greeting)

    # 문자열 보간
    name := "World"
    message := "Hello, ~{name}!"
    puts(message)

    0
}

배열 처리

F sum_array(arr: [i64; 5]) -> i64 {
    result := mut 0
    L i:0..5 {
        result = result + arr[i]
    }
    result
}

F main() {
    numbers := [1, 2, 3, 4, 5]
    total := sum_array(numbers)
    println("Sum: ~{total}")
}

빌트인 함수

Vais 컴파일러가 제공하는 내장 함수입니다:

swap — 배열 요소 교환

swap(ptr, idx1, idx2) 빌트인으로 배열 요소를 교환할 수 있습니다:

F main() {
    arr: *i64 = [10, 20, 30]
    swap(arr, 0, 2)       # arr[0]과 arr[2] 교환
    # arr = [30, 20, 10]
    println("~{load_i64(arr + 0 * 8)}")  # 30
}

다음 단계

• 언어 레퍼런스: 완전한 언어 사양
• 표준 라이브러리: 내장 함수와 타입
• 에러 처리 가이드: 에러 처리 패턴
• 성능 튜닝 가이드: 최적화 기법
• 코딩 스타일 가이드: 커뮤니티 스타일 가이드

에디터 지원

Vais Editor Integration Guide

This document provides setup instructions for using Vais with various text editors and IDEs.

Overview

Vais provides editor support through:

• LSP Server (vais-lsp) - Language Server Protocol for IDE features
• Syntax Highlighting - TextMate grammar and editor-specific highlighting
• Extensions/Plugins - Editor-specific integration packages

Quick Start

Build the LSP Server

First, build the Vais LSP server:

cd /path/to/vais
cargo build --release --bin vais-lsp

# Add to PATH (optional)
export PATH="$PATH:$(pwd)/target/release"

Supported Editors

Visual Studio Code

VS Code has the most complete integration through the official extension.

Installation

1. From Marketplace (coming soon):

   ext install vais-vscode
   

2. Manual Installation:

   cd vscode-vais
   npm install
   npm run compile
   code --install-extension vais-vscode-0.2.0.vsix
   

Features

• Full syntax highlighting
• LSP integration (completion, hover, go-to-definition)
• Real-time diagnostics
• Semantic tokens
• Code actions and quick fixes
• Inlay hints
• Call hierarchy

Configuration

Open VS Code settings and configure:

{
  "vais.languageServer.path": "/path/to/vais-lsp",
  "vais.trace.server": "verbose"
}

Neovim

Neovim integration uses native Vim syntax and nvim-lspconfig.

Installation

Option 1: Automated Installation

cd editors/neovim
chmod +x install.sh
./install.sh

Option 2: Manual Installation

# Copy syntax files
mkdir -p ~/.config/nvim/syntax
mkdir -p ~/.config/nvim/ftdetect
mkdir -p ~/.config/nvim/ftplugin

cp editors/neovim/syntax/vais.vim ~/.config/nvim/syntax/
cp editors/neovim/ftdetect/vais.vim ~/.config/nvim/ftdetect/
cp editors/neovim/ftplugin/vais.vim ~/.config/nvim/ftplugin/

Option 3: Plugin Manager (lazy.nvim)

{
  dir = "/path/to/vais/editors/neovim",
  ft = "vais",
}

LSP Setup

Add to your Neovim config (init.lua):

-- Basic LSP setup
local lspconfig = require('lspconfig')

local configs = require('lspconfig.configs')
if not configs.vais_lsp then
  configs.vais_lsp = {
    default_config = {
      cmd = { 'vais-lsp' },
      filetypes = { 'vais' },
      root_dir = lspconfig.util.root_pattern('.git', 'Cargo.toml'),
      settings = {},
    },
  }
end

lspconfig.vais_lsp.setup({
  on_attach = function(client, bufnr)
    -- Key mappings
    local opts = { noremap = true, silent = true, buffer = bufnr }
    vim.keymap.set('n', 'gd', vim.lsp.buf.definition, opts)
    vim.keymap.set('n', 'K', vim.lsp.buf.hover, opts)
    vim.keymap.set('n', 'gr', vim.lsp.buf.references, opts)
    vim.keymap.set('n', '<leader>rn', vim.lsp.buf.rename, opts)
    vim.keymap.set('n', '<leader>ca', vim.lsp.buf.code_action, opts)
  end,
})

See editors/neovim/lsp.lua for complete configuration with all features.

Key Bindings (with LSP)

Helix

Helix provides built-in LSP support with minimal configuration.

Installation

# Copy language configuration
cp editors/helix/languages.toml ~/.config/helix/languages.toml

# Copy syntax queries (optional, for enhanced highlighting)
mkdir -p ~/.config/helix/runtime/queries/vais
cp editors/helix/queries/vais/highlights.scm ~/.config/helix/runtime/queries/vais/

Or merge with existing languages.toml:

[[language]]
name = "vais"
scope = "source.vais"
injection-regex = "vais"
file-types = ["vais"]
comment-tokens = "#"
indent = { tab-width = 4, unit = "    " }
language-servers = ["vais-lsp"]

[language-server.vais-lsp]
command = "vais-lsp"

Features

All features work automatically after setup:

• Syntax highlighting
• Auto-completion (Ctrl+Space)
• Hover documentation (Space+k)
• Go to definition (gd)
• Find references (gr)
• Rename (Space+r)
• Code actions (Space+a)

Key Bindings

Emacs

Emacs integration provides a full major mode with LSP support.

Installation

Option 1: use-package

(use-package vais-mode
  :load-path "/path/to/vais/editors/emacs"
  :mode "\\.vais\\'"
  :custom
  (vais-indent-offset 4))

(use-package vais-lsp
  :load-path "/path/to/vais/editors/emacs"
  :after (vais-mode lsp-mode)
  :hook (vais-mode . lsp-deferred)
  :custom
  (vais-lsp-server-path "/path/to/vais-lsp"))

Option 2: straight.el

(straight-use-package
 '(vais-mode :type git :local-repo "/path/to/vais/editors/emacs"))

Option 3: Manual

(add-to-list 'load-path "/path/to/vais/editors/emacs")
(require 'vais-mode)
(require 'vais-lsp)

LSP Setup

With lsp-mode:

(use-package lsp-mode
  :hook (vais-mode . lsp-deferred)
  :commands lsp)

;; vais-lsp.el automatically registers the server

With eglot (Emacs 29+):

(with-eval-after-load 'eglot
  (add-to-list 'eglot-server-programs
               '(vais-mode . ("vais-lsp"))))

(add-hook 'vais-mode-hook 'eglot-ensure)

Features

• Full syntax highlighting (font-lock)
• Smart indentation
• Comment handling (# single-line)
• Imenu integration (functions, structs, enums, traits)
• LSP features via lsp-mode or eglot

Key Bindings

LSP Features Reference

The Vais LSP server (vais-lsp) provides these capabilities:

Code Actions

Available quick fixes:

1. Create variable - For undefined variables
2. Import module - Auto-import standard library
3. Type cast - Fix type mismatches
4. Extract variable - Extract expression to variable
5. Extract function - Extract selection to function

Troubleshooting

LSP Server Not Starting

1. Check if server is built:

   ls -la target/release/vais-lsp
   

2. Check if server is in PATH:

   which vais-lsp
   

3. Run server manually to check for errors:

   vais-lsp 2>&1 | head -20
   

Syntax Highlighting Not Working

1. Verify file extension: Must be .vais
2. Check filetype detection:
   • Neovim: :set ft? should show vais
   • Emacs: M-x describe-mode should show Vais
3. Reload syntax files after installation

Completion Not Triggering

1. Verify LSP is connected:
   • Neovim: :LspInfo
   • VS Code: Check status bar
   • Emacs: M-x lsp-describe-session
2. Check trigger characters: . and : trigger completion
3. Manual trigger: Use Ctrl+Space or your editor's completion key

Performance Issues

1. Large files: LSP may be slow on files >10,000 lines
2. Enable incremental sync if available
3. Check for excessive logging: Disable trace/verbose modes

Debug Adapter Protocol (DAP)

Vais includes a Debug Adapter Protocol server (vais-dap) for IDE-level debugging support.

Building the DAP Server

cargo build --release --bin vais-dap

# Add to PATH (optional)
export PATH="$PATH:$(pwd)/target/release"

Features

• Source-level debugging with breakpoints
• Step over, step into, step out
• Local variables and arguments inspection
• Register inspection
• Memory read/write
• Disassembly view
• Conditional breakpoints
• Function breakpoints
• Exception breakpoints (panic)
• Expression evaluation

VS Code Debugging

1. Install the Vais extension
2. Create a launch configuration in .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "vais",
      "request": "launch",
      "name": "Debug Vais Program",
      "program": "${workspaceFolder}/main.vais",
      "stopOnEntry": true,
      "autoCompile": true,
      "optLevel": 0
    }
  ]
}

3. Set breakpoints by clicking in the gutter
4. Press F5 to start debugging

Neovim Debugging

With nvim-dap:

local dap = require('dap')

dap.adapters.vais = {
  type = 'executable',
  command = 'vais-dap',
}

dap.configurations.vais = {
  {
    type = 'vais',
    request = 'launch',
    name = 'Debug Vais Program',
    program = '${file}',
    stopOnEntry = true,
    autoCompile = true,
  }
}

Emacs Debugging

With dap-mode:

(require 'dap-mode)

(dap-register-debug-template
 "Vais Debug"
 (list :type "vais"
       :request "launch"
       :name "Debug Vais"
       :program nil  ; Will prompt for file
       :stopOnEntry t
       :autoCompile t))

;; Or use dap-debug directly
(defun vais-debug ()
  "Debug current Vais file."
  (interactive)
  (dap-debug
   (list :type "vais"
         :request "launch"
         :name "Debug"
         :program (buffer-file-name)
         :stopOnEntry t
         :autoCompile t)))

CLI Usage

# Start DAP server (stdio mode, for IDE integration)
vais-dap

# Start DAP server on TCP port (for remote debugging)
vais-dap --port 4711

# With verbose logging
vais-dap --log-level debug

Compile with Debug Info

To enable source-level debugging, compile with the -g flag:

vaisc build main.vais -g -O0

Contributing

Found an issue or want to add support for another editor?

1. Open an issue at https://github.com/vais-lang/vais/issues
2. PRs welcome for new editor integrations
3. Follow existing patterns in editors/ directory

See Also

• Language Specification
• Standard Library Reference
• Tutorial

Learning Path

Vais를 체계적으로 배울 수 있는 3단계 학습 경로입니다. 프로그래밍 경험에 따라 적절한 단계부터 시작하세요.

사전 준비

시작하기 전에 Vais를 설치하세요:

# Homebrew (추천)
brew tap vaislang/tap && brew install vais

# 또는 소스에서 빌드
git clone https://github.com/vaislang/vais.git
cd vais && cargo build --release

에디터 설정: VSCode 확장 또는 IntelliJ 플러그인을 설치하면 구문 강조와 자동 완성을 사용할 수 있습니다.

Stage 1: 초급 (2시간)

대상: 프로그래밍 경험이 있지만 Vais는 처음인 개발자

1.1 Hello World (15분)

읽기: Getting Started - 설치부터 첫 프로그램까지

F main() {
    println("Hello, Vais!")
}

실습: hello.vais 파일을 만들고 vaisc run hello.vais로 실행

확인:

• vaisc --version으로 설치 확인
• Hello World 컴파일 및 실행 성공
• REPL (vaisc repl) 사용해보기

1.2 변수와 타입 (20분)

읽기: Getting Started - 변수 선언

Vais의 핵심 문법을 익히세요:

# 불변 변수
x := 42
name := "Vais"

# 가변 변수
counter := mut 0
counter = counter + 1

# 타입 명시 (선택)
pi: f64 = 3.14159

실습: 다양한 타입의 변수를 선언하고 출력하는 프로그램 작성

참고 예제: examples/hello.vais

1.3 함수 (20분)

읽기: Getting Started - 함수 정의

# 단일 표현식 함수
F add(a: i64, b: i64) -> i64 = a + b

# 복수 줄 함수
F factorial(n: i64) -> i64 {
    I n <= 1 { R 1 }
    R n * factorial(n - 1)
}

# 자재귀 연산자 @
F fib(n: i64) -> i64 = n < 2 ? n : @(n-1) + @(n-2)

실습: @ 연산자를 사용하는 재귀 함수 작성 (피보나치, 팩토리얼)

참고 예제: examples/fib.vais

1.4 제어 흐름 (20분)

읽기: Getting Started - 조건문/반복문

# if/else (I/E)
I x > 0 { println("positive") }
E { println("non-positive") }

# 삼항 연산자
result := x > 0 ? "yes" : "no"

# 범위 루프
L i:0..10 { println("~{i}") }

# 조건 루프
L x < 100 { x = x * 2 }

# 패턴 매칭
M status {
    200 => println("OK"),
    404 => println("Not Found"),
    _ => println("Unknown")
}

실습: FizzBuzz를 Vais로 작성 (L, I, E, M 사용)

참고 예제: examples/control_flow.vais, examples/match_test.vais

1.5 구조체와 메서드 (25분)

읽기: Getting Started - 구조체

S Point {
    x: i64
    y: i64
}

X Point {
    F sum(&self) -> i64 = self.x + self.y
}

F main() {
    p := Point { x: 10, y: 20 }
    println("~{p.sum()}")
}

실습: Rectangle 구조체를 정의하고 area(), perimeter() 메서드 구현

참고 예제: examples/method_test.vais

1.6 Enum과 패턴 매칭 (20분)

읽기: Getting Started - Enum

E Shape {
    Circle(i64),
    Rectangle(i64, i64)
}

F area(s: Shape) -> i64 {
    M s {
        Shape.Circle(r) => r * r * 3,
        Shape.Rectangle(w, h) => w * h
    }
}

실습: 간단한 계산기 Enum (Add, Sub, Mul, Div) + 패턴 매칭 구현

참고 예제: examples/enum_test.vais

Stage 1 체크리스트

• := / mut 변수 선언 이해
• F 함수, @ 자재귀 사용
• I/E 조건문, L 루프, M 매칭 사용
• S 구조체, X impl 블록, E enum 정의
• ~{expr} 문자열 보간 사용
• 간단한 프로그램을 독립적으로 작성 가능

Stage 2: 중급 (4시간)

대상: Stage 1을 완료했거나 Rust/C 경험이 있는 개발자

2.1 제네릭 (30분)

읽기: Generics

F max<T>(a: T, b: T) -> T {
    I a > b { R a } E { R b }
}

S Container<T> {
    value: T
}

X Container<T> {
    F get(&self) -> T = self.value
}

실습: 제네릭 Stack<T> 구현 (push, pop, peek)

참고 예제: examples/generic_test.vais, examples/generic_struct_test.vais

2.2 Trait와 다형성 (40분)

읽기: Advanced Types

W Printable {
    F to_string(&self) -> str
}

S Dog { name: str }

X Dog: Printable {
    F to_string(&self) -> str = self.name
}

# Trait 바운드
F print_item<T: Printable>(item: T) {
    println(item.to_string())
}

실습: Serializable trait 정의 + 2개 이상의 구조체에 구현

참고 예제: examples/trait_test.vais, examples/trait_advanced_test.vais

2.3 에러 처리 (30분)

읽기: Error Handling

# Option
F find(arr: *i64, len: i64, target: i64) -> i64 {
    L i:0..len {
        I arr[i] == target { R i }
    }
    R -1
}

# Result와 ? 연산자
F divide(a: i64, b: i64) -> i64 {
    I b == 0 { R -1 }
    R a / b
}

실습: 파일 읽기 + 파싱 + 결과 출력 함수 체인 작성

참고 예제: examples/option_result_test.vais, examples/result_test.vais

2.4 클로저와 파이프 연산자 (30분)

읽기: Closures & Lambda

# 클로저
double := |x| x * 2

# 파이프 연산자
result := 5 |> double |> |x| x + 1
# result = 11

실습: 파이프 연산자로 데이터 변환 파이프라인 작성

참고 예제: examples/lambda_test.vais, examples/pipe_operator.vais

2.5 표준 라이브러리 활용 (40분)

읽기: Standard Library Reference

핵심 모듈:

실습: JSON 파일을 읽고 특정 필드를 추출하는 프로그램 작성

2.6 실전 프로젝트: CLI 도구 (30분)

읽기: Tutorial: CLI Tool 만들기, Tutorial: CLI Framework 만들기

실습: 간단한 텍스트 처리 CLI 도구를 처음부터 작성. 서브커맨드 디스패치와 옵션 파싱도 시도해보세요.

참고 예제: examples/tutorial_cli_framework.vais

2.7 Defer와 리소스 관리 (20분)

읽기: Defer Statement

F process_file(path: str) -> i64 {
    fd := open(path, 0)
    D close(fd)    # 함수 종료 시 자동 실행
    # fd를 사용한 처리...
    0
}

실습: 파일 열기/닫기에 defer 패턴 적용

참고 예제: examples/defer_test.vais

Stage 2 체크리스트

• 제네릭 함수와 구조체 작성 가능
• Trait 정의, 구현, 바운드 사용
• 에러 처리 패턴 (Option, Result, ?) 적용
• 클로저와 파이프 연산자 활용
• 표준 라이브러리 주요 모듈 사용
• Defer로 리소스 관리
• 100줄 이상의 프로그램 독립 작성 가능

Stage 3: 고급 (4시간)

대상: Stage 2를 완료했거나 시스템 프로그래밍/타입 시스템에 익숙한 개발자

3.1 매크로 시스템 (30분)

읽기: Macro System

macro debug! {
    ($expr) => {
        println("DEBUG: ~{$expr}")
    }
}

실습: assert! 매크로 + 사용자 정의 매크로 작성

참고 예제: examples/macro_test.vais

3.2 비동기 프로그래밍 (40분)

읽기: Async Programming

A F fetch_data(url: str) -> str {
    response := Y http_get(url)
    R response
}

F main() {
    data := spawn fetch_data("http://example.com")
    # ...다른 작업...
    result := Y data
}

실습: 비동기 HTTP 클라이언트 작성

참고 예제: examples/async_test.vais

3.3 FFI와 C 상호운용 (40분)

읽기: FFI Guide

N "C" {
    F printf(fmt: str, ...) -> i32
    F strlen(s: str) -> i64
}

F main() {
    len := strlen("hello")
    printf("Length: %lld\n", len)
}

실습: C 라이브러리 바인딩 작성 (예: SQLite 기본 연동)

참고 예제: examples/ffi_test.vais

3.4 WASM 컴파일 (30분)

읽기: WASM Getting Started

vaisc --target wasm32-unknown-unknown calculator.vais

#[wasm_export("add")]
F add(a: i32, b: i32) -> i32 = a + b

실습: 간단한 계산기를 WASM으로 컴파일하고 브라우저에서 실행

참고 예제: examples/wasm_calculator.vais

3.5 타입 시스템 심화 (40분)

읽기: Advanced Types, Type Inference

고급 타입 기능:

• Where 절: F foo<T>(x: T) -> T where T: Printable
• Trait 별칭: T Numeric = Add + Sub + Mul
• 연관 타입: W Container { T Item; F get(&self) -> Self.Item }

실습: where 절과 trait 별칭을 사용하는 제네릭 컬렉션 라이브러리 작성

3.6 성능 최적화 (20분)

읽기: Performance Guide

최적화 기법:

• comptime 컴파일 타임 평가
• inline 힌트
• 배열 대신 포인터 직접 조작
• SIMD 벡터 연산

참고 예제: examples/bench_fibonacci.vais, examples/simd_test.vais

3.7 실전 프로젝트: WebSocket 서버 (40분)

읽기: Tutorial: WebSocket Chat Server

실습: WebSocket 에코 서버를 만들고 handshake, frame encoding, 메시지 루프를 구현

참고 예제: examples/tutorial_ws_chat.vais, examples/websocket_example.vais

3.8 실전 프로젝트: JSON Parser (30분)

읽기: Tutorial: JSON Parser 만들기

실습: 재귀 하강 파서로 JSON 문자열을 파싱하는 프로그램 작성

참고 예제: examples/tutorial_json_parser.vais

3.9 실전 프로젝트: REST API 서버 (40분)

읽기: Tutorial: HTTP Server 만들기

실습: HTTP 서버 + JSON API + 데이터 저장 프로젝트 작성

Stage 3 체크리스트

• 선언적 매크로 작성 가능
• async/await + spawn 사용
• C FFI 바인딩 작성
• WASM 타겟 컴파일 및 실행
• 고급 타입 시스템 (where, trait alias, associated types) 활용
• 성능 최적화 기법 적용
• WebSocket 서버 또는 JSON 파서 구현 완료
• 500줄 이상의 실전 프로젝트 독립 완성 가능

대상별 학습 트랙

Systems Programmer (C/C++/Rust 경험자)

추천 예제: bench_sorting.vais, ffi_test.vais, simd_test.vais

Web Developer (WASM 관심)

추천 예제: wasm_calculator.vais, wasm_todo_app.vais, js_target.vais

AI/ML Developer (GPU 활용)

추천 예제: gpu_vector_add.vais, simd_test.vais, simd_distance.vais

추가 자료

• 언어 레퍼런스 - 완전한 문법 스펙
• 표준 라이브러리 - 74개 모듈 레퍼런스
• API 문서 - 타입별 API 레퍼런스
• 트러블슈팅 - 자주 묻는 질문과 해결 방법
• 기여 가이드 - 컴파일러 개발에 참여하기
• Playground - 브라우저에서 Vais 실행 (40+ 예제)
• 인터랙티브 튜토리얼 - 단계별 연습 문제

실전 튜토리얼

Tutorial: CLI Tool 만들기

이 튜토리얼에서는 Vais로 텍스트 파일의 줄 수, 단어 수, 바이트 수를 세는 CLI 도구 vwc (Vais Word Count)를 만듭니다. Unix의 wc 명령어의 간단한 버전입니다.

최종 결과

$ vaisc run examples/tutorial_wc.vais
=== Vais Word Count (vwc) ===
Lines: 15
Words: 42
Bytes: 256

사전 준비

• Vais 설치 완료 (vaisc --version으로 확인)
• 텍스트 에디터 (VSCode + Vais 확장 추천)

Step 1: 프로젝트 뼈대 (5분)

tutorial_wc.vais 파일을 만들고 기본 구조를 작성합니다:

# vwc — Vais Word Count
# 텍스트 파일의 줄/단어/바이트를 센다

F main() -> i64 {
    puts("=== Vais Word Count (vwc) ===")
    0
}

컴파일 및 실행:

vaisc run tutorial_wc.vais

핵심 개념: Vais에서 F는 함수 선언 키워드입니다. main() 함수는 프로그램 진입점이며, 반환 타입을 생략하면 암시적으로 i64를 반환합니다.

Step 2: 결과를 담을 구조체 (10분)

카운트 결과를 저장할 구조체를 정의합니다:

# 카운트 결과를 저장하는 구조체
S WcResult {
    lines: i64
    words: i64
    bytes: i64
}

# 메서드 정의
X WcResult {
    F new() -> WcResult {
        R WcResult { lines: 0, words: 0, bytes: 0 }
    }

    F print(&self) {
        puts("Lines: ~{self.lines}")
        puts("Words: ~{self.words}")
        puts("Bytes: ~{self.bytes}")
    }
}

핵심 개념:

• S는 구조체(struct) 선언 키워드
• X는 impl 블록 (메서드 정의)
• &self는 해당 구조체의 불변 참조
• ~{expr}는 문자열 보간 (string interpolation)
• R은 return 키워드

Step 3: 바이트 카운팅 함수 (10분)

입력 텍스트의 바이트 수를 세는 함수를 작성합니다:

N "C" {
    F strlen(s: str) -> i64
}

F count_bytes(text: str) -> i64 {
    R strlen(text)
}

핵심 개념:

• N "C"는 extern 블록으로, C 표준 라이브러리 함수를 호출합니다
• Vais는 LLVM 백엔드를 사용하므로 C 함수를 직접 호출할 수 있습니다

Step 4: 줄 수 세기 (10분)

문자열을 순회하며 줄바꿈 문자(\n, ASCII 10)를 세는 함수입니다:

F count_lines(text: str, len: i64) -> i64 {
    count := mut 0
    L i:0..len {
        byte := load_byte(text, i)
        I byte == 10 {
            count = count + 1
        }
    }
    # 마지막 줄이 줄바꿈으로 끝나지 않는 경우
    I len > 0 {
        last := load_byte(text, len - 1)
        I last != 10 {
            count = count + 1
        }
    }
    count
}

핵심 개념:

• L i:0..len은 범위 루프 (0부터 len-1까지)
• load_byte(ptr, offset)는 메모리에서 바이트를 읽는 빌트인 함수
• I는 if, 10은 줄바꿈 문자의 ASCII 코드
• mut는 가변 변수 선언

Step 5: 단어 수 세기 (15분)

공백, 탭, 줄바꿈을 구분자로 사용하여 단어를 셉니다:

F is_whitespace(b: i64) -> i64 {
    # 공백(32), 탭(9), 줄바꿈(10), 캐리지 리턴(13)
    I b == 32 { R 1 }
    I b == 9 { R 1 }
    I b == 10 { R 1 }
    I b == 13 { R 1 }
    0
}

F count_words(text: str, len: i64) -> i64 {
    count := mut 0
    in_word := mut 0

    L i:0..len {
        byte := load_byte(text, i)
        I is_whitespace(byte) == 1 {
            I in_word == 1 {
                count = count + 1
                in_word = 0
            }
        } E {
            in_word = 1
        }
    }

    # 마지막 단어 처리
    I in_word == 1 {
        count = count + 1
    }

    count
}

핵심 개념:

• E는 else 키워드
• 상태 머신 패턴: in_word 플래그로 단어 경계를 추적
• Vais의 bool은 0/1 정수로 처리됩니다 (i64 기반)

Step 6: 전체 조합 (10분)

모든 함수를 조합하여 완성합니다:

F analyze(text: str) -> WcResult {
    len := strlen(text)
    R WcResult {
        lines: count_lines(text, len),
        words: count_words(text, len),
        bytes: len
    }
}

F main() -> i64 {
    puts("=== Vais Word Count (vwc) ===")

    # 테스트 텍스트
    text := "Hello Vais World\nThis is line two\nAnd line three\n"
    result := analyze(text)
    result.print()

    0
}

Step 7: 복수 텍스트 처리 (10분)

여러 텍스트를 처리하고 합계를 구하는 기능을 추가합니다:

F add_results(a: WcResult, b: WcResult) -> WcResult {
    R WcResult {
        lines: a.lines + b.lines,
        words: a.words + b.words,
        bytes: a.bytes + b.bytes
    }
}

F main() -> i64 {
    puts("=== Vais Word Count (vwc) ===")

    text1 := "Hello Vais World\nThis is a test\n"
    text2 := "Another paragraph\nWith more words here\n"

    r1 := analyze(text1)
    r2 := analyze(text2)
    total := add_results(r1, r2)

    puts("\n--- File 1 ---")
    r1.print()

    puts("\n--- File 2 ---")
    r2.print()

    puts("\n--- Total ---")
    total.print()

    0
}

전체 코드

examples/tutorial_wc.vais에서 전체 코드를 확인할 수 있습니다.

vaisc run examples/tutorial_wc.vais

확장 아이디어

이 프로젝트를 더 발전시킬 수 있는 아이디어:

1. 파일 읽기: std/io.vais의 read_file() 함수로 실제 파일 처리
2. 명령행 인수: std/args.vais로 파일 경로를 인수로 받기
3. 포맷 출력: 칼럼 정렬로 wc와 유사한 출력 형식
4. 성능 측정: std/time.vais로 처리 시간 측정

배운 것 요약

다음 튜토리얼: HTTP Server 만들기

Tutorial: HTTP Server 만들기

이 튜토리얼에서는 Vais의 표준 라이브러리를 사용하여 간단한 REST API 서버를 만듭니다. JSON 요청/응답 처리와 간단한 메모리 내 데이터 저장을 구현합니다.

최종 결과

$ vaisc run examples/tutorial_http_server.vais
Server listening on port 8080
# 다른 터미널에서:
$ curl http://localhost:8080/api/hello
{"message":"Hello from Vais!"}

사전 준비

• Vais 설치 완료
• CLI Tool 튜토리얼 완료 권장
• curl 또는 브라우저 (API 테스트용)

Step 1: TCP 서버 기반 (10분)

HTTP 서버는 TCP 소켓 위에 동작합니다. Vais에서는 C 런타임 함수를 통해 네트워킹을 지원합니다:

# 외부 함수 선언
N "C" {
    F __tcp_listen(port: i64) -> i64
    F __tcp_accept(listener_fd: i64) -> i64
    F __tcp_send(fd: i64, data: i64, len: i64) -> i64
    F __tcp_recv(fd: i64, buffer: i64, len: i64) -> i64
    F __tcp_close(fd: i64) -> i64
    F strlen(s: str) -> i64
    F malloc(size: i64) -> i64
    F free(ptr: i64) -> i64
}

핵심 개념:

• N "C"는 C FFI 블록입니다
• TCP 함수들은 파일 디스크립터(fd) 기반으로 동작합니다
• __tcp_listen은 포트를 열고, __tcp_accept는 연결을 수락합니다

Step 2: HTTP 요청 파싱 (15분)

HTTP 요청의 첫 줄에서 메서드와 경로를 추출합니다:

# HTTP 요청 정보
S HttpRequest {
    method: i64    # 0=GET, 1=POST, 2=PUT, 3=DELETE
    path_start: i64
    path_len: i64
    buffer: i64
}

F parse_request(buf: i64, len: i64) -> HttpRequest {
    # 메서드 판별 (첫 바이트)
    first := load_byte(buf, 0)
    method := mut 0
    I first == 71 { method = 0 }   # G -> GET
    I first == 80 { method = 1 }   # P -> POST

    # 경로 시작점 찾기 (첫 번째 공백 이후)
    path_s := mut 0
    L i:0..len {
        I load_byte(buf, i) == 32 {
            path_s = i + 1
            B
        }
    }

    # 경로 끝점 찾기 (두 번째 공백)
    path_e := mut path_s
    L i:path_s..len {
        I load_byte(buf, i) == 32 {
            path_e = i
            B
        }
    }

    R HttpRequest {
        method: method,
        path_start: path_s,
        path_len: path_e - path_s,
        buffer: buf
    }
}

핵심 개념:

• B는 break (루프 탈출)
• 32는 공백 문자의 ASCII 코드
• HTTP 요청 형식: GET /path HTTP/1.1\r\n...
• 구조체 필드에 i64를 사용하는 이유: Vais의 기본 정수 타입

Step 3: HTTP 응답 생성 (10분)

HTTP 응답을 구성하는 헬퍼 함수를 만듭니다:

F send_response(fd: i64, status: i64, body: str) {
    # 응답 헤더 구성
    header := mut "HTTP/1.1 200 OK\r\nContent-Type: application/json\r\n\r\n"
    I status == 404 {
        header = "HTTP/1.1 404 Not Found\r\nContent-Type: application/json\r\n\r\n"
    }

    # 헤더 전송
    hdr_len := strlen(header)
    __tcp_send(fd, header, hdr_len)

    # 본문 전송
    body_len := strlen(body)
    __tcp_send(fd, body, body_len)
}

핵심 개념:

• HTTP 응답은 상태 줄 + 헤더 + 빈 줄 + 본문으로 구성
• \r\n은 HTTP 줄바꿈 (CRLF)
• Content-Type: application/json으로 JSON 응답 명시

Step 4: 라우터 구현 (15분)

경로에 따라 다른 핸들러를 실행하는 라우터를 만듭니다:

F path_equals(buf: i64, start: i64, len: i64, target: str) -> i64 {
    target_len := strlen(target)
    I len != target_len { R 0 }

    L i:0..len {
        I load_byte(buf, start + i) != load_byte(target, i) {
            R 0
        }
    }
    R 1
}

F handle_request(fd: i64, req: HttpRequest) {
    # 라우트 매칭
    I path_equals(req.buffer, req.path_start, req.path_len, "/") == 1 {
        send_response(fd, 200, "{\"service\":\"Vais API\",\"version\":\"1.0\"}")
        R 0
    }

    I path_equals(req.buffer, req.path_start, req.path_len, "/api/hello") == 1 {
        send_response(fd, 200, "{\"message\":\"Hello from Vais!\"}")
        R 0
    }

    I path_equals(req.buffer, req.path_start, req.path_len, "/health") == 1 {
        send_response(fd, 200, "{\"status\":\"ok\"}")
        R 0
    }

    # 404 Not Found
    send_response(fd, 404, "{\"error\":\"Not Found\"}")
}

핵심 개념:

• 바이트 단위 문자열 비교 (길이 비교 + 바이트별 비교)
• 라우팅은 경로 매칭의 연속입니다
• R 0으로 함수 조기 반환 (early return)

Step 5: 서버 메인 루프 (10분)

요청을 수신하고 처리하는 메인 루프를 작성합니다:

F main() -> i64 {
    port := 8080
    puts("Starting Vais HTTP Server on port ~{port}...")

    listener := __tcp_listen(port)
    I listener < 0 {
        puts("ERROR: Failed to listen on port ~{port}")
        R 1
    }

    puts("Server listening on port ~{port}")
    puts("Try: curl http://localhost:~{port}/api/hello")

    # 요청 수신 버퍼
    buf := malloc(4096)

    # 서버 루프 (데모: 10개 요청 처리 후 종료)
    L i:0..10 {
        client := __tcp_accept(listener)
        I client < 0 { C }   # 에러 시 스킵

        # 요청 읽기
        n := __tcp_recv(client, buf, 4095)
        I n > 0 {
            store_byte(buf, n, 0)   # null-terminate
            req := parse_request(buf, n)
            handle_request(client, req)
        }

        __tcp_close(client)
    }

    free(buf)
    __tcp_close(listener)
    puts("Server shut down.")
    0
}

핵심 개념:

• C는 continue (현재 반복 스킵)
• malloc/free로 버퍼 메모리 관리
• store_byte로 null-terminator 추가
• 데모용으로 10개 요청 후 종료 (실제 서버는 무한 루프 사용)

Step 6: JSON 응답 빌더 (15분)

동적 JSON 응답을 생성하는 헬퍼를 추가합니다:

# 간단한 JSON key:value 응답 생성
F json_kv(key: str, value: str) -> i64 {
    buf := malloc(512)
    pos := mut 0

    # {"key":"value"}
    store_byte(buf, pos, 123)   # {
    pos = pos + 1
    store_byte(buf, pos, 34)    # "
    pos = pos + 1

    # key 복사
    key_len := strlen(key)
    L i:0..key_len {
        store_byte(buf, pos, load_byte(key, i))
        pos = pos + 1
    }

    store_byte(buf, pos, 34)    # "
    pos = pos + 1
    store_byte(buf, pos, 58)    # :
    pos = pos + 1
    store_byte(buf, pos, 34)    # "
    pos = pos + 1

    # value 복사
    val_len := strlen(value)
    L i:0..val_len {
        store_byte(buf, pos, load_byte(value, i))
        pos = pos + 1
    }

    store_byte(buf, pos, 34)    # "
    pos = pos + 1
    store_byte(buf, pos, 125)   # }
    pos = pos + 1
    store_byte(buf, pos, 0)     # null

    buf
}

핵심 개념:

• 바이트 단위로 JSON 문자열을 수동 조립합니다
• ASCII 코드: {=123, }=125, "=34, :=58
• 반환된 포인터는 호출자가 free()해야 합니다

Step 7: 카운터 엔드포인트 (10분)

요청 횟수를 추적하는 상태 관리 기능을 추가합니다:

# 전역 카운터
G request_count := 0

F handle_request_with_counter(fd: i64, req: HttpRequest) {
    request_count = request_count + 1

    I path_equals(req.buffer, req.path_start, req.path_len, "/stats") == 1 {
        puts("Request #~{request_count}: /stats")
        # 응답 생성
        body := json_kv("requests", "~{request_count}")
        send_response(fd, 200, body)
        free(body)
        R 0
    }

    # 기존 라우트...
    handle_request(fd, req)
}

핵심 개념:

• G는 전역 변수 선언 키워드
• 전역 변수로 요청 간 상태를 유지합니다
• 참고: 실전에서는 구조체 기반 상태 관리를 권장합니다

전체 코드

examples/tutorial_http_server.vais에서 전체 코드를 확인할 수 있습니다.

API 테스트

# 서버 실행
vaisc run examples/tutorial_http_server.vais

# 다른 터미널에서 테스트
curl http://localhost:8080/
curl http://localhost:8080/api/hello
curl http://localhost:8080/health
curl http://localhost:8080/stats
curl http://localhost:8080/unknown    # 404

확장 아이디어

1. 요청 본문 파싱: POST 요청의 JSON 본문을 파싱하여 데이터 저장
2. 라우트 패턴: /users/:id 같은 동적 경로 파라미터
3. CORS 헤더: 브라우저 호환을 위한 Access-Control 헤더 추가
4. 파일 서빙: 정적 파일을 HTTP로 서빙
5. 로깅: 요청/응답 로그를 파일에 기록

배운 것 요약

이전 튜토리얼: CLI Tool 만들기 다음 튜토리얼: Data Pipeline 만들기

Tutorial: Data Pipeline 만들기

이 튜토리얼에서는 Vais로 데이터를 읽고, 변환하고, 출력하는 파이프라인을 만듭니다. CSV 형식의 데이터를 파싱하여 통계를 계산하고, 결과를 출력하는 프로그램입니다.

최종 결과

$ vaisc run examples/tutorial_pipeline.vais
=== Data Pipeline ===
Records: 5
Total score: 435
Average: 87
Max: 98
Min: 72

사전 준비

• Vais 설치 완료
• CLI Tool 튜토리얼 완료 권장

Step 1: 데이터 모델 (10분)

파이프라인에서 처리할 데이터 구조를 정의합니다:

# 학생 성적 레코드
S Record {
    id: i64
    score: i64
}

# 통계 결과
S Stats {
    count: i64
    total: i64
    max_val: i64
    min_val: i64
}

X Stats {
    F average(&self) -> i64 {
        I self.count == 0 { R 0 }
        R self.total / self.count
    }

    F print(&self) {
        puts("Records: ~{self.count}")
        puts("Total score: ~{self.total}")
        puts("Average: ~{self.average()}")
        puts("Max: ~{self.max_val}")
        puts("Min: ~{self.min_val}")
    }
}

핵심 개념:

• S로 데이터 모델 정의
• X로 메서드 추가 (self를 통한 필드 접근)
• I/R로 0 나눗셈 방어

Step 2: 데이터 소스 (10분)

메모리 내 배열로 데이터를 구성합니다. 실전에서는 파일이나 네트워크에서 읽어옵니다:

N "C" {
    F malloc(size: i64) -> i64
    F free(ptr: i64) -> i64
    F strlen(s: str) -> i64
}

# 고정 배열로 데이터 생성
F create_dataset(buf: i64) -> i64 {
    # 5개 레코드: id, score 쌍
    # Record 0: id=1, score=85
    store_i64(buf, 0, 1)
    store_i64(buf, 8, 85)
    # Record 1: id=2, score=92
    store_i64(buf, 16, 2)
    store_i64(buf, 24, 92)
    # Record 2: id=3, score=78
    store_i64(buf, 32, 3)
    store_i64(buf, 40, 78)
    # Record 3: id=4, score=98
    store_i64(buf, 48, 4)
    store_i64(buf, 56, 98)
    # Record 4: id=5, score=72
    store_i64(buf, 64, 5)
    store_i64(buf, 72, 72)

    R 5   # 레코드 수 반환
}

F store_i64(buf: i64, offset: i64, value: i64) {
    # 8바이트 정수 저장 (little-endian)
    L i:0..8 {
        byte := (value >> (i * 8)) & 255
        store_byte(buf + offset, i, byte)
    }
}

F load_i64_at(buf: i64, offset: i64) -> i64 {
    result := mut 0
    L i:0..8 {
        byte := load_byte(buf + offset, i)
        result = result | (byte << (i * 8))
    }
    result
}

핵심 개념:

• 바이트 레벨 메모리 조작으로 데이터 저장/로드
• store_byte/load_byte는 빌트인 함수
• 비트 연산 (>>, <<, &, |)으로 바이트 추출/조합

Step 3: 변환 단계 (Transform) (15분)

데이터를 읽고 변환하는 파이프라인 단계를 구현합니다:

# 레코드 하나 읽기
F read_record(buf: i64, index: i64) -> Record {
    offset := index * 16   # 각 레코드 16바이트 (id 8 + score 8)
    R Record {
        id: load_i64_at(buf, offset),
        score: load_i64_at(buf, offset + 8)
    }
}

# 점수 보정: 커브 적용 (10% 보너스, 최대 100)
F apply_curve(score: i64) -> i64 {
    curved := score + score / 10
    I curved > 100 { R 100 }
    curved
}

# 필터: 최소 점수 이상만 통과
F passes_filter(score: i64, min_score: i64) -> i64 {
    I score >= min_score { R 1 }
    0
}

핵심 개념:

• 순수 함수로 각 변환 단계를 구현
• 구조체를 값으로 반환
• 조건부 반환으로 범위 제한

Step 4: 집계 단계 (Aggregate) (15분)

전체 데이터를 순회하며 통계를 계산합니다:

F compute_stats(buf: i64, count: i64) -> Stats {
    total := mut 0
    max_v := mut 0
    min_v := mut 999999

    L i:0..count {
        rec := read_record(buf, i)
        score := apply_curve(rec.score)

        total = total + score

        I score > max_v {
            max_v = score
        }
        I score < min_v {
            min_v = score
        }
    }

    R Stats {
        count: count,
        total: total,
        max_val: max_v,
        min_val: min_v
    }
}

핵심 개념:

• 루프 내에서 min/max 추적 패턴
• mut 변수로 누적 계산
• 파이프라인 단계: read -> transform (curve) -> aggregate

Step 5: 필터링 파이프라인 (15분)

조건에 맞는 레코드만 처리하는 필터를 추가합니다:

F compute_filtered_stats(buf: i64, count: i64, min_score: i64) -> Stats {
    total := mut 0
    max_v := mut 0
    min_v := mut 999999
    passed := mut 0

    L i:0..count {
        rec := read_record(buf, i)
        score := apply_curve(rec.score)

        I passes_filter(score, min_score) == 1 {
            total = total + score
            passed = passed + 1

            I score > max_v { max_v = score }
            I score < min_v { min_v = score }
        }
    }

    I passed == 0 {
        min_v = 0
    }

    R Stats {
        count: passed,
        total: total,
        max_val: max_v,
        min_val: min_v
    }
}

핵심 개념:

• 필터와 변환을 조합하는 패턴
• 빈 결과 처리 (passed == 0일 때 min 초기화)

Step 6: 전체 파이프라인 조합 (10분)

F main() -> i64 {
    puts("=== Data Pipeline ===")

    # 1. 데이터 생성
    buf := malloc(256)
    count := create_dataset(buf)

    # 2. 전체 통계
    puts("\n--- All Records (with curve) ---")
    all_stats := compute_stats(buf, count)
    all_stats.print()

    # 3. 필터링 통계 (85점 이상)
    puts("\n--- Filtered (min 85, with curve) ---")
    filtered := compute_filtered_stats(buf, count, 85)
    filtered.print()

    # 4. 원본 데이터 출력
    puts("\n--- Raw Data ---")
    L i:0..count {
        rec := read_record(buf, i)
        curved := apply_curve(rec.score)
        puts("  ID ~{rec.id}: ~{rec.score} -> ~{curved}")
    }

    # 5. 정리
    free(buf)

    puts("\nPipeline complete.")
    0
}

파이프라인 아키텍처

[데이터 소스]     [변환]        [집계]       [출력]
 create_dataset -> read_record -> compute_  -> print()
                   apply_curve    stats
                   passes_filter

이 구조는 일반적인 ETL (Extract-Transform-Load) 패턴을 따릅니다:

• Extract: create_dataset + read_record
• Transform: apply_curve + passes_filter
• Load: compute_stats + print

Step 7: 파이프 연산자 활용 (보너스)

Vais의 |> 연산자로 변환 체인을 표현적으로 작성할 수 있습니다:

# 단일 레코드 처리
F process_score(score: i64) -> i64 {
    score |> apply_curve |> |s| I s > 100 { 100 } E { s }
}

핵심 개념:

• |>는 파이프 연산자: 왼쪽 결과를 오른쪽 함수의 첫 인수로 전달
• 클로저 |s| expr와 조합하여 인라인 변환 가능

전체 코드

examples/tutorial_pipeline.vais에서 전체 코드를 확인할 수 있습니다.

vaisc run examples/tutorial_pipeline.vais

확장 아이디어

1. CSV 파싱: std/string.vais의 split_char()로 실제 CSV 파일 파싱
2. JSON 출력: std/json.vais로 결과를 JSON 형식으로 출력
3. TOML 설정: std/toml.vais로 파이프라인 설정 파일 읽기
4. 정렬: 버블 정렬이나 swap() 빌트인으로 결과 정렬
5. 다단계 파이프라인: 변환 함수를 배열로 구성하여 동적 파이프라인

배운 것 요약

이전 튜토리얼: HTTP Server 만들기

다음 단계

• 학습 경로 - 체계적 학습 가이드
• 표준 라이브러리 - 사용 가능한 모든 모듈
• Cookbook - 실전 레시피 모음

Tutorial: WebSocket Chat Server 만들기

이 튜토리얼에서는 Vais로 실시간 WebSocket 채팅 서버를 만듭니다. 클라이언트가 메시지를 보내면 서버가 모든 연결된 클라이언트에게 브로드캐스트하는 echo-broadcast 패턴을 구현합니다.

최종 결과

$ vaisc run examples/tutorial_ws_chat.vais
=== Vais WebSocket Chat Server ===
Listening on port 9001
Test with: websocat ws://127.0.0.1:9001

사전 준비

• Vais 설치 완료
• CLI Tool 튜토리얼 완료 권장
• websocat 또는 wscat (WebSocket 클라이언트)

Step 1: TCP 기반 서버 뼈대 (10분)

WebSocket은 TCP 위에 동작합니다. 먼저 TCP 서버를 설정합니다:

# 외부 함수 선언 — C 런타임 네트워킹
N "C" {
    F __tcp_listen(port: i64) -> i64
    F __tcp_accept(listener_fd: i64) -> i64
    F __tcp_send(fd: i64, data: i64, len: i64) -> i64
    F __tcp_recv(fd: i64, buffer: i64, len: i64) -> i64
    F __tcp_close(fd: i64) -> i64
    F __malloc(size: i64) -> i64
    F __free(ptr: i64) -> i64
}

F main() -> i64 {
    port := 9001
    puts("=== Vais WebSocket Chat Server ===")

    listener := __tcp_listen(port)
    I listener < 0 {
        puts("Failed to start server")
        R 1
    }

    puts("Listening on port 9001")
    puts("Waiting for connections...")

    # Accept loop
    L true {
        client := __tcp_accept(listener)
        I client < 0 { C }

        puts("New connection!")
        __tcp_close(client)
    }

    __tcp_close(listener)
    0
}

핵심 포인트:

• N "C" { ... } 블록으로 C 런타임 함수를 선언합니다
• __tcp_listen은 포트를 바인딩하고 리스너 파일 디스크립터를 반환합니다
• L true { ... }는 무한 루프입니다 (클라이언트를 계속 수락)

Step 2: WebSocket 핸드셰이크 (15분)

WebSocket 연결은 HTTP Upgrade 요청으로 시작됩니다. 핸드셰이크를 처리하는 함수를 작성합니다:

# WebSocket 런타임 함수들
N "C" {
    F __ws_parse_upgrade_request(buffer: i64, len: i64) -> i64
    F __ws_accept_key(client_key: i64) -> i64
    F __ws_build_upgrade_response(accept_key: i64, out_buffer: i64) -> i64
    F __find_header_end(buffer: i64, len: i64) -> i64
    F __strlen(s: str) -> i64
}

F do_handshake(fd: i64) -> i64 {
    buf := __malloc(8192)
    I buf == 0 { R 0 }

    # HTTP 요청 전체를 읽기 (헤더 끝까지)
    total := mut 0
    L true {
        n := __tcp_recv(fd, buf + total, 4096)
        I n <= 0 {
            __free(buf)
            R 0
        }
        total = total + n
        I __find_header_end(buf, total) >= 0 { B }
        I total >= 8192 {
            __free(buf)
            R 0
        }
    }

    # Sec-WebSocket-Key 추출
    ws_key := __ws_parse_upgrade_request(buf, total)
    __free(buf)
    I ws_key == 0 { R 0 }

    # SHA-1 + Base64로 Accept 키 생성
    accept_key := __ws_accept_key(ws_key)
    __free(ws_key)
    I accept_key == 0 { R 0 }

    # 101 Switching Protocols 응답 전송
    resp_buf := __malloc(512)
    I resp_buf == 0 {
        __free(accept_key)
        R 0
    }
    resp_len := __ws_build_upgrade_response(accept_key, resp_buf)
    __free(accept_key)

    sent := __tcp_send(fd, resp_buf, resp_len)
    __free(resp_buf)

    I sent > 0 { 1 } E { 0 }
}

핵심 포인트:

• WebSocket 핸드셰이크는 HTTP → WebSocket 프로토콜 업그레이드입니다
• __ws_parse_upgrade_request가 Sec-WebSocket-Key 헤더를 추출합니다
• __ws_accept_key가 RFC 6455 규격에 따라 Accept 키를 계산합니다
• D (defer)로 메모리 해제를 보장할 수도 있습니다 (Step 4 참고)

Step 3: 메시지 수신과 에코 (15분)

WebSocket 프레임을 디코딩하고 에코하는 루프를 작성합니다:

# WebSocket opcodes
C WS_TEXT: i64 = 1
C WS_CLOSE: i64 = 8
C WS_PING: i64 = 9
C WS_PONG: i64 = 10

N "C" {
    F __ws_encode_frame(opcode: i64, payload: i64, payload_len: i64,
                        masked: i64, mask_key: i64, out_frame: i64) -> i64
    F __ws_decode_frame(data: i64, data_len: i64, out_frame: i64) -> i64
    F __load_i64(ptr: i64) -> i64
}

F ws_send_text(fd: i64, msg: str) -> i64 {
    msg_len := __strlen(msg)
    buf := __malloc(msg_len + 14)
    I buf == 0 { R -1 }
    frame_len := __ws_encode_frame(WS_TEXT, msg as i64, msg_len, 0, 0, buf)
    sent := __tcp_send(fd, buf, frame_len)
    __free(buf)
    sent
}

F handle_client(fd: i64) -> i64 {
    recv_buf := __malloc(65550)
    frame_out := __malloc(40)   # 5 x i64 필드
    I recv_buf == 0 { R -1 }

    is_open := mut 1
    L is_open == 1 {
        # 최소 2바이트 수신 (프레임 헤더)
        total := mut 0
        L total < 2 {
            n := __tcp_recv(fd, recv_buf + total, 4096)
            I n <= 0 { is_open = 0; B }
            total = total + n
        }
        I is_open == 0 { B }

        # 프레임 디코딩
        consumed := __ws_decode_frame(recv_buf, total, frame_out)

        opcode := __load_i64(frame_out)
        payload := __load_i64(frame_out + 8)
        payload_len := __load_i64(frame_out + 16)

        M opcode {
            1 => {
                # 텍스트 메시지 — 에코
                puts("Received text message")
                ws_send_text(fd, payload as str)
            },
            8 => {
                # Close 프레임
                puts("Client disconnected")
                is_open = 0
            },
            9 => {
                # Ping → Pong 응답
                pong_buf := __malloc(16)
                __ws_encode_frame(WS_PONG, 0, 0, 0, 0, pong_buf)
                __tcp_send(fd, pong_buf, 2)
                __free(pong_buf)
            },
            _ => { }
        }

        I payload != 0 { __free(payload) }
    }

    __free(recv_buf)
    __free(frame_out)
    0
}

핵심 포인트:

• M opcode { ... }로 WebSocket 프레임 타입별 처리를 합니다
• 서버→클라이언트는 마스킹 없이 (masked=0) 전송합니다
• __load_i64(frame_out + offset)으로 구조체 필드를 읽습니다
• is_open := mut 1 — 가변 플래그로 루프 제어

Step 4: Defer로 리소스 정리 (5분)

메모리 누수를 방지하기 위해 D (defer)를 활용합니다:

F handle_client_safe(fd: i64) -> i64 {
    recv_buf := __malloc(65550)
    D __free(recv_buf)       # 함수 종료 시 자동 해제

    frame_out := __malloc(40)
    D __free(frame_out)      # LIFO 순서로 해제

    # ... 나머지 로직 동일
    0
}

D 문은 현재 스코프가 종료될 때 역순(LIFO)으로 실행됩니다. 에러 경로에서도 정리가 보장됩니다.

Step 5: 전체 조합 (10분)

모든 함수를 조합하여 완전한 서버를 만듭니다:

F main() -> i64 {
    port := 9001
    puts("=== Vais WebSocket Chat Server ===")

    listener := __tcp_listen(port)
    I listener < 0 {
        puts("Failed to start server")
        R 1
    }

    puts("Listening on port 9001")
    puts("Test with: websocat ws://127.0.0.1:9001")

    L true {
        client := __tcp_accept(listener)
        I client < 0 { C }

        puts("New TCP connection")

        ok := do_handshake(client)
        I ok == 1 {
            puts("WebSocket handshake OK")
            handle_client(client)
        } E {
            puts("Handshake failed")
        }

        __tcp_close(client)
    }

    __tcp_close(listener)
    0
}

빌드 및 테스트

# IR 생성
vaisc --emit-ir examples/tutorial_ws_chat.vais

# C 런타임과 링크
clang -o ws_chat tutorial_ws_chat.ll std/http_runtime.c std/websocket_runtime.c

# 실행
./ws_chat

# 다른 터미널에서 테스트
websocat ws://127.0.0.1:9001
# "Hello!" 입력 → "Hello!" 에코 확인

핵심 개념 정리

다음 단계

• HTTP Server 튜토리얼 — REST API 서버 만들기
• JSON Parser 튜토리얼 — 재귀 하강 파서 구현
• WebSocket API Reference — 전체 WebSocket API
• examples/websocket_example.vais — 완전한 에코 서버 예제

Tutorial: JSON Parser 만들기

이 튜토리얼에서는 Vais로 간단한 JSON 파서를 만듭니다. 재귀 하강(recursive descent) 기법으로 JSON 문자열을 파싱하고, 값을 추출하는 프로그램을 작성합니다.

최종 결과

$ vaisc run examples/tutorial_json_parser.vais
=== Vais JSON Parser ===
Parsing: {"name":"vais","version":1,"active":true}
Found key: name = vais
Found key: version = 1
Found key: active = true
Parse OK — 3 fields

사전 준비

• Vais 설치 완료
• CLI Tool 튜토리얼 완료 권장
• JSON 형식 기본 이해

Step 1: 토큰 정의 (10분)

JSON은 6가지 값 타입을 갖습니다: 문자열, 숫자, 불리언, null, 배열, 객체. 먼저 토큰 타입을 정의합니다:

# JSON 토큰 타입 상수
C TOK_STRING: i64 = 1
C TOK_NUMBER: i64 = 2
C TOK_TRUE: i64 = 3
C TOK_FALSE: i64 = 4
C TOK_NULL: i64 = 5
C TOK_LBRACE: i64 = 6    # {
C TOK_RBRACE: i64 = 7    # }
C TOK_LBRACKET: i64 = 8  # [
C TOK_RBRACKET: i64 = 9  # ]
C TOK_COLON: i64 = 10    # :
C TOK_COMMA: i64 = 11    # ,
C TOK_EOF: i64 = 12
C TOK_ERROR: i64 = -1

핵심 포인트:

• C 키워드로 컴파일 타임 상수를 정의합니다
• 토큰을 정수 코드로 표현하면 M (match)로 빠르게 분기할 수 있습니다

Step 2: 렉서 (Lexer) 구현 (15분)

입력 문자열을 토큰 스트림으로 변환하는 렉서를 작성합니다:

# 파서 상태 — 전역 변수로 위치 추적
G input_str: str = ""
G pos: i64 = mut 0
G input_len: i64 = 0

# 현재 문자 읽기
F peek_char() -> i64 {
    I pos >= input_len { R 0 }
    load_byte(input_str as i64 + pos)
}

# 다음 문자로 이동
F advance() -> i64 {
    I pos < input_len { pos = pos + 1 }
    0
}

# 공백 건너뛰기
F skip_whitespace() -> i64 {
    L pos < input_len {
        ch := peek_char()
        # space(32), tab(9), newline(10), carriage return(13)
        I ch == 32 | ch == 9 | ch == 10 | ch == 13 {
            advance()
        } E {
            B
        }
    }
    0
}

# 다음 토큰 타입 반환
F next_token() -> i64 {
    skip_whitespace()
    I pos >= input_len { R TOK_EOF }

    ch := peek_char()
    M ch {
        123 => { advance(); TOK_LBRACE },    # '{'
        125 => { advance(); TOK_RBRACE },    # '}'
        91  => { advance(); TOK_LBRACKET },  # '['
        93  => { advance(); TOK_RBRACKET },  # ']'
        58  => { advance(); TOK_COLON },     # ':'
        44  => { advance(); TOK_COMMA },     # ','
        34  => { scan_string() },            # '"'
        _   => {
            # 숫자 또는 키워드 (true/false/null)
            I ch >= 48 & ch <= 57 | ch == 45 {
                scan_number()
            } E {
                scan_keyword()
            }
        }
    }
}

핵심 포인트:

• G 키워드로 전역 변수를 선언합니다 (파서 상태 공유)
• M ch { ... }로 문자별 분기 처리합니다
• 문자 코드를 직접 사용합니다 (예: 123 = {, 34 = ")

Step 3: 문자열과 숫자 스캐너 (15분)

문자열과 숫자 토큰을 파싱하는 헬퍼 함수를 작성합니다:

# 문자열 값을 저장할 버퍼
G str_buf: i64 = 0
G str_len: i64 = 0

F scan_string() -> i64 {
    advance()   # 여는 '"' 건너뛰기
    start := pos

    L pos < input_len {
        ch := peek_char()
        I ch == 34 {  # 닫는 '"'
            str_len = pos - start
            str_buf = input_str as i64 + start
            advance()
            R TOK_STRING
        }
        I ch == 92 {  # '\' 이스케이프
            advance()
        }
        advance()
    }
    TOK_ERROR   # 닫는 따옴표 없음
}

# 파싱된 숫자 값
G num_value: i64 = 0

F scan_number() -> i64 {
    negative := mut 0
    I peek_char() == 45 {  # '-'
        negative = 1
        advance()
    }

    result := mut 0
    L pos < input_len {
        ch := peek_char()
        I ch >= 48 & ch <= 57 {
            result = result * 10 + (ch - 48)
            advance()
        } E {
            B
        }
    }

    num_value = I negative == 1 { -result } E { result }
    TOK_NUMBER
}

F scan_keyword() -> i64 {
    # true, false, null 식별
    ch := peek_char()
    I ch == 116 {  # 't'
        pos = pos + 4   # "true"
        R TOK_TRUE
    }
    I ch == 102 {  # 'f'
        pos = pos + 5   # "false"
        R TOK_FALSE
    }
    I ch == 110 {  # 'n'
        pos = pos + 4   # "null"
        R TOK_NULL
    }
    TOK_ERROR
}

핵심 포인트:

• str_buf와 str_len으로 파싱된 문자열의 위치와 길이를 추적합니다
• 숫자 파싱은 자릿수별로 result * 10 + digit 누적합니다
• 키워드는 첫 문자로 판별하고 고정 길이만큼 건너뜁니다

Step 4: 재귀 하강 파서 (20분)

JSON 객체와 배열을 재귀적으로 파싱합니다:

# JSON 값 파싱 — 재귀 진입점
F parse_value() -> i64 {
    tok := next_token()
    M tok {
        1 => {  # TOK_STRING
            puts("  string value")
            1
        },
        2 => {  # TOK_NUMBER
            puts("  number value")
            1
        },
        3 => { 1 },  # true
        4 => { 1 },  # false
        5 => { 1 },  # null
        6 => parse_object(),  # '{'
        8 => parse_array(),   # '['
        _ => {
            puts("Parse error: unexpected token")
            0
        }
    }
}

# JSON 객체 파싱: { "key": value, ... }
F parse_object() -> i64 {
    field_count := mut 0

    tok := next_token()
    I tok == TOK_RBRACE { R 0 }  # 빈 객체 {}

    # 첫 번째 키-값 쌍
    I tok != TOK_STRING {
        puts("Error: expected string key")
        R -1
    }
    puts("  key found")
    field_count = field_count + 1

    # ':' 구분자
    colon := next_token()
    I colon != TOK_COLON {
        puts("Error: expected ':'")
        R -1
    }

    # 값 파싱 (재귀)
    I parse_value() < 0 { R -1 }

    # 나머지 키-값 쌍
    L true {
        tok = next_token()
        I tok == TOK_RBRACE { B }   # 객체 끝
        I tok != TOK_COMMA {
            puts("Error: expected ',' or '}'")
            R -1
        }

        # 다음 키-값
        tok = next_token()
        I tok != TOK_STRING { R -1 }
        field_count = field_count + 1

        colon = next_token()
        I colon != TOK_COLON { R -1 }

        I parse_value() < 0 { R -1 }
    }

    field_count
}

# JSON 배열 파싱: [ value, ... ]
F parse_array() -> i64 {
    count := mut 0

    # 빈 배열 체크
    skip_whitespace()
    I peek_char() == 93 {  # ']'
        advance()
        R 0
    }

    # 첫 번째 요소
    I parse_value() < 0 { R -1 }
    count = count + 1

    # 나머지 요소
    L true {
        tok := next_token()
        I tok == TOK_RBRACKET { B }
        I tok != TOK_COMMA { R -1 }
        I parse_value() < 0 { R -1 }
        count = count + 1
    }

    count
}

핵심 포인트:

• parse_value() → parse_object() → parse_value() 재귀 구조
• @ (자재귀)는 단일 함수 내에서만 사용 가능 — 여기서는 상호 재귀이므로 직접 호출
• 에러 시 -1 반환으로 에러 전파 (수동 Result 패턴)

Step 5: main 함수와 통합 (10분)

F main() -> i64 {
    puts("=== Vais JSON Parser ===")

    # 테스트 JSON 문자열
    json := "{\"name\":\"vais\",\"version\":1,\"active\":true}"
    input_str = json
    input_len = __strlen(json)
    pos = 0

    puts("Parsing JSON...")

    tok := next_token()
    I tok == TOK_LBRACE {
        fields := parse_object()
        I fields >= 0 {
            puts("Parse OK")
            R 0
        }
    }

    puts("Parse failed")
    1
}

빌드 및 실행

vaisc run examples/tutorial_json_parser.vais

확장 아이디어

1. 값 추출 함수

# 특정 키의 문자열 값을 찾기
F find_string_value(json: str, key: str) -> i64 {
    input_str = json
    input_len = __strlen(json)
    pos = 0
    # ... 파싱하면서 key 매칭
    0
}

2. 중첩 객체 지원

재귀 하강 패턴 덕분에 중첩 객체는 자동으로 지원됩니다:

{"user": {"name": "Alice", "scores": [95, 87, 92]}}

3. 에러 위치 보고

F report_error(msg: str) -> i64 {
    puts("Error at position {pos}: {msg}")
    -1
}

핵심 개념 정리

다음 단계

• Data Pipeline 튜토리얼 — CSV 데이터 처리
• CLI Framework 튜토리얼 — 명령행 프레임워크 만들기
• std/json API — 표준 라이브러리 JSON 모듈
• examples/json_test.vais — JSON 테스트 예제

Tutorial: CLI Framework 만들기

이 튜토리얼에서는 Vais로 재사용 가능한 CLI (Command-Line Interface) 프레임워크를 만듭니다. 서브커맨드, 옵션 파싱, 헬프 출력을 지원하는 미니 프레임워크를 구현합니다.

최종 결과

$ ./mycli help
mycli v1.0 — Vais CLI Framework Demo

Commands:
  greet <name>     Say hello
  count <n>        Count from 1 to n
  fib <n>          Compute Fibonacci
  help             Show this help

$ ./mycli greet Vais
Hello, Vais!

$ ./mycli count 5
1 2 3 4 5

$ ./mycli fib 10
fib(10) = 55

사전 준비

• Vais 설치 완료
• CLI Tool 튜토리얼 완료 권장

Step 1: 인자 파싱 기반 (10분)

CLI 프로그램의 핵심은 명령행 인자를 읽는 것입니다. Vais에서는 C 런타임의 argc/argv를 통해 접근합니다:

# C 런타임 함수
N "C" {
    F __get_argc() -> i64
    F __get_argv(index: i64) -> str
    F __strlen(s: str) -> i64
    F __strcmp(a: str, b: str) -> i64
    F __atoi(s: str) -> i64
}

F main() -> i64 {
    argc := __get_argc()

    I argc < 2 {
        puts("Usage: mycli <command> [args...]")
        puts("Try: mycli help")
        R 1
    }

    cmd := __get_argv(1)
    puts("Command: {cmd}")
    0
}

핵심 포인트:

• __get_argc()는 인자 개수, __get_argv(i)는 i번째 인자를 반환합니다
• __strcmp로 문자열 비교 (0이면 동일)
• __atoi로 문자열→정수 변환

Step 2: 커맨드 디스패처 (15분)

서브커맨드별로 핸들러 함수를 분기하는 디스패처를 만듭니다:

# 서브커맨드 핸들러들
F cmd_help() -> i64 {
    puts("mycli v1.0 — Vais CLI Framework Demo")
    puts("")
    puts("Commands:")
    puts("  greet <name>     Say hello")
    puts("  count <n>        Count from 1 to n")
    puts("  fib <n>          Compute Fibonacci")
    puts("  help             Show this help")
    0
}

F cmd_greet() -> i64 {
    argc := __get_argc()
    I argc < 3 {
        puts("Error: greet requires a name")
        puts("Usage: mycli greet <name>")
        R 1
    }
    name := __get_argv(2)
    puts("Hello, {name}!")
    0
}

F cmd_count() -> i64 {
    argc := __get_argc()
    I argc < 3 {
        puts("Error: count requires a number")
        R 1
    }
    n := __atoi(__get_argv(2))
    I n <= 0 {
        puts("Error: n must be positive")
        R 1
    }

    L i:1..n+1 {
        putchar(i / 10 + 48)
        putchar(i % 10 + 48)
        putchar(32)   # space
    }
    putchar(10)  # newline
    0
}

F cmd_fib() -> i64 {
    argc := __get_argc()
    I argc < 3 {
        puts("Error: fib requires a number")
        R 1
    }
    n := __atoi(__get_argv(2))
    result := fib(n)
    puts("fib({n}) = {result}")
    0
}

# 피보나치 (자재귀)
F fib(n: i64) -> i64 = n < 2 ? n : @(n-1) + @(n-2)

# 디스패처
F dispatch(cmd: str) -> i64 {
    I __strcmp(cmd, "help") == 0 { R cmd_help() }
    I __strcmp(cmd, "greet") == 0 { R cmd_greet() }
    I __strcmp(cmd, "count") == 0 { R cmd_count() }
    I __strcmp(cmd, "fib") == 0 { R cmd_fib() }

    puts("Unknown command: {cmd}")
    puts("Try: mycli help")
    1
}

F main() -> i64 {
    argc := __get_argc()
    I argc < 2 {
        R cmd_help()
    }

    cmd := __get_argv(1)
    dispatch(cmd)
}

핵심 포인트:

• 각 커맨드는 독립 함수로 분리합니다
• dispatch가 문자열 비교로 적절한 핸들러를 호출합니다
• 인자 검증을 각 핸들러에서 수행합니다 (argc 체크)
• R (return)으로 조기 반환하여 에러 처리합니다

Step 3: 옵션 파싱 (15분)

--verbose, --output=file 같은 옵션을 파싱하는 기능을 추가합니다:

# 전역 옵션 플래그
G verbose: i64 = mut 0
G output_file: str = ""

# 문자열 접두사 비교
F starts_with(s: str, prefix: str) -> i64 {
    s_len := __strlen(s)
    p_len := __strlen(prefix)
    I p_len > s_len { R 0 }

    i := mut 0
    L i < p_len {
        sc := load_byte(s as i64 + i)
        pc := load_byte(prefix as i64 + i)
        I sc != pc { R 0 }
        i = i + 1
    }
    1
}

# 옵션 파싱 — 옵션이 아닌 첫 인자의 인덱스 반환
F parse_options() -> i64 {
    argc := __get_argc()
    i := mut 1    # argv[0]은 프로그램 이름

    L i < argc {
        arg := __get_argv(i)

        I __strcmp(arg, "--verbose") == 0 | __strcmp(arg, "-v") == 0 {
            verbose = 1
            i = i + 1
            C
        }

        I starts_with(arg, "--output=") == 1 {
            # "=" 뒤의 값 추출
            output_file = arg as i64 + 9 as str
            i = i + 1
            C
        }

        I starts_with(arg, "-") == 1 {
            puts("Unknown option: {arg}")
            i = i + 1
            C
        }

        # 옵션이 아닌 인자 발견 → 커맨드 시작
        B
    }

    i   # 커맨드 인자의 시작 인덱스
}

핵심 포인트:

• 전역 플래그 G verbose: i64 = mut 0로 옵션 상태를 저장합니다
• starts_with 헬퍼로 접두사 매칭합니다
• C (continue)로 다음 인자를 처리합니다
• B (break)로 옵션 파싱을 종료하고 커맨드 처리로 넘어갑니다

Step 4: 에러 처리와 종료 코드 (10분)

Unix 관례에 따라 적절한 종료 코드를 반환합니다:

C EXIT_OK: i64 = 0
C EXIT_USAGE: i64 = 1
C EXIT_ERROR: i64 = 2

F error(msg: str) -> i64 {
    puts("Error: {msg}")
    EXIT_ERROR
}

F usage_error(msg: str) -> i64 {
    puts("Error: {msg}")
    puts("")
    cmd_help()
    EXIT_USAGE
}

# 개선된 디스패처
F dispatch_v2(cmd: str) -> i64 {
    I verbose == 1 {
        puts("[verbose] Dispatching command: {cmd}")
    }

    I __strcmp(cmd, "help") == 0 { R cmd_help() }
    I __strcmp(cmd, "greet") == 0 { R cmd_greet() }
    I __strcmp(cmd, "count") == 0 { R cmd_count() }
    I __strcmp(cmd, "fib") == 0 { R cmd_fib() }

    usage_error("unknown command")
}

Step 5: 전체 프로그램 (10분)

F main() -> i64 {
    # 1) 옵션 파싱
    cmd_start := parse_options()

    argc := __get_argc()
    I cmd_start >= argc {
        R cmd_help()
    }

    # 2) 커맨드 실행
    cmd := __get_argv(cmd_start)

    I verbose == 1 {
        puts("[verbose] Options parsed")
        I __strlen(output_file) > 0 {
            puts("[verbose] Output: {output_file}")
        }
    }

    dispatch_v2(cmd)
}

빌드 및 실행

# 빌드
vaisc --emit-ir examples/tutorial_cli_framework.vais
clang -o mycli tutorial_cli_framework.ll

# 테스트
./mycli help
./mycli greet World
./mycli --verbose fib 10
./mycli --output=result.txt count 5

확장 아이디어

1. 플러그인 커맨드 등록

# 함수 포인터 배열로 커맨드 등록
S Command {
    name: str,
    description: str,
    handler: i64    # 함수 포인터
}

2. 자동 완성 힌트

F suggest_command(partial: str) -> i64 {
    # "co" → "count"
    # "fi" → "fib"
    # 접두사 매칭으로 후보 출력
    0
}

3. 환경 변수 지원

N "C" {
    F getenv(name: str) -> str
}

F get_config_dir() -> str {
    dir := getenv("MYCLI_CONFIG")
    I __strlen(dir) == 0 {
        R "/etc/mycli"
    }
    dir
}

핵심 개념 정리

다음 단계

• WebSocket Chat 튜토리얼 — 실시간 서버 만들기
• Data Pipeline 튜토리얼 — 데이터 처리 파이프라인
• Cookbook — 실전 레시피 모음
• Testing Guide — 테스트 작성법

에러 처리 패턴 가이드

Vais에서 에러를 안전하게 처리하는 방법을 배웁니다. Vais는 예외 대신 타입 기반의 에러 처리를 권장합니다.

에러 처리 전략

Vais는 여러 에러 처리 패턴을 지원합니다:

1. 에러 코드 반환 - 정수 반환값으로 상태 표시
2. Option/Result 패턴 - 선택적 값과 에러 정보
3. 에러 전파 - 고수준 함수에 에러 처리 위임
4. 패닉 (panic) - 복구 불가능한 에러

1. 에러 코드 패턴

기본 에러 코드

전통적인 C 스타일의 에러 코드를 사용합니다:

# 에러 코드 상수
G SUCCESS: i64 = 0
G ERROR_FILE_NOT_FOUND: i64 = 1
G ERROR_INVALID_INPUT: i64 = 2
G ERROR_PERMISSION_DENIED: i64 = 3

# 함수에서 에러 코드 반환
F read_config(path: str) -> i64 {
    I path.len() == 0 {
        R ERROR_INVALID_INPUT
    }

    # 파일 읽기 시뮬레이션
    R SUCCESS
}

F main() -> i64 {
    status := read_config("")

    I status == SUCCESS {
        puts("Configuration loaded")
    } E I status == ERROR_INVALID_INPUT {
        puts("Error: Invalid file path")
    } E I status == ERROR_FILE_NOT_FOUND {
        puts("Error: File not found")
    } E {
        puts("Error: Unknown error")
    }

    status
}

에러 코드 모듈화

여러 함수에서 재사용할 수 있도록 에러 코드를 모듈화합니다:

# errors.vais - 에러 정의 모듈
S ErrorCode {
    code: i64
    message: str
}

F error_success() -> ErrorCode = ErrorCode { code: 0, message: "Success" }
F error_not_found() -> ErrorCode = ErrorCode { code: 1, message: "Not found" }
F error_invalid_arg() -> ErrorCode = ErrorCode { code: 2, message: "Invalid argument" }
F error_io() -> ErrorCode = ErrorCode { code: 3, message: "I/O error" }

F is_error(err: ErrorCode) -> bool = err.code != 0
F error_message(err: ErrorCode) -> str = err.message

2. Option 패턴

Option 타입으로 값이 있을 수도, 없을 수도 있는 경우를 표현합니다:

# Option 구조체 정의
E Option<T> {
    Some(T),
    None
}

# Option을 반환하는 함수
F find_user(id: i64) -> Option<str> {
    I id == 1 {
        R Option.Some("Alice")
    }
    R Option.None
}

# Option 값 처리
F main() -> i64 {
    user := find_user(1)

    M user {
        Option.Some(name) => puts("Found user: ~{name}"),
        Option.None => puts("User not found")
    }

    0
}

Option 체이닝

여러 Option 연산을 연쇄적으로 수행합니다:

S User {
    id: i64
    name: str
    email: str
}

# Option 반환 함수들
F find_user_by_id(id: i64) -> Option<User> {
    I id > 0 {
        R Option.Some(User { id: id, name: "User", email: "user@example.com" })
    }
    R Option.None
}

F get_email(user: User) -> Option<str> {
    I user.email.len() > 0 {
        R Option.Some(user.email)
    }
    R Option.None
}

# 함수 조합
F get_user_email(user_id: i64) -> Option<str> {
    user := find_user_by_id(user_id)
    M user {
        Option.Some(u) => get_email(u),
        Option.None => Option.None
    }
}

3. Result 패턴

에러 정보와 함께 성공/실패를 표현하는 패턴입니다:

# Result 구조체 정의
E Result<T> {
    Ok(T),
    Err(str)
}

# Result를 반환하는 함수
F parse_number(s: str) -> Result<i64> {
    # 간단한 파싱 (실제로는 더 복잡함)
    I s.len() == 0 {
        R Result.Err("Empty string")
    }

    # 성공 케이스
    R Result.Ok(42)
}

F main() -> i64 {
    result := parse_number("123")

    M result {
        Result.Ok(num) => puts("Parsed: ~{num}"),
        Result.Err(err) => puts("Error: ~{err}")
    }

    0
}

Result 에러 전파

에러를 상위 함수로 전파합니다:

E FileError {
    NotFound,
    PermissionDenied,
    IoError
}

E Result<T> {
    Ok(T),
    Err(FileError)
}

# 파일 읽기 함수
F read_file(path: str) -> Result<str> {
    I path.len() == 0 {
        R Result.Err(FileError.NotFound)
    }

    # 파일 내용 읽기
    content := "file content"
    R Result.Ok(content)
}

# 파일 처리 함수 (에러 전파)
F process_file(path: str) -> Result<i64> {
    content := read_file(path)

    M content {
        Result.Ok(data) => {
            # 데이터 처리
            line_count := 1
            R Result.Ok(line_count)
        },
        Result.Err(err) => {
            # 에러 전파
            R Result.Err(err)
        }
    }
}

4. 안전한 에러 처리 패턴

기본값 제공

F get_config_value(key: str) -> i64 {
    # 기본값 반환
    0
}

F main() -> i64 {
    # 에러 발생 시 기본값 사용
    timeout := get_config_value("timeout")

    # 0이 기본값 (에러 처리됨)
    actual_timeout := timeout > 0 ? timeout : 30
    puts("Timeout: ~{actual_timeout}")

    0
}

조건부 처리

F divide(a: i64, b: i64) -> Result<i64> {
    I b == 0 {
        R Result.Err("Division by zero")
    }
    R Result.Ok(a / b)
}

F main() -> i64 {
    result := divide(10, 2)

    M result {
        Result.Ok(value) => puts("Result: ~{value}"),
        Result.Err(msg) => puts("Cannot divide: ~{msg}")
    }

    0
}

5. 구조화된 로깅 통합

에러와 함께 로깅합니다:

# log.vais 사용 (표준 라이브러리)

E LogLevel {
    Debug,
    Info,
    Warn,
    Error,
    Fatal
}

S Logger {
    level: LogLevel
}

X Logger {
    F log(&self, level: LogLevel, msg: str) {
        M level {
            LogLevel.Error => puts("[ERROR] ~{msg}"),
            LogLevel.Warn => puts("[WARN] ~{msg}"),
            LogLevel.Info => puts("[INFO] ~{msg}"),
            LogLevel.Debug => puts("[DEBUG] ~{msg}"),
            LogLevel.Fatal => {
                puts("[FATAL] ~{msg}")
                # 프로그램 종료
            }
        }
    }

    F error(&self, msg: str) {
        self.log(LogLevel.Error, msg)
    }

    F warn(&self, msg: str) {
        self.log(LogLevel.Warn, msg)
    }
}

F main() -> i64 {
    logger := Logger { level: LogLevel.Info }

    result := divide(10, 0)

    M result {
        Result.Ok(value) => logger.log(LogLevel.Info, "Division successful"),
        Result.Err(msg) => logger.error("Division failed: ~{msg}")
    }

    0
}

6. 리소스 정리 (defer)

에러 발생 후에도 리소스를 정리하는 패턴입니다:

F read_and_process(filename: str) -> Result<i64> {
    # 파일 열기
    handle := fopen(filename, "r")

    I handle == 0 {
        R Result.Err("Failed to open file")
    }

    # defer를 사용하여 파일 닫기 보장
    D fclose(handle)

    # 파일 처리
    line_count := 0
    # ... 파일 읽기 로직 ...

    R Result.Ok(line_count)
}

7. 복합 에러 처리 예제

실제 시나리오에서의 에러 처리:

S Config {
    host: str
    port: i64
    timeout: i64
}

E ConfigError {
    NotFound,
    InvalidFormat,
    MissingField
}

F load_config(path: str) -> Result<Config> {
    # 1. 파일 존재 확인
    I path.len() == 0 {
        R Result.Err(ConfigError.NotFound)
    }

    # 2. 파일 읽기
    content := "host=localhost\nport=8080\ntimeout=30"

    # 3. 파싱
    I content.len() == 0 {
        R Result.Err(ConfigError.InvalidFormat)
    }

    # 4. 구성 객체 생성
    config := Config {
        host: "localhost",
        port: 8080,
        timeout: 30
    }

    R Result.Ok(config)
}

F validate_config(config: Config) -> Result<bool> {
    I config.port <= 0 || config.port > 65535 {
        R Result.Err(ConfigError.InvalidFormat)
    }

    I config.timeout <= 0 {
        R Result.Err(ConfigError.InvalidFormat)
    }

    R Result.Ok(true)
}

F main() -> i64 {
    # 설정 로드
    config_result := load_config("config.txt")

    I config_result {
        M config_result {
            Result.Ok(cfg) => {
                # 설정 검증
                valid := validate_config(cfg)
                M valid {
                    Result.Ok(_) => {
                        puts("Configuration loaded and validated")
                        puts("Host: ~{cfg.host}:~{cfg.port}")
                    },
                    Result.Err(_) => puts("Configuration validation failed")
                }
            },
            Result.Err(err) => {
                M err {
                    ConfigError.NotFound => puts("Config file not found"),
                    ConfigError.InvalidFormat => puts("Invalid config format"),
                    ConfigError.MissingField => puts("Missing required field")
                }
            }
        }
    }

    0
}

모범 사례 (Best Practices)

1. 명확한 에러 타입

# Good: 명확한 에러 타입
E DatabaseError {
    ConnectionFailed,
    QueryFailed,
    TimeoutError
}

# Bad: 문자열만 사용
F bad_db_operation() -> Result<str> {
    R Result.Err("Some error occurred")
}

2. 에러 전파 명시

# 에러 전파를 함수 시그니처에 명시
F fetch_user_data(id: i64) -> Result<str> {
    # ...에러 처리...
}

3. 컨텍스트 제공

F process_records(count: i64) -> Result<bool> {
    I count <= 0 {
        # 좋은 에러 메시지: 무엇이 잘못되었는지 알 수 있음
        R Result.Err("Record count must be positive, got ~{count}")
    }
    R Result.Ok(true)
}

4. 조기 반환

F validate_user(name: str, age: i64) -> Result<bool> {
    # 각 조건을 빠르게 검사하고 반환
    I name.len() == 0 { R Result.Err("Name is required") }
    I age < 0 { R Result.Err("Age cannot be negative") }
    I age > 150 { R Result.Err("Age seems invalid") }

    R Result.Ok(true)
}

테스트 에러 처리

# 에러를 예상하는 테스트
F test_division_by_zero() {
    result := divide(10, 0)

    M result {
        Result.Ok(_) => puts("Test failed: should have returned error"),
        Result.Err(_) => puts("Test passed: error caught correctly")
    }
}

# 성공을 예상하는 테스트
F test_valid_division() {
    result := divide(10, 2)

    M result {
        Result.Ok(value) => {
            I value == 5 {
                puts("Test passed: correct result")
            } E {
                puts("Test failed: wrong result")
            }
        },
        Result.Err(_) => puts("Test failed: unexpected error")
    }
}

다음 단계

• 성능 튜닝 가이드: 에러 처리의 성능 영향
• 코딩 스타일 가이드: 에러 처리 스타일
• 표준 라이브러리: 표준 에러 타입

성능 최적화 가이드

Vais 컴파일러는 다양한 최적화 기법을 제공하여 실행 속도와 컴파일 시간을 모두 개선할 수 있습니다. 이 가이드는 Vais 프로그램의 성능을 극대화하는 방법을 다룹니다.

최적화 레벨

Vais 컴파일러는 4가지 최적화 레벨을 제공합니다.

-O0 (기본값)

최적화 없음. 디버깅에 최적화되어 있습니다.

vaisc build main.vais
vaisc build main.vais -O0

• 장점: 빠른 컴파일, 디버깅 용이
• 단점: 느린 실행 속도
• 사용 시점: 개발 단계, 버그 추적

-O1

기본 최적화. 컴파일 시간과 실행 속도의 균형.

vaisc build main.vais -O1

• 최적화: dead code elimination, constant folding, basic inlining
• 사용 시점: 일반 개발, CI 빌드

-O2

적극적 최적화. 프로덕션 권장 레벨.

vaisc build main.vais -O2

• 최적화: loop unrolling, vectorization, function inlining, tail call optimization
• 컴파일 시간: -O1 대비 20-30% 증가
• 실행 속도: -O1 대비 30-50% 개선
• 사용 시점: 프로덕션 릴리스, 벤치마크

-O3

최대 최적화. 컴파일 시간 희생.

vaisc build main.vais -O3

• 최적화: aggressive inlining, loop transformations, interprocedural optimization
• 컴파일 시간: -O2 대비 50-100% 증가
• 실행 속도: -O2 대비 5-15% 추가 개선
• 사용 시점: CPU-bound 애플리케이션, 고성능 라이브러리

PGO (Profile-Guided Optimization)

PGO는 실제 실행 프로파일을 기반으로 최적화합니다. 2단계 프로세스입니다.

1단계: 프로파일 수집

# 프로파일링 빌드 생성
vaisc build main.vais --pgo-gen -O2

# 실행하여 프로파일 데이터 수집 (.profraw 생성)
./main

# 프로파일 병합 (여러 실행 결과 통합)
llvm-profdata merge -o default.profdata default_*.profraw

2단계: 프로파일 사용

# 프로파일 기반 최적화 빌드
vaisc build main.vais --pgo-use=default.profdata -O2

PGO 성능 향상

• 브랜치 예측: 자주 실행되는 경로를 최적화
• 함수 인라이닝: 호출 빈도 기반 인라이닝 결정
• 코드 레이아웃: 핫 경로를 연속된 메모리에 배치

예상 성능 개선: 5-20% (워크로드 의존적)

모범 사례

1. 대표적인 워크로드 사용: 프로파일링 실행은 실제 사용 패턴을 반영해야 함
2. 여러 시나리오 수집: 다양한 입력으로 여러 번 실행 후 병합
3. 정기적 갱신: 코드 변경 시 프로파일 재수집

# 예: 여러 워크로드 프로파일링
vaisc build server.vais --pgo-gen -O2
./server < workload1.txt
./server < workload2.txt
./server < workload3.txt
llvm-profdata merge -o server.profdata default_*.profraw
vaisc build server.vais --pgo-use=server.profdata -O2

인크리멘탈 컴파일

대규모 프로젝트에서 컴파일 시간을 단축합니다.

기본 사용법

# 모듈별 컴파일 활성화
vaisc build main.vais --per-module

동작 방식

1. 각 모듈을 개별 LLVM IR로 컴파일
2. 변경되지 않은 모듈은 캐시 재사용
3. 변경된 모듈만 재컴파일
4. 링크 단계에서 통합

성능 수치

캐시 관리

# 캐시 크기 제한 (기본값: 512MB)
vaisc build main.vais --per-module --cache-limit=256

# 캐시 위치: ~/.vais-cache/ir_cache/
# 수동 정리:
rm -rf ~/.vais-cache/ir_cache/

주의사항

• 초기 빌드는 더 느릴 수 있음 (캐시 생성 오버헤드)
• 디스크 공간 사용: 대규모 프로젝트는 수백 MB 캐시
• 최적화 레벨: -O2/-O3와 함께 사용 가능

벤치마크 작성

Vais는 Criterion 기반 벤치마크를 지원합니다.

기본 벤치마크

# benches/my_bench.vais
U std/bench

F fibonacci(n: i64) -> i64 {
  I n <= 1 { R n }
  R fibonacci(n - 1) + fibonacci(n - 2)
}

F bench_fib() {
  benchmark("fibonacci_20", || {
    fibonacci(20)
  })
}

F main() {
  bench_fib()
  bench_report()
}

실행

vaisc bench benches/my_bench.vais

비교 벤치마크

F bench_sorting() {
  v1 := vec_new<i64>()
  L i := 0; i < 1000; i := i + 1 {
    vec_push(v1, 1000 - i)
  }

  benchmark("quicksort_1000", || {
    vec_sort(v1)
  })

  benchmark("merge_sort_1000", || {
    vec_merge_sort(v1)
  })
}

벤치마크 모범 사례

1. 워밍업: 첫 실행은 캐시 미스로 느릴 수 있음
2. 반복 횟수: 충분히 반복하여 통계적 유의성 확보
3. 일관된 환경: CPU 거버너 설정, 백그라운드 프로세스 최소화
4. 프로파일링과 병행: --profile 플래그로 상세 분석

메모리 최적화

Arena Allocator

빈번한 할당/해제 시 성능 향상.

U std/alloc

F main() {
  arena := arena_new(1024 * 1024)  # 1MB arena

  L i := 0; i < 10000; i := i + 1 {
    ptr := arena_alloc(arena, 64)
    # 개별 free 불필요
  }

  arena_free(arena)  # 한 번에 전체 해제
}

성능: 일반 malloc 대비 10-50배 빠름 (할당 패턴 의존)

Object Pool

재사용 가능한 객체 풀.

U std/pool

S Connection { fd: i64 }

F main() {
  pool := pool_new<Connection>(10)  # 10개 미리 할당

  L i := 0; i < 100; i := i + 1 {
    conn := pool_acquire(pool)
    # 연결 사용
    pool_release(pool, conn)
  }
}

Box (힙 할당)

큰 구조체는 Box로 감싸서 스택 오버플로 방지.

S LargeData {
  buffer: [i64; 10000]
}

F main() {
  data := box(LargeData { buffer: [0; 10000] })
  # 스택 대신 힙에 할당
}

SIMD 활용

Vais는 SIMD (Single Instruction Multiple Data)를 지원합니다.

기본 SIMD 연산

U std/simd

F dot_product_simd(a: Vec<f32>, b: Vec<f32>) -> f32 {
  result := 0.0
  len := vec_len(a)

  # SIMD 레지스터 크기 (4 floats for SSE, 8 for AVX)
  simd_width := 8

  L i := 0; i + simd_width < len; i := i + simd_width {
    va := simd_load_f32(vec_ptr(a), i)
    vb := simd_load_f32(vec_ptr(b), i)
    vc := simd_mul_f32(va, vb)
    result := result + simd_sum_f32(vc)
  }

  # 나머지 처리
  L i >= len - simd_width; i < len; i := i + 1 {
    result := result + vec_get(a, i) * vec_get(b, i)
  }

  R result
}

SIMD 성능 향상

• AVX2 (256-bit): 4-8배 속도 향상 (f32 기준)
• NEON (ARM): 3-4배 속도 향상
• 자동 벡터화: -O2/-O3는 일부 루프를 자동 SIMD화

컴파일러 힌트

# AVX2 활성화
vaisc build main.vais -O3 --target-cpu=native

# 특정 CPU 타겟
vaisc build main.vais -O3 --target-cpu=skylake

프로파일링

--profile 플래그

컴파일러 내부 프로파일링.

vaisc build main.vais --profile

출력 예:

=== Vais Compiler Profile ===
Lexing:        12ms
Parsing:       45ms
Type Checking: 78ms
Codegen:       234ms
Linking:       91ms
Total:         460ms

런타임 프로파일링

# Linux: perf
perf record ./main
perf report

# macOS: Instruments
instruments -t "Time Profiler" ./main

# 범용: flamegraph
vaisc build main.vais -O2 --debug-info
perf record -g ./main
perf script | stackcollapse-perf.pl | flamegraph.pl > flame.svg

컴파일 시간 최적화

1. 인크리멘탈 컴파일 사용

vaisc build main.vais --per-module

2. 병렬 컴파일

# 4개 스레드로 병렬 컴파일 (기본값: CPU 코어 수)
vaisc build main.vais --per-module --jobs=4

3. IR 캐싱

# IR 파일 보존 (재컴파일 시 재사용)
vaisc build main.vais --emit-ir --per-module

4. 타입 체커 최적화

• 모듈 분할: 대형 파일을 여러 모듈로 분리
• 제네릭 사용 최소화: 과도한 monomorphization 방지
• 타입 명시: 타입 추론 부담 감소

# 나쁨: 과도한 타입 추론
F process(data) {
  result := transform(data)
  R finalize(result)
}

# 좋음: 명시적 타입
F process(data: Vec<i64>) -> i64 {
  result: Vec<i64> = transform(data)
  R finalize(result)
}

5. 의존성 최소화

# 나쁨: 전체 라이브러리 임포트
U std/collections

# 좋음: 필요한 함수만 선택적 임포트
U std/collections { vec_new, vec_push, vec_len }

성능 체크리스트

개발 단계

• -O0 또는 -O1 사용
• --per-module 활성화 (빠른 재컴파일)
• 디버그 심볼 유지

프로덕션 릴리스

• -O2 또는 -O3 사용
• PGO 적용 고려 (CPU-bound 앱)
• --strip (디버그 심볼 제거, 바이너리 크기 50% 감소)
• SIMD 최적화 활성화 (--target-cpu=native)

성능 크리티컬 애플리케이션

• PGO 필수 적용
• 벤치마크 작성 및 정기 실행
• 프로파일링으로 핫스팟 식별
• Arena/Pool 할당자 고려
• SIMD 수동 최적화

실전 예제

고성능 HTTP 서버 빌드

# 1. PGO 프로파일 수집
vaisc build server.vais --pgo-gen -O2 --per-module
./server &
SERVER_PID=$!
wrk -t4 -c100 -d30s http://localhost:8000/
kill $SERVER_PID
llvm-profdata merge -o server.profdata default_*.profraw

# 2. 최적화 빌드
vaisc build server.vais \
  --pgo-use=server.profdata \
  -O3 \
  --target-cpu=native \
  --strip

# 3. 검증
wrk -t4 -c100 -d60s http://localhost:8000/

수치 계산 라이브러리 빌드

vaisc build matrix.vais \
  -O3 \
  --target-cpu=native \
  --emit-ir \
  --per-module

# SIMD 벡터화 확인
grep "vectorize" matrix.ll

추가 리소스

• Compiler Flags Reference
• Benchmark Suite
• Profiler Documentation
• LLVM Optimization Guide

성능 최적화는 측정에서 시작합니다. 벤치마크 → 프로파일 → 최적화 → 검증 사이클을 반복하세요.

코딩 스타일 가이드

Vais 커뮤니티가 권장하는 코딩 스타일입니다. 이 가이드를 따르면 코드가 일관되고 읽기 쉬워집니다.

네이밍 컨벤션 (Naming Conventions)

함수 이름

함수명은 snake_case를 사용합니다. 동사로 시작하는 것이 좋습니다.

# 좋은 예
F calculate_sum(numbers: [i64; 10]) -> i64 { }
F is_prime(n: i64) -> bool { }
F get_user_by_id(id: i64) -> Option<User> { }
F parse_json(text: str) -> Result<Json> { }
F validate_email(email: str) -> bool { }

# 나쁜 예
F CalcSum(numbers: [i64; 10]) -> i64 { }      # PascalCase 사용 금지
F isprime(n: i64) -> bool { }                 # 약자 사용
F getUserById(id: i64) -> Option<User> { }    # camelCase 사용 금지
F PARSE_JSON(text: str) -> Result<Json> { }   # SCREAMING_SNAKE_CASE 함수명 사용 금지

구조체 이름

구조체명은 PascalCase를 사용합니다.

# 좋은 예
S User {
    id: i64
    name: str
}

S HttpResponse {
    status_code: i64
    body: str
}

S LinkedListNode<T> {
    value: T
    next: i64
}

# 나쁜 예
S user { }                # snake_case 사용 금지
S userProfile { }         # camelCase 사용 금지
S USER_DATA { }           # SCREAMING_SNAKE_CASE 사용 금지

변수 이름

변수명은 snake_case를 사용합니다.

# 좋은 예
user_count := 0
total_price := 99.99
is_valid := true
temp_buffer := "data"
mutable_counter := mut 0

# 나쁬 예
UserCount := 0              # PascalCase 사용 금지
totalPrice := 99.99         # camelCase 사용 금지
TEMP_BUFFER := "data"       # 변수에 SCREAMING_SNAKE_CASE 사용 금지
x := 0                      # 의미 없는 한 글자 (루프 제외)

상수 이름

상수명은 SCREAMING_SNAKE_CASE를 사용합니다.

# 좋은 예
G MAX_BUFFER_SIZE: i64 = 1024
G DEFAULT_TIMEOUT: i64 = 30
G PI: f64 = 3.14159
G APP_VERSION: str = "0.1.0"
G ERROR_FILE_NOT_FOUND: i64 = 1

# 나쁜 예
G MaxBufferSize: i64 = 1024   # PascalCase 사용 금지
G max_buffer_size: i64 = 1024 # snake_case 사용 금지
G maxBufferSize: i64 = 1024   # camelCase 사용 금지

Trait 이름

Trait명은 PascalCase를 사용합니다. 보통 형용사나 행동을 나타냅니다.

# 좋은 예
W Drawable {
    F draw(&self) -> i64
}

W Serializable {
    F serialize(&self) -> str
}

W Comparable {
    F compare(&self, other: i64) -> i64
}

W Reader {
    F read(&self) -> i64
}

# 나쁜 예
W drawable { }        # snake_case 사용 금지
W draw_able { }       # snake_case 사용 금지

Enum 이름

Enum명과 변수명 모두 PascalCase를 사용합니다.

# 좋은 예
E Color {
    Red,
    Green,
    Blue
}

E HttpMethod {
    Get,
    Post,
    Put,
    Delete
}

color := Color.Red
method := HttpMethod.Post

# 나쁜 예
E color { }           # snake_case 사용 금지
E COLOR { }           # SCREAMING_SNAKE_CASE 사용 금지
E http_method { }     # snake_case 사용 금지

파일 및 모듈 구조

파일 이름

파일명은 snake_case를 사용합니다.

# 좋은 구조
src/
├── main.vais              # 메인 엔트리 포인트
├── lib.vais               # 라이브러리 메인
├── user.vais              # 사용자 관련 모듈
├── config.vais            # 설정 관련 모듈
├── database.vais          # 데이터베이스 관련 모듈
└── utils.vais             # 유틸리티 함수

# 나쁬 구조
src/
├── User.vais              # PascalCase 사용 금지
├── Config.vais            # PascalCase 사용 금지
├── get_user_by_id.vais   # 파일명이 너무 상세함

모듈 크기

파일이 너무 커지지 않도록 주의합니다.

권장 파일 크기:
- 300줄 이하: 이상적
- 300-500줄: 괜찮음
- 500줄 이상: 분할 검토

모듈 구성

관련 기능별로 파일을 구성합니다.

src/
├── http/
│   ├── request.vais       # HTTP 요청 타입
│   ├── response.vais      # HTTP 응답 타입
│   └── status.vais        # HTTP 상태 코드
├── database/
│   ├── connection.vais    # DB 연결
│   ├── query.vais         # 쿼리 빌더
│   └── migration.vais     # 마이그레이션
└── middleware/
    ├── auth.vais          # 인증
    └── logging.vais       # 로깅

주석 및 문서화

주석 스타일

# 한 줄 주석은 #를 사용합니다

# 여러 줄 주석은 여러 개의 #를 사용합니다
# 이것은 복잡한 로직을 설명합니다
# 각 줄마다 #를 붙입니다

F example() {
    # 코드 내 주석
    x := 42  # 인라인 주석은 간단하게
}

API 문서화

공개 함수는 주석으로 문서화합니다.

# Calculate the sum of two numbers
#
# Arguments:
#   a: first number
#   b: second number
#
# Returns:
#   sum of a and b
#
# Example:
#   result := add(2, 3)  # result = 5
F add(a: i64, b: i64) -> i64 = a + b

# Parse a JSON string
#
# Arguments:
#   text: JSON string to parse
#
# Returns:
#   Ok(JsonValue) if parsing succeeds
#   Err(ParseError) if parsing fails
#
# Note:
#   This function is strict about JSON format
F parse_json(text: str) -> Result<JsonValue> {
    # ...
}

설명이 필요한 주석

복잡한 로직에만 주석을 작성합니다.

# 좋은 예: 왜 이렇게 하는지 설명
F find_user_efficiently(id: i64) -> Option<User> {
    # Use binary search on sorted user list
    # Linear search would be O(n), but we have 100k users
    # so O(log n) is critical for performance
    # ...
}

# 나쁜 예: 명확한 코드는 주석 불필요
F add(a: i64, b: i64) -> i64 {
    # Add a to b
    a + b
}

포매팅 (Formatting)

들여쓰기

4개의 스페이스를 사용합니다. 탭은 사용하지 않습니다.

# 좋은 예
F outer() {
    I true {
        puts("inner")
    }
}

# 나쁜 예 (탭 사용)
F outer() {
→   I true {
→       puts("inner")
→   }
}

줄 길이

한 줄은 100자를 넘지 않도록 합니다.

# 좋은 예
result := calculate_complex_value(arg1, arg2, arg3)

# 나쁜 예 (한 줄이 너무 김)
result := calculate_complex_value(arg1, arg2, arg3) + another_function(x, y, z) * some_multiplier

# 개선
result := calculate_complex_value(arg1, arg2, arg3)
extra := another_function(x, y, z) * some_multiplier
result = result + extra

공백

함수 정의와 구현 사이에 빈 줄을 추가합니다.

# 좋은 예
F first_function() -> i64 {
    42
}

F second_function() -> str {
    "hello"
}

# 나쁜 예 (빈 줄 없음)
F first_function() -> i64 {
    42
}
F second_function() -> str {
    "hello"
}

연산자 주변 공백

연산자 주변에 공백을 추가합니다.

# 좋은 예
x := a + b
result := value * factor + offset
I count > 0 {
    # ...
}

# 나쁜 예
x := a+b
result := value*factor+offset
I count>0 {
    # ...
}

구조체와 함수 구조

구조체 레이아웃

필드는 논리적으로 그룹화합니다.

# 좋은 예
S User {
    # 식별 정보
    id: i64
    name: str
    email: str

    # 프로필 정보
    age: i64
    bio: str

    # 상태 정보
    is_active: bool
    created_at: i64
    updated_at: i64
}

# 나쁜 예 (순서 무작위)
S User {
    name: str
    created_at: i64
    id: i64
    email: str
    is_active: bool
    age: i64
    updated_at: i64
    bio: str
}

impl 블록 구조

impl 블록의 메서드를 논리적으로 정렬합니다.

X User {
    # 생성자
    F new(id: i64, name: str) -> User {
        User { id: id, name: name, email: "", age: 0, bio: "", is_active: true, created_at: 0, updated_at: 0 }
    }

    # 기본 접근자
    F get_id(&self) -> i64 = self.id
    F get_name(&self) -> str = self.name

    # 수정자
    F set_email(&self, email: str) {
        # ...
    }

    # 비즈니스 로직
    F is_valid(&self) -> bool {
        self.id > 0 && self.name.len() > 0
    }

    # 직렬화
    F to_string(&self) -> str {
        # ...
    }
}

에러 처리

에러 처리는 일관되게 합니다.

# 좋은 예: 명확한 에러 타입
E DatabaseError {
    ConnectionFailed,
    QueryFailed,
    TimeoutError
}

F query_user(id: i64) -> Result<User> {
    I id <= 0 {
        R Result.Err(DatabaseError.QueryFailed)
    }
    # ...
}

# 나쁜 예: 문자열로 에러 표현
F query_user_bad(id: i64) -> Result<User> {
    I id <= 0 {
        R Result.Err("bad id")
    }
    # ...
}

타입 시스템

명시적 타입 주석을 사용합니다.

# 좋은 예: 명확한 타입
F process_data(items: [i64; 10]) -> i64 {
    sum: i64 := mut 0
    # ...
}

# 나쁜 예: 타입 생략
F process_data(items) {
    sum := mut 0  # 타입 불명확
    # ...
}

성능 관련 스타일

불필요한 복사 피하기

# 좋은 예: 참조 사용
F process_large_data(data: &[i64; 1000]) {
    # data 사용
}

# 나쁜 예: 복사 발생
F process_large_data_bad(data: [i64; 1000]) {
    # 전체 배열이 복사됨
}

사전 할당 (Pre-allocation)

# 좋은 예: 사전 할당
F build_results() {
    results: [i64; 1000]  # 미리 할당

    i := mut 0
    L i < 1000 {
        results[i] = process(i)
        i = i + 1
    }
}

# 나쁜 예: 반복 할당
F build_results_bad() {
    results: [i64]  # 동적 배열 (매번 재할당)
    # ...
}

테스트 작성

테스트 함수는 명확한 이름을 사용합니다.

# 테스트 함수는 test_로 시작
F test_add_positive_numbers() {
    result := add(2, 3)
    I result != 5 {
        puts("FAIL: test_add_positive_numbers")
        R
    }
    puts("PASS: test_add_positive_numbers")
}

F test_add_negative_numbers() {
    result := add(-2, -3)
    I result != -5 {
        puts("FAIL: test_add_negative_numbers")
        R
    }
    puts("PASS: test_add_negative_numbers")
}

F test_add_zero() {
    result := add(0, 0)
    I result != 0 {
        puts("FAIL: test_add_zero")
        R
    }
    puts("PASS: test_add_zero")
}

스타일 체크리스트

명명:
□ 함수: snake_case
□ 구조체: PascalCase
□ 변수: snake_case
□ 상수: SCREAMING_SNAKE_CASE
□ 파일: snake_case

포매팅:
□ 들여쓰기: 4 스페이스
□ 줄 길이: 100자 이내
□ 함수 사이: 빈 줄 추가
□ 연산자 주변: 공백 추가

문서화:
□ 공개 함수: 문서화 주석
□ 복잡한 로직: 설명 주석
□ 의미 없는 주석: 제거

구조:
□ 파일 크기: 500줄 이하
□ 논리적 그룹화
□ impl 메서드: 순서대로 정렬

테스트:
□ 중요한 함수: 테스트 작성
□ 테스트 이름: test_* 형식
□ 엣지 케이스: 테스트 포함

다음 단계

• Getting Started 가이드: 기본 문법
• 에러 처리 가이드: 에러 처리 스타일
• 성능 튜닝 가이드: 성능 최적화

Rust에서 Vais로 전환하기

개요

Vais는 Rust와 유사한 타입 시스템과 소유권 모델을 가지고 있지만, AI 최적화를 위해 단일 문자 키워드를 사용합니다. Rust 개발자라면 Vais의 핵심 개념이 익숙할 것입니다.

주요 차이점:

• 단일 문자 키워드 (F, S, E, I, L, M, R 등)
• @ 연산자로 자기 재귀 표현
• := 로 변수 바인딩
• 간결한 문법 (세미콜론 선택적)
• LLVM 기반 컴파일러
• 완전한 타입 추론

키워드 대조표

타입 매핑

기본 타입

// Rust
let x: i8 = 42;
let y: i16 = 100;
let z: i32 = 1000;
let w: i64 = 10000;
let a: u8 = 255;
let b: u32 = 4294967295;
let f: f32 = 3.14;
let d: f64 = 2.718;
let s: &str = "hello";
let b: bool = true;

# Vais
x := 42i8
y := 100i16
z := 1000i32
w := 10000          # i64가 기본
a := 255u8
b := 4294967295u32
f := 3.14f32
d := 2.718          # f64가 기본
s := "hello"        # str 타입
b := true           # bool 타입

컬렉션 타입

// Rust
let arr: [i32; 3] = [1, 2, 3];
let vec: Vec<i32> = vec![1, 2, 3];
let opt: Option<i32> = Some(42);
let res: Result<i32, String> = Ok(42);

# Vais
arr := [1, 2, 3]              # [i32; 3]
vec := Vec::new()             # Vec<i32>
opt := Some(42)               # Option<i32>
res := Ok(42)                 # Result<i32, str>

함수 정의

기본 함수

// Rust
fn add(a: i64, b: i64) -> i64 {
    a + b
}

fn greet(name: &str) -> String {
    format!("Hello, {}", name)
}

# Vais
F add(a: i64, b: i64) -> i64 = a + b

F greet(name: str) -> str {
    "Hello, " + name
}

제네릭 함수

// Rust
fn identity<T>(x: T) -> T {
    x
}

fn max<T: Ord>(a: T, b: T) -> T {
    if a > b { a } else { b }
}

# Vais
F identity<T>(x: T) -> T = x

F max<T: Ord>(a: T, b: T) -> T {
    I a > b { a } E { b }
}

메서드

// Rust
impl Point {
    fn new(x: f64, y: f64) -> Self {
        Point { x, y }
    }

    fn distance(&self) -> f64 {
        (self.x * self.x + self.y * self.y).sqrt()
    }
}

# Vais
X Point {
    F new(x: f64, y: f64) -> Point {
        Point { x, y }
    }

    F distance(&self) -> f64 {
        (self.x * self.x + self.y * self.y).sqrt()
    }
}

구조체

// Rust
struct Point {
    x: f64,
    y: f64,
}

struct Rectangle {
    top_left: Point,
    width: f64,
    height: f64,
}

// 튜플 구조체
struct Color(u8, u8, u8);

# Vais
S Point {
    x: f64,
    y: f64,
}

S Rectangle {
    top_left: Point,
    width: f64,
    height: f64,
}

# 튜플 구조체
S Color(u8, u8, u8)

열거형

기본 열거형

// Rust
enum Color {
    Red,
    Green,
    Blue,
}

enum Message {
    Quit,
    Move { x: i32, y: i32 },
    Write(String),
    ChangeColor(u8, u8, u8),
}

# Vais
E Color {
    Red,
    Green,
    Blue,
}

E Message {
    Quit,
    Move { x: i32, y: i32 },
    Write(str),
    ChangeColor(u8, u8, u8),
}

Option과 Result

// Rust
fn divide(a: i64, b: i64) -> Option<i64> {
    if b == 0 {
        None
    } else {
        Some(a / b)
    }
}

fn parse_number(s: &str) -> Result<i64, String> {
    s.parse().map_err(|_| "Invalid number".to_string())
}

# Vais
F divide(a: i64, b: i64) -> Option<i64> {
    I b == 0 {
        None
    } E {
        Some(a / b)
    }
}

F parse_number(s: str) -> Result<i64, str> {
    # parse 함수 사용
    parse_i64(s)
}

에러 처리

? 연산자

// Rust
fn read_file(path: &str) -> Result<String, std::io::Error> {
    let content = std::fs::read_to_string(path)?;
    Ok(content.to_uppercase())
}

fn process() -> Result<i64, String> {
    let x = parse_number("42")?;
    let y = parse_number("10")?;
    Ok(x + y)
}

# Vais
U std/io

F read_file(path: str) -> Result<str, str> {
    content := read_to_string(path)?
    R Ok(content.to_uppercase())
}

F process() -> Result<i64, str> {
    x := parse_number("42")?
    y := parse_number("10")?
    R Ok(x + y)
}

unwrap/expect

// Rust
let x = Some(42).unwrap();
let y = parse_number("100").expect("Failed to parse");

# Vais
x := Some(42)!          # ! = unwrap
y := parse_number("100")!

패턴 매칭

기본 매칭

// Rust
fn describe(n: i32) -> &'static str {
    match n {
        0 => "zero",
        1 => "one",
        2..=10 => "small",
        _ => "large",
    }
}

# Vais
F describe(n: i32) -> str {
    M n {
        0 => "zero",
        1 => "one",
        2..=10 => "small",
        _ => "large",
    }
}

열거형 매칭

// Rust
fn area(shape: Shape) -> f64 {
    match shape {
        Shape::Circle(r) => 3.14159 * r * r,
        Shape::Rectangle(w, h) => w * h,
        Shape::Triangle(b, h) => 0.5 * b * h,
    }
}

# Vais
F area(shape: Shape) -> f64 {
    M shape {
        Circle(r) => 3.14159 * r * r,
        Rectangle(w, h) => w * h,
        Triangle(b, h) => 0.5 * b * h,
    }
}

Option/Result 매칭

// Rust
fn process_option(opt: Option<i32>) -> i32 {
    match opt {
        Some(x) => x * 2,
        None => 0,
    }
}

fn process_result(res: Result<i32, String>) -> i32 {
    match res {
        Ok(x) => x,
        Err(_) => -1,
    }
}

# Vais
F process_option(opt: Option<i32>) -> i32 {
    M opt {
        Some(x) => x * 2,
        None => 0,
    }
}

F process_result(res: Result<i32, str>) -> i32 {
    M res {
        Ok(x) => x,
        Err(_) => -1,
    }
}

트레이트와 Impl

트레이트 정의

// Rust
trait Display {
    fn display(&self) -> String;
}

trait Add<T> {
    type Output;
    fn add(self, rhs: T) -> Self::Output;
}

# Vais
W Display {
    F display(&self) -> str;
}

W Add<T> {
    T Output;
    F add(self, rhs: T) -> Output;
}

트레이트 구현

// Rust
impl Display for Point {
    fn display(&self) -> String {
        format!("({}, {})", self.x, self.y)
    }
}

impl Add<Point> for Point {
    type Output = Point;

    fn add(self, rhs: Point) -> Point {
        Point {
            x: self.x + rhs.x,
            y: self.y + rhs.y,
        }
    }
}

# Vais
X Point: Display {
    F display(&self) -> str {
        "(" + self.x.to_string() + ", " + self.y.to_string() + ")"
    }
}

X Point: Add<Point> {
    T Output = Point;

    F add(self, rhs: Point) -> Point {
        Point {
            x: self.x + rhs.x,
            y: self.y + rhs.y,
        }
    }
}

제네릭 제약

// Rust
fn print_if_display<T: Display>(value: T) {
    println!("{}", value.display());
}

fn compare<T: Ord + Clone>(a: T, b: T) -> T {
    if a > b { a.clone() } else { b.clone() }
}

# Vais
F print_if_display<T: Display>(value: T) {
    println(value.display())
}

F compare<T: Ord + Clone>(a: T, b: T) -> T {
    I a > b { a.clone() } E { b.clone() }
}

Async/Await

// Rust
async fn fetch_url(url: &str) -> Result<String, reqwest::Error> {
    let response = reqwest::get(url).await?;
    let body = response.text().await?;
    Ok(body)
}

async fn process_data() -> Result<(), Box<dyn std::error::Error>> {
    let data1 = fetch_url("https://api.example.com/1").await?;
    let data2 = fetch_url("https://api.example.com/2").await?;

    // Process data...

    Ok(())
}

# Vais
A F fetch_url(url: str) -> Result<str, str> {
    response := http_get(url).Y
    body := response.text().Y
    R Ok(body)
}

A F process_data() -> Result<(), str> {
    data1 := fetch_url("https://api.example.com/1").Y
    data2 := fetch_url("https://api.example.com/2").Y

    # Process data...

    R Ok(())
}

소유권과 차용

소유권 이동

// Rust
fn take_ownership(s: String) {
    println!("{}", s);
}

fn main() {
    let s = String::from("hello");
    take_ownership(s);
    // s는 더 이상 사용 불가
}

# Vais
F take_ownership(s: str) {
    println(s)
}

F main() {
    s := "hello"
    take_ownership(s)
    # s는 더 이상 사용 불가
}

참조와 차용

// Rust
fn calculate_length(s: &String) -> usize {
    s.len()
}

fn append(s: &mut String, suffix: &str) {
    s.push_str(suffix);
}

fn main() {
    let s = String::from("hello");
    let len = calculate_length(&s);

    let mut s2 = String::from("hello");
    append(&mut s2, " world");
}

# Vais
F calculate_length(s: &str) -> i64 {
    s.len()
}

F append(s: &mut str, suffix: str) {
    s.push_str(suffix)
}

F main() {
    s := "hello"
    len := calculate_length(&s)

    s2 := mut "hello"
    append(&mut s2, " world")
}

모듈 시스템

모듈 정의와 사용

// Rust
// math.rs
pub fn add(a: i64, b: i64) -> i64 {
    a + b
}

pub fn multiply(a: i64, b: i64) -> i64 {
    a * b
}

// main.rs
mod math;
use math::{add, multiply};

fn main() {
    let sum = add(1, 2);
    let product = multiply(3, 4);
}

# Vais
# math.vais
F add(a: i64, b: i64) -> i64 = a + b
F multiply(a: i64, b: i64) -> i64 = a * b

# main.vais
U math

F main() {
    sum := add(1, 2)
    product := multiply(3, 4)
}

표준 라이브러리 사용

// Rust
use std::collections::HashMap;
use std::fs::File;
use std::io::{self, Read};

fn main() -> io::Result<()> {
    let mut file = File::open("data.txt")?;
    let mut contents = String::new();
    file.read_to_string(&mut contents)?;

    let mut map = HashMap::new();
    map.insert("key", "value");

    Ok(())
}

# Vais
U std/collections
U std/io

F main() -> Result<(), str> {
    file := File::open("data.txt")?
    contents := file.read_to_string()?

    map := HashMap::new()
    map.insert("key", "value")

    R Ok(())
}

자기 재귀 (@ 연산자)

Vais의 독특한 기능 중 하나는 @ 연산자를 사용한 자기 재귀입니다.

// Rust
fn factorial(n: i64) -> i64 {
    if n <= 1 {
        1
    } else {
        n * factorial(n - 1)
    }
}

fn fibonacci(n: i64) -> i64 {
    if n <= 1 {
        n
    } else {
        fibonacci(n - 1) + fibonacci(n - 2)
    }
}

# Vais
F factorial(n: i64) -> i64 {
    I n <= 1 { 1 } E { n * @(n - 1) }
}

F fibonacci(n: i64) -> i64 {
    I n <= 1 { n } E { @(n - 1) + @(n - 2) }
}

루프

무한 루프

// Rust
loop {
    if should_break {
        break;
    }
    // work...
}

# Vais
L {
    I should_break { B }
    # work...
}

while 루프 스타일

// Rust
let mut i = 0;
while i < 10 {
    println!("{}", i);
    i += 1;
}

# Vais
i := mut 0
L {
    I i >= 10 { B }
    println(i)
    i = i + 1
}

for 루프 스타일 (iterator)

// Rust
for i in 0..10 {
    println!("{}", i);
}

for item in vec.iter() {
    println!("{}", item);
}

# Vais
# Range iterator 사용
range := 0..10
L {
    opt := range.next()
    M opt {
        Some(i) => println(i),
        None => B,
    }
}

# Vec iterator 사용
iter := vec.iter()
L {
    opt := iter.next()
    M opt {
        Some(item) => println(item),
        None => B,
    }
}

마무리

Vais는 Rust의 강력한 타입 시스템과 소유권 모델을 유지하면서도 더 간결한 문법을 제공합니다. 주요 차이점은:

1. 단일 문자 키워드: 코드 길이 단축 및 AI 최적화
2. @ 연산자: 재귀 호출을 명시적으로 표현
3. := 바인딩: let 대신 간결한 표기
4. 표현식 중심: 대부분의 구문이 값을 반환
5. 간소화된 모듈 시스템: U 키워드로 통합

Rust 개발자라면 Vais의 학습 곡선이 매우 낮을 것입니다. 기존 Rust 코드를 Vais로 포팅할 때는 주로 키워드만 변경하면 됩니다.

C/C++에서 Vais로 전환하기

개요

Vais는 C/C++와 달리 현대적인 타입 시스템, 메모리 안전성, 그리고 AI 최적화 문법을 제공합니다. C/C++ 개발자를 위해 주요 차이점과 전환 가이드를 제공합니다.

주요 개선사항:

• 메모리 안전성: 자동 메모리 관리, 댕글링 포인터 방지
• 타입 안전성: 강력한 타입 추론, 컴파일 타임 체크
• 에러 처리: errno 대신 Result<T, E> 타입
• 제네릭: 템플릿보다 간결하고 명확한 제네릭
• 모던 문법: 단일 문자 키워드로 간결한 코드

키워드 대조표

타입 매핑

기본 타입

// C
char c = 'a';
short s = 100;
int i = 1000;
long l = 100000L;
unsigned int ui = 4000000000U;

float f = 3.14f;
double d = 2.718;

const char* str = "hello";
void* ptr = malloc(100);

# Vais
c := 'a'              # char (u8)
s := 100i16           # i16
i := 1000i32          # i32
l := 100000           # i64 (기본)
ui := 4000000000u32   # u32

f := 3.14f32          # f32
d := 2.718            # f64 (기본)

str := "hello"        # str 타입
ptr := malloc(100)    # 포인터

배열과 포인터

// C
int arr[5] = {1, 2, 3, 4, 5};
int* ptr = arr;

int** matrix = (int**)malloc(10 * sizeof(int*));
for (int i = 0; i < 10; i++) {
    matrix[i] = (int*)malloc(10 * sizeof(int));
}

# Vais
arr := [1, 2, 3, 4, 5]     # [i32; 5] 배열
ptr := &arr[0]              # 포인터

# Vec 사용 (동적 배열)
matrix := Vec::new()
i := mut 0
L {
    I i >= 10 { B }
    row := Vec::new()
    matrix.push(row)
    i = i + 1
}

함수 정의

기본 함수

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

double square(double x) {
    return x * x;
}

void print_message(const char* msg) {
    printf("%s\n", msg);
}

# Vais
F add(a: i32, b: i32) -> i32 = a + b

F square(x: f64) -> f64 = x * x

F print_message(msg: str) {
    println(msg)
}

함수 포인터

// C
typedef int (*BinaryOp)(int, int);

int apply(int a, int b, BinaryOp op) {
    return op(a, b);
}

int multiply(int a, int b) {
    return a * b;
}

int main() {
    int result = apply(3, 4, multiply);
    return 0;
}

# Vais
T BinaryOp = F(i32, i32) -> i32

F apply(a: i32, b: i32, op: BinaryOp) -> i32 {
    R op(a, b)
}

F multiply(a: i32, b: i32) -> i32 = a * b

F main() -> i32 {
    result := apply(3, 4, multiply)
    R result
}

구조체

구조체 정의

// C
struct Point {
    double x;
    double y;
};

struct Rectangle {
    struct Point top_left;
    double width;
    double height;
};

typedef struct {
    int r;
    int g;
    int b;
} Color;

# Vais
S Point {
    x: f64,
    y: f64,
}

S Rectangle {
    top_left: Point,
    width: f64,
    height: f64,
}

S Color {
    r: i32,
    g: i32,
    b: i32,
}

구조체 메서드

// C
struct Point {
    double x;
    double y;
};

double point_distance(const struct Point* p) {
    return sqrt(p->x * p->x + p->y * p->y);
}

struct Point point_new(double x, double y) {
    struct Point p = {x, y};
    return p;
}

# Vais
S Point {
    x: f64,
    y: f64,
}

X Point {
    F new(x: f64, y: f64) -> Point {
        Point { x, y }
    }

    F distance(&self) -> f64 {
        (self.x * self.x + self.y * self.y).sqrt()
    }
}

# 사용
F main() {
    p := Point::new(3.0, 4.0)
    d := p.distance()    # 5.0
}

포인터와 메모리

포인터 사용

// C
void swap(int* a, int* b) {
    int temp = *a;
    *a = *b;
    *b = temp;
}

int main() {
    int x = 10, y = 20;
    swap(&x, &y);
    printf("x=%d, y=%d\n", x, y);
    return 0;
}

# Vais
F swap(a: &mut i32, b: &mut i32) {
    temp := *a
    *a = *b
    *b = temp
}

F main() {
    x := mut 10
    y := mut 20
    swap(&mut x, &mut y)
    println("x=" + x.to_string() + ", y=" + y.to_string())
}

동적 메모리 할당

// C
int* allocate_array(size_t n) {
    int* arr = (int*)malloc(n * sizeof(int));
    if (arr == NULL) {
        return NULL;
    }
    for (size_t i = 0; i < n; i++) {
        arr[i] = i;
    }
    return arr;
}

void use_array() {
    int* arr = allocate_array(10);
    if (arr != NULL) {
        // use arr...
        free(arr);
    }
}

# Vais
F allocate_array(n: i64) -> Vec<i32> {
    arr := Vec::new()
    i := mut 0
    L {
        I i >= n { B }
        arr.push(i as i32)
        i = i + 1
    }
    R arr
}

F use_array() {
    arr := allocate_array(10)
    # use arr...
    # 자동으로 메모리 해제됨
}

에러 처리

errno vs Result

// C
#include <stdio.h>
#include <errno.h>
#include <string.h>

FILE* open_file(const char* path) {
    FILE* f = fopen(path, "r");
    if (f == NULL) {
        fprintf(stderr, "Error: %s\n", strerror(errno));
        return NULL;
    }
    return f;
}

int read_number(const char* path) {
    FILE* f = open_file(path);
    if (f == NULL) {
        return -1;  // error indicator
    }

    int value;
    if (fscanf(f, "%d", &value) != 1) {
        fclose(f);
        return -1;
    }

    fclose(f);
    return value;
}

# Vais
U std/io

F open_file(path: str) -> Result<File, str> {
    M File::open(path) {
        Ok(f) => Ok(f),
        Err(e) => Err("Failed to open file: " + e),
    }
}

F read_number(path: str) -> Result<i32, str> {
    f := open_file(path)?
    line := f.read_line()?
    number := parse_i32(line)?
    R Ok(number)
}

제네릭

C++ 템플릿 vs Vais 제네릭

// C++
template<typename T>
T max(T a, T b) {
    return (a > b) ? a : b;
}

template<typename T>
class Vec {
private:
    T* data;
    size_t size;
    size_t capacity;

public:
    Vec() : data(nullptr), size(0), capacity(0) {}

    void push(T value) {
        if (size >= capacity) {
            resize();
        }
        data[size++] = value;
    }

    T get(size_t index) const {
        return data[index];
    }
};

# Vais
F max<T: Ord>(a: T, b: T) -> T {
    I a > b { a } E { b }
}

S Vec<T> {
    data: *mut T,
    size: i64,
    capacity: i64,
}

X Vec<T> {
    F new() -> Vec<T> {
        Vec { data: null(), size: 0, capacity: 0 }
    }

    F push(&mut self, value: T) {
        I self.size >= self.capacity {
            self.resize()
        }
        # store value...
        self.size = self.size + 1
    }

    F get(&self, index: i64) -> &T {
        # return reference...
    }
}

열거형

C enum vs Vais enum

// C
enum Color {
    RED,
    GREEN,
    BLUE
};

enum Status {
    OK = 0,
    ERROR = -1,
    PENDING = 1
};

void process_color(enum Color c) {
    switch (c) {
        case RED:
            printf("Red\n");
            break;
        case GREEN:
            printf("Green\n");
            break;
        case BLUE:
            printf("Blue\n");
            break;
    }
}

# Vais
E Color {
    Red,
    Green,
    Blue,
}

E Status {
    Ok,
    Error,
    Pending,
}

F process_color(c: Color) {
    M c {
        Red => println("Red"),
        Green => println("Green"),
        Blue => println("Blue"),
    }
}

값을 가진 열거형 (Tagged Union)

// C
enum ShapeType {
    SHAPE_CIRCLE,
    SHAPE_RECTANGLE
};

struct Shape {
    enum ShapeType type;
    union {
        struct { double radius; } circle;
        struct { double width; double height; } rectangle;
    } data;
};

double shape_area(const struct Shape* s) {
    switch (s->type) {
        case SHAPE_CIRCLE:
            return 3.14159 * s->data.circle.radius * s->data.circle.radius;
        case SHAPE_RECTANGLE:
            return s->data.rectangle.width * s->data.rectangle.height;
        default:
            return 0.0;
    }
}

# Vais
E Shape {
    Circle(f64),
    Rectangle(f64, f64),
}

F shape_area(s: Shape) -> f64 {
    M s {
        Circle(r) => 3.14159 * r * r,
        Rectangle(w, h) => w * h,
    }
}

# 사용
F main() {
    circle := Circle(5.0)
    rect := Rectangle(3.0, 4.0)

    a1 := shape_area(circle)     # 78.54
    a2 := shape_area(rect)        # 12.0
}

매크로

C 전처리기 vs Vais

// C
#define MAX(a, b) ((a) > (b) ? (a) : (b))
#define SQUARE(x) ((x) * (x))
#define PI 3.14159

#ifdef DEBUG
    #define LOG(msg) printf("DEBUG: %s\n", msg)
#else
    #define LOG(msg)
#endif

int main() {
    int x = MAX(10, 20);
    double area = PI * SQUARE(5.0);
    LOG("Starting program");
    return 0;
}

# Vais
# 매크로 대신 인라인 함수 또는 상수 사용
F max(a: i32, b: i32) -> i32 = I a > b { a } E { b }
F square(x: f64) -> f64 = x * x

PI := 3.14159

#[cfg(debug)]
F log(msg: str) {
    println("DEBUG: " + msg)
}

#[cfg(not(debug))]
F log(msg: str) {
    # no-op
}

F main() -> i32 {
    x := max(10, 20)
    area := PI * square(5.0)
    log("Starting program")
    R 0
}

문자열 처리

C 문자열 vs Vais 문자열

// C
#include <string.h>
#include <stdlib.h>

char* concat(const char* a, const char* b) {
    size_t len_a = strlen(a);
    size_t len_b = strlen(b);
    char* result = malloc(len_a + len_b + 1);

    strcpy(result, a);
    strcat(result, b);

    return result;
}

void process_string() {
    const char* s1 = "Hello";
    const char* s2 = " World";
    char* s3 = concat(s1, s2);

    printf("%s\n", s3);

    free(s3);
}

# Vais
F concat(a: str, b: str) -> str {
    R a + b
}

F process_string() {
    s1 := "Hello"
    s2 := " World"
    s3 := concat(s1, s2)

    println(s3)

    # 자동 메모리 해제
}

입출력

C stdio vs Vais I/O

// C
#include <stdio.h>

void write_file(const char* path, const char* content) {
    FILE* f = fopen(path, "w");
    if (f == NULL) {
        fprintf(stderr, "Failed to open file\n");
        return;
    }

    fprintf(f, "%s", content);
    fclose(f);
}

void read_file(const char* path) {
    FILE* f = fopen(path, "r");
    if (f == NULL) {
        fprintf(stderr, "Failed to open file\n");
        return;
    }

    char buffer[256];
    while (fgets(buffer, sizeof(buffer), f) != NULL) {
        printf("%s", buffer);
    }

    fclose(f);
}

# Vais
U std/io

F write_file(path: str, content: str) -> Result<(), str> {
    f := File::create(path)?
    f.write_all(content)?
    R Ok(())
}

F read_file(path: str) -> Result<str, str> {
    f := File::open(path)?
    content := f.read_to_string()?
    R Ok(content)
}

F main() {
    M write_file("test.txt", "Hello, World!") {
        Ok(_) => println("Written successfully"),
        Err(e) => println("Error: " + e),
    }

    M read_file("test.txt") {
        Ok(content) => println(content),
        Err(e) => println("Error: " + e),
    }
}

주요 차이점 요약

메모리 관리

에러 처리

타입 안전성

마무리

Vais는 C/C++의 성능을 유지하면서 다음을 제공합니다:

1. 메모리 안전성: 댕글링 포인터, 이중 해제 방지
2. 타입 안전성: 강력한 타입 시스템, 컴파일 타임 체크
3. 모던 문법: 간결하고 읽기 쉬운 코드
4. 에러 처리: Result/Option으로 명시적 에러 처리
5. 제로 비용 추상화: 런타임 오버헤드 없음

C/C++ 개발자가 Vais로 전환하면 생산성과 안전성이 크게 향상됩니다.

Vais Cookbook — 실전 레시피 모음

이 페이지는 Vais 언어로 자주 사용되는 패턴과 작업을 빠르게 해결할 수 있는 실전 코드 레시피를 제공합니다. 각 레시피는 바로 실행 가능한 완성형 코드입니다.

기본 (Basics)

Hello World

F main() {
  print("Hello, Vais!")
}

명령줄 인수 처리

U std/args

F main() {
  args := get_args()
  I args.len() > 1 {
    print("First argument: ")
    print(args.get(1))
  } E {
    print("No arguments provided")
  }
}

환경변수 읽기

U std/env

F main() {
  path := env_get("PATH")
  M path {
    Some(p) => print(p),
    None => print("PATH not set")
  }
}

문자열 (Strings)

문자열 결합

F main() {
  first := "Hello"
  second := "World"
  result := first + " " + second
  print(result)  # "Hello World"
}

문자열 분할

U std/string

F main() {
  text := "apple,banana,cherry"
  parts := str_split(text, ",")
  I parts.len() > 0 {
    print(parts.get(0))  # "apple"
  }
}

문자열 포맷팅

F main() {
  name := "Alice"
  age := 30
  msg := "Name: " + name + ", Age: " + i64_to_str(age)
  print(msg)
}

문자열 트림 및 대소문자 변환

U std/string

F main() {
  text := "  Hello  "
  trimmed := str_trim(text)
  upper := str_to_upper(trimmed)
  lower := str_to_lower(trimmed)
  print(upper)  # "HELLO"
  print(lower)  # "hello"
}

컬렉션 (Collections)

Vec 생성 및 조작

U std/collections

F main() {
  v := Vec::new<i64>()
  v.push(10)
  v.push(20)
  v.push(30)

  I v.len() > 0 {
    first := v.get(0)
    print(i64_to_str(first))  # "10"
  }
}

HashMap 사용

U std/collections

F main() {
  map := HashMap::new<str, i64>()
  map.insert("apple", 5)
  map.insert("banana", 10)

  M map.get("apple") {
    Some(val) => print(i64_to_str(val)),  # "5"
    None => print("Not found")
  }
}

정렬

U std/collections

F main() {
  v := Vec::new<i64>()
  v.push(30)
  v.push(10)
  v.push(20)

  v.sort()

  # 정렬 결과: [10, 20, 30]
  L i:0..v.len() {
    print(i64_to_str(v.get(i)))
  }
}

필터 및 맵

U std/collections

F is_even(x: i64) -> bool {
  x % 2 == 0
}

F double(x: i64) -> i64 {
  x * 2
}

F main() {
  v := Vec::new<i64>()
  v.push(1)
  v.push(2)
  v.push(3)
  v.push(4)

  evens := v.filter(is_even)
  doubled := evens.map(double)

  # 결과: [4, 8]
}

파일 I/O

파일 읽기

U std/io

F main() {
  content := file_read("input.txt")
  M content {
    Ok(data) => print(data),
    Err(e) => print("Error reading file")
  }
}

파일 쓰기

U std/io

F main() {
  result := file_write("output.txt", "Hello, file!")
  M result {
    Ok(_) => print("Write successful"),
    Err(e) => print("Write failed")
  }
}

디렉토리 탐색

U std/io

F main() {
  entries := dir_read(".")
  M entries {
    Ok(files) => {
      L i:0..files.len() {
        print(files.get(i))
      }
    },
    Err(e) => print("Error reading directory")
  }
}

CSV 파싱

U std/string

F main() {
  csv := "name,age,city\nAlice,30,NYC\nBob,25,LA"
  lines := str_split(csv, "\n")

  L i:1..lines.len() {
    line := lines.get(i)
    fields := str_split(line, ",")
    I fields.len() >= 3 {
      name := fields.get(0)
      age := fields.get(1)
      city := fields.get(2)
      print("Name: " + name + ", Age: " + age + ", City: " + city)
    }
  }
}

에러 처리 (Error Handling)

Result 체이닝

U std/io

F process_file(path: str) -> Result<i64, str> {
  content := file_read(path)?
  len := str_len(content)
  Ok(len)
}

F main() {
  M process_file("data.txt") {
    Ok(len) => print("File length: " + i64_to_str(len)),
    Err(e) => print("Error: " + e)
  }
}

? 연산자 사용

U std/io

F read_and_parse(path: str) -> Result<i64, str> {
  content := file_read(path)?
  num := str_to_i64(content)?
  Ok(num * 2)
}

F main() {
  result := read_and_parse("number.txt")
  M result {
    Ok(n) => print(i64_to_str(n)),
    Err(e) => print("Failed: " + e)
  }
}

커스텀 에러 타입

E MyError {
  NotFound(str),
  InvalidInput(str),
  IoError(str)
}

F find_user(id: i64) -> Result<str, MyError> {
  I id < 0 {
    R Err(MyError::InvalidInput("ID must be positive"))
  }
  I id > 1000 {
    R Err(MyError::NotFound("User not found"))
  }
  Ok("User_" + i64_to_str(id))
}

F main() {
  M find_user(1500) {
    Ok(user) => print(user),
    Err(MyError::NotFound(msg)) => print("Not found: " + msg),
    Err(MyError::InvalidInput(msg)) => print("Invalid: " + msg),
    Err(_) => print("Unknown error")
  }
}

비동기 (Async)

기본 async/await

A F fetch_data() -> str {
  # 비동기 작업 시뮬레이션
  R "Data fetched"
}

A F main() {
  result := fetch_data().Y
  print(result)
}

HTTP 요청

U std/http

A F fetch_url(url: str) -> Result<str, str> {
  response := http_get(url).Y?
  Ok(response.body)
}

A F main() {
  M fetch_url("https://api.example.com/data").Y {
    Ok(body) => print(body),
    Err(e) => print("HTTP error: " + e)
  }
}

동시 작업

U std/async

A F task1() -> i64 {
  R 42
}

A F task2() -> i64 {
  R 100
}

A F main() {
  future1 := spawn(task1())
  future2 := spawn(task2())

  result1 := future1.Y
  result2 := future2.Y

  total := result1 + result2
  print("Total: " + i64_to_str(total))  # "Total: 142"
}

FFI (Foreign Function Interface)

C 함수 호출

extern F strlen(s: i64) -> i64

F main() {
  text := "Hello"
  ptr := str_to_ptr(text)
  length := strlen(ptr)
  print("Length: " + i64_to_str(length))  # "Length: 5"
}

공유 라이브러리 사용

extern F my_c_function(x: i64) -> i64

F main() {
  result := my_c_function(10)
  print(i64_to_str(result))
}

JSON

JSON 파싱

U std/json

F main() {
  json_str := "{\"name\":\"Alice\",\"age\":30}"
  parsed := json_parse(json_str)

  M parsed {
    Ok(obj) => {
      name := json_get_string(obj, "name")
      age := json_get_i64(obj, "age")
      print("Name: " + name)
      print("Age: " + i64_to_str(age))
    },
    Err(e) => print("Parse error")
  }
}

JSON 생성

U std/json

F main() {
  obj := json_object_new()
  json_set_string(obj, "name", "Bob")
  json_set_i64(obj, "age", 25)
  json_set_bool(obj, "active", true)

  json_str := json_stringify(obj)
  print(json_str)  # {"name":"Bob","age":25,"active":true}
}

JSON 배열

U std/json

F main() {
  arr := json_array_new()
  json_array_push_i64(arr, 10)
  json_array_push_i64(arr, 20)
  json_array_push_i64(arr, 30)

  json_str := json_stringify(arr)
  print(json_str)  # [10,20,30]
}

네트워킹 (Networking)

TCP 서버

U std/net

F handle_client(conn: TcpStream) {
  msg := tcp_read(conn)
  M msg {
    Ok(data) => {
      response := "Echo: " + data
      tcp_write(conn, response)
    },
    Err(e) => print("Read error")
  }
  tcp_close(conn)
}

F main() {
  listener := tcp_listen("127.0.0.1:8080")
  M listener {
    Ok(l) => {
      print("Server listening on :8080")
      L {
        M tcp_accept(l) {
          Ok(conn) => handle_client(conn),
          Err(e) => print("Accept error")
        }
      }
    },
    Err(e) => print("Listen error")
  }
}

HTTP 서버

U std/http

F handler(req: HttpRequest) -> HttpResponse {
  I req.path == "/" {
    R http_response(200, "Hello, HTTP!")
  } E {
    R http_response(404, "Not Found")
  }
}

F main() {
  server := http_server_new("127.0.0.1:8000", handler)
  M server {
    Ok(s) => {
      print("HTTP server running on :8000")
      http_serve(s)
    },
    Err(e) => print("Server error")
  }
}

WebSocket 서버

U std/websocket

F on_message(conn: WsConnection, msg: str) {
  print("Received: " + msg)
  ws_send(conn, "Echo: " + msg)
}

F main() {
  server := ws_server_new("127.0.0.1:9000", on_message)
  M server {
    Ok(s) => {
      print("WebSocket server on :9000")
      ws_serve(s)
    },
    Err(e) => print("WS error")
  }
}

동시성 (Concurrency)

스레드 생성

U std/thread

F worker(id: i64) {
  print("Worker " + i64_to_str(id) + " started")
}

F main() {
  t1 := thread_spawn(|| { worker(1) })
  t2 := thread_spawn(|| { worker(2) })

  thread_join(t1)
  thread_join(t2)

  print("All workers done")
}

뮤텍스 (Mutex)

U std/sync

F main() {
  counter := mutex_new(0)

  t1 := thread_spawn(|| {
    L i:0..1000 {
      mutex_lock(counter)
      val := mutex_get(counter)
      mutex_set(counter, val + 1)
      mutex_unlock(counter)
    }
  })

  thread_join(t1)

  final_val := mutex_get(counter)
  print("Counter: " + i64_to_str(final_val))
}

채널 (Channel)

U std/channel

F sender(ch: Channel<i64>) {
  L i:0..10 {
    channel_send(ch, i)
  }
  channel_close(ch)
}

F main() {
  ch := channel_new<i64>()

  thread_spawn(|| { sender(ch) })

  L {
    M channel_recv(ch) {
      Ok(val) => print(i64_to_str(val)),
      Err(_) => B  # 채널 닫힘
    }
  }

  print("All messages received")
}

여러 채널 select

U std/channel

F main() {
  ch1 := channel_new<i64>()
  ch2 := channel_new<i64>()

  thread_spawn(|| { channel_send(ch1, 10) })
  thread_spawn(|| { channel_send(ch2, 20) })

  set := channel_set_new()
  channel_set_add(set, ch1)
  channel_set_add(set, ch2)

  M channel_select(set) {
    Ok((ch, val)) => print("Received: " + i64_to_str(val)),
    Err(_) => print("No data")
  }
}

추가 팁

Self-Recursion (@)

F factorial(n: i64) -> i64 {
  I n <= 1 {
    R 1
  }
  R n * @(n - 1)  # @ = self-recursion
}

F main() {
  result := factorial(5)
  print(i64_to_str(result))  # "120"
}

Ternary 연산자

F main() {
  x := 10
  sign := x >= 0 ? "positive" : "negative"
  print(sign)  # "positive"
}

Range 반복

F main() {
  L i:0..10 {
    print(i64_to_str(i))
  }
  # 0부터 9까지 출력
}

Pattern Matching with Guards

E Status {
  Active(i64),
  Inactive
}

F check_status(s: Status) -> str {
  M s {
    Active(n) I n > 100 => "High activity",
    Active(n) => "Normal activity",
    Inactive => "No activity"
  }
}

F main() {
  status := Status::Active(150)
  msg := check_status(status)
  print(msg)  # "High activity"
}

이 Cookbook은 Vais 언어의 주요 패턴과 관용구를 다룹니다. 더 많은 예제와 심화 내용은 Language Guide와 Standard Library API를 참고하세요.

테스팅 가이드

Vais 프로그램의 품질을 보장하기 위한 테스트 작성 방법을 안내합니다.

개요

Vais는 다양한 수준의 테스트를 지원합니다:

• 단위 테스트: 개별 함수와 모듈의 동작 검증
• 통합 테스트: 여러 모듈 간 상호작용 검증
• 속성 기반 테스트: 무작위 입력으로 속성 검증
• E2E 테스트: 컴파일부터 실행까지 전체 파이프라인 검증
• 벤치마킹: 성능 측정 및 회귀 감지

단위 테스트

기본 테스트 함수

Vais에서 테스트 함수는 test_ 접두사로 시작하는 함수로 작성합니다:

# math.vais
F add(a: i64, b: i64) -> i64 {
    a + b
}

F test_add_positive() {
    assert_eq(add(2, 3), 5)
}

F test_add_negative() {
    assert_eq(add(-5, 3), -2)
}

F test_add_zero() {
    assert_eq(add(0, 0), 0)
}

Assert 빌트인

Vais는 다음 assert 빌트인을 제공합니다:

# 조건 검증
assert(condition)
assert(x > 0)

# 값 동등성 검증
assert_eq(actual, expected)
assert_eq(result, 42)

# 부동소수점 근사 비교 (epsilon: 1e-10)
assert_approx(3.14159, pi(), 0.0001)

구조체 테스트

S Point {
    x: i64,
    y: i64
}

F Point::distance_squared(self) -> i64 {
    self.x * self.x + self.y * self.y
}

F test_point_distance() {
    p := Point { x: 3, y: 4 }
    assert_eq(p.distance_squared(), 25)
}

F test_point_origin() {
    origin := Point { x: 0, y: 0 }
    assert_eq(origin.distance_squared(), 0)
}

Enum 및 패턴 매칭 테스트

E Result<T, E> {
    Ok(T),
    Err(E)
}

F divide(a: i64, b: i64) -> Result<i64, str> {
    I b == 0 {
        R Result::Err("division by zero")
    }
    Result::Ok(a / b)
}

F test_divide_success() {
    result := divide(10, 2)
    M result {
        Result::Ok(val) => assert_eq(val, 5),
        Result::Err(_) => assert(false)
    }
}

F test_divide_by_zero() {
    result := divide(10, 0)
    M result {
        Result::Ok(_) => assert(false),
        Result::Err(msg) => assert_eq(msg, "division by zero")
    }
}

통합 테스트

모듈 간 테스트

여러 모듈을 조합하여 테스트합니다:

# tests/integration_test.vais
U std/vec
U std/string

F test_vec_operations() {
    v := Vec::new()
    v.push(10)
    v.push(20)
    v.push(30)

    assert_eq(v.len(), 3)
    assert_eq(v.get(0), 10)
    assert_eq(v.get(2), 30)
}

F test_string_manipulation() {
    s := String::from("hello")
    s.push_str(" world")

    assert_eq(s.len(), 11)
    assert_eq(s.as_str(), "hello world")
}

파일 I/O 테스트

U std/fs

F test_file_roundtrip() {
    path := "/tmp/test.txt"
    content := "test data"

    # 파일 쓰기
    fs::write_file(path, content)

    # 파일 읽기
    read_content := fs::read_file(path)
    assert_eq(read_content, content)

    # 정리
    fs::remove_file(path)
}

속성 기반 테스트

vais-testgen 크레이트를 사용하여 속성 기반 테스트를 작성할 수 있습니다:

U vais_testgen/property

# 속성: 리스트를 정렬한 후 뒤집으면 내림차순 정렬과 같다
F prop_sort_reverse() {
    gen := property::list_i64(100)

    property::check(gen, |xs| {
        sorted := xs.sort()
        reversed := sorted.reverse()
        descending := xs.sort_by(|a, b| b - a)

        assert_eq(reversed, descending)
    })
}

# 속성: 문자열 연결은 결합법칙을 만족한다
F prop_string_concat_associative() {
    gen := property::string_gen(50)

    property::check_triple(gen, |a, b, c| {
        left := a.concat(b).concat(c)
        right := a.concat(b.concat(c))

        assert_eq(left, right)
    })
}

E2E 테스트

컴파일 및 실행 테스트

# 컴파일 성공 테스트
vaisc examples/hello.vais -o hello
./hello

# 출력 검증
output=$(./hello)
test "$output" = "Hello, Vais!"

# 종료 코드 검증
./hello
test $? -eq 0

에러 케이스 테스트

# 컴파일 에러 테스트
vaisc examples/invalid.vais 2>&1 | grep "E032: Type inference failed"

# 런타임 에러 테스트 (예상된 panic)
vaisc examples/bounds_check.vais -o bounds_check
! ./bounds_check  # 실패가 예상되므로 ! 사용

Rust 기반 E2E 테스트

// crates/vaisc/tests/e2e_tests.rs
#[test]
fn test_fibonacci() {
    let output = std::process::Command::new("cargo")
        .args(&["run", "--bin", "vaisc", "--", "examples/fibonacci.vais"])
        .output()
        .expect("Failed to execute vaisc");

    assert!(output.status.success());

    // 컴파일된 바이너리 실행
    let result = std::process::Command::new("./fibonacci")
        .output()
        .expect("Failed to execute fibonacci");

    assert_eq!(String::from_utf8_lossy(&result.stdout), "55\n");
}

벤치마킹

Criterion 기반 벤치마크 (Rust)

// benches/my_benchmark.rs
use criterion::{black_box, criterion_group, criterion_main, Criterion};
use vais_parser::Parser;
use vais_lexer::tokenize;

fn bench_parser(c: &mut Criterion) {
    let source = std::fs::read_to_string("examples/large.vais").unwrap();
    let tokens = tokenize(&source).unwrap();

    c.bench_function("parse_large_file", |b| {
        b.iter(|| {
            let mut parser = Parser::new(black_box(&tokens));
            parser.parse_module()
        })
    });
}

criterion_group!(benches, bench_parser);
criterion_main!(benches);

런타임 벤치마크 (Vais)

# benches/bench_sorting.vais
U std/vec
U std/time

F benchmark_bubble_sort(size: i64) -> i64 {
    v := Vec::with_capacity(size)

    # 무작위 데이터 생성
    L i:0..size {
        v.push(size - i)
    }

    start := time::now_micros()
    bubble_sort(&v)
    end := time::now_micros()

    end - start  # 마이크로초 단위 반환
}

F bubble_sort(arr: &mut Vec<i64>) {
    n := arr.len()
    L i:0..n {
        L j:0..(n - i - 1) {
            I arr.get(j) > arr.get(j + 1) {
                swap(arr, j, j + 1)
            }
        }
    }
}

F main() -> i64 {
    time_1k := benchmark_bubble_sort(1000)
    time_5k := benchmark_bubble_sort(5000)

    print_i64(time_1k)
    print_i64(time_5k)

    0
}

컴파일 후 실행:

vaisc benches/bench_sorting.vais --emit-ir -o bench_sorting.ll
clang bench_sorting.ll -o bench_sorting -lm
./bench_sorting

코드 커버리지

LLVM Source-Based Coverage

Vais 컴파일러는 --coverage 플래그로 LLVM 커버리지를 지원합니다:

# 커버리지 활성화하여 컴파일
vaisc --coverage src/main.vais -o main

# 실행하여 프로파일 생성
./main  # default.profraw 생성됨

# HTML 리포트 생성
llvm-profdata merge -sparse default.profraw -o default.profdata
llvm-cov show ./main -instr-profile=default.profdata -format=html > coverage.html

Rust 컴파일러 커버리지

# Rust 컴파일러 테스트 커버리지
cargo install cargo-llvm-cov
cargo llvm-cov --html --open

CI 통합

GitHub Actions 워크플로우

# .github/workflows/test.yml
name: Test

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Install LLVM 17
        run: |
          wget https://apt.llvm.org/llvm.sh
          chmod +x llvm.sh
          sudo ./llvm.sh 17

      - name: Setup Rust
        uses: actions-rs/toolchain@v1
        with:
          toolchain: stable
          override: true

      - name: Run tests
        run: cargo test --workspace

      - name: Run clippy
        run: cargo clippy --workspace -- -D warnings

      - name: E2E tests
        run: |
          cargo build --release
          ./target/release/vaisc examples/hello.vais -o hello
          ./hello

커버리지 리포팅

# codecov 통합
- name: Generate coverage
  run: cargo llvm-cov --lcov --output-path lcov.info

- name: Upload to codecov
  uses: codecov/codecov-action@v3
  with:
    files: lcov.info

테스트 조직화

디렉토리 구조

my_project/
├── src/
│   ├── main.vais
│   ├── lib.vais
│   └── utils.vais
├── tests/
│   ├── unit/
│   │   ├── test_lib.vais
│   │   └── test_utils.vais
│   ├── integration/
│   │   └── test_full_pipeline.vais
│   └── e2e/
│       └── test_cli.sh
└── benches/
    └── bench_performance.vais

테스트 명명 규칙

• 단위 테스트: test_<function_name>_<scenario>
• 통합 테스트: test_<module>_<interaction>
• E2E 테스트: test_e2e_<feature>
• 벤치마크: bench_<operation>_<size>

모범 사례

1. 독립성: 각 테스트는 독립적으로 실행 가능해야 합니다
2. 결정성: 테스트 결과는 항상 동일해야 합니다
3. 빠른 실행: 단위 테스트는 밀리초 단위로 실행되어야 합니다
4. 명확한 실패 메시지: assert 시 의미 있는 메시지를 포함합니다
5. 경계 조건: 0, 음수, 최대값 등 경계 케이스를 테스트합니다
6. 에러 경로: 정상 경로뿐만 아니라 에러 경로도 테스트합니다

추가 자료

• Vais 표준 라이브러리
• 컴파일러 아키텍처
• CI/CD 가이드
• 벤치마크 결과

에러 처리 모범 사례

개요

Vais는 예외(exceptions) 대신 명시적인 에러 타입을 사용하는 시스템 프로그래밍 언어입니다. 모든 실패 가능한 연산은 Result<T, E> 또는 Option<T> 타입을 반환하여 컴파일 타임에 에러 처리를 강제합니다.

핵심 원칙

• 명시성: 함수 시그니처에서 에러 가능성이 드러남
• 타입 안전성: 컴파일러가 처리되지 않은 에러를 감지
• 제로 비용 추상화: 런타임 오버헤드 없음

Result<T, E> 패턴

기본 구조

Result enum은 성공(Ok)과 실패(Err) 두 가지 상태를 표현합니다:

E Result<T, E> {
    Ok(T),
    Err(E)
}

함수에서 Result 반환

U std.io

F read_config(path: str) -> Result<str, str> {
    file := open(path)?
    content := read_to_string(file)?
    close(file)
    Result.Ok(content)
}

? 연산자로 에러 전파

? 연산자는 Result가 Err일 때 즉시 함수에서 반환합니다:

F parse_and_process(data: str) -> Result<i64, str> {
    # parse가 실패하면 즉시 Err 반환
    num := parse_i64(data)?

    # 검증 실패 시 커스텀 에러
    I num < 0 {
        R Result.Err("음수는 허용되지 않습니다")
    }

    Result.Ok(num * 2)
}

! 연산자로 언래핑

! 연산자는 Ok 값을 추출하고, Err일 경우 패닉을 발생시킵니다:

F main() -> i64 {
    # 확실히 성공하는 경우에만 사용
    config := read_config("app.conf")!

    print_str(config)
    0
}

주의: !는 프로토타입이나 테스트 코드에서만 사용하고, 프로덕션 코드에서는 명시적 처리를 권장합니다.

M (match)로 Result 처리

F safe_divide(a: i64, b: i64) -> Result<i64, str> {
    I b == 0 {
        R Result.Err("0으로 나눌 수 없습니다")
    }
    Result.Ok(a / b)
}

F main() -> i64 {
    result := safe_divide(10, 2)

    M result {
        Result.Ok(value) => {
            print_str("결과: ")
            print_i64(value)
        },
        Result.Err(err) => {
            print_str("에러: ")
            print_str(err)
        }
    }

    0
}

Option<T> 패턴

기본 구조

Option은 값이 있을 수도 없을 수도 있는 상황을 표현합니다:

E Option<T> {
    Some(T),
    None
}

널 안전성

F find_user(id: i64) -> Option<str> {
    I id == 1 {
        R Option.Some("Alice")
    }
    Option.None
}

F main() -> i64 {
    user := find_user(1)

    M user {
        Option.Some(name) => {
            print_str("찾은 사용자: ")
            print_str(name)
        },
        Option.None => {
            print_str("사용자를 찾을 수 없습니다")
        }
    }

    0
}

?와 ! 연산자 사용

F get_first_char(s: str) -> Option<i64> {
    I strlen(s) == 0 {
        R Option.None
    }
    Option.Some(load_byte(s, 0))
}

F process_string(s: str) -> Option<i64> {
    # Option에서도 ? 연산자 사용 가능
    first := get_first_char(s)?
    Option.Some(first + 1)
}

F main() -> i64 {
    # ! 연산자로 Some 값 추출 (None이면 패닉)
    ch := get_first_char("Hello")!
    print_i64(ch)
    0
}

커스텀 에러 타입

에러 enum 정의

E FileError {
    NotFound(str),
    PermissionDenied(str),
    IoError(str)
}

F read_file(path: str) -> Result<str, FileError> {
    I !file_exists(path) {
        R Result.Err(FileError.NotFound(path))
    }

    I !can_read(path) {
        R Result.Err(FileError.PermissionDenied(path))
    }

    # 실제 읽기 로직...
    Result.Ok("file content")
}

에러 변환 패턴

E ParseError {
    InvalidFormat(str),
    OutOfRange(i64)
}

F parse_positive_number(s: str) -> Result<i64, ParseError> {
    # 기본 파싱
    M parse_i64(s) {
        Result.Ok(num) => {
            I num < 0 {
                R Result.Err(ParseError.OutOfRange(num))
            }
            Result.Ok(num)
        },
        Result.Err(_) => {
            Result.Err(ParseError.InvalidFormat(s))
        }
    }
}

에러 전파 패턴

? 체이닝

U std.io

F load_and_parse_config(path: str) -> Result<i64, str> {
    content := read_file(path)?
    trimmed := trim(content)?
    number := parse_i64(trimmed)?
    Result.Ok(number)
}

파이프라인에서의 에러 처리

F process_data(input: str) -> Result<i64, str> {
    input
        |> validate_input
        |> parse_number
        |> transform_value
}

F validate_input(s: str) -> Result<str, str> {
    I strlen(s) == 0 {
        R Result.Err("빈 입력")
    }
    Result.Ok(s)
}

F parse_number(s: str) -> Result<i64, str> {
    parse_i64(s)
}

F transform_value(n: i64) -> Result<i64, str> {
    Result.Ok(n * 2)
}

모범 사례

1. 라이브러리 vs 애플리케이션 에러 처리

라이브러리 코드: 항상 Result를 반환하여 호출자가 결정하도록 합니다.

# ✅ 좋은 예: 라이브러리 함수
F lib_parse(data: str) -> Result<i64, str> {
    I strlen(data) == 0 {
        R Result.Err("빈 데이터")
    }
    parse_i64(data)
}

애플리케이션 코드: 최상위에서 에러를 처리하거나 의미 있는 에러 메시지를 제공합니다.

# ✅ 좋은 예: 애플리케이션 엔트리포인트
F main() -> i64 {
    M run_app() {
        Result.Ok(_) => {
            print_str("성공적으로 완료되었습니다")
            0
        },
        Result.Err(e) => {
            print_str("에러: ")
            print_str(e)
            1
        }
    }
}

F run_app() -> Result<i64, str> {
    config := load_config()?
    data := process_data(config)?
    Result.Ok(data)
}

2. 에러 메시지 가이드라인

구체적이고 실행 가능한 정보를 제공하세요:

# ❌ 나쁜 예
F open_file(path: str) -> Result<File, str> {
    Result.Err("에러 발생")
}

# ✅ 좋은 예
F open_file(path: str) -> Result<File, str> {
    I !file_exists(path) {
        R Result.Err("파일을 찾을 수 없습니다: " + path)
    }
    # ...
}

3. 절대 하지 말아야 할 것들

에러 무시하지 않기:

# ❌ 절대 금지
F bad_example() -> i64 {
    _ := might_fail()  # 에러 무시!
    0
}

# ✅ 올바른 방법
F good_example() -> Result<i64, str> {
    might_fail()?
    Result.Ok(0)
}

과도한 ! 사용 금지:

# ❌ 나쁜 예: 프로덕션 코드에서 !
F process() -> i64 {
    data := read_file("data.txt")!
    parse_i64(data)!
}

# ✅ 좋은 예: 명시적 에러 처리
F process() -> Result<i64, str> {
    data := read_file("data.txt")?
    parse_i64(data)
}

실전 예제

파일 읽기 에러 처리

U std.io

E FileError {
    NotFound(str),
    ReadError(str)
}

F read_config_file(path: str) -> Result<str, FileError> {
    # 파일 존재 확인
    I !file_exists(path) {
        R Result.Err(FileError.NotFound(path))
    }

    # 파일 열기
    file := M open(path) {
        Result.Ok(f) => f,
        Result.Err(e) => {
            R Result.Err(FileError.ReadError(e))
        }
    }

    # 내용 읽기
    content := M read_to_string(file) {
        Result.Ok(c) => c,
        Result.Err(e) => {
            close(file)
            R Result.Err(FileError.ReadError(e))
        }
    }

    close(file)
    Result.Ok(content)
}

F main() -> i64 {
    M read_config_file("config.txt") {
        Result.Ok(content) => {
            print_str("설정 파일 내용: ")
            print_str(content)
            0
        },
        Result.Err(FileError.NotFound(path)) => {
            print_str("파일을 찾을 수 없습니다: ")
            print_str(path)
            1
        },
        Result.Err(FileError.ReadError(msg)) => {
            print_str("읽기 에러: ")
            print_str(msg)
            2
        }
    }
}

네트워크 요청 에러 처리

U std.net

E HttpError {
    ConnectionFailed(str),
    Timeout,
    InvalidResponse(i64)
}

F fetch_data(url: str) -> Result<str, HttpError> {
    # 연결 시도
    conn := M connect(url) {
        Result.Ok(c) => c,
        Result.Err(e) => {
            R Result.Err(HttpError.ConnectionFailed(e))
        }
    }

    # 요청 전송 (타임아웃 5초)
    response := M send_request(conn, 5000) {
        Result.Ok(r) => r,
        Result.Err("timeout") => {
            R Result.Err(HttpError.Timeout)
        },
        Result.Err(e) => {
            R Result.Err(HttpError.ConnectionFailed(e))
        }
    }

    # 상태 코드 확인
    status := get_status_code(response)
    I status != 200 {
        R Result.Err(HttpError.InvalidResponse(status))
    }

    Result.Ok(read_response_body(response))
}

파싱 에러 처리

E JsonError {
    SyntaxError(i64, str),  # line, message
    TypeError(str)
}

F parse_user_json(json: str) -> Result<User, JsonError> {
    # JSON 파싱
    obj := M parse_json(json) {
        Result.Ok(o) => o,
        Result.Err(msg) => {
            line := find_error_line(json, msg)
            R Result.Err(JsonError.SyntaxError(line, msg))
        }
    }

    # 필드 추출
    name := M get_string_field(obj, "name") {
        Result.Ok(n) => n,
        Result.Err(_) => {
            R Result.Err(JsonError.TypeError("name 필드가 없거나 문자열이 아닙니다"))
        }
    }

    age := M get_i64_field(obj, "age") {
        Result.Ok(a) => a,
        Result.Err(_) => {
            R Result.Err(JsonError.TypeError("age 필드가 없거나 숫자가 아닙니다"))
        }
    }

    Result.Ok(User { name: name, age: age })
}

S User {
    name: str,
    age: i64
}

요약

Vais의 에러 처리는 다음 원칙을 따릅니다:

1. 명시적 타입: Result<T, E>와 Option<T>로 실패 가능성 표현
2. ? 연산자: 에러 전파를 간결하게
3. ! 연산자: 프로토타입/테스트 전용, 프로덕션에서는 신중히
4. 패턴 매칭: M으로 모든 경우를 처리
5. 커스텀 에러 타입: 도메인 특화 에러로 명확성 향상

이러한 패턴을 통해 Vais는 안전하고 유지보수 가능한 시스템 프로그래밍을 지원합니다.

Ecosystem Packages

Vais provides a growing ecosystem of pure-Vais packages for common tasks. These packages are implemented entirely in Vais, demonstrating the language's capabilities while providing production-ready functionality.

Available Packages

vais-crc32

CRC32 checksum calculation — IEEE 802.3 and Castagnoli (CRC32C) polynomials.

Features:

• IEEE 802.3 (0xEDB88320) polynomial
• Castagnoli/CRC32C (0x82F63B78) polynomial
• 256-entry lookup table for fast computation
• Slice-based API for efficient processing

Usage:

U vais_crc32.{crc32_ieee, crc32_castagnoli}

data := "Hello, Vais!".as_bytes()
checksum := crc32_ieee(data[..])
print_u32(checksum)

Implementation: 256-entry lookup table generated at initialization, then table-driven byte-by-byte XOR operations.

vais-lz4

LZ4 compression and decompression — Pure Vais implementation of the LZ4 algorithm.

Features:

• Block format compression/decompression
• Frame format support (LZ4 framing specification)
• Streaming API for large data
• No unsafe code or external dependencies

Usage:

U vais_lz4.{compress, decompress}

original := "The quick brown fox jumps over the lazy dog"
compressed := compress(original.as_bytes())
decompressed := decompress(compressed[..])

# Round-trip preserves data
print(String::from_bytes(decompressed))

Algorithm:

• Literal run encoding
• Match copy (offset + length)
• Token byte: 4 bits literals length + 4 bits match length
• Optimized for speed over compression ratio

vais-aes

AES-256 encryption — FIPS 197 compliant Advanced Encryption Standard.

Features:

• AES-256 (256-bit key) encryption and decryption
• Block cipher modes: ECB, CBC, CTR
• PKCS7 padding for block alignment
• Pure Vais implementation (S-box, key expansion, round transformations)

Usage:

U vais_aes.{Aes256, BlockMode}

key := [0u8; 32]    # 256-bit key
iv := [0u8; 16]     # Initialization vector (for CBC/CTR)

cipher := Aes256::new(key, BlockMode::CBC, iv)
plaintext := "Secret message".as_bytes()

ciphertext := cipher.encrypt(plaintext[..])
decrypted := cipher.decrypt(ciphertext[..])

print(String::from_bytes(decrypted))    # "Secret message"

Operations:

• SubBytes (S-box substitution)
• ShiftRows
• MixColumns
• AddRoundKey
• Key expansion (14 rounds for AES-256)

vais-json

JSON parser and serializer — Pure Vais JSON implementation with streaming tokenizer.

Features:

• Full JSON spec compliance (RFC 8259)
• Streaming tokenizer for large files
• Unicode escape handling (\uXXXX)
• Pretty-printing with configurable indentation
• Object/Array/String/Number/Bool/Null types

Usage:

U vais_json.{parse, stringify, JsonValue}

# Parsing
json_str := '{"name": "Vais", "version": 1.0, "features": ["fast", "safe"]}'
value := parse(json_str)

M value {
    JsonValue::Object(obj) => {
        name := obj.get("name")
        print(name)    # "Vais"
    },
    _ => {}
}

# Serialization
obj := JsonValue::Object([
    ("language", JsonValue::String("Vais")),
    ("year", JsonValue::Number(2024.0))
])
output := stringify(obj, 2)    # Pretty-print with 2-space indent
print(output)

Architecture:

• Tokenizer: State machine-based lexer
• Parser: Recursive descent
• Serializer: Depth-first traversal with indent tracking

vais-csv

CSV reader and writer — Configurable delimiter, quote handling, and escaping.

Features:

• RFC 4180 compliant
• Configurable delimiter (comma, tab, semicolon, custom)
• Quoted field support
• Escape character handling
• Header row parsing
• Streaming API for large files

Usage:

U vais_csv.{CsvReader, CsvWriter}

# Reading
csv := "name,age,city\nAlice,30,NYC\nBob,25,LA"
reader := CsvReader::new(csv, ',')
rows := reader.read_all()

I rows.len() > 1 {
    header := rows[0]
    first_row := rows[1]
    print(first_row[0])    # "Alice"
}

# Writing
writer := CsvWriter::new(',')
writer.write_row(["name", "age", "city"])
writer.write_row(["Charlie", "35", "SF"])
output := writer.to_string()
print(output)
# name,age,city
# Charlie,35,SF

Implementation:

• State machine parser for quoted/unquoted fields
• Configurable delimiter and quote character
• Efficient string building with minimal allocations

Using Ecosystem Packages

Installation

Packages are distributed as source code. Add them to your project's vais.toml:

[dependencies]
vais-crc32 = { path = "../vais-crc32" }
vais-json = { path = "../vais-json" }

Or install from the registry (when available):

vais pkg add vais-json@1.0.0

Importing

Use the U (use) keyword to import package modules:

U vais_json.{parse, stringify}
U vais_crc32.crc32_ieee
U vais_aes.Aes256

Building

Build your project with dependencies:

vais pkg build

The package manager automatically resolves transitive dependencies and compiles in topological order.

Package Development

Creating a Package

vais pkg init --lib

This creates a new library package with:

• vais.toml manifest
• src/lib.vais entry point
• tests/ directory for tests

Publishing

vais pkg publish

See the Package Manager Guide for details.

Standard Library Integration

Ecosystem packages integrate with the standard library:

• Collections — Use Vec<T>, HashMap<K,V> from std/vec.vais, std/hashmap.vais
• I/O — File operations from std/io.vais
• Strings — String and OwnedString from std/string.vais
• Error Handling — Result<T,E> and Option<T> from std/result.vais

Performance

All ecosystem packages are optimized for performance:

(Benchmarks run on Apple M2, single-threaded)

Contributing

To contribute a new ecosystem package:

1. Design — Propose the API in a GitHub issue
2. Implement — Write pure Vais code (no unsafe blocks)
3. Test — Achieve >90% coverage with unit + integration tests
4. Document — Add usage examples and API docs
5. Benchmark — Compare performance with reference implementations
6. Submit — Open a pull request

See CONTRIBUTING.md for details.

vais-base64

Base64 encoding and decoding — RFC 4648 compliant implementation.

Features:

• Standard Base64 alphabet (A-Z, a-z, 0-9, +, /)
• URL-safe variant (using - and _ instead of + and /)
• Padding support (= character)
• Pure Vais implementation with lookup tables

Usage:

U vais_base64.{encode, decode}

data := "Hello, Vais!".as_bytes()
encoded := encode(data[..])
print(String::from_bytes(encoded))    # "SGVsbG8sIFZhaXMh"

decoded := decode(encoded[..])
print(String::from_bytes(decoded))    # "Hello, Vais!"

Implementation: 6-bit group encoding with base64 alphabet lookup table.

vais-sha256

SHA-256 cryptographic hash — FIPS 180-4 compliant implementation.

Features:

• SHA-256 (256-bit hash output)
• Message scheduling (64 rounds)
• FIPS 180-4 standard compliance
• Big-endian length encoding
• Pure Vais implementation

Usage:

U vais_sha256.{sha256, hash_to_hex}

data := "Hello, Vais!".as_bytes()
hash := sha256(data[..])
hex_str := hash_to_hex(hash)
print(hex_str)    # "a591a6d4..."

Operations:

• Ch, Maj, Σ0, Σ1, σ0, σ1 functions
• Message expansion (16 → 64 words)
• 64 rounds of compression
• Big-endian finalization

vais-uuid

UUID generation — RFC 4122 Version 4 (random) UUIDs.

Features:

• UUID v4 (random) generation
• RFC 4122 compliant formatting
• Hyphenated string representation
• Pure Vais implementation

Usage:

U vais_uuid.{generate_v4, uuid_to_string}

uuid := generate_v4()
uuid_str := uuid_to_string(uuid)
print(uuid_str)    # "550e8400-e29b-41d4-a716-446655440000"

Format: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx (128-bit random with version/variant bits)

vais-regex

Regular expression engine — Pattern matching with backtracking.

Features:

• Core regex syntax (., *, +, ?, [], ^, $, |)
• Character classes ([a-z], [^abc])
• Anchors (^, $)
• Alternation (|)
• Grouping (())
• Backtracking-based matching

Usage:

U vais_regex.{compile, match}

pattern := compile("^[a-z]+@[a-z]+\\.[a-z]+$")
I match(pattern, "user@example.com") {
    print("Valid email")
} E {
    print("Invalid email")
}

Implementation: NFA-based state machine with backtracking for alternation and grouping.

Roadmap

Upcoming ecosystem packages:

• vais-xml — XML parser/serializer
• vais-yaml — YAML 1.2 support
• vais-http — HTTP client/server (building on std/http.vais)
• vais-image — PNG/JPEG/WebP image decoding
• vais-markdown — Markdown to HTML converter

See Also

• Package Manager Design
• Standard Library Reference
• FFI Guide
• API Index

트러블슈팅 & FAQ

이 문서는 Vais 개발 중 자주 발생하는 문제와 해결 방법, 자주 묻는 질문을 다룹니다.

자주 발생하는 컴파일 에러

E001: Type mismatch (타입 불일치)

원인: 함수나 연산자가 기대하는 타입과 전달된 값의 타입이 다릅니다.

예시:

F add(x: i64, y: i64) -> i64 {
  R x + y
}

F main() {
  result := add(5, "hello")  # E001: 기대 i64, 실제 str
}

해결법:

• 타입을 명시적으로 확인하고 올바른 타입의 값을 전달하세요.
• 필요시 타입 변환을 수행하세요.

F main() {
  result := add(5, 10)  # 올바름
}

특수 케이스:

• () (void) vs i64: store_i64()는 void 반환이므로 I cond { store_i64(...); 0 } E { 0 } 형태로 작성
• match arm에서 서로 다른 타입 반환 시 phi node 충돌 가능

E002: Undefined variable (정의되지 않은 변수)

원인: 선언되지 않은 변수를 사용하려고 했습니다.

예시:

F main() {
  print(x)  # E002: x가 정의되지 않음
}

해결법:

• 변수를 사용하기 전에 :=로 선언하세요.

F main() {
  x := 42
  print(x)  # 올바름
}

E003: Undefined type (정의되지 않은 타입)

원인: 선언되지 않은 타입을 참조했습니다.

예시:

F process(data: MyStruct) {  # E003: MyStruct가 정의되지 않음
  # ...
}

해결법:

• 타입을 사용하기 전에 S (struct) 또는 E (enum)으로 정의하세요.
• 표준 라이브러리 타입은 U std/xxx로 import하세요.

S MyStruct {
  value: i64
}

F process(data: MyStruct) {  # 올바름
  # ...
}

E004: Undefined function (정의되지 않은 함수)

원인: 선언되지 않은 함수를 호출하려고 했습니다.

예시:

F main() {
  result := calculate(5)  # E004: calculate가 정의되지 않음
}

해결법:

• 함수를 호출하기 전에 F로 정의하거나 import하세요.

F calculate(x: i64) -> i64 {
  R x * 2
}

F main() {
  result := calculate(5)  # 올바름
}

E005: Not callable (호출할 수 없는 값)

원인: 함수가 아닌 값에 () 호출 구문을 사용했습니다.

예시:

F main() {
  x := 42
  x()  # E005: i64는 호출할 수 없음
}

해결법:

• 함수만 호출할 수 있습니다. 변수가 함수 포인터인지 확인하세요.

E006: Argument count mismatch (인수 개수 불일치)

원인: 함수 호출 시 전달한 인수의 개수가 함수 정의와 다릅니다.

예시:

F add(x: i64, y: i64) -> i64 {
  R x + y
}

F main() {
  result := add(5)  # E006: 2개 기대, 1개 전달
}

해결법:

• 함수 시그니처에 맞춰 정확한 개수의 인수를 전달하세요.

F main() {
  result := add(5, 10)  # 올바름
}

E007: Cannot infer type (타입 추론 실패)

원인: 컴파일러가 표현식의 타입을 추론할 수 없습니다.

예시:

F main() {
  x := []  # E007: 빈 배열의 타입을 추론할 수 없음
}

해결법:

• 명시적으로 타입을 지정하세요.

F main() {
  x: [i64] = []  # 올바름
}

E008: Duplicate definition (중복 정의)

원인: 같은 이름의 함수, 변수, 타입이 중복으로 정의되었습니다.

예시:

F foo() { }
F foo() { }  # E008: foo가 중복 정의됨

해결법:

• 각 심볼에 고유한 이름을 사용하세요.

E009: Immutable assign (불변 변수에 대입 시도)

원인: mut 없이 선언된 변수에 새 값을 대입하려고 했습니다.

예시:

F main() {
  x := 5
  x = 10  # E009: x는 불변
}

해결법:

• 변수를 변경 가능하게 선언하려면 := mut를 사용하세요.

F main() {
  x := mut 5
  x = 10  # 올바름
}

E010: Non-exhaustive match (패턴 매칭 불완전)

원인: match 표현식이 모든 가능한 케이스를 처리하지 않습니다.

예시:

E Status {
  Ok,
  Error,
  Pending
}

F main() {
  status := Status.Ok
  M status {
    Status.Ok => print("ok"),
    Status.Error => print("error")
    # E010: Pending 케이스가 누락됨
  }
}

해결법:

• 모든 케이스를 처리하거나 _ (와일드카드)를 추가하세요.

F main() {
  status := Status.Ok
  M status {
    Status.Ok => print("ok"),
    Status.Error => print("error"),
    _ => print("other")  # 올바름
  }
}

E016: Move after use (이동 후 사용)

원인: 값이 이동된 후 다시 사용하려고 했습니다.

예시:

F take_ownership(s: str) {
  print(s)
}

F main() {
  x := "hello"
  take_ownership(x)
  print(x)  # E016: x는 이미 이동됨
}

해결법:

• 복사 가능한 타입을 사용하거나, 참조를 전달하거나, 값을 복제하세요.

E022: Use after move (이동된 값 사용)

원인: 소유권이 이동된 값을 다시 사용하려고 했습니다.

예시:

F main() {
  s := "test"
  len := strlen(s)
  memcpy_str(dest, src, s)  # E022: s는 이미 strlen에서 move됨
}

해결법:

• str_to_ptr(s)로 포인터 변환 후 사용하거나, 순서를 조정하세요.

F main() {
  s := "test"
  ptr := str_to_ptr(s)
  len := calculate_length(ptr)
  # 포인터 기반 연산 사용
}

E024: Assign while borrowed (차용 중 대입)

원인: 값이 차용(borrow)된 상태에서 대입을 시도했습니다.

예시:

F main() {
  x := mut 5
  r := &x
  x = 10  # E024: x가 r에 의해 차용됨
  print(r)
}

해결법:

• 차용이 끝난 후 대입하세요.

E026: Borrow conflict (차용 충돌)

원인: 불변 차용과 가변 차용이 동시에 존재하거나, 가변 차용이 여러 개 존재합니다.

해결법:

• 차용 스코프를 조정하여 충돌을 피하세요.

E030: No such field (존재하지 않는 필드)

원인: 구조체에 존재하지 않는 필드에 접근하려고 했습니다.

예시:

S Point {
  x: i64,
  y: i64
}

F main() {
  p := Point { x: 1, y: 2 }
  print(p.z)  # E030: Point에 z 필드가 없음
}

해결법:

• 올바른 필드 이름을 사용하거나, 필요하면 구조체 정의에 필드를 추가하세요.

F main() {
  p := Point { x: 1, y: 2 }
  print(p.x)  # 올바름
}

링크 에러

undefined symbol

원인: LLVM IR에서 참조한 함수가 링크 단계에서 찾을 수 없습니다.

예시:

undefined symbol: _my_external_function

해결법:

• C 함수는 extern F로 선언하세요.
• 라이브러리 링크가 필요하면 -l 플래그를 추가하세요.

extern F puts(s: i64) -> i64

F main() {
  puts(str_to_ptr("hello"))
}

컴파일 시:

vaisc myfile.vais -o myfile

LLVM not found

원인: LLVM 17이 시스템에 설치되지 않았거나 PATH에 없습니다.

해결법:

macOS (Homebrew):

brew install llvm@17
export PATH="/opt/homebrew/opt/llvm@17/bin:$PATH"
export LDFLAGS="-L/opt/homebrew/opt/llvm@17/lib"
export CPPFLAGS="-I/opt/homebrew/opt/llvm@17/include"

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install llvm-17 llvm-17-dev clang-17

빌드 후 확인:

llvm-config --version  # 17.x.x 출력 확인
cargo build

clang linking errors

원인: clang이 생성된 LLVM IR을 실행 파일로 링크하지 못했습니다.

해결법:

• clang이 설치되어 있는지 확인하세요.
• 플랫폼별 링커 옵션이 필요할 수 있습니다.

which clang  # clang 경로 확인

런타임 에러

Segmentation fault (Segfault)

원인:

• 널 포인터 역참조
• 배열 범위를 벗어난 접근
• 잘못된 메모리 주소 접근
• 해제된 메모리 접근

디버깅:

# LLDB (macOS)
lldb ./myprogram
run
bt  # 백트레이스

# GDB (Linux)
gdb ./myprogram
run
bt

예방법:

• 포인터 사용 전 널 체크
• 배열 인덱스 범위 검증
• 메모리 해제 후 포인터를 다시 사용하지 않기

F safe_access(arr: [i64], idx: i64) -> i64 {
  I idx < 0 || idx >= arr.len() {
    R 0  # 기본값 반환
  }
  R arr[idx]
}

Stack overflow

원인: 무한 재귀 또는 너무 깊은 재귀 호출.

예시:

F infinite() {
  @()  # 자기 재귀, 종료 조건 없음
}

해결법:

• 재귀 함수에 기저 조건(base case)을 추가하세요.

F factorial(n: i64) -> i64 {
  I n <= 1 {
    R 1  # 기저 조건
  }
  R n * @(n - 1)
}

Memory leaks

원인: malloc으로 할당한 메모리를 free하지 않았습니다.

예방법:

• RAII 패턴 사용
• 스코프가 끝날 때 리소스 해제
• GC 크레이트 활성화 고려 (vais-gc)

자주 묻는 질문 (FAQ)

:= vs =의 차이는?

• := (콜론-등호): 새 변수 선언 및 바인딩 (let binding)
• = (등호): 기존 변수에 새 값 대입 (reassignment)

F main() {
  x := 5      # 새 변수 선언
  x = 10      # E009: x는 불변이므로 에러

  y := mut 5  # 가변 변수 선언
  y = 10      # 올바름: 재할당 가능
}

mut 없이 재할당하면?

E009 에러가 발생합니다. Vais는 기본적으로 불변(immutable)입니다.

F main() {
  counter := 0
  counter = counter + 1  # E009 에러
}

해결법: := mut로 선언하세요.

F main() {
  counter := mut 0
  counter = counter + 1  # 올바름
}

E 키워드가 else와 enum 둘 다?

네, 문맥에 따라 달라집니다.

else로 사용:

I x > 0 {
  print("positive")
} E {
  print("non-positive")
}

enum으로 사용:

E Status {
  Ok,
  Error
}

파서가 문맥을 통해 자동으로 구분합니다.

@ 자기 재귀란?

@는 현재 함수를 재귀 호출하는 연산자입니다. 함수 이름을 반복하지 않아도 됩니다.

F factorial(n: i64) -> i64 {
  I n <= 1 {
    R 1
  }
  R n * @(n - 1)  # factorial(n - 1)과 동일
}

장점:

• 함수 이름 변경 시 재귀 호출 수정 불필요
• 코드가 간결해짐

Vais에 GC(가비지 컬렉션)가 있나요?

기본적으로 없습니다. Vais는 수동 메모리 관리(malloc/free)를 사용합니다.

옵션:

• vais-gc 크레이트를 활성화하면 선택적 GC 사용 가능
• 소유권(ownership) 시스템이 메모리 안전성을 제공

# 수동 관리
F main() {
  ptr := malloc(1024)
  # ... 사용 ...
  free(ptr)
}

LLVM 버전 요구사항은?

LLVM 17이 필요합니다. Vais는 inkwell 0.4 (LLVM 17 바인딩)를 사용합니다.

확인 방법:

llvm-config --version
# 17.x.x 출력되어야 함

다른 버전 사용 시 빌드 에러가 발생할 수 있습니다.

Rust와 Vais의 차이는?

반복문에서 R과 B의 차이는?

• R (return): 함수 전체에서 반환 (루프 포함)
• B (break): 현재 루프만 탈출

F find_value(arr: [i64], target: i64) -> i64 {
  i := mut 0
  L {
    I i >= arr.len() {
      B  # 루프 탈출
    }
    I arr[i] == target {
      R i  # 함수에서 반환
    }
    i = i + 1
  }
  R -1  # 루프 후 기본 반환값
}

주의: I cond { R 0 } 패턴은 루프를 벗어나는 게 아니라 함수를 종료합니다.

구조체 리터럴과 if 블록 구분은?

파서는 첫 문자가 대문자(A-Z)인지로 구분합니다.

# 구조체 리터럴 (첫 문자 대문자)
point := Point { x: 1, y: 2 }

# if 블록 (소문자 변수)
I condition {
  # ...
}

연산자 우선순위는?

비교 (==, !=) > 비트 연산 (&, |)

# 주의: 괄호 필요
I (val >> bit) & 1 == 1 {  # 잘못된 파싱
  # ...
}

# 올바른 방법:
masked := (val >> bit) & 1
I masked == 1 {
  # ...
}

표준 라이브러리 import가 E2E에서 안 되는데?

E2E 테스트에서는 U std/xxx import가 제한될 수 있습니다.

해결법: 필요한 로직을 테스트 파일에 인라인으로 작성하세요.

# import 대신
# U std/math

# 직접 구현
F abs(x: i64) -> i64 {
  I x < 0 { R -x }
  R x
}

더 많은 도움이 필요하면?

• 문서: docs-site/ 디렉토리의 다른 가이드 참조
• 예제: examples/ 디렉토리에 168+ 예제 파일
• 테스트: crates/vaisc/tests/ — 415개 E2E 테스트 참고
• GitHub Issues: vaislang/vais 저장소에 이슈 제출

추가 리소스

• LLVM IR 가이드: docs-site/src/llvm-ir-guide.md
• 타입 시스템: docs-site/src/type-system.md
• 언어 스펙: docs-site/src/language-spec.md
• 컴파일러 구조: docs-site/src/compiler-architecture.md

언어 사양

Vais Language Specification

Version: 1.0.0

Table of Contents

1. Overview
2. Lexical Structure
3. Keywords
4. Types
5. Operators
6. Expressions
7. Statements
8. Functions
9. Structs
10. Enums
11. Error Handling
12. Traits and Implementations
13. Pattern Matching
14. Generics
15. Module System
16. Async/Await
17. Iterators and Generators
18. Closures and Lambdas
19. Memory Management
20. Built-in Functions
21. Constants
22. Package Ecosystem
23. Best Practices
24. Examples
25. Grammar Summary

Overview

Vais is a token-efficient, AI-optimized systems programming language designed to minimize token usage in AI code generation while maintaining full systems programming capabilities. It features:

• Single-letter keywords for maximum token efficiency
• Expression-oriented syntax where everything returns a value
• Self-recursion operator @ for concise recursive functions
• LLVM-based compilation for native performance
• Type inference with minimal annotations
• Advanced features: Generics, Traits, Async/Await, Pattern Matching

Lexical Structure

Comments

Comments start with # and continue to the end of the line:

# This is a comment
F add(a:i64, b:i64)->i64 = a + b  # Inline comment

Whitespace

Whitespace (spaces, tabs, newlines) is ignored except when separating tokens.

Identifiers

Identifiers start with a letter or underscore, followed by letters, digits, or underscores:

[a-zA-Z_][a-zA-Z0-9_]*

Examples: x, my_var, Counter, _private

Literals

Integer Literals:

42
1_000_000    # Underscores for readability
-42          # Negative (using unary minus operator)

Float Literals:

3.14
1.0e10
2.5e-3
1_000.5_00

String Literals:

"Hello, World!"
"Line with \"quotes\""

String Interpolation:

name := "Vais"
println("Hello, ~{name}!")           # Variable interpolation
println("Result: ~{2 + 3}")         # Expression interpolation
println("Escaped: {{not interp}}") # Escaped braces

Boolean Literals:

true
false

Keywords

Vais uses single-letter keywords for maximum token efficiency:

Note: The C keyword has dual meaning - C for continue in loops, and C for constants (see Constants). Context determines usage.

Multi-letter Keywords

• mut - Mutable variable/reference
• self - Instance reference
• Self - Type reference in impl
• true, false - Boolean literals
• spawn - Spawn async task
• await - Await async result (also available as Y shorthand)
• weak - Weak reference
• clone - Clone operation
• yield - Yield value in iterator/coroutine (simplified implementation)

Shorthand Keywords (Phase 29)

Types

Primitive Types

Integer Types:

• i8, i16, i32, i64, i128 - Signed integers
• u8, u16, u32, u64, u128 - Unsigned integers

Floating-Point Types:

• f32 - 32-bit floating point
• f64 - 64-bit floating point

Other Types:

• bool - Boolean type (true or false)
• str - String type

Pointer Types

*i64        # Pointer to i64
*T          # Pointer to type T

Array Types

[i64]       # Array of i64
[T]         # Array of type T

Generic Types

Option<T>   # Generic Option type
Vec<T>      # Generic vector type
Pair<A, B>  # Multiple type parameters

Operators

Arithmetic Operators

Comparison Operators

Logical Operators

Assignment Operators

Special Operators

Note on ? operator: The ? operator has two uses:

• Ternary conditional: condition ? true_val : false_val
• Try operator: result? - propagates errors to caller (see Error Handling)

Operator Precedence

Operators are listed from highest to lowest precedence:

Note: Bitwise & has higher precedence than comparison operators like ==. Use parentheses to clarify: (a == b) & (c == d).

Expressions

Everything in Vais is an expression that returns a value.

Literals

42          # Integer
3.14        # Float
"hello"     # String
true        # Boolean

Variable References

x
my_variable

Binary Expressions

a + b
x * y - z
a == b

Unary Expressions

-x
!flag
~bits

Function Calls

add(1, 2)
compute(x, y, z)
obj.method()

Ternary Conditional

condition ? true_value : false_value
x > 0 ? x : -x    # Absolute value

Array/Index Access

arr[0]
data[i * 2 + 1]

Member Access

point.x
counter.value
obj.method()

Self-Recursion

The @ operator calls the current function recursively:

F fib(n:i64)->i64 = n<2 ? n : @(n-1) + @(n-2)

Equivalent to:

F fib(n:i64)->i64 = n<2 ? n : fib(n-1) + fib(n-2)

Pipe Operator

The |> operator passes the left-hand value as the first argument to the right-hand function:

# x |> f is equivalent to f(x)
result := 5 |> double |> add_one

# Chaining multiple transformations
F double(x: i64) -> i64 = x * 2
F add_one(x: i64) -> i64 = x + 1

F main() -> i64 = 5 |> double |> add_one  # 11

String Interpolation

Embed expressions inside string literals with ~{expr}:

name := "World"
println("Hello, ~{name}!")          # Variable
println("Sum: ~{2 + 3}")           # Expression
println("Escaped: {{braces}}")    # Literal braces with {{ }}

Tuple Destructuring

Unpack tuple values into multiple variables:

(a, b) := get_pair()
(x, y, z) := (1, 2, 3)

Block Expressions

Blocks are expressions that return the value of their last expression:

{
    x := 10
    y := 20
    x + y    # Returns 30
}

Auto-Return

Functions in Vais automatically return the value of their last expression. No explicit R (return) is needed unless early return is required:

F add(a: i64, b: i64) -> i64 {
    a + b    # Automatically returned
}

F max(a: i64, b: i64) -> i64 {
    I a > b {
        a    # Each branch returns its last expression
    } E {
        b
    }
}

# Explicit R is only needed for early return
F safe_divide(a: i64, b: i64) -> i64 {
    I b == 0 {
        R 0    # Early return
    }
    a / b      # Auto-returned
}

This applies to all block expressions including I/E, M, and L.

Statements

Variable Declaration

# Type-inferred (immutable)
x := 10

# Explicit type
y: i64 = 20

# Mutable
z := mut 30

If-Else Expression

# Single-line ternary
result := x > 0 ? 1 : -1

# Block form
I x < 0 {
    -1
} E {
    0
}

# Else-if chain
I x < 0 {
    -1
} E I x == 0 {
    0
} E {
    1
}

Note: E is used for "else" in if expressions.

Loop Expression

# Infinite loop
L {
    # ... body
    B  # Break
}

# Range loop
L i: 0..10 {
    puts("Iteration")
}

# Array iteration (conceptual)
L item: array {
    # ... process item
}

Match Expression

M value {
    0 => "zero",
    1 => "one",
    2 => "two",
    _ => "other"    # Wildcard/default
}

# With variable binding
M option {
    Some(x) => x,
    None => 0
}

Break and Continue

L i: 0..100 {
    I i == 50 { B }      # Break
    I i % 2 == 0 { C }   # Continue
    process(i)
}

Return Statement

F compute(x: i64) -> i64 {
    I x < 0 {
        R 0    # Early return
    }
    x * 2
}

Functions

Function Definition

Expression form (single expression):

F add(a:i64, b:i64)->i64 = a + b

Block form:

F factorial(n:i64)->i64 {
    I n < 2 {
        1
    } E {
        n * @(n-1)
    }
}

Parameters

F example(x: i64, y: f64, name: str) -> i64 { ... }

Parameter Type Inference

Parameter types can be omitted when they can be inferred from call sites:

# Types inferred from usage
F add(a, b) = a + b

# Mixed: some explicit, some inferred
F scale(x, factor: f64) -> f64 = x * factor

# The compiler infers types from how the function is called
F main() -> i64 {
    add(1, 2)       # a: i64, b: i64 inferred
    scale(3.0, 2.0)  # x: f64 inferred
    0
}

Return Types

F returns_int() -> i64 { 42 }
F returns_nothing() -> i64 { 0 }  # Convention: 0 for void

Generic Functions

F identity<T>(x: T) -> T = x

F swap<A, B>(a: A, b: B) -> (B, A) {
    (b, a)
}

Self-Recursion

F fib(n:i64)->i64 = n<2 ? n : @(n-1) + @(n-2)
F countdown(n:i64)->i64 = n<1 ? 0 : @(n-1)

External Functions

Declare C functions with X F:

X F puts(s: i64) -> i64
X F malloc(size: i64) -> i64
X F sqrt(x: f64) -> f64

Structs

Struct Definition

S Point {
    x: f64,
    y: f64
}

S Person {
    name: str,
    age: i64
}

Generic Structs

S Pair<T> {
    first: T,
    second: T
}

S Container<K, V> {
    key: K,
    value: V
}

Struct Instantiation

p := Point { x: 10.0, y: 20.0 }
person := Person { name: "Alice", age: 30 }
pair := Pair { first: 1, second: 2 }

Field Access

x_coord := p.x
person_age := person.age

Enums

Enum Definition

Simple enum:

E Color {
    Red,
    Green,
    Blue
}

Enum with data:

E Option {
    None,
    Some(i64)
}

E Result {
    Ok(i64),
    Err(str)
}

Enum Usage

color := Red
opt := Some(42)
err := Err("file not found")

Enum Implementation Blocks

Enums can have methods just like structs:

E Color {
    Red,
    Green,
    Blue
}

X Color {
    F is_warm(&self) -> bool {
        M self {
            Red => true,
            Green => false,
            Blue => false,
            _ => false
        }
    }

    F to_hex(&self) -> str {
        M self {
            Red => "#FF0000",
            Green => "#00FF00",
            Blue => "#0000FF",
            _ => "#000000"
        }
    }
}

# Usage
F main() -> i64 {
    c := Red
    I c.is_warm() {
        puts("This is a warm color")
    }
    puts(c.to_hex())
    0
}

Error Handling

Vais uses a Result/Option-based error handling system without traditional try-catch blocks. Error handling is done through the ? (try) and ! (unwrap) operators.

The ? Operator (Error Propagation)

The ? operator is used to propagate errors to the caller. When applied to a Result<T, E> or Option<T>, it:

• Returns the inner value if Ok(value) or Some(value)
• Early-returns the error/None to the calling function if Err(e) or None

E Result<T, E> {
    Ok(T),
    Err(E)
}

F read_file(path: str) -> Result<str, str> {
    # If open fails, propagate the error immediately
    file := open(path)?

    # If read fails, propagate the error
    data := file.read()?

    # Success case
    Ok(data)
}

F process() -> Result<i64, str> {
    # The ? operator automatically propagates errors
    content := read_file("config.txt")?

    # Continue processing if no error
    Ok(parse(content))
}

The ! Operator (Unwrap)

The ! operator forcefully extracts the value from a Result or Option. If the value is Err or None, the program will panic:

# Unwrap an Option - panics if None
value := some_option!

# Unwrap a Result - panics if Err
data := some_result!

# Example usage
F get_config() -> Option<str> {
    # ... returns Some(config) or None
}

F main() -> i64 {
    # This panics if get_config returns None
    config := get_config()!

    puts(config)
    0
}

Error Type Derivation

Use #[derive(Error)] to automatically implement error traits:

#[derive(Error)]
E AppError {
    NotFound(str),
    Permission(str),
    Network(str)
}

F find_user(id: i64) -> Result<str, AppError> {
    I id < 0 {
        Err(NotFound("User ID cannot be negative"))
    } E {
        Ok("User data")
    }
}

Standard Library Error Module

Vais provides std/error.vais with common error handling utilities (similar to Rust's anyhow and thiserror):

U std/error

# Error trait implementation
F handle_errors() -> Result<i64, str> {
    data := read_file("data.txt")?
    result := process(data)?
    Ok(result)
}

Traits and Implementations

Trait Definition

W Printable {
    F print(&self) -> i64
}

W Comparable {
    F compare(&self, other: &Self) -> i64
}

Trait Implementation

S Counter {
    value: i64
}

X Counter: Printable {
    F print(&self) -> i64 {
        puts("Counter value:")
        print_i64(self.value)
        0
    }
}

Method Implementation (without trait)

X Counter {
    F increment(&self) -> i64 {
        self.value + 1
    }

    F double(&self) -> i64 {
        self.value * 2
    }
}

Calling Methods

c := Counter { value: 42 }
c.print()
inc := c.increment()
dbl := c.double()

Pattern Matching

Basic Match

F classify(n: i64) -> str {
    M n {
        0 => "zero",
        1 => "one",
        _ => "other"
    }
}

Match with Binding

F describe(opt: Option) -> i64 {
    M opt {
        Some(x) => x,
        None => 0
    }
}

Match with Guards

M value {
    x if x > 0 => "positive",
    x if x < 0 => "negative",
    _ => "zero"
}

Pattern Alias

Pattern aliases allow you to bind a name to a matched pattern using the @ operator. This is useful when you need both the matched value and access to the whole pattern:

# Basic pattern alias with range
F describe(n: i64) -> str {
    M n {
        x @ 1..10 => "small: ~{x}",
        x @ 10..100 => "medium: ~{x}",
        x @ 100..1000 => "large: ~{x}",
        _ => "very large"
    }
}

# Pattern alias with enum destructuring
E Option<T> {
    None,
    Some(T)
}

F process(opt: Option<i64>) -> i64 {
    M opt {
        val @ Some(x) => {
            # 'val' holds the entire Some variant
            # 'x' holds the inner value
            x * 2
        },
        None => 0
    }
}

# Pattern alias with struct destructuring
S Point {
    x: i64,
    y: i64
}

F classify_point(p: Point) -> str {
    M p {
        origin @ Point { x: 0, y: 0 } => "origin",
        pt @ Point { x, y } if x == y => "diagonal point",
        _ => "other point"
    }
}

# Nested pattern aliases
E Result<T, E> {
    Ok(T),
    Err(E)
}

F handle_result(r: Result<i64, str>) -> str {
    M r {
        success @ Ok(value) if value > 0 => "positive success",
        failure @ Err(msg) => "error: ~{msg}",
        _ => "zero or negative"
    }
}

The pattern alias x @ pattern syntax binds x to the matched value while also matching against pattern. This is particularly useful when:

• You need to refer to the matched value multiple times
• You want to combine pattern matching with guards
• You need both the whole value and destructured parts

Destructuring

E Result {
    Ok(i64),
    Err(str)
}

M result {
    Ok(value) => value,
    Err(msg) => 0
}

Wildcard Pattern

M x {
    0 => "zero",
    _ => "non-zero"   # Matches everything else
}

Generics

Generic Functions

F identity<T>(x: T) -> T = x

F max<T>(a: T, b: T) -> T {
    I a > b { a } E { b }
}

Generic Structs

S Pair<T> {
    first: T,
    second: T
}

S Box<T> {
    value: T
}

Generic Enums

E Option<T> {
    None,
    Some(T)
}

E Result<T, E> {
    Ok(T),
    Err(E)
}

Generic Constraints (bounds)

# Function requiring trait bound
F print_all<T: Printable>(items: [T]) -> i64 {
    L item: items {
        item.print()
    }
    0
}

Where Clauses

Where clauses provide an alternative syntax for specifying generic type constraints, especially useful when constraints are complex or numerous:

# Basic where clause
F find_max<T>(list: Vec<T>) -> T where T: Ord {
    result := mut list.get(0)
    L i: 1..list.len() {
        I list.get(i) > result {
            result = list.get(i)
        }
    }
    result
}

# Multiple bounds on a single type
F serialize<T>(val: T) -> str where T: Display, T: Clone {
    val.to_string()
}

# Multiple type parameters with bounds
F compare_and_print<T, U>(a: T, b: U) -> i64
    where T: Ord, U: Display
{
    puts(b.to_string())
    I a > a { 1 } E { 0 }
}

# Where clauses with structs
S Container<T> where T: Clone {
    value: T
}

Where clauses are especially useful when:

• Type constraints are complex or lengthy
• Multiple type parameters have constraints
• Constraints reference associated types
• You want to separate type parameters from their constraints for readability

Module System

Importing Modules

# Import from standard library
U std/math
U std/io

# Import custom module
U mymodule

Using Imported Items

U std/math

F main() -> i64 {
    pi := PI              # Constant from math
    result := sqrt(16.0)  # Function from math
    puts("Square root: ")
    print_f64(result)
    0
}

Module Paths

U std/io           # Standard library module
U std/collections  # Nested module path

Async/Await

Async Function Definition

A F compute(x: i64) -> i64 {
    x * 2
}

A F fetch_data(url: str) -> str {
    # ... async operations
    result
}

Awaiting Async Functions

F main() -> i64 {
    # Call async function and await result
    result := compute(21).await

    # Using Y shorthand (equivalent to .await)
    result2 := compute(21).Y

    # Chain async calls
    data := fetch_data("example.com").Y

    0
}

Spawning Tasks

# Spawn a task (runs concurrently)
task := spawn compute(42)

# Later, await the result
result := task.await

Iterators and Generators

The yield Keyword

The yield keyword is used to produce values in iterators and coroutines. In the current simplified implementation, yield returns a value from the iteration:

F counter(max: i64) -> i64 {
    L i: 0..max {
        yield i
    }
    0
}

F fibonacci(n: i64) -> i64 {
    a := 0
    b := 1
    L i: 0..n {
        yield a
        tmp := a + b
        a = b
        b = tmp
    }
    0
}

Iterator Protocol

Vais implements an iterator protocol similar to Rust's Iterator trait. Collections can be iterated using the standard for-loop syntax:

# Iterate over a range
L i: 0..10 {
    puts("Value: ")
    print_i64(i)
}

# Iterate over an array
items := [1, 2, 3, 4, 5]
L item: items {
    print_i64(item)
}

Iterator Adapters

Vais provides functional iterator adapters for transforming and filtering collections:

iter_map - Transform each element:

items := [1, 2, 3, 4, 5]
doubled := iter_map(items, |x| x * 2)
# Result: [2, 4, 6, 8, 10]

iter_filter - Keep elements matching a predicate:

numbers := [1, 2, 3, 4, 5, 6]
evens := iter_filter(numbers, |x| x % 2 == 0)
# Result: [2, 4, 6]

iter_take - Take first N elements:

data := [10, 20, 30, 40, 50]
first_three := iter_take(data, 3)
# Result: [10, 20, 30]

iter_skip - Skip first N elements:

data := [10, 20, 30, 40, 50]
after_two := iter_skip(data, 2)
# Result: [30, 40, 50]

iter_chain - Concatenate two iterators:

first := [1, 2, 3]
second := [4, 5, 6]
combined := iter_chain(first, second)
# Result: [1, 2, 3, 4, 5, 6]

iter_zip - Combine two iterators pairwise:

a := [1, 2, 3]
b := [10, 20, 30]
pairs := iter_zip(a, b)
# Result: [(1, 10), (2, 20), (3, 30)]

iter_enumerate - Add indices to elements:

items := ["a", "b", "c"]
indexed := iter_enumerate(items)
# Result: [(0, "a"), (1, "b"), (2, "c")]

Chaining Iterator Adapters

Iterator adapters can be chained together for complex transformations:

numbers := [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

# Get first 5 even numbers, doubled
result := numbers
    |> iter_filter(|x| x % 2 == 0)
    |> iter_take(5)
    |> iter_map(|x| x * 2)
# Result: [4, 8, 12, 16, 20]

Closures and Lambdas

Basic Closures

Closures (also called lambdas or anonymous functions) are inline function definitions that can capture variables from their surrounding scope:

# Basic closure syntax
add_one := |x| x + 1

# Closure with multiple parameters
multiply := |x, y| x * y

# Closure with block body
complex := |n| {
    result := n * 2
    result + 10
}

# Using closures with iterator adapters
numbers := [1, 2, 3, 4, 5]
doubled := iter_map(numbers, |x| x * 2)

Closure Capture Modes

Closures can capture variables from their surrounding scope in different ways. Vais provides explicit control over how variables are captured:

By Value (Default):

By default, closures capture variables by copying their values:

F main() -> i64 {
    x := 42

    # Closure captures 'x' by value (copy)
    add_x := |n| n + x

    result := add_x(10)  # Returns 52
    # Original 'x' is unchanged
    0
}

Move Capture:

The move keyword forces the closure to take ownership of captured variables by moving them into the closure:

F create_consumer() -> i64 {
    x := 42
    data := allocate_data()

    # Move 'x' and 'data' into the closure
    consumer := move |n| {
        # 'x' and 'data' are now owned by the closure
        result := n + x
        process(data)
        result
    }

    # Error: 'x' and 'data' have been moved
    # Cannot use them here anymore

    consumer(10)
}

# Common use case: returning closures
F make_adder(amount: i64) -> |i64| -> i64 {
    # Must use 'move' to transfer ownership
    move |x| x + amount
}

# Common use case: spawning async tasks
F spawn_worker(task_id: i64) -> i64 {
    data := load_task_data(task_id)

    # Move 'data' into the spawned task
    spawn move |()| {
        # 'data' is owned by this task
        process_task(data)
        0
    }

    0
}

Capture Mode Summary

Note: By-reference capture modes (& and &mut) are part of the type system but require advanced lifetime analysis. The current implementation supports by-value and move semantics.

Closure Examples

Using closures with higher-order functions:

# Filter with closure
F get_evens(numbers: [i64]) -> [i64] {
    iter_filter(numbers, |x| x % 2 == 0)
}

# Map with closure
F square_all(numbers: [i64]) -> [i64] {
    iter_map(numbers, |x| x * x)
}

# Chaining closures
F process_numbers(nums: [i64]) -> [i64] {
    nums
        |> iter_filter(|x| x > 0)
        |> iter_map(|x| x * 2)
        |> iter_take(10)
}

Closures capturing multiple variables:

F calculate(base: i64, multiplier: i64) -> i64 {
    # Closure captures both 'base' and 'multiplier'
    compute := |x| (x + base) * multiplier

    compute(5)
}

Move semantics with spawned tasks:

F parallel_process(data: Vec<i64>) -> i64 {
    L item: data {
        # Each task gets its own copy via move
        spawn move |()| {
            process_item(item)
            0
        }
    }
    0
}

Memory Management

Stack Allocation

Default allocation for local variables:

F main() -> i64 {
    x := 10        # Stack allocated
    p := Point { x: 1.0, y: 2.0 }  # Stack allocated
    0
}

Heap Allocation

Use malloc and free:

# Allocate memory
ptr := malloc(64)

# Use memory
store_i64(ptr, 42)
value := load_i64(ptr)

# Free memory
free(ptr)

Smart Pointers

Box (unique ownership):

U std/box

b := Box::new(42)
value := b.get()

Rc (reference counting):

U std/rc

rc := Rc::new(100)
rc2 := rc.clone()  # Increment ref count
value := rc.get()

Arena Allocation

U std/arena

arena := Arena::with_capacity(1024)
ptr := arena.alloc(64)
# ... use allocated memory
arena.reset()  # Clear all allocations

Built-in Functions

The following functions are provided by the compiler:

I/O Functions

puts(s: str) -> i64          # Print string with newline
println(s: str) -> i64       # Print with interpolation support: println("x={x}")
print(s: str) -> i64         # Print without newline
putchar(c: i64) -> i64       # Print character
puts_ptr(ptr: i64) -> i64    # Print C string from pointer

Memory Functions

malloc(size: i64) -> i64            # Allocate memory
free(ptr: i64) -> i64               # Free memory
memcpy(dst: i64, src: i64, n: i64) # Copy memory
load_i64(ptr: i64) -> i64           # Load i64 from memory
store_i64(ptr: i64, val: i64)       # Store i64 to memory
load_byte(ptr: i64) -> i64          # Load byte
store_byte(ptr: i64, val: i64)      # Store byte

String Functions

strlen(s: i64) -> i64        # Get string length

Utility Functions

print_i64(n: i64) -> i64     # Print integer
print_f64(n: f64) -> i64     # Print float

Constants

Define compile-time constants with C:

C PI: f64 = 3.141592653589793
C MAX_SIZE: i64 = 1024
C VERSION: str = "0.0.1"

Package Ecosystem

Vais includes a built-in package management system integrated into the vaisc compiler.

Creating a New Package

Use vaisc new to create a new Vais project:

# Create a new package
vaisc new myproject

# Creates directory structure:
# myproject/
#   ├── Vais.toml       # Package manifest
#   ├── src/
#   │   └── main.vais   # Entry point
#   └── tests/          # Test directory

Package Manifest (Vais.toml)

The Vais.toml file configures your package:

[package]
name = "myproject"
version = "0.1.0"
authors = ["Your Name <you@example.com>"]
edition = "2024"

[dependencies]
# Add dependencies here
# std = "1.0"

[dev-dependencies]
# Test-only dependencies

[build]
optimization = 2
target = "x86_64-unknown-linux-gnu"

Running Tests

Use vaisc test to run all tests in your package:

# Run all tests
vaisc test

# Run specific test file
vaisc test tests/my_test.vais

Writing tests:

# tests/math_test.vais

F test_addition() -> i64 {
    result := add(2, 3)
    I result != 5 {
        puts("FAIL: expected 5, got different value")
        R 1
    }
    puts("PASS: addition works")
    0
}

F test_multiplication() -> i64 {
    result := multiply(3, 4)
    I result != 12 {
        puts("FAIL: expected 12")
        R 1
    }
    puts("PASS: multiplication works")
    0
}

Package Commands

# Create new package
vaisc new <package_name>

# Build package
vaisc build

# Run package
vaisc run

# Run tests
vaisc test

# Check package validity
vaisc check

# Generate documentation
vaisc doc

Package Tree and Documentation

View package structure and generate documentation:

# Show package dependency tree
vaisc pkg tree

# Generate package documentation
vaisc pkg doc

Best Practices

1. Use type inference with := when the type is obvious
2. Use expression forms for simple functions: F add(a:i64,b:i64)->i64 = a+b
3. Use self-recursion @ for cleaner recursive functions
4. Pattern match instead of nested if-else chains
5. Leverage generics to reduce code duplication
6. Import only needed modules to keep token count low
7. Use match exhaustiveness to catch all cases
8. Use |> pipe operator for readable function chaining
9. Use string interpolation println("x=~{x}") instead of manual concatenation
10. Omit parameter types when they can be inferred from call sites
11. Use ? operator for error propagation instead of manual match/return
12. Use iterator adapters (iter_map, iter_filter, etc.) for functional transformations
13. Prefer derive(Error) for custom error types to reduce boilerplate
14. Use enum impl blocks to add behavior to enums
15. Structure projects with vaisc new and Vais.toml for better organization

Examples

Hello World

F main()->i64 {
    puts("Hello, Vais!")
    0
}

Fibonacci

F fib(n:i64)->i64 = n<2 ? n : @(n-1) + @(n-2)

F main()->i64 = fib(10)

Pattern Matching

E Option {
    None,
    Some(i64)
}

F unwrap_or(opt: Option, default: i64) -> i64 {
    M opt {
        Some(x) => x,
        None => default
    }
}

Generic Struct

S Pair<T> {
    first: T,
    second: T
}

X Pair {
    F sum(&self) -> i64 {
        self.first + self.second
    }
}

F main() -> i64 {
    p := Pair { first: 10, second: 20 }
    p.sum()
}

Error Handling with ? and !

E FileError {
    NotFound(str),
    PermissionDenied(str)
}

F read_config(path: str) -> Result<str, FileError> {
    # Use ? to propagate errors
    file := open_file(path)?
    data := file.read_all()?
    Ok(data)
}

F main() -> i64 {
    # Use ! to unwrap (panics on error)
    config := read_config("config.txt")!
    puts(config)

    # Or handle errors with match
    result := read_config("data.txt")
    M result {
        Ok(content) => {
            puts("Success:")
            puts(content)
        },
        Err(NotFound(msg)) => {
            puts("File not found:")
            puts(msg)
        },
        Err(PermissionDenied(msg)) => {
            puts("Permission denied:")
            puts(msg)
        },
        _ => puts("Unknown error")
    }
    0
}

Iterator Adapters

F main() -> i64 {
    numbers := [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

    # Chain iterator adapters
    result := numbers
        |> iter_filter(|x| x % 2 == 0)    # Keep even numbers
        |> iter_map(|x| x * x)             # Square them
        |> iter_take(3)                    # Take first 3

    # result = [4, 16, 36]

    L item: result {
        print_i64(item)
    }

    0
}

Enum with Methods

#[derive(Error)]
E Color {
    Red,
    Green,
    Blue
}

X Color {
    F is_primary(&self) -> bool {
        true  # All are primary colors
    }

    F to_rgb(&self) -> (i64, i64, i64) {
        M self {
            Red => (255, 0, 0),
            Green => (0, 255, 0),
            Blue => (0, 0, 255),
            _ => (0, 0, 0)
        }
    }
}

F main() -> i64 {
    color := Red
    (r, g, b) := color.to_rgb()

    puts("RGB values:")
    print_i64(r)
    print_i64(g)
    print_i64(b)

    0
}

Grammar Summary

The complete formal EBNF grammar is maintained at docs/grammar/vais.ebnf (~320 productions, generated from the parser source). Ambiguity resolution rules and notation conventions are documented in docs/grammar/README.md.

Below is a condensed quick-reference:

Module       ::= Item*
Item         ::= Attribute* ['P'] (FunctionDef | StructDef | EnumDef | UnionDef
                 | TypeAlias | TraitAlias | UseDef | TraitDef | ImplDef
                 | MacroDef | ExternBlock | ConstDef | GlobalDef)

FunctionDef  ::= ['A'] 'F' Ident Generics? '(' Params? ')' ['->' Type] WhereClause? ('=' Expr | Block)
StructDef    ::= 'S' Ident Generics? WhereClause? '{' (Field | Method)* '}'
EnumDef      ::= 'E' Ident Generics? '{' Variant (',' Variant)* '}'
UnionDef     ::= 'O' Ident Generics? '{' Field (',' Field)* '}'
TraitDef     ::= 'W' Ident Generics? [':' TraitBounds] WhereClause? '{' (AssocType | TraitMethod)* '}'
ImplDef      ::= 'X' Generics? Type [':' Ident] WhereClause? '{' Method* '}'
ExternBlock  ::= 'N' StringLit? '{' ExternFunc* '}' | 'X' 'F' ExternFuncSig
UseDef       ::= 'U' Path ['.' ('{' Idents '}' | Ident)] [';']
ConstDef     ::= 'C' Ident ':' Type '=' Expr
GlobalDef    ::= 'G' Ident ':' Type '=' Expr
TypeAlias    ::= 'T' Ident Generics? '=' Type
TraitAlias   ::= 'T' Ident Generics? '=' TraitBound ('+' TraitBound)*
MacroDef     ::= 'macro' Ident '!' '{' MacroRule* '}'

Expr         ::= Assignment | Pipe | Ternary | LogicalOr | LogicalAnd
               | BitwiseOr | BitwiseXor | BitwiseAnd | Equality | Range
               | Comparison | Shift | Term | Factor | Unary | Postfix | Primary

Stmt         ::= 'R' Expr? | 'B' Expr? | 'C' | 'D' Expr | LetStmt | Expr

Type         ::= BaseType ['?' | '!']
BaseType     ::= NamedType | TupleType | FnType | ArrayType | MapType
               | PointerType | RefType | SliceType | DynTraitType
               | LinearType | AffineType | ImplTraitType | DependentType | FnPtrType

Pattern      ::= '_' | Ident ['@' Pattern] | Ident '(' Patterns ')' | Literal
               | '(' Patterns ')' | Pattern '..' Pattern | Pattern '|' Pattern

Closure      ::= '|' Params? '|' Expr | 'move' '|' Params? '|' Expr

See docs/grammar/vais.ebnf for the complete grammar with all 18 sections, parser function cross-references, and operator precedence levels.

Conclusion

Vais is designed to be a minimal yet powerful systems programming language optimized for AI code generation. Its single-letter keywords, expression-oriented design, and self-recursion operator make it highly token-efficient while maintaining the expressiveness needed for complex systems programming tasks.

For more examples, see the /examples directory. For standard library documentation, see STDLIB.md.

제네릭

Vais 제네릭 및 트레이트 심화 튜토리얼

이 튜토리얼은 Vais의 제네릭 프로그래밍과 트레이트 시스템을 심층적으로 다룹니다. 타입 추론, 모노모피제이션, 그리고 실전 활용법을 배웁니다.

목차

1. 제네릭 개념
2. 제네릭 함수
3. 제네릭 구조체
4. 제네릭 Enum
5. 트레이트 정의와 구현
6. 제네릭 바운드
7. 표준 라이브러리 제네릭
8. 고급 패턴
9. 타입 추론
10. 실전 예제

제네릭 개념

제네릭이란?

제네릭은 타입을 매개변수화하여 여러 타입에 대해 동작하는 코드를 작성할 수 있게 합니다.

제네릭 없이:

# i64용 함수
F identity_i64(x: i64) -> i64 = x

# f64용 함수
F identity_f64(x: f64) -> f64 = x

# str용 함수
F identity_str(x: str) -> str = x

# 각 타입마다 중복 코드!

제네릭 사용:

# 하나의 함수로 모든 타입 처리
F identity<T>(x: T) -> T = x

F main() -> i64 {
    a := identity(42)        # T = i64
    b := identity(3.14)      # T = f64
    c := identity("hello")   # T = str

    0
}

Vais 제네릭의 특징

1. Monomorphization: 컴파일 시 각 사용된 타입에 대해 코드 생성
2. Zero-cost Abstraction: 런타임 오버헤드 없음
3. 타입 추론: 대부분의 경우 타입 명시 불필요
4. 정적 디스패치: 컴파일 타임에 모든 타입 결정

제네릭 함수

기본 제네릭 함수

단일 타입 매개변수:

# 가장 간단한 제네릭 함수
F identity<T>(x: T) -> T = x

# 여러 번 사용
F first<T>(a: T, b: T) -> T = a
F second<T>(a: T, b: T) -> T = b

# 블록 형태
F duplicate<T>(x: T) -> T {
    puts("Duplicating value")
    x
}

F main() -> i64 {
    # 타입 추론 - 명시 불필요
    x := identity(100)
    y := first(10, 20)
    z := duplicate(42)

    print_i64(x + y + z)  # 152
    0
}

다중 타입 매개변수

여러 타입 매개변수를 사용:

# 두 개의 타입 매개변수
F pair<A, B>(a: A, b: B) -> A = a

# 타입이 다른 값들 처리
F first_of_pair<A, B>(a: A, b: B) -> A = a
F second_of_pair<A, B>(a: A, b: B) -> B = b

# 삼중 타입
F choose_first<A, B, C>(a: A, b: B, c: C) -> A = a

F main() -> i64 {
    # A=i64, B=f64
    x := pair(10, 3.14)

    # A=i64, B=str
    y := first_of_pair(42, "hello")

    # A=i64, B=f64, C=str
    z := choose_first(100, 2.5, "world")

    print_i64(x + y + z)  # 152
    0
}

제네릭 함수의 타입 추론

Vais는 대부분의 경우 타입을 자동으로 추론합니다:

F swap<A, B>(a: A, b: B) -> (B, A) {
    (b, a)
}

F main() -> i64 {
    # 타입 추론: A=i64, B=i64
    (x, y) := swap(10, 20)

    # 타입 추론: A=i64, B=str
    (num, text) := swap(42, "answer")

    print_i64(x)  # 20
    0
}

제네릭과 Self-Recursion

제네릭 함수에서 @ 사용:

# 제네릭 재귀 함수
F repeat<T>(x: T, count: i64) -> T {
    I count <= 0 {
        x
    } E {
        @(x, count - 1)
    }
}

F main() -> i64 {
    result := repeat(42, 5)
    print_i64(result)  # 42
    0
}

제네릭 구조체

기본 제네릭 구조체

# 단일 타입 매개변수
S Box<T> {
    value: T
}

# 생성 및 사용
F main() -> i64 {
    # Box<i64>
    int_box := Box { value: 42 }

    # Box<f64>
    float_box := Box { value: 3.14 }

    print_i64(int_box.value)  # 42
    0
}

다중 타입 매개변수 구조체

# Pair - 두 개의 값을 담는 구조체
S Pair<T> {
    first: T,
    second: T
}

# Container - 서로 다른 타입
S Container<K, V> {
    key: K,
    value: V
}

# Triple - 세 개의 타입
S Triple<A, B, C> {
    first: A,
    second: B,
    third: C
}

F main() -> i64 {
    # Pair<i64>
    pair := Pair { first: 10, second: 20 }

    # Container<i64, str>
    container := Container { key: 1, value: "data" }

    # Triple<i64, f64, str>
    triple := Triple { first: 42, second: 3.14, third: "hello" }

    print_i64(pair.first)  # 10
    0
}

제네릭 구조체 메서드

X 키워드로 제네릭 구조체에 메서드 추가:

S Pair<T> {
    first: T,
    second: T
}

# Pair에 메서드 구현
X Pair {
    # self는 Pair<T> 타입
    F sum(&self) -> i64 {
        self.first + self.second
    }

    F swap(&self) -> Pair {
        Pair { first: self.second, second: self.first }
    }

    F first_value(&self) -> T {
        self.first
    }
}

F main() -> i64 {
    p := Pair { first: 10, second: 20 }

    # 메서드 호출
    total := p.sum()         # 30
    swapped := p.swap()      # Pair { first: 20, second: 10 }
    first := p.first_value() # 10

    print_i64(total)
    print_i64(swapped.first)
    print_i64(first)

    0
}

중첩 제네릭 구조체

S Box<T> {
    value: T
}

S Pair<T> {
    first: T,
    second: T
}

F main() -> i64 {
    # Box<i64>
    simple := Box { value: 42 }

    # Pair<i64>
    pair := Pair { first: 10, second: 20 }

    # Box<Pair<i64>> - 중첩 제네릭
    boxed_pair := Box {
        value: Pair { first: 1, second: 2 }
    }

    # 접근
    inner_pair := boxed_pair.value
    first_val := inner_pair.first

    print_i64(first_val)  # 1
    0
}

제네릭 Enum

기본 제네릭 Enum

# Option<T> - 값이 있거나 없음
E Option<T> {
    None,
    Some(T)
}

# Result<T, E> - 성공 또는 에러
E Result<T, E> {
    Ok(T),
    Err(E)
}

F main() -> i64 {
    # Option<i64>
    opt_int := Some(42)
    opt_none := None

    # Result<i64, str>
    result_ok := Ok(100)
    result_err := Err("Error message")

    0
}

제네릭 Enum 패턴 매칭

E Option<T> {
    None,
    Some(T)
}

F unwrap_or<T>(opt: Option<T>, default: T) -> T {
    M opt {
        Some(value) => value,
        None => default
    }
}

F main() -> i64 {
    opt1 := Some(42)
    opt2 := None

    v1 := unwrap_or(opt1, 0)   # 42
    v2 := unwrap_or(opt2, 99)  # 99

    print_i64(v1)
    print_i64(v2)

    0
}

다중 variant 제네릭 Enum

E Either<L, R> {
    Left(L),
    Right(R)
}

F process_either<L, R>(either: Either<L, R>) -> i64 {
    M either {
        Left(l) => {
            puts("Got Left")
            0
        },
        Right(r) => {
            puts("Got Right")
            1
        }
    }
}

F main() -> i64 {
    # Either<i64, str>
    left := Left(42)
    right := Right("hello")

    r1 := process_either(left)   # 0
    r2 := process_either(right)  # 1

    print_i64(r1 + r2)  # 1
    0
}

트레이트 정의와 구현

트레이트 정의

W 키워드로 트레이트(인터페이스) 정의:

# Printable 트레이트
W Printable {
    F print(&self) -> i64
}

# Comparable 트레이트
W Comparable {
    F compare(&self, other: &Self) -> i64
}

# 여러 메서드를 가진 트레이트
W Drawable {
    F draw(&self) -> i64
    F erase(&self) -> i64
    F move(&self, x: i64, y: i64) -> i64
}

트레이트 구현

X 키워드로 구조체에 트레이트 구현:

W Printable {
    F print(&self) -> i64
}

S Point {
    x: i64,
    y: i64
}

# Point에 Printable 구현
X Point: Printable {
    F print(&self) -> i64 {
        puts("Point(")
        print_i64(self.x)
        puts(", ")
        print_i64(self.y)
        puts(")")
        putchar(10)
        0
    }
}

F main() -> i64 {
    p := Point { x: 10, y: 20 }
    p.print()  # Point(10, 20)
    0
}

여러 트레이트 구현

W Printable {
    F print(&self) -> i64
}

W Resettable {
    F reset(&self) -> i64
}

S Counter {
    value: i64
}

# Printable 구현
X Counter: Printable {
    F print(&self) -> i64 {
        puts("Counter: ")
        print_i64(self.value)
        putchar(10)
        0
    }
}

# Resettable 구현
X Counter: Resettable {
    F reset(&self) -> i64 {
        self.value = 0
        0
    }
}

F main() -> i64 {
    c := Counter { value: 42 }
    c.print()   # Counter: 42
    c.reset()
    c.print()   # Counter: 0
    0
}

트레이트 없는 메서드 (Impl)

트레이트 없이 직접 메서드 추가:

S Rectangle {
    width: i64,
    height: i64
}

# 트레이트 없이 메서드 추가
X Rectangle {
    F area(&self) -> i64 {
        self.width * self.height
    }

    F perimeter(&self) -> i64 {
        (self.width + self.height) * 2
    }

    F is_square(&self) -> i64 {
        I self.width == self.height { 1 } E { 0 }
    }
}

F main() -> i64 {
    rect := Rectangle { width: 10, height: 20 }

    area := rect.area()           # 200
    perimeter := rect.perimeter() # 60
    is_sq := rect.is_square()     # 0

    print_i64(area)
    print_i64(perimeter)

    0
}

제네릭 바운드

트레이트 바운드 개념

제네릭 타입에 제약 조건을 추가:

# T는 Printable을 구현해야 함
F print_twice<T: Printable>(value: &T) -> i64 {
    value.print()
    value.print()
    0
}

Where 절

복잡한 바운드 표현:

# 여러 바운드
F process<T>(value: T) -> i64
where
    T: Printable,
    T: Comparable
{
    value.print()
    0
}

# Where clause with struct methods
S Container<T> where T: Clone {
    value: T
}

X Container<T> where T: Clone {
    F get_copy(&self) -> T {
        self.value.clone()
    }
}

# Where clause separating bounds from type parameters
F complex_transform<T, U>(input: T) -> U
where
    T: Display,
    U: Default
{
    # Transform logic
    0
}

Where 절 vs 인라인 바운드:

• 인라인: F func<T: Trait>(x: T) — 간단한 단일 바운드에 적합
• Where 절: F func<T>(x: T) where T: TraitA, T: TraitB — 복잡한 다중 바운드에 적합

다중 바운드 예제

W Display {
    F display(&self) -> i64
}

W Clone {
    F clone(&self) -> Self
}

S Point {
    x: i64,
    y: i64
}

X Point: Display {
    F display(&self) -> i64 {
        puts("(")
        print_i64(self.x)
        puts(",")
        print_i64(self.y)
        puts(")")
        0
    }
}

X Point: Clone {
    F clone(&self) -> Point {
        Point { x: self.x, y: self.y }
    }
}

F show_and_clone<T>(value: &T) -> T
where
    T: Display,
    T: Clone
{
    value.display()
    value.clone()
}

F main() -> i64 {
    p := Point { x: 10, y: 20 }
    p2 := show_and_clone(&p)

    p2.display()  # (10,20)
    0
}

표준 라이브러리 제네릭

Vec<T> - 동적 배열

U std/vec

F main() -> i64 {
    # Vec<i64> 생성
    v := Vec.with_capacity(10)

    # 요소 추가
    v.push(10)
    v.push(20)
    v.push(30)

    # 길이 확인
    len := v.len()  # 3

    # 요소 접근
    first := v.get(0)   # 10
    second := v.get(1)  # 20

    # 요소 제거
    last := v.pop()  # 30

    print_i64(len)
    print_i64(first)
    print_i64(last)

    v.drop()  # 메모리 해제
    0
}

Option<T> - 선택적 값

U std/option

F safe_divide(a: i64, b: i64) -> Option<i64> {
    I b == 0 {
        None
    } E {
        Some(a / b)
    }
}

F main() -> i64 {
    result := safe_divide(10, 2)

    # 패턴 매칭
    M result {
        Some(value) => {
            puts("Result: ")
            print_i64(value)  # 5
        },
        None => {
            puts("Division by zero!")
        }
    }

    # unwrap_or 메서드
    value := result.unwrap_or(0)
    print_i64(value)  # 5

    # is_some / is_none
    has_value := result.is_some()  # 1

    0
}

Result<T, E> - 에러 처리

E Result<T, E> {
    Ok(T),
    Err(E)
}

F parse_positive(x: i64) -> Result<i64, str> {
    I x < 0 {
        Err("Negative number")
    } E I x == 0 {
        Err("Zero")
    } E {
        Ok(x)
    }
}

F main() -> i64 {
    result1 := parse_positive(42)
    result2 := parse_positive(-5)

    M result1 {
        Ok(value) => {
            puts("Success: ")
            print_i64(value)  # 42
        },
        Err(msg) => {
            puts("Error: ")
            puts(msg)
        }
    }

    M result2 {
        Ok(value) => {
            puts("Success: ")
            print_i64(value)
        },
        Err(msg) => {
            puts("Error: ")
            puts(msg)  # "Negative number"
        }
    }

    0
}

HashMap<K, V> - 해시맵

U std/hashmap

F main() -> i64 {
    # HashMap<i64, i64>
    map := HashMap.with_capacity(10)

    # 삽입
    map.insert(1, 100)
    map.insert(2, 200)
    map.insert(3, 300)

    # 조회
    value := map.get(2)  # 200

    # 존재 확인
    exists := map.contains(1)  # 1

    # 크기
    size := map.len()  # 3

    print_i64(value)
    print_i64(size)

    map.drop()
    0
}

고급 패턴

제네릭 팩토리 패턴

S Box<T> {
    value: T
}

X Box<T> {
    # 정적 메서드 - 생성자
    F new(value: T) -> Box<T> {
        Box { value: value }
    }

    F get(&self) -> T {
        self.value
    }

    F set(&self, new_value: T) -> i64 {
        self.value = new_value
        0
    }
}

F main() -> i64 {
    # 팩토리 메서드 사용
    box1 := Box::new(42)
    box2 := Box::new(3.14)

    val1 := box1.get()  # 42

    box1.set(100)
    val2 := box1.get()  # 100

    print_i64(val1)
    print_i64(val2)

    0
}

제네릭 빌더 패턴

S Builder<T> {
    value: T,
    count: i64
}

X Builder<T> {
    F new(initial: T) -> Builder<T> {
        Builder { value: initial, count: 0 }
    }

    F with_count(&self, n: i64) -> Builder<T> {
        self.count = n
        self
    }

    F build(&self) -> T {
        self.value
    }
}

F main() -> i64 {
    builder := Builder::new(42)
    builder.with_count(10)
    result := builder.build()

    print_i64(result)  # 42
    0
}

제네릭 컨테이너 패턴

# Stack<T>
S Stack<T> {
    data: Vec<T>,
    top: i64
}

X Stack<T> {
    F new() -> Stack<T> {
        Stack {
            data: Vec.with_capacity(10),
            top: 0
        }
    }

    F push(&self, value: T) -> i64 {
        self.data.push(value)
        self.top = self.top + 1
        self.top
    }

    F pop(&self) -> Option<T> {
        I self.top > 0 {
            self.top = self.top - 1
            value := self.data.pop()
            Some(value)
        } E {
            None
        }
    }

    F is_empty(&self) -> i64 {
        I self.top == 0 { 1 } E { 0 }
    }
}

F main() -> i64 {
    stack := Stack::new()

    stack.push(10)
    stack.push(20)
    stack.push(30)

    M stack.pop() {
        Some(v) => print_i64(v),  # 30
        None => puts("Empty")
    }

    M stack.pop() {
        Some(v) => print_i64(v),  # 20
        None => puts("Empty")
    }

    0
}

타입 추론

타입 추론 규칙

Vais는 강력한 타입 추론을 제공합니다:

F identity<T>(x: T) -> T = x

F main() -> i64 {
    # 리터럴로부터 추론
    a := identity(42)        # T = i64
    b := identity(3.14)      # T = f64
    c := identity("text")    # T = str

    # 변수로부터 추론
    x := 100
    d := identity(x)         # T = i64 (x의 타입)

    # 반환 타입으로부터 추론
    result: i64 = identity(50)  # T = i64

    0
}

컨텍스트 기반 추론

S Pair<T> {
    first: T,
    second: T
}

F make_pair<T>(a: T, b: T) -> Pair<T> {
    Pair { first: a, second: b }
}

F main() -> i64 {
    # 반환 타입으로부터 추론
    p1: Pair<i64> = make_pair(10, 20)  # T = i64

    # 인자로부터 추론
    p2 := make_pair(1, 2)  # T = i64

    print_i64(p1.first)  # 10
    print_i64(p2.first)  # 1

    0
}

추론 실패와 명시적 타입

추론이 불가능한 경우:

# 이 함수는 T를 추론할 정보가 없음
F create_default<T>() -> T {
    # 기본값 반환
    0
}

F main() -> i64 {
    # 에러: T를 추론할 수 없음
    # x := create_default()

    # 해결: 타입 명시
    x: i64 = create_default()  # T = i64

    print_i64(x)
    0
}

실전 예제

예제 1: 제네릭 연결 리스트

E List<T> {
    Nil,
    Cons(T, i64)  # (value, next pointer)
}

X List<T> {
    F new() -> List<T> {
        Nil
    }

    F prepend(&self, value: T) -> List<T> {
        # self를 next로 하는 새 노드 생성
        Cons(value, 0)  # 간소화
    }

    F is_empty(&self) -> i64 {
        M self {
            Nil => 1,
            Cons(_, _) => 0
        }
    }

    F len(&self) -> i64 {
        M self {
            Nil => 0,
            Cons(_, next_ptr) => {
                # 재귀적으로 길이 계산
                1
            }
        }
    }
}

F main() -> i64 {
    list := List::new()

    node1 := list.prepend(10)
    node2 := node1.prepend(20)
    node3 := node2.prepend(30)

    is_empty := node3.is_empty()  # 0
    len := node3.len()             # 1

    print_i64(is_empty)
    print_i64(len)

    0
}

예제 2: 제네릭 Tree

E Tree<T> {
    Empty,
    Node(T, i64, i64)  # (value, left, right)
}

X Tree<T> {
    F empty() -> Tree<T> {
        Empty
    }

    F leaf(value: T) -> Tree<T> {
        Node(value, 0, 0)
    }

    F height(&self) -> i64 {
        M self {
            Empty => 0,
            Node(_, _, _) => 1
        }
    }

    F is_leaf(&self) -> i64 {
        M self {
            Empty => 0,
            Node(_, left, right) => {
                I left == 0 && right == 0 { 1 } E { 0 }
            }
        }
    }
}

F main() -> i64 {
    empty := Tree::empty()
    leaf := Tree::leaf(42)

    h1 := empty.height()    # 0
    h2 := leaf.height()     # 1
    is_l := leaf.is_leaf()  # 1

    print_i64(h1)
    print_i64(h2)
    print_i64(is_l)

    0
}

예제 3: 제네릭 Iterator

W Iterator<T> {
    F next(&self) -> Option<T>
    F has_next(&self) -> i64
}

S RangeIterator {
    current: i64,
    end: i64
}

X RangeIterator: Iterator<i64> {
    F next(&self) -> Option<i64> {
        I self.current < self.end {
            value := self.current
            self.current = self.current + 1
            Some(value)
        } E {
            None
        }
    }

    F has_next(&self) -> i64 {
        I self.current < self.end { 1 } E { 0 }
    }
}

F sum_iterator<T>(iter: &Iterator<T>) -> i64 {
    sum := 0

    L iter.has_next() {
        M iter.next() {
            Some(value) => {
                sum = sum + value
            },
            None => B
        }
    }

    sum
}

F main() -> i64 {
    iter := RangeIterator { current: 0, end: 10 }

    # 0+1+2+...+9 = 45
    total := sum_iterator(&iter)

    print_i64(total)  # 45
    0
}

예제 4: 제네릭 캐시

U std/hashmap
U std/option

S Cache<K, V> {
    map: HashMap<K, V>,
    capacity: i64
}

X Cache<K, V> {
    F new(capacity: i64) -> Cache<K, V> {
        Cache {
            map: HashMap.with_capacity(capacity),
            capacity: capacity
        }
    }

    F get(&self, key: K) -> Option<V> {
        has := self.map.contains(key)

        I has {
            value := self.map.get(key)
            Some(value)
        } E {
            None
        }
    }

    F put(&self, key: K, value: V) -> i64 {
        # 용량 체크
        I self.map.len() >= self.capacity {
            puts("Cache full!")
            0
        } E {
            self.map.insert(key, value)
            1
        }
    }

    F clear(&self) -> i64 {
        self.map.clear()
        0
    }
}

F main() -> i64 {
    cache := Cache::new(3)

    # 데이터 저장
    cache.put(1, 100)
    cache.put(2, 200)
    cache.put(3, 300)

    # 조회
    M cache.get(2) {
        Some(value) => {
            puts("Found: ")
            print_i64(value)  # 200
        },
        None => {
            puts("Not found")
        }
    }

    # 없는 키
    M cache.get(99) {
        Some(value) => {
            puts("Found: ")
            print_i64(value)
        },
        None => {
            puts("Not found")  # 이쪽 실행
        }
    }

    cache.clear()
    0
}

성능 고려사항

Monomorphization의 장단점

장점:

• 런타임 오버헤드 없음 (virtual dispatch 불필요)
• 인라이닝 최적화 가능
• 타입별 최적화 가능

단점:

• 코드 크기 증가 (각 타입마다 별도 코드)
• 컴파일 시간 증가

제네릭 사용 팁

1. 자주 사용하는 타입만 제네릭으로:

# 좋음: 재사용성 높음
F swap<T>(a: T, b: T) -> (T, T) {
    (b, a)
}

# 피하기: 한 번만 사용
F process_int(x: i64) -> i64 = x * 2
# 제네릭 불필요

2. 타입 수 제한:

# 많은 타입에 사용 -> 큰 바이너리
F generic<A, B, C, D, E>(...) -> ... { ... }

# 필요한 만큼만
F simple<T>(x: T) -> T { x }

3. 인라인 가능한 작은 함수:

# 인라인되기 좋음
F identity<T>(x: T) -> T = x

# 큰 함수는 신중히
F complex<T>(x: T) -> T {
    # 100줄 코드...
}

요약

핵심 개념

1. 제네릭 함수: F name<T>(x: T) -> T
2. 제네릭 구조체: S Name<T> { field: T }
3. 제네릭 Enum: E Name<T> { Variant(T) }
4. 트레이트 정의: W Trait { F method(&self) }
5. 트레이트 구현: X Type: Trait { F method(&self) { ... } }
6. 제네릭 바운드: <T: Trait>

베스트 프랙티스

• ✅ 타입 추론 활용
• ✅ 재사용성 높은 코드에 제네릭 사용
• ✅ 트레이트로 공통 인터페이스 정의
• ✅ 표준 라이브러리 제네릭 타입 활용 (Vec, Option, Result)
• ❌ 과도한 제네릭화 피하기
• ❌ 불필요한 트레이트 바운드 피하기

다음 단계

• 고급 트레이트 패턴
• 제네릭과 Async 결합
• 커스텀 컬렉션 구현
• 제네릭 라이브러리 설계

참고 자료

• 기본 튜토리얼: TUTORIAL.md
• Async 튜토리얼: async_tutorial.md
• 언어 스펙: LANGUAGE_SPEC.md
• 표준 라이브러리: STDLIB.md
• 예제 코드:
  • examples/generic_struct_test.vais
  • examples/generic_bounds_test.vais
  • examples/trait_test.vais
  • examples/option_test.vais

Happy generic coding with Vais!

Type Inference Safety

Vais features a powerful type inference system that reduces boilerplate while maintaining type safety. Since Phase 61, the compiler enforces stricter rules to prevent ambiguous type inference scenarios.

Inference Rules

Automatic Type Inference

When type information can be unambiguously determined from context, Vais infers types automatically:

F add(a: i64, b: i64) -> i64 {
    a + b
}

F main() -> i64 {
    x := 5          # i64 inferred from literal
    y := add(x, 3)  # i64 inferred from function signature
    0
}

Unconstrained Type Error (E032)

When the compiler cannot infer types from context, it raises an InferFailed error (E032):

# ERROR: Cannot infer parameter types
F add(a, b) {
    a + b
}
# Error E032: Type inference failed: unconstrained type parameters

This prevents the compiler from making arbitrary assumptions about types, which could lead to runtime errors or unexpected behavior.

Fix: Provide explicit type annotations:

F add(a: i64, b: i64) -> i64 {
    a + b
}

Recursive Functions

Return Type Required

Functions that use self-recursion (via @) must specify an explicit return type:

# ERROR: Missing return type in recursive function
F fib(n: i64) {
    I n <= 1 { n }
    E { @(n - 1) + @(n - 2) }
}
# Error E032: Recursive function requires explicit return type annotation

Why? The compiler needs the return type to properly type-check recursive calls before the function body is fully analyzed.

Fix: Add the return type annotation:

F fib(n: i64) -> i64 {
    I n <= 1 { n }
    E { @(n - 1) + @(n - 2) }
}