Simply Documentation

The complete reference for the Simply programming language — syntax, built-ins, package bridging, tools, and everything in between.

What is Simply?

Simply is a dynamically-typed, interpreted programming language designed to be readable, minimal, and immediately useful. Its biggest feature is native bridging to both the npm (Node.js) and Python package ecosystems — meaning you can import and call packages from either ecosystem directly inside your .simply file without writing JavaScript or Python yourself.

Simply files use the .simply extension and are run by the Simply interpreter (simply.exe) either from the command line or by double-clicking the file.

Design goals

• Syntax that reads close to plain English
• Consistent structure — every block opens with { and closes with } end
• Zero package manager — use npm and Python packages you already have
• Auto type inference with opt-in strict typing
• Works from the terminal and by double-clicking

Installation

Simply runs on Windows, macOS, and Linux. Pick your platform below.

🍎 macOS & 🐧 Linux

The Mac/Linux build is a Node.js script. Open your Terminal and paste:

curl -fsSL beirutsites.com/simply/install.sh | bash

This downloads simply.js to ~/.simply/, creates a simply command in ~/.local/bin/, adds it to your PATH (via ~/.zshrc or ~/.bashrc), and optionally installs the VSCode syntax extension.

Update or uninstall

curl -fsSL beirutsites.com/simply/install.sh | bash -s update
curl -fsSL beirutsites.com/simply/install.sh | bash -s uninstall

🪟 Windows

Simply is installed through the Simply Bootstrapper — a small GUI application that downloads, installs, updates, and removes Simply (interpreter + IDE) from your machine.

Step 1 — Download the Bootstrapper

Go to beirutsites.com/simply and click Download for Windows. The bootstrapper is a single .exe file (~22 KB).

Step 2 — Install Simply

1. Open the downloaded bootstrapper.
2. Windows will ask for admin rights (UAC prompt) — click Yes. This is needed to add Simply to your system PATH.
3. Choose a version from the dropdown (latest beta is selected by default).
4. Optionally check "Install VSCode syntax highlighting extension" if you have VSCode installed.
5. Click Install Simply.

Simply installs to C:\Simply\ and is added to your system PATH automatically. After installation you can open any terminal and run:

simply --version

Prerequisites

Updating Simply

Open the bootstrapper again. It detects your installed version and shows an Update Simply button. Pick the version you want from the dropdown and click Update.

Uninstalling Simply

Open the bootstrapper and click Uninstall. This removes C:\Simply\ from disk, removes it from PATH, and unregisters the .simply file type.

Your First Program

Create a file called hello.simply and write:

define name = "World"
output("Hello, " + name + "!")

Run it:

simply hello.simply

Output:

Hello, World!

You can also double-click hello.simply in File Explorer and it will open a console window and run.

Running Files

Command line

simply <file.simply>
simply --version

Double-click

After installation, .simply files are registered with Windows. Double-clicking any .simply file runs it in a console window.

Comments

Comments begin with -- and run to the end of the line. There are no multi-line comments.

-- This is a comment
define x = 5  -- inline comment
output(x)    -- prints 5

Variables & Types

Variables are declared with the define keyword. Simply automatically infers the type of the value. You can also enforce a specific type using define:Type.

Auto-typed declaration

define age = 25           -- Int
define name = "Alice"     -- String
define active = true     -- Bool
define score = 9.5       -- Float
define items = [1, 2, 3] -- Array
define nothing = null    -- Null

Strict-typed declaration

Add :Type after define to enforce a type. Simply will try to coerce the value — if it can't, it throws an error.

define:String  city   = "Beirut"
define:Int     count  = 10
define:Float   ratio  = 3.14
define:Bool    flag   = false

-- Coercion example: number → string
define:String numStr = 42   -- becomes "42"

Reassigning variables

Use the variable name and = without define to reassign an existing variable:

define x = 10
x = 20
output(x)  -- 20

Types reference

Operators

Arithmetic

Comparison

Logical

Truthy & falsy values

Simply follows these truthiness rules in conditions:

null
false
0
""         -- empty string
[]         -- empty array

true
-- any non-zero number
-- any non-empty string
-- any non-empty array
-- any function

Output

output() prints a value to the console followed by a newline. It accepts any type and converts it to a readable string automatically.

output("Hello")           -- Hello
output(42)              -- 42
output(true)           -- true
output([1, 2, 3])     -- [1, 2, 3]
output("x = " + x)     -- concatenation

To print without a newline is not directly supported in v1.0-beta. Use output() and structure your output accordingly.

User Input

The built-in input() function reads a line from the user. You can pass an optional prompt string.

define name = input("Enter your name: ")
output("Hello, " + name)

-- Convert to number
define age = num(input("Enter your age: "))
output("In 10 years you will be " + (age + 10))

If / Else

Conditionals use if (condition) { } end. An optional else { } block can follow before end.

define score = 75

if (score >= 90) {
    output("Grade: A")
} else {
    output("Grade: B or lower")
} end

Chained conditions

Use and / or to combine multiple conditions in one check:

define age = 20
define hasId = true

if (age >= 18 and hasId) {
    output("Access granted")
} else {
    output("Access denied")
} end

Nested if

define x = 15

if (x > 10) {
    if (x > 20) {
        output("very big")
    } else {
        output("medium")
    } end
} else {
    output("small")
} end

loop()

Repeat a block a fixed number of times. The count is an expression evaluated once before the loop begins.

loop (5) {
    output("Hello!")
} end

-- With a variable
define times = 3
loop (times) {
    output("repeating")
} end

while()

Repeat a block as long as a condition is truthy. The condition is checked before each iteration.

define i = 0

while (i < 5) {
    output("i = " + i)
    i = i + 1
} end

for...in

Iterate over every element of an array. The loop variable is scoped to the loop body.

define fruits = ["apple", "banana", "mango"]

for (fruit in fruits) {
    output(fruit)
} end

With range()

Use the built-in range() function to iterate over a numeric sequence:

-- range(n) → [0, 1, 2, ..., n-1]
for (i in range(5)) {
    output(i)
} end

-- range(start, end)
for (i in range(3, 8)) {
    output(i)   -- 3 4 5 6 7
} end

Defining Functions

Functions are declared with fn followed by the name, a parameter list in (), a body in { }, and closing end.

fn greet(name) {
    output("Hello, " + name + "!")
} end

greet("Alice")   -- Hello, Alice!
greet("Bob")     -- Hello, Bob!

Multiple parameters

fn add(a, b) {
    output(a + b)
} end

add(3, 7)   -- 10

No parameters

fn sayHi() {
    output("Hi!")
} end

sayHi()

Functions as values

Functions are first-class values in Simply. You can store them in variables and pass them around:

fn double(x) {
    return(x * 2)
} end

define op = double
output(op(5))   -- 10

Return Values

Use return(value) inside a function to exit early and produce a value. If a function reaches its end without a return, it returns null.

fn multiply(a, b) {
    return(a * b)
} end

define result = multiply(4, 6)
output(result)   -- 24

Early return (guard clause)

fn safeDivide(a, b) {
    if (b = 0) {
        return("Cannot divide by zero")
    } end
    return(a / b)
} end

output(safeDivide(10, 2))   -- 5
output(safeDivide(10, 0))   -- Cannot divide by zero

Function Expressions

You can create anonymous functions inline using fn(params) { } end and assign them to variables or pass them as arguments.

define square = fn(x) {
    return(x * x)
} end

output(square(9))   -- 81

Passing functions as arguments

fn applyTwice(f, x) {
    return(f(f(x)))
} end

define addOne = fn(n) { return(n + 1) } end

output(applyTwice(addOne, 5))   -- 7

Scope

Simply uses lexical (static) scoping. Each block (if, while, for, fn) creates its own scope. Inner scopes can read variables from outer scopes, and can modify them if they already exist.

define count = 0

fn increment() {
    count = count + 1   -- modifies outer 'count'
} end

increment()
increment()
output(count)   -- 2

Arrays

Arrays are ordered lists of values. They are created with square bracket literals and can hold any mix of types.

define nums   = [1, 2, 3, 4, 5]
define mixed  = ["hello", 42, true, null]
define empty  = []

-- Access by index (zero-based)
output(nums[0])   -- 1
output(nums[4])   -- 5

-- Assign by index
nums[0] = 99
output(nums[0])   -- 99

-- Length
output(nums.length)   -- 5

Array Methods

define list = ["a", "b", "c"]

list.push("d")
output(list)              -- [a, b, c, d]

output(list.join("-"))   -- a-b-c-d

output(list.contains("b"))  -- true
output(list.indexOf("c"))   -- 2

output(list.slice(1, 3))   -- [b, c]

define removed = list.pop()
output(removed)   -- d

Higher-Order Array Methods New in v2.0

Functional programming on arrays. Each method takes a callback function.

define nums = [3, 1, 4, 1, 5, 9, 2]

define doubled = nums.map(fn(n) { return(n * 2) } end)
define evens   = nums.filter(fn(n) { return(n % 2 = 0) } end)
define total   = nums.reduce(fn(acc, n) { return(acc + n) } end, 0)

output(doubled)   -- [6, 2, 8, 2, 10, 18, 4]
output(evens)     -- [4, 2]
output(total)     -- 25

Objects New in v2.0

Objects are key-value collections. Keys are strings, values are any Simply type. Objects are the foundation of structured data — use them for JSON responses, configs, models, anything.

Creating objects

define user = {
    name: "Firas",
    age: 25,
    city: "Beirut",
    skills: ["JS", "Python", "Simply"]
}

output(user.name)        -- Firas
output(user.skills[0])   -- JS

Modifying objects

user.age = 26
user.age += 1
user.email = "firas@example.com"   -- add new property

output(user.age)    -- 27
output(user.email)  -- firas@example.com

Object utilities

String Methods

Strings in Simply are immutable sequences of characters. Method calls return new strings.

define s = "  Hello, World!  "

output(s.trim())                    -- "Hello, World!"
output(s.trim().lower())            -- "hello, world!"
output(s.trim().replace(",", ""))  -- "Hello World!"

define words = "one two three"
define parts = words.split(" ")
output(parts[1])   -- two

try / catch

Use try { } catch (e) { } end to handle errors. If any code in the try block throws an error, execution jumps to the catch block. The error message is bound to the variable in the parentheses.

try {
    define x = num("not a number")
    output(x)
} catch (err) {
    output("Caught error: " + err)
} end

Catching package errors

Wrap use statements and package calls in try/catch to handle missing packages gracefully:

try {
    use npm:axios
    output("axios is available")
} catch (e) {
    output("Please run: npm install axios")
} end

String Interpolation New in v2.0

Embed variables directly inside string literals using {varName}. Only scope-level variables work — to embed object properties, assign them first.

define name = "Alice"
define age = 30

output("Hello, {name}! You are {age} years old.")

-- For object properties, extract first
define user = { city: "Beirut" }
define city = user.city
output("You live in {city}.")

Importing Other Simply Files New in v2.0

Split your code across multiple .simply files and load them with import. The imported file runs in your current scope — any functions or variables it defines become available.

fn double(x) { return(x * 2) } end

fn greet(name) { output("Hello, {name}!") } end

import "utils.simply"

greet("World")
output(double(21))   -- 42

Paths are resolved relative to the file doing the import. Use forward slashes for cross-platform code.

File I/O New in v2.0

Read, write, and manage files and directories directly — no package bridging required.

File operations

Directory operations

-- Read a file, modify, write back
define content = readFile("notes.txt")
content = content + "\nNew line added"
writeFile("notes.txt", content)

-- List all .simply files in a folder
for (file in listDir("./src")) {
    if (file.endsWith(".simply")) { output(file) } end
} end

Paths are resolved relative to the running .simply file, just like import.

HTTP — fetch() New in v2.0

Make HTTP requests with the built-in fetch() function. No imports, no package install.

Basic GET

define resp = fetch("https://api.github.com")

if (resp.ok) {
    output("Status: " + resp.status)
    output(resp.text)
} end

POST with JSON body

define body = json.stringify({
    name: "firas",
    age: 25
})

define resp = fetch("https://api.example.com/users", {
    method: "POST",
    body: body,
    headers: {
        "Content-Type": "application/json",
        "Authorization": "Bearer abc123"
    }
})

output(resp.status)
define data = json.parse(resp.text)
output(data.id)

Response object

JSON New in v2.0

Convert between Simply objects/arrays and JSON strings.

define data = {
    name: "Simply",
    version: "2.0.0-beta",
    features: ["objects", "http", "file-io"]
}

define jsonStr = json.stringify(data, 2)
output(jsonStr)

define parsed = json.parse(jsonStr)
output(parsed.features[0])   -- objects

Package Bridging — Overview

Simply has no built-in package manager of its own. Instead, it bridges directly to the two most widely used package ecosystems: npm (Node.js) and Python (pip).

How it works

1. You write use npm:packagename or use python:packagename at the top of your file.
2. Simply checks that the package is installed on your system. If not, it throws a clear error with the install command.
3. The package name becomes a variable in your Simply scope. You can call methods on it.
4. Under the hood, Simply spawns a node -e or python -c subprocess, passes arguments as JSON, and captures the result as a Simply value.

Prerequisites

• For use npm:x — Node.js must be installed and node must be on PATH.
• For use python:x — Python 3 must be installed and python or python3 must be on PATH.
• The package itself must already be installed (npm install x or pip install x).

npm Packages

Import any installed npm package with use npm:packagename. The package name becomes a variable you can call methods on.

use npm:lodash

define nums = [3, 1, 4, 1, 5, 9, 2]
define sorted = lodash.sortBy(nums)
output(sorted)

Installing an npm package

Open any terminal in the folder where your .simply file is and run:

npm install lodash
npm install axios
npm install chalk

What happens if the package is missing

Simply Error: npm package 'lodash' not found. Install it with: npm install lodash

Calling methods

Method calls on npm objects follow the pattern package.method(args). Arguments are serialised to JSON and the return value is parsed from JSON back into a Simply value.

use npm:lodash

define words = ["hello", "world", "simply"]

-- Call lodash.uniq
define dupes = [1, 2, 2, 3, 3, 3]
define unique = lodash.uniq(dupes)
output(unique)   -- [1, 2, 3]

Python Packages

Import any installed Python package with use python:packagename. Follows the same pattern as npm bridging.

use python:math

output(math.sqrt(144))    -- 12.0
output(math.floor(3.9))   -- 3
output(math.pi)            -- 3.141592653589793

Installing a Python package

pip install requests
pip install numpy
pip install pandas

Using requests (HTTP)

use python:requests

try {
    define resp = requests.get("https://api.github.com")
    output(resp.status_code)
} catch (e) {
    output("Request failed: " + e)
} end

Built-in Functions

These functions are always available — no import needed.

Math Functions

Built-in math functions — no import required.

-- Random integer between 1 and 10
define roll = floor(random() * 10) + 1
output("You rolled: " + roll)

Simply Code IDE New in v2.0

Simply Code is a dedicated, dark-themed (and light-themed) IDE for the Simply language. It ships with Simply — installed automatically by the bootstrapper, with shortcuts placed on your Desktop and in Documents.

Launching

• Double-click the Simply Code desktop shortcut
• Or open the Documents folder and double-click Simply Code.lnk
• From a terminal: simply-code or simply-code path/to/file.simply
• Double-click any .simply file → choose Open in Simply Code in the popup
• Right-click any .simply file → Edit with Simply Code

Simply Code — Features

Editor

• Syntax highlighting for every Simply keyword, type, built-in, and operator
• Autocomplete (IntelliSense) — start typing a keyword or built-in name and a popup suggests matches. Arrow keys navigate, Enter / Tab to accept, Escape to dismiss
• Line numbers with current-line highlight
• Auto-indent on Enter — preserves the previous line's indentation, adds extra indent inside blocks
• Tab inserts 4 spaces — consistent indentation
• Comment toggle with Ctrl+/ on the selection
• Find & Replace with Ctrl+H
• Font zoom with Ctrl+= / Ctrl+- / Ctrl+0

File explorer

• Open a folder as a workspace (File → Open Folder)
• Tree shows folders and files; double-click to open files in a new tab
• Right-click for context menu: New File, Rename, Delete, Run File

Tabs

• Open multiple files at once
• Click a tab to switch, click × or middle-click to close
• Unsaved files show a dot indicator next to the file name
• Prompts to save when closing modified files

Embedded terminal

• Runs at the bottom of the window. Press F5 or click ▶ Run to execute the current file
• Output appears live as your script runs
• Type into the input box at the bottom — input flows into your running program's stdin (so input() calls work)
• Shift+F5 stops a running process
• Click ✕ in the terminal header to clear output

Themes New

• Settings → Light Theme or Dark Theme — switch instantly
• Settings → Match Windows Theme — follow the OS preference
• Your choice is saved to %APPDATA%\SimplyCode\settings.txt and persists across sessions
• The icon in the title bar and taskbar matches the active theme

Simply Code — Keyboard Shortcuts

File

Edit

Run

View

VSCode Extension

Simply ships a VSCode extension that adds syntax highlighting for .simply files. It is installed automatically by the bootstrapper if you check the option, or you can install it manually.

What it provides

• Keyword highlighting: define, fn, if, else, for, while, loop, try, catch, end, return, use, in, and, or, not
• Type highlighting: String, Int, Float, Bool
• Package source highlighting: npm, python
• String, number, boolean, and comment highlighting
• Function name detection
• Auto-close for (), {}, [], ""
• Comment toggling with Ctrl+/ (uses --)

Manual installation

1. Download the bootstrapper and run it
2. Check the VSCode extension checkbox before clicking Install

Or, if you already have Simply installed:

code --install-extension "C:\Simply\simply-lang.vsix"

Bootstrapper

The Simply Bootstrapper is the install manager for Simply. It is a small Windows application (~22 KB) that handles everything.

Features

• Install Simply from any available version
• Update to a newer or older version (downgrade is supported)
• Uninstall Simply completely (removes files, PATH entry, and file association)
• Optionally install the VSCode syntax extension
• Shows installed version vs. available versions
• Automatically requests admin rights (needed for PATH and registry)

What it does on install

1. Downloads simply-runtime-win.zip from beirutsites.com/simply/version/<ver>/
2. Extracts simply.exe to C:\Simply\
3. Writes C:\Simply\version.txt with the installed version
4. Adds C:\Simply to the system PATH
5. Registers .simply file type in the Windows registry
6. Optionally downloads and installs the .vsix extension

CLI Reference

simply hello.simply
simply --version

Keyword Index

Type Reference

Changelog

The full version history with every change for every release lives on a dedicated page.

📜 View Full Changelog →