morse-lang 1.1.0
Morse programming language
License: MIT
Requires Python: >=3.9

<div id="top" align="center">

  <h1>Morse Lang</h1>
  <p><em>A tiny programming language written entirely in Morse code.</em></p>

  <p>
    <img alt="PyPI - Version" src="https://img.shields.io/pypi/v/morse-lang?style=flat&color=0080ff" />
    <img alt="PyPI - Python Version" src="https://img.shields.io/pypi/pyversions/morse-lang?style=flat&color=0080ff" />
    <img alt="GitHub last commit" src="https://img.shields.io/github/last-commit/sharky-3/morse-programming-language?style=flat&logo=git&logoColor=white&color=0080ff" />
    <img alt="GitHub top language" src="https://img.shields.io/github/languages/top/sharky-3/morse-programming-language?style=flat&color=0080ff" />
    <img alt="GitHub language count" src="https://img.shields.io/github/languages/count/sharky-3/morse-programming-language?style=flat&color=0080ff" />
  </p>

  <p><em>Built with:</em></p>
  <p>
    <img alt="Python" src="https://img.shields.io/badge/Python-3.x-3776AB?style=flat&logo=python&logoColor=white" />
    <img alt="Flask" src="https://img.shields.io/badge/Flask-2.x-000000?style=flat&logo=flask&logoColor=white" />
  </p>

</div>

<br />
<hr />

## Table of Contents

- **[What You Can Do](#what-you-can-do)**
- **[Overview](#overview)**
- **[Getting Started](#getting-started)**
  - **[Prerequisites](#prerequisites)**
  - **[Installation (from PyPI)](#installation-from-pypi)**
  - **[Installation (from source)](#installation-from-source)**
  - **[Running Your First Morse Program](#running-your-first-morse-program)**
- **[How It Works](#how-it-works)**
- **[Language Basics](#language-basics)**
- **[Web Frontend (Text ⇄ Morse Translator)](#web-frontend-text--morse-translator)**
- **[Development](#development)**

<hr />

## What You Can Do

**Morse Lang** lets you write full Python programs using only dots (`.`) and dashes (`-`). Here's what you can build:

### 🔢 **Variables**

Create and store values in variables:

**Python:**
```python
var x = 10
var y = 20
var name = "morse"
```

**Morse:**
```text
...- .- .-.   -..-   -...-   .---- -----
...- .- .-.   -.--   -...-   ..--- -----
...- .- .-.   -.. .- -- .   -...-   .----. -- --- .-. ... . .----.
```

### ➕ **Math Operations**

Perform arithmetic with addition, subtraction, multiplication, and division:

**Python:**
```python
var result = 5 + 3
var product = 10 * 2
var difference = 100 - 25
var quotient = 20 / 4
```

**Morse:**
```text
...- .- .-.   .-. . ... ..- .-.. -   -...-   ..... .-.-. ...--
...- .- .-.   .--. .-. --- -.. ..- -.-. -   -...-   .---- ----- -.-.- ..---
...- .- .-.   -.. .. ..-. ..-. . .-. . -. -.-. .   -...-   .---- ----- ----- -....- ..--- .....
...- .- .-.   --.- ..- --- - .. . -. -   -...-   ..--- ----- -..-. ....-
```

### 📝 **Print Statements**

Display output to the console:

**Python:**
```python
print("Hello, World!")
print(42)
print(x + y)
```

**Morse:**
```text
.--. .-. .. -. - -.--. .----. .... . .-.. .-.. --- --..--  .-- --- .-. .-.. -.. .----. -.--.-
.--. .-. .. -. - -.--. ....- ..--- -.--.-
.--. .-. .. -. - -.--. -..- .-.-. -.-- -.--.-
```

### 🔁 **For Loops**

Iterate over a range of numbers:

**Python:**
```python
for i in range(5):
  print i
```

**Morse:**
```text
..-. --- .-.   ..   .. -.   .-. .- -. --. . -.--. ..... -.--.- --- --..--
  .--. .-. .. -. -   ..
```

**Output:**
```
0
1
2
3
4
```

### 🔄 **While Loops**

Repeat code while a condition is true:

**Python:**
```python
var count = 0
while count < 3:
  print count
  var count = count + 1
```

**Morse:**
```text
...- .- .-.   -.-. --- ..- -. -   -...-   -----
.-- .... .. .-.. .   -.-. --- ..- -. -   -....-   ...--
  .--. .-. .. -. -   -.-. --- ..- -. -
  ...- .- .-.   -.-. --- ..- -. -   -...-   -.-. --- ..- -. - .-.-. .----
```

**Output:**
```
0
1
2
```

### ⚙️ **Functions**

Define reusable functions with parameters and return values:

**Python:**
```python
func greet():
  print hello
  print world

greet()

func add(a b):
  return a + b

var result = add(3 5)
print result
```

**Morse:**
```text
..-. ..- -. -.-.   --. .-. . . - -.--. -.--.- --- --..--
  .--. .-. .. -. -   .... . .-.. .-.. ---
  .--. .-. .. -. -   .-- --- .-. .-.. -..

--. .-. . . - -.--. -.--.-

..-. ..- -. -.-.   .- -.. -.. -.--. .-   -... -.--.- --- --..--
  .-. . - ..- .-. -.   .- .-.-. -...

...- .- .-.   .-. . ... ..- .-.. -   -...-   .- -.. -.. -.--. ...--   ..... -.--.-
.--. .-. .. -. -   .-. . ... ..- .-.. -
```

**Output:**
```
hello
world
8
```

### 🎯 **Complete Example**

Here's a full program that combines all features:

**Python:**
```python
func calculate_sum(a b):
  return a + b

var x = 5
var y = 10
var total = calculate_sum(x y)
print total

for i in range(3):
  print i
```

**Morse:**
```text
..-. ..- -. -.-.   -.-. .- .-.. -.-. ..- .-.. .- - .   ... ..- -- -.--. .-   -... -.--.- --- --..--
  .-. . - ..- .-. -.   .- .-.-. -...

...- .- .-.   -..-   -...-   .....
...- .- .-.   -.--   -...-   .---- -----
...- .- .-.   - --- - .- .-..   -...-   -.-. .- .-.. -.-. ..- .-.. .- - .   ... ..- -- -.--. -..-   -.-- -.--.-
.--. .-. .. -. -   - --- - .- .-..

..-. --- .-.   ..   .. -.   .-. .- -. --. . -.--. ...-- -.--.- --- --..--
  .--. .-. .. -. -   ..
```

**Output:**
```
15
0
1
2
```

> 💡 **Note:** Morse Lang supports all these features and more! You can combine variables, math, loops, and functions to build complex programs entirely in Morse code.

<hr />

## Overview

**Morse Lang** is a programming language where your source code is written entirely in Morse code. You write a `.mc` file using dots (`.`) and dashes (`-`), the `morse` CLI decodes it into Python, and then executes it.  
It works the same way on **macOS**, **Windows**, and **Linux** as long as you have Python installed.

**Use cases**

- **Learning / teaching Morse code** with a fun programming twist
- **Code golf / esolangs** and experimentation
- **Novel demos** where the source file looks like radio traffic but runs like Python

<hr />

## How It Works

- **Step 1 – Morse source (`.mc`):**  
  You create a file filled with Morse symbols (e.g. `.-`, `--..--`) separated by spaces.

- **Step 2 – Decode to Python:**  
  The CLI uses `morse_lang.morse_to_text` and `MORSE_MAP` to translate each Morse token into a character, building a normal Python source file line by line.

- **Step 3 – Execute:**  
  The decoded Python string is executed with `exec(...)` in a fresh namespace, just like running a regular `.py` script.

Because of this, **Morse Lang programs can do anything Python can**. Only run `.mc` files you trust, just as you would with untrusted Python code.

<hr />

## Getting Started

### Prerequisites

- **Python:** 3.8 or newer (3.10+ recommended)
- Works on:
  - **macOS** (tested on recent versions)
  - **Windows 10/11**
  - **Linux** (any modern distro)

You can check your Python version with:

```bash
python --version
```

On Windows, you may need:

```powershell
py --version
```

### Installation (from PyPI)

The simplest way is to install the package directly from PyPI.

- **macOS / Linux (bash, zsh, etc.):**

```bash
python -m pip install --upgrade pip
python -m pip install morse-lang
```

- **Windows (PowerShell or Command Prompt):**

```powershell
py -m pip install --upgrade pip
py -m pip install morse-lang
```

After installation, the `morse` command should be available on your PATH.

### Installation (from source)

If you are working directly with this repository:

```bash
git clone https://github.com/sharky-3/morse-programming-language.git
cd morse-programming-language

# (Optional but recommended) create a virtual environment
python -m venv .venv
source .venv/bin/activate    # Windows: .venv\Scripts\activate

python -m pip install --upgrade pip
python -m pip install -e .
```

This installs `morse-lang` in editable mode so changes to the source are reflected immediately.

### Running Your First Morse Program

#### 1. Try the included example

If you cloned this repository, you can immediately run the included example:

- **macOS / Linux:**

  ```bash
  morse examples/hello.mc
  ```

- **Windows:**

  ```powershell
  morse examples\hello.mc
  ```

You should see:

```text
hello, world
```

#### 2. Create your own program

Create a new file, for example `my_program.mc`, and add some Morse code:

**Example: Simple math program**

Create `math.mc`:

```text
...- .- .-.   -..-   -...-   .---- -----
...- .- .-.   -.--   -...-   .....
...- .- .-.   ... ..- --   -...-   -..- .-.-. -.--
.--. .-. .. -. -   ... ..- --
```

Run it:

- **macOS / Linux:**

  ```bash
  morse math.mc
  ```

- **Windows:**

  ```powershell
  morse math.mc
  ```

**Output:**
```
15
```

**Example: Try loops and functions**

You can also run the included example with loops and functions:

- **macOS / Linux:**

  ```bash
  morse examples/loops_and_functions.mc
  ```

- **Windows:**

  ```powershell
  morse examples\loops_and_functions.mc
  ```

> 💡 **Tip:** Use the [Web Frontend](#web-frontend-text--morse-translator) to help translate your Python code to Morse code!

#### 3. Troubleshooting: Command not found

If the `morse` command is not found after installation:

**Windows:**
```powershell
# Try using Python module directly
py -m morse_lang.cli math.mc

# Or with full path
python -m morse_lang.cli math.mc
```

**macOS / Linux:**
```bash
# Try using Python module directly
python -m morse_lang.cli math.mc

# Or check if morse is in your PATH
which morse
```

If it's still not working, make sure:
- Python is installed and in your PATH
- You've activated your virtual environment (if using one)
- The package was installed successfully (`pip list | grep morse-lang`)

<hr />

## Language Basics

At its core, **Morse Lang is "Python in Morse"**. Each Morse token is mapped to a character using standard Morse code conventions:

### 📋 **Syntax Rules**

- **Single space (`" "`)** between Morse codes → separates letters within a word
- **Triple space (`"   "`)** between sequences → separates words
- **Each line** in your `.mc` file → one line of decoded Python

### 🔤 **Morse Code Mapping**

The mapping is defined in `MORSE_MAP` and includes:

#### **Letters (A-Z)**
```
.-   → a      -... → b      -.-. → c      -..  → d      .    → e
..-. → f      --.  → g      .... → h      ..   → i      .--- → j
-.-  → k      .-.. → l      --   → m      -.   → n      ---  → o
.--. → p      --.- → q      .-.  → r      ...  → s      -    → t
..-  → u      ...- → v      .--  → w      -..- → x      -.-- → y
--.. → z
```

#### **Digits (0-9)**
```
----- → 0     .---- → 1     ..--- → 2     ...-- → 3     ....- → 4
..... → 5     -.... → 6     --... → 7     ---.. → 8     ----. → 9
```

#### **Math Operators**
```
.-.-.  → +    (addition)
-....- → -    (subtraction)
-.-.-  → *    (multiplication)
-..-.  → /    (division)
-...-  → =    (assignment/equality)
```

#### **Punctuation & Symbols**
```
--..-- → ,    (comma)
...... → .    (period)
.----. → '    (apostrophe)
-.--.  → (    (left parenthesis)
-.--.- → )    (right parenthesis)
```

### 💡 **Writing Morse Code Programs**

When writing your `.mc` files, remember:

1. **Separate letters with single spaces:** `.... . .-.. .-.. ---` = `hello`
2. **Separate words with triple spaces:** `.... . .-.. .-.. ---   .-- --- .-. .-.. -..` = `hello world`
3. **Each line becomes one Python line:** Line breaks in `.mc` become line breaks in Python

### 📚 **Example Programs**

#### **Simple Print**
**Python:**
```python
print("Hello, World!")
```

**Morse:**
```text
.--. .-. .. -. - -.--. .----. .... . .-.. .-.. --- --..--  .-- --- .-. .-.. -.. .----. -.--.-
```

#### **Variables and Math**
**Python:**
```python
var x = 10
var y = 5
var result = x + y
print result
```

**Morse:**
```text
...- .- .-.   -..-   -...-   .---- -----
...- .- .-.   -.--   -...-   .....
...- .- .-.   .-. . ... ..- .-.. -   -...-   -..- .-.-. -.--
.--. .-. .. -. -   .-. . ... ..- .-.. -
```

**Output:**
```
15
```

#### **For Loops**
**Python:**
```python
for i in range(5):
  print i
```

**Morse:**
```text
..-. --- .-.   ..   .. -.   .-. .- -. --. . -.--. ..... -.--.- --- --..--
  .--. .-. .. -. -   ..
```

**Output:**
```
0
1
2
3
4
```

#### **While Loops**
**Python:**
```python
var count = 0
while count < 3:
  print count
  var count = count + 1
```

**Morse:**
```text
...- .- .-.   -.-. --- ..- -. -   -...-   -----
.-- .... .. .-.. .   -.-. --- ..- -. -   -....-   ...-- --- --..--
  .--. .-. .. -. -   -.-. --- ..- -. -
  ...- .- .-.   -.-. --- ..- -. -   -...-   -.-. --- ..- -. - .-.-. .----
```

**Output:**
```
0
1
2
```

#### **Functions**
**Python:**
```python
func add(a b):
  return a + b

var result = add(3 5)
print result
```

**Morse:**
```text
..-. ..- -. -.-.   .- -.. -.. -.--. .-   -... -.--.- --- --..--
  .-. . - ..- .-. -.   .- .-.-. -...

...- .- .-.   .-. . ... ..- .-.. -   -...-   .- -.. -.. -.--. ...--   ..... -.--.-
.--. .-. .. -. -   .-. . ... ..- .-.. -
```

**Output:**
```
8
```

> 🚀 **Pro Tip:** Morse Lang supports variables (`var`), math operations, print statements, for loops (`for i in range(n):`), while loops (`while condition:`), and functions (`func name(args):` with `return`). Use indentation (spaces) to define code blocks, just like Python!

<hr />

## Web Frontend (Text ⇄ Morse Translator)

This repository also includes a small **Flask** web app that lets you convert between text and Morse interactively.

### Run the web UI (macOS & Windows)

From the project root:

```bash
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate

python -m pip install --upgrade pip
python -m pip install -r requirements.txt

python app.py
```

Then open `http://localhost:5000` in your browser.

The page lets you:

- **Type text → get Morse code**
- **Paste Morse → get decoded text**

The web app uses the same `MORSE_MAP` as the CLI, so behavior is consistent.

<hr />

## Development

If you want to hack on Morse Lang itself:

- **Clone and install in editable mode:**

```bash
git clone https://github.com/sharky-3/morse-programming-language.git
cd morse-programming-language

python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate

python -m pip install --upgrade pip
python -m pip install -e .
python -m pip install -r requirements.txt
```

- **Run tests:**

```bash
python -m pip install pytest
pytest
```

- **Play with the internals:**
  - `morse_lang/lexer.py` – Morse → text decoding
  - `morse_lang/morse_map.py` – core Morse symbol map
  - `morse_lang/cli.py` – `morse` command-line entrypoint

You can now iterate on the language, extend the Morse mapping, or experiment with new features.

---

Enjoy writing code in dots and dashes!  
If you build something cool with Morse Lang, feel free to share it or open an issue/PR on the GitHub repo.