SymbolCore Documentation

01. Overview

SymbolCore compiles to Python (for library access) and C (for speed). Pure functions auto-compile to native C via gcc. Python library calls stay as Python. The compiler decides — you write one file.

# hello.sym — this is all you need
print "Hello from SymbolCore!"

let name = "World"
print "Hello, {name}!"

# Run it
sym run hello.sym

02. Variables & Constants

let — mutable variable

let x = 42
let name = "Abir"
let pi = 3.14159
let active = true
let items = [1, 2, 3]

const — immutable

const MAX = 1000
const URL = "https://api.example.com"

With types (optional)

let x: int = 42
let name: str = "Abir"

Reassignment (no let)

let x = 10
x = 20        # no let for reassignment
x += 5        # compound: +=  -=  *=  /=

03. Type System gradual

Types are optional. Adding them enables better C compilation and catches errors early.

04. Functions

Basic

fn add(a: int, b: int) -> int
    return a + b

Single expression (fat arrow)

fn double(x: int) -> int => x * 2

No return type (void)

fn greet(name: str)
    print "Hello {name}"

Default parameters

fn connect(host: str, port: int = 8080)
    print "Connecting to {host}:{port}"

Recursive

fn factorial(n: int) -> int
    if n <= 1
        return 1
    return n * factorial(n - 1)

05. Control Flow

if / elif / else

if score >= 90
    grade = "A"
elif score >= 80
    grade = "B"
else
    grade = "F"

06. Loops & Ranges

for with range (..)

for i in 0..10
    print i            # 0 through 9 (exclusive end)

for over collection

for item in items
    print item

for with index

for i, val in enumerate(data)
    print "{i}: {val}"

while

let x = 0
while x < 100
    x += 1

break / continue

for i in 0..100
    if i == 50
        break
    if i % 2 == 0
        continue
    print i

07. Strings & Interpolation

let name = "Abir"
let age = 28
print "Name: {name}, Age: {age}"     # auto f-string
print "2 + 2 = {2 + 2}"              # expressions work

let msg = "Score: " + str(score)     # concatenation

08. Collections

Lists

let nums = [1, 2, 3, 4, 5]
let first = nums[0]          # indexing
let slice = nums[1:3]       # slicing
nums.append(6)               # methods work

Dicts

let user = {"name": "Abir", "age": 28}
print user["name"]

Tuples

let point = (3.0, 4.0)

09. Structs & Methods

struct Point
    x: float
    y: float

    fn distance(self, other: Point) -> float
        let dx = self.x - other.x
        let dy = self.y - other.y
        return sqrt(dx * dx + dy * dy)

let p1 = Point(0.0, 0.0)
let p2 = Point(3.0, 4.0)
print p1.distance(p2)     # 5.0

Default fields

struct Config
    host: str = "localhost"
    port: int = 8080

10. Traits & Impl

trait Printable
    fn to_string(self) -> str

impl Printable for Point
    fn to_string(self) -> str
        return "Point({self.x}, {self.y})"

11. Python Interop killer feature

Use ANY pip package. The py. prefix tells the compiler it's a Python library. Missing packages are auto-installed.

Import syntax

import py.numpy as np
import py.pandas as pd
import py.matplotlib.pyplot as plt
import py.requests as req
import py.sklearn.ensemble as sk
import py.torch as torch
import py.bs4.BeautifulSoup as BS
import py.json as json
import py.os as os
import py.sys as sys

Usage

import py.numpy as np

let data = np.array([1, 2, 3, 4, 5])
print "Mean: {np.mean(data)}"

Auto-install chain

When a package is missing: pip install --user → pip3 install --user → sudo apt install python3-pkg → prints manual instructions.

Name mappings

12. Built-in Functions

Always available. No import needed.

Constants: PI, E, INF

13. Error Handling

try
    let data = read_file("config.json")
catch e
    print "Error: " + str(e)

# With type
try
    let r = py.requests.get(url)
catch e: Exception
    print "Failed"

14. Pattern Matching

match command
    "start" => run()
    "stop"  => shutdown()
    "help"  => show_help()
    _       => print "Unknown"

15. Lambdas & Pipes

Lambda

let sq = (x) => x * x
let add = (a, b) => a + b

let evens = filter(data, (x) => x % 2 == 0)

Pipe operator

let result = data |> filter((x) => x > 0) |> map((x) => x * 2)

16. Benchmark & Optimize

benchmark fn test_algo()
    let result = fibonacci(30)
    print result

test_algo()   # prints timing automatically

Smart sort picks algorithm by data size:

17. All Three Syntax Modes

All three compile to the same AST — zero performance difference. Choose your style.

Hello World

print "Hello!"
let x = 42
print "x = {x}"

#compact
>> "Hello!"
@ x = 42
>> "x = {x}"

#symbol
⊕ "Hello!"
∂ x = 42
⊕ "x = {x}"

Functions

fn fib(n: int) -> int
    if n <= 1
        return n
    return fib(n-1) + fib(n-2)

#compact
f fib(n: int) -> int
    ? n <= 1
        <- n
    <- fib(n-1) + fib(n-2)

#symbol
ƒ fib(n:ℤ)→ℤ
    ? n ≤ 1
        ← n
    ← fib(n-1) + fib(n-2)

Loops

for i in 0..10
    print i

while x > 0
    x -= 1

#compact
~ i in 0..10
    >> i

~~ x > 0
    x -= 1

#symbol
∀ i in 0..10
    ⊕ i

⟳ x > 0
    x -= 1

Imports

import py.numpy as np

#compact
<< py.numpy as np

#symbol
⊂ py.numpy as np

18. Compact Mode — Complete Reference

Start file with #compact on the first line.

Everything else (operators, types, strings, structs, etc.) stays the same.

19. Symbol Mode — Complete Reference

Start file with #symbol. Inherits ALL compact mode shortcuts plus Unicode operators.

Symbol mode also supports compact shortcuts: ? for if, ! for else, ~ for for, ~~ for while, >> for print, << for import, <- for return.

20. Compilation & Hybrid Engine

How it works

sym run file.sym automatically:

1. Parses the file
2. Analyzes each function — does it use py.* libraries?
3. Pure functions (no Python deps) → compiled to C shared library (.so)
4. Python-dependent functions → stay as Python
5. Generated Python loads .so via ctypes, calls native C functions
6. The .so is cached — subsequent runs skip compilation

What goes to C (pure)

• Math functions with typed params
• Loops over ranges
• Integer/float arithmetic
• Fixed-size array operations
• Recursive functions

What stays Python

• Any function using py.* imports
• Functions calling other Python-dependent functions
• benchmark functions
• Struct methods
• Dynamic list operations (append, concat)
• try/catch and match statements

Check the split

sym check file.sym
# ✅ file.sym: 7 statements
#    Functions: 5 total
#      → C:      4 (fibonacci, is_prime, count_primes, sum_cubes)
#      → Python: 1

21. Benchmarks vs Python real numbers

All benchmarks run on the same machine, same test (fib(35) + sum_squares(1M) + count_primes(100K)).

When to use which mode

22. Operators Reference

23. CLI Reference

24. Full Examples

Web Scraper

import py.requests as req
import py.json as json

let r = req.get("https://api.github.com/repos/python/cpython")
let data = r.json()
print "Stars: " + str(data["stargazers_count"])

Data Pipeline

import py.numpy as np
import py.pandas as pd

# Pure → compiles to C
fn sum_squares(n: int) -> int
    let total = 0
    for i in 0..n
        total += i * i
    return total

# Python interop → stays Python
let df = pd.read_csv("data.csv")
print df.describe()

Hybrid Speed Demo

import py.json as json

# These 4 → compiled to C
fn fibonacci(n: int) -> int
    if n <= 1
        return n
    return fibonacci(n - 1) + fibonacci(n - 2)

fn is_prime(n: int) -> int
    if n < 2
        return 0
    let i = 2
    while i * i <= n
        if n % i == 0
            return 0
        i += 1
    return 1

# This → stays Python (uses json)
let results = {"fib": fibonacci(35)}
print json.dumps(results, indent=2)

Snake Game (Symbol Mode)

#symbol
⊂ py.curses as curses
⊂ py.random as random

ƒ game(stdscr)
    curses.curs_set(0)
    ∂ snake = [[10, 15], [10, 14], [10, 13]]
    ∂ dy = 0
    ∂ dx = 1
    ∂ alive = 1

    ⟳ alive == 1
        ∂ key = stdscr.getch()
        ? key == curses.KEY_UP
            ? dy ≠ 1
                dy = -1
                dx = 0
        # ... movement logic

∂ final = curses.wrapper(game)

25. All Rules Summary