I Built a Programming Language from Scratch

This week, I wanted to stop using languages and start understanding them.

Most of us write code in existing languages — Python, JavaScript, C — but very few of us stop to ask:

So that’s what I set out to do: build a minimal, English-like programming language from first principles.

No libraries. No frameworks. Just me, Python, and a goal — make the computer respond to simple, readable commands like:

set x to 5 increase x by 3 show x

What Is PebbleLang?

PebbleLang is a custom scripting language I built using Python. It doesn’t try to be powerful. It tries to be understandable.

It supports:

• Creating and modifying variables (set, increase, decrease)

• Outputting values (show)

• Ignoring lines that start with comment:

It’s deliberately simple. The idea is to strip programming down to something that feels like talking — a language closer to how we think.

A First PebbleLang Program

Here’s what a valid .peb file looks like:

comment: this is a PebbleLang script set x to 10 set y to 5 increase x by y decrease y by 2 show x show y

When you run it, you’ll get:

15 3

Variables x and y are stored internally, and operations like increase x by y work even if y is a variable instead of a literal number.

How It Works (Technically)

Let’s break it down into its components.

The Parser

A parser is a piece of software that takes human-written code and turns it into structured instructions the computer can understand.

For example, the line:

increase x by y

Gets converted into a Python dictionary like this:

{ "command": "increase", "var": "x", "value": "y" }

This structured format makes it easier to handle inside the interpreter.

The Interpreter

An interpreter is a program that reads and executes commands line-by-line.

PebbleLang’s interpreter stores variables in a dictionary like:

variables = { "x": 10, "y": 5 }

It then uses a function called resolve() to figure out what y means. If y is a number, it returns the number. If y is another variable, it looks up its current value. This allows commands like increase x by y to work whether y is a value like 3 or a variable like y.

The Runner

This is the command-line tool that puts it all together. It reads a .peb file line by line, parses each line, and then passes the result to the interpreter.

You can run it like this:

python pebble.py example.peb

Design Goals

My goals for PebbleLang were:

• Human readability: You should be able to guess what a line does just by reading it.

• Minimal syntax: No symbols, no brackets, no semicolons.

• Educational clarity: A beginner should be able to read the source code and understand how it works.

What It Doesn’t Do (Yet)

PebbleLang is not a complete language. It lacks:

• Conditionals
  There’s no if statement yet. You can’t say “if x is greater than y then show x.”

• Loops
  You can’t repeat blocks of code.

• Functions
  There’s no way to define reusable pieces of logic.

• Data types
  Everything is either a number or a string label. No lists, booleans, or strings as values.

All of these could be added later — and I’m tempted to try — but I wanted to focus on getting the basics right first.

Why It’s Called PebbleLang

A pebble is small, simple, and foundational. It’s not trying to be a boulder. It’s not meant to crush problems — just to be held in your hand and understood.

I liked the idea of starting with something elemental — a single pebble at the base of a much larger mountain.

What I Learned

Here are some reflections from the process:

1. Programming languages aren’t magical.
   They’re made up of rules, structures, and simple logic. Once you break them down, they’re surprisingly approachable.

2. Parsing is just pattern matching.
   I always thought writing a parser would be complex. But in PebbleLang, it’s just checking if the line starts with “set”, “increase”, etc., and splitting it into parts.

3. Interpreters are just decision trees.
   Once you have structured input, you can write a big if/else chain that handles each type of instruction.

4. Clear errors matter.
   When I tried invalid syntax or referenced undefined variables, I made sure PebbleLang responded clearly — like “Variable y is not defined” instead of crashing. It made testing easier and reminded me that error messages are part of the user experience.

Where You Can See It

The full code is on GitHub here:
 https://github.com/Verma-Labs/pebblelang

Clone the repo, run the script, and modify it. It’s around 100 lines of Python. Very readable.

What’s Next?

Here’s what I might add if I keep going:

• if x is greater than y then show x

• repeat 5 times: style loops

• define double n: function blocks

• An online version (maybe using Streamlit)

• More syntax features — maybe even a basic compiler down the line

But even if I stop here, PebbleLang taught me more about programming than learning a new language ever could.

Final Thoughts

Sometimes the best way to understand how things work is to try and build your own version from scratch.

PebbleLang isn’t meant for production. It’s not going to change the world. But it gave me a new appreciation for what it means to communicate with a machine - and how much work goes into making something feel simple.

This was Week 21 of Project52.

If you're curious, give it a try.
And if you want to build your own, I’d be happy to show you where to start.