[!IMPORTANT] Solo Developer Project: Neutron is actively developed by a single developer and currently lacks many advanced features and libraries found in mature languages. The ecosystem is small with no established community yet. Contributions are highly encouraged to help grow the language and its ecosystem!

Overview

Neutron is a high-performance, dynamically-typed programming language with a modern C++ runtime. Designed for developers who want Python's simplicity with significantly better performance, Neutron combines familiar syntax with native compilation capabilities and a comprehensive standard library.

Key Highlights

[!NOTE] New to Neutron? Check out the Quick Start Guide to get running in under 5 minutes.

Why Choose Neutron?

Performance That Matters

Neutron's C++ bytecode virtual machine delivers 2-10x faster execution compared to Python for computational workloads. The combination of efficient bytecode compilation and native C++ runtime makes it ideal for:

• Data processing pipelines
• System automation scripts
• Web servers and API backends
• Command-line tools
• Algorithm implementations

Developer-Friendly Design

Familiar Syntax - C-style syntax that feels natural if you know JavaScript, Python, or Java
Dynamic Typing - Write code quickly without type annotations, with runtime type safety
Rich Standard Library - Batteries included: HTTP client, JSON, file I/O, math, time, and more
Zero Configuration - No virtual environments, pip issues, or dependency conflicts

Architecture

Neutron is built on a modern three-stage architecture designed for both performance and flexibility:

┌─────────────────────────────────────────────────────────────────┐
│                     Neutron Architecture                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  Source Code (.nt)                                              │
│        ↓                                                         │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │ Scanner & Parser (C++)                                    │  │
│  │ • Lexical analysis                                        │  │
│  │ • Syntax tree generation                                  │  │
│  └──────────────────────────────────────────────────────────┘  │
│        ↓                                                         │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │ Bytecode Compiler                                         │  │
│  │ • Optimized bytecode generation                           │  │
│  │ • Static analysis                                         │  │
│  │ • Constant folding                                        │  │
│  └──────────────────────────────────────────────────────────┘  │
│        ↓                                                         │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │ Virtual Machine (C++ Runtime)                             │  │
│  │ • Stack-based bytecode interpreter                        │  │
│  │ • Native function integration                             │  │
│  │ • Automatic memory management                             │  │
│  │ • JIT-ready architecture                                  │  │
│  └──────────────────────────────────────────────────────────┘  │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Core Components

Scanner & Parser - Hand-written lexer and recursive descent parser in C++ for maximum speed

Bytecode Compiler - Converts AST to optimized bytecode with single-pass compilation

Virtual Machine - Stack-based VM with efficient instruction dispatch using C++ switch statements

Memory Management - Smart pointers and RAII patterns ensure zero memory leaks

Native Module Interface - Direct C++ integration without FFI overhead

Performance Optimizations

• Bytecode Caching - Compiled bytecode can be serialized for faster startup
• Inline Caching - Method lookup optimization for object-oriented code
• Native Modules - Performance-critical code runs at C++ speed
• Efficient Value Representation - Tagged unions minimize memory overhead
• Direct System Calls - No interpreter overhead for I/O operations

Core Features

Installation

Prerequisites

Build from Source

# Linux (Debian/Ubuntu)
sudo apt-get install build-essential cmake libcurl4-openssl-dev libjsoncpp-dev
cmake -B build && cmake --build build -j$(nproc)

# macOS
brew install cmake curl jsoncpp
cmake -B build && cmake --build build -j$(sysctl -n hw.ncpu)

# Windows (Visual Studio)
cmake -B build && cmake --build build --config Release

# Windows (MSYS2 MINGW64 - Alternative)
pacman -S mingw-w64-x86_64-{gcc,cmake,curl,jsoncpp} make
cmake -B build -G "MSYS Makefiles" && cmake --build build

Build Options

# Example: Enable unsafe optimizations for benchmarking
cmake -B build -DNEUTRON_UNSAFE_OPTIMIZATIONS=ON
cmake --build build --config Release

[!WARNING] For detailed platform-specific instructions and troubleshooting, see the Build Guide.

Running Tests

python3 run_tests.py          # Linux/macOS
python3 run_tests.py

The test suite includes 21 comprehensive tests covering all language features. See Test Suite Documentation for details.

Shell Completion (Optional)

Enable tab completion for better command-line experience:

# ZSH - Add to ~/.zshrc
fpath=(/path/to/neutron/scripts $fpath)
autoload -U compinit && compinit

# Bash - Add to ~/.bashrc
source /path/to/neutron/scripts/neutron-completion.bash

See scripts/README.md for detailed installation instructions.

Quick Start

Project-Based Development

# Create a new project
./neutron init my-app

# Run your project
./neutron run

# Build to standalone native executable (bundles all dependencies)
./neutron build

# Install Box package manager
./neutron install box

Hello World

// hello.nt
say("Hello, World!");

./neutron hello.nt  # Run it directly

[!TIP] Common Mistake: Use .length (property), not .length() (method). See Common Pitfalls Guide.

[!NOTE] Looking for more examples? Check out the examples/real_world/ directory for practical applications like a Todo CLI, HTTP Server, and Data Processing scripts.

Real-World Examples

// github.nt - Fetch repository information
use http;
use json;

var response = http.get("https://api.github.com/repos/microsoft/vscode");
var repo = json.parse(response.body);

say("Repository: ${repo.name}");
say("Stars: ${repo.stargazers_count}");
say("Forks: ${repo.forks_count}");
say("Language: ${repo.language}");

// server.nt - Simple HTTP server
use http;

fun handler(req) {
    say("Request: " + req.method + " " + req.path);
    
    if (req.path == "/") {
        return "Hello from Neutron!";
    } else {
        return {
            "status": 404,
            "body": "Not Found"
        };
    }
}

say("Starting server on port 8080...");
var server = http.createServer(handler);
http.listen(server, 8080);

// fibonacci.nt - Fast recursive fibonacci
fun fib(n) {
    if (n <= 1) return n;
    return fib(n - 1) + fib(n - 2);
}

use time;
var start = time.now();

for (var i = 0; i < 30; i = i + 1) {
    say("fib(${i}) = ${fib(i)}");
}

var elapsed = time.now() - start;
say("Computed in ${elapsed}ms");

// person.nt - Object-oriented programming
class Person {
    var name;
    var age;

    fun init(name, age) {
        this.name = name;
        this.age = age;
    }

    fun greet() {
        return "Hi, I'm ${this.name}, ${this.age} years old";
    }

    fun birthday() {
        this.age = this.age + 1;
        say("Happy birthday! Now ${this.age}!");
    }
}

var alice = Person();
alice.init("Alice", 25);
say(alice.greet());
alice.birthday();

// analyzer.nt - Analyze log files
use sys;

var content = sys.read("server.log");
var lines = content.split("\n");

var errors = 0;
var warnings = 0;

for (var i = 0; i < lines.length(); i = i + 1) {
    var line = lines[i];
    if (line.contains("ERROR")) {
        errors = errors + 1;
    }
    if (line.contains("WARN")) {
        warnings = warnings + 1;
    }
}

say("Log Analysis:");
say("  Errors: ${errors}");
say("  Warnings: ${warnings}");

[!TIP] See the Quick Start Guide for more examples and the Language Reference for complete syntax.

Documentation

Complete Documentation Index

Essential Guides

• Project System Guide - Project management, building, and deployment
• Language Reference - Complete syntax and features
• Module System - Using and creating modules

Module Documentation

• Sys Module - File I/O and system operations
• JSON Module - JSON parsing, serialization, and file I/O
• HTTP Module - HTTP client and server functionality
• Regex Module - Regular expressions and pattern matching
• Math Module - Mathematical operations
• More modules...

Box Package Manager

Native C++ modules for Neutron - Install, manage, and use high-performance native extensions with zero configuration. Box automatically detects Neutron projects and installs modules locally.

Installation Example

# Install a native module (auto-installs to .box/modules/ in projects)
box install base64

// Use it in your code immediately
use base64;

var encoded = base64.encode("Hello, World!");
say(encoded);  // SGVsbG8sIFdvcmxkIQ==

var decoded = base64.decode(encoded);
say(decoded);  // Hello, World!

Features

Common Commands

[!NOTE] See Box Documentation for creating native modules and the Box Modules Guide for advanced usage.

Language Syntax

Variables & Functions

// Variables with dynamic typing
var name = "Alice";
var age = 25;
var scores = [95, 87, 92];

// Functions
fun add(a, b) {
    return a + b;
}

// Lambdas
var multiply = fun(a, b) { return a * b; };
say(multiply(3, 4));  // 12

Control Flow

// If-else
if (age >= 18) {
    say("Adult");
} else {
    say("Minor");
}

// Loops
for (var i = 0; i < 10; i = i + 1) {
    say(i);
}

while (condition) {
    // loop body
}

// Match statement (pattern matching)
match (value) {
    case 1 => say("One");
    case 2 => say("Two");
    default => say("Other");
}

Classes & OOP

class Animal {
    init(name) {
        this.name = name;
    }

    speak() {
        return "${this.name} makes a sound";
    }
}

class Dog extends Animal {
    speak() {
        return "${this.name} barks!";
    }
}

var dog = Dog("Buddy");
say(dog.speak());  // Buddy barks!

Exception Handling

try {
    var data = json.parse(invalid_json);
} catch (e) {
    say("Error: ${e}");
} finally {
    say("Cleanup code here");
}

[!NOTE] For complete language documentation, see the Language Reference.

Performance Comparison

Neutron vs Python

Neutron significantly outperforms Python in computational tasks thanks to its C++ bytecode VM and efficient runtime:

[!TIP] Run ./run_benchmark.sh to see real-time performance comparisons on your hardware.

Why Neutron is Faster

1. C++ Native Runtime

• No interpreter overhead - bytecode executes directly in C++
• Efficient instruction dispatch with optimized switch statements
• Native data structures with minimal boxing/unboxing

2. Optimized Bytecode

• Single-pass compilation with constant folding
• Efficient stack-based operations
• Minimal bytecode instruction set for better cache locality

3. Direct System Integration

• Native C++ modules run at full CPU speed
• No FFI marshalling overhead
• Direct memory access for I/O operations

4. Smart Memory Management

• C++ smart pointers with deterministic destruction
• No stop-the-world garbage collection pauses
• Efficient reference counting for complex types

Contributing

We welcome contributions from the community! Whether it's bug fixes, new features, documentation improvements, or native modules.

How to Contribute

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Guidelines

• Read CONTRIBUTING.md for detailed guidelines
• Follow the existing code style and conventions
• Write tests for new features
• Update documentation as needed

Community

• Discord: Join our server for discussions and support
• Issues: Report bugs or request features
• Discussions: Share ideas and get help from the community

License

Neutron is distributed under the Neutron Public License 1.0.

See LICENSE for complete terms and conditions.