📚 Stack-Based Emoji Programming Language

A Forth-inspired stack language where everything is emoji.

Quick Example

💭 Hello World
🔤Hello, World!🔤 😀

💭 Math with keycap digits
5️⃣ 3️⃣ ➕ 2️⃣ ✖️ 😀  💭 (5 + 3) * 2 = 16

💭 Define square function
📖 🟪 📚 ✖️ 📕
7️⃣ 🟪 😀  💭 prints 49

💭 Factorial with recursion
📖 ❗
  📚 2️⃣ ⬇️ 👍
    🗑️ 1️⃣
  👎
    📚 1️⃣ ➖ ❗ ✖️
  🔚
📕
5️⃣ ❗ 😀  💭 prints 120

Getting Started

Requirements:

• Crystal - required to run the transpiler
• Python 3 - optional, only needed if using the Python backend

Quick Start:

1. Install Crystal.
2. Run an example: crystal src/cli.cr examples/hello.emoji

Installation & Usage

# Run a program with Crystal backend (default - transpiles, compiles, and executes)
crystal src/cli.cr examples/hello.emoji

# Run a program with Python backend (transpiles and executes)
crystal src/cli.cr examples/hello.emoji --backend python

# Show generated code with Crystal backend
crystal src/cli.cr examples/hello.emoji --show-code

# Use Python backend and show generated code
crystal src/cli.cr examples/hello.emoji --backend python --show-code

# Save generated code to file
crystal src/cli.cr examples/hello.emoji -o output.cr
crystal src/cli.cr examples/hello.emoji --backend python -o output.py

Language Reference

Literals

Numbers:

• 🔢42 - number literal (for any number)
• 3️⃣ - keycap digit (0️⃣-9️⃣ for single digits)

Strings:

• 🔤text🔤 - string literal

Booleans:

• ✅ - true
• ❌ - false

Basic Stack Operations

• 📚 - dup (duplicate top)
• 🗑️ - drop (remove top)
• 🔄 - swap (swap top two)
• 📋 - over (copy second to top)

Advanced Stack Operations (Tier 2)

• 🔃 - rot (rotate 3 forward: a b c → b c a)
• 🔂 - -rot (rotate 3 backward: a b c → c a b)
• 🪞 - 2dup (duplicate top 2: a b → a b a b)
• 🚮 - 2drop (drop top 2)
• 🎯 - pick (copy nth item)

Arithmetic

• ➕ - add
• ➖ - subtract
• ✖️ - multiply
• ➗ - divide
• 🔀 - modulo

Comparison

• 🟰 - equal
• ⬆️ - greater than
• ⬇️ - less than

Boolean Operations

• ⚡ - or (logical OR)
• 🔗 - and (logical AND)
• 🚫 - not (logical NOT)

I/O

• 😀 - print (with newline)
• 💬 - emit (without newline)
• 🎤 - input (read from stdin)

Control Flow

• 🔁 - loop (repeat while true on stack)
• 👍 - starts a conditional (then branch first)
• 👎 - starts a conditional (else branch first)
• 🔚 - ends a conditional

Conditional Syntax:

👍 <then> 🔚                 💭 If true, execute then
👍 <then> 👎 <else> 🔚       💭 Then/else (traditional order)
👎 <else> 🔚                 💭 If false, execute else
👎 <else> 👍 <then> 🔚       💭 Else/then (reversed source order)

Word Definition

• 📖 <emoji> - start word definition
• 📕 - end word definition

Variables

• 📦 <emoji> - declare variable
• 💾 <emoji> - store to variable (pops value from stack)
• 📤 <emoji> - fetch from variable (pushes value to stack)

Return Stack

• ⬅️ - push to return stack
• ➡️ - pop from return stack
• 👁️ - peek return stack (non-destructive)

Comments

• 💭 - comment to end of line

How It Works

.emoji source → Tokenizer → Parser → AST → Backend → Compile → Run

1. Tokenizer - Converts emoji to tokens
2. Parser - Builds Abstract Syntax Tree
3. Backend - Code generation (pluggable: Crystal, Python, etc.)
4. Transpiler - Ties it together
5. Execution - Compiles and runs generated code

Backend Implementations

Crystal Backend:

• Generates Crystal code
• Uses module with class variables for state
• Macros for stack operations
• Fast execution (compiled)

Python Backend:

• Generates Python 3 code
• Uses module-level variables for state
• Helper functions for stack operations
• Emoji names are hex-encoded for Python compatibility
• Interpreted execution

Pluggable Architecture

• Easy to add new backends (Rust, JavaScript, etc.)
• Shared AST representation
• Backend-agnostic tokenizer and parser

Stack-Based Execution:

5️⃣ 3️⃣ ➕
→ push 5, push 3, add
→ stack: [8]

Word Definitions:

📖 🟪 📚 ✖️ 📕  💭 Define 🟪 (square) as: dup multiply
5️⃣ 🟪            💭 Call it: push 5, call square
→ stack: [25]

Recursion:

📖 ❗
  📚 2️⃣ ⬇️ 👍
    🗑️ 1️⃣
  👎
    📚 1️⃣ ➖ ❗ ✖️
  🔚
📕

Testing

• Unit tests: crystal spec
• Integration tests: crystal src/test_runner.cr tests/; single file: crystal src/test_runner.cr tests/boolean_ops.test.emoji

Design Philosophy

Inspired by Forth and Factor, this is a concatenative language where:

1. Everything is a word (function)
2. Words consume and produce stack values
3. Composition is concatenation (🟪 🟪 = square twice)
4. Minimal primitives, maximum composition
5. Optional variables (data flow can use stack or variables)

Credits

Inspired by:

• Emojicode - The original emoji programming language
• Forth - Stack-based concatenative language
• Factor - Modern concatenative language
• Crystal - The implementation language

License

This work is dedicated to the public domain by Todd Sundsted worldwide using the CC0 1.0 Universal Public Domain Dedication.