Documentation

Master the art of human-first coding with our comprehensive guides.

Install Pumpkin

Get up and running in seconds.

NPM (Recommended)

For macOS, Linux, and Windows

$ npm install pumpkin-lang

Requires Node.js v14+. Add -g for global (may require sudo).

# Verify the install
$ npx pumpkin --version

Binaries

Standalone executables for x86_64 systems. No dependencies required.

Download Release

From Source

Build the optimized Rust core yourself. Requires Cargo.

cargo install --path .
v0.1 Reference

Language Reference

Everything you need to master the craft of writing Pumpkin code.

Program Structure

A Pumpkin program is a sequence of statements executed from top to bottom.

show "Start"
let x = 10
show x

Comments

Use # for comments. They are ignored by the computer.

# This is a comment
let x = 1 # Inline comment

Variables

Use let to create variables. Use = to update.

let name = "Pumpkin"
name = "Pie"

Types

  • Number: 42, 3.14
  • String: "Hello"
  • Boolean: true, false

Math & Logic

Math: +, -, *, /, ^

Logic: Use English keywords.

true and false
not true
10 > 5

Conditionals

if score > 90 {
    show "Win"
} else {
    show "Try loop"
}

Loops

While and Repeat loops.

repeat 3 times {
    show "Hip Hop"
}

while x < 5 { ... }

Output

Use show to print to the screen.

show "Hello World"
Deep Dive

Language Semantics

How Pumpkin actually thinks and works under the hood.

Stack Execution

Pumpkin runs on a Stack-Based Virtual Machine. Expressions are evaluated Left-to-Right. Logical operators use short-circuit evaluation.

# VM Lab: 1 + 2 * 3
01 PUSH 1
02 PUSH 2
03 PUSH 3
04 MUL (Pop 2, 3 → Push 6)
05 ADD (Pop 1, 6 → Push 7)

Scoping

  • Global Scope

    Variables at the top level persist for the entire program lifetime. Rooted in the patch.

  • Local Scope

    Variables inside functions exist only during the call. Clean. Predictable. Lexical.

Truthiness

Only false and nil are falsy. Everything else is true. No weird edge cases.

falseFalse
nilFalse
trueTrue
0True
""True
[]True

Runtime Safety

  • Memory Safe

    No buffer overflows or raw pointer access. The VM handles the ground work.

  • Strict Sandbox

    No file system or network access by default. Secure from the first seed.

  • Panic-Free

    Runtime errors halt execution safely with human-readable diagnostics.

Known Limitations (v0.1)

Transparent constraints of the initial release.

No User-Defined Functions

You cannot define reusable blocks of code with parameters.

Rationalizationv0.1 focuses on linear imperative execution logic.

Fixed in v0.2

No Arrays or Lists

Variables can only hold single numbers, strings, or booleans.

RationalizationHeap allocation and GC complexity were deferred.

Fixed in v0.2

Single-File Only

No imports. All code must reside in a single .pumpkin file.

RationalizationModule resolution logic is complex intentionally.

Fixed in v0.2

No File I/O

You cannot read/write files. Only 'show' output is supported.

RationalizationStrict sandboxing for embedded safety.

Planned for v0.3
Project Blueprint

Architecture Overview

How the Pumpkin repository is organized for stability and speed.

pumpkin_core/

The Rust Engine

Contains the VM, Compiler, and OpCode definitions. The source of truth for execution.

grammar/

Syntax Definition

Holds 'pumpkin.ohm'. Uses Ohm.js (PEG) to define the human-friendly syntax rules.

src/

CLI & Tooling

TypeScript wrappers for the CLI commands and legacy interpreter logic.

website/

Documentation

Next.js application powering this site and the playground.

The Compilation Pipeline

Source Code (.pumpkin)
Lexer/Parser (Ohm)
Abstract Syntax Tree
Bytecode VM (Rust)
Gallery

Learn by Example

Real programs you can study, run, and break right now.

FizzBuzz

The classic programming challenge. Print Fizz, Buzz, or FizzBuzz.

let i = 1
while i <= 20 {
    let is_fizz = i % 3 == 0
    let is_buzz = i % 5 == 0
    
    if is_fizz and is_buzz {
        show "FizzBuzz"
    } else {
        if is_fizz {
            show "Fizz"
        } else {
            if is_buzz {
                show "Buzz"
            } else {
                show i
            }
        }
    }
    i = i + 1
}

Prime Checker

Check if a number is prime using a simple division test.

let number = 17
let is_prime = true

if number < 2 {
    is_prime = false
}

let divisor = 2
while divisor < number {
    if number % divisor == 0 {
        is_prime = false
    }
    divisor = divisor + 1
}

if is_prime {
    show "Prime!"
} else {
    show "Not prime"
}

Factorial

Calculate n! iteratively (e.g., 5! = 120).

let n = 5
let result = 1
let counter = n

while counter > 0 {
    result = result * counter
    counter = counter - 1
}

show result

State Machine

A traffic light that cycles: Green → Yellow → Red.

let state = "green"
let cycles = 0

while cycles < 6 {
    show state
    
    if state == "green" {
        state = "yellow"
    } else {
        if state == "yellow" {
            state = "red"
        } else {
            state = "green"
        }
    }
    cycles = cycles + 1
}

Hungry for more code?

Browse GitHub Examples
Console Mastery

Command Line Interface

Control Pumpkin directly from your favorite terminal.

run

<file.pumpkin>

Executes a source file.

$ pumpkin run hello.pumpkin

repl

no flags

Starts interactive mode.

$ pumpkin repl

--version

no flags

Shows current version.

$ pumpkin --version

--help

[command]

Displays help info.

$ pumpkin --help