rev/mpl
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Make every README claim verifiable and every code block parse

Browse source 
- Rewrite all mpl code blocks in canonical syntax: ✎ output, guarded
  alternatives, f(a, b) calls, -- comments; remove 📤, ternary ?:, %, ∑,
  √, ², |x|, ranges, indexing/slicing and where (deferred to M1, and the
  README now says so explicitly)
- Add DocumentationTest: extracts every fenced mpl block from README.md
  and asserts it parses, preventing future drift
- Replace '1000+ test cases' and 'zero ambiguities' with claims CI
  actually checks (zero ANTLR errors/warnings, 10/10 examples, 200+
  syntax assertions)
- Remove unmeasured performance metrics section
- Mark type checking, code generation and non-escape input methods as
  planned/envisioned rather than existing
- Fix clone URL (github.com/developtheweb/mpl); replace the fictional
  Discord link with GitHub issues
This commit is contained in:
developtheweb 2026-07-09 03:03:52 -04:00
parent b9a232667e
commit 96002ec1bf
2 changed files with 142 additions and 105 deletions
Download patch file Download diff file Expand all files Collapse all files

205
README.md
View file

@ -4,11 +4,11 @@
<div align="center"> <div align="center">
![Status](https://img.shields.io/badge/status-proof--of--concept-orange) ![Status](https://img.shields.io/badge/status-proof--of--concept-orange)
![Parser](https://img.shields.io/badge/parser-complete-brightgreen) ![Parser](https://img.shields.io/badge/parser-M0-brightgreen)
![Execution](https://img.shields.io/badge/execution-not--implemented-red) ![Execution](https://img.shields.io/badge/execution-not--implemented-red)
![License](https://img.shields.io/badge/license-AGPLv3-blue) ![License](https://img.shields.io/badge/license-AGPLv3-blue)
**∀ child ∈ world : programming.accessible = true** **∀ child ∈ world : canCode(child)**
[🎓 For Educators](#for-educators) | [💻 For Developers](#for-developers) | [🌍 For Humanity](#for-humanity) [🎓 For Educators](#for-educators) | [💻 For Developers](#for-developers) | [🌍 For Humanity](#for-humanity)
@ -18,14 +18,16 @@
## 🚨 Project Status: Proof of Concept ## 🚨 Project Status: Proof of Concept
**Important**: MPL is currently a research prototype demonstrating that programming languages can be built from mathematical notation. We have implemented a complete parser that validates the concept, but **programs cannot yet be executed**. This is a vision project seeking contributors to help build the interpreter and runtime. **Important**: MPL is currently a research prototype demonstrating that programming languages can be built from mathematical notation. We have implemented a working M0 parser that validates the concept, but **programs cannot yet be executed**. This is a vision project seeking contributors to help build the interpreter and runtime.
### What Works Today ✅ ### What Works Today ✅
- Complete ANTLR 4 grammar with 70+ mathematical symbols
- Parser that successfully processes all major programming paradigms Every item below is enforced by [CI](.github/workflows/ci.yml) on every push:
- Zero grammar ambiguities
- Comprehensive test suite validating syntax - An ANTLR 4 grammar built from mathematical symbols that compiles with zero errors and zero warnings (warnings are treated as errors)
- ASCII escape sequences for every Unicode symbol - All 10 [example programs](examples/) parse (`./gradlew parseExamples`)
- A test suite covering the lexer, the parser, the examples, and every ```` ```mpl ```` code block in this README (`./gradlew test`)
- An ASCII escape sequence for every Unicode symbol ([glyph-escapes.md](glyph-escapes.md))
### What Doesn't Work Yet 🚧 ### What Doesn't Work Yet 🚧
- **No interpreter** - Programs parse but don't run - **No interpreter** - Programs parse but don't run
@ -51,16 +53,14 @@ Every design decision in MPL must pass one simple test: **Can a 10-year-old non-
### Traditional programming ### Traditional programming
```python ```python
# English required: # English required:
for i in range(10): for n in [1, 2, 3, 4, 5]:
if i % 2 == 0: print(n * n)
print(i)
``` ```
### MPL - Universal understanding ### MPL - Universal understanding
```mpl ```mpl
# Mathematical symbols only: -- Mathematical symbols only:
∀ i ∈ [0,10) : ∀ n ∈ [1, 2, 3, 4, 5] : ✎(n × n)
i % 2 = 0 ? 📤(i)
``` ```
If Fatima can't understand it with her basic math knowledge, we redesign it. No exceptions. If Fatima can't understand it with her basic math knowledge, we redesign it. No exceptions.
@ -98,14 +98,14 @@ print("Hello, World!")
<td> <td>
```mpl ```mpl
📤("Hello, World!") ✎"Hello, World!"
``` ```
</td> </td>
</tr> </tr>
<tr> <tr>
<td>English words: print</td> <td>English words: print</td>
<td>Universal symbol: 📤 (output)</td> <td>Universal symbol: ✎ (output/trace)</td>
</tr> </tr>
</table> </table>
@ -121,7 +121,7 @@ Write code using mathematical symbols instead of English words. It's that simple
``` ```
┌─────────────────────────────────────────────┐ ┌─────────────────────────────────────────────┐
│ Mathematical Notation │ │ Mathematical Notation │
│ λn: n > 0 ? n × fact(n-1) : 1 │ │ λn: (n ≤ 1 ⟹ 1) | (n × fact(n-1)) │
└────────────────┬───────────────────────────┘ └────────────────┬───────────────────────────┘
│ │
▼ ▼
@ -139,30 +139,30 @@ Write code using mathematical symbols instead of English words. It's that simple
### Five ways to write λ (lambda) ### Five ways to write λ (lambda)
1. **👆 Click** — Visual symbol palette Today the parser accepts two spellings of every symbol: the Unicode glyph (λ) and its ASCII escape (`\lambda`). The rest are the input methods we envision tooling for:
2. **⌨️ Type** — `\lambda` transforms automatically
3. **🎤 Speak** — "Lambda" in ANY language (العربية, 中文, Español...) 1. **⌨️ Type** — `\lambda` (works today, in any editor)
4. **✍️ Draw** — Handwriting recognition on tablets 2. **👆 Click** — Visual symbol palette (envisioned)
5. **⚡ Shortcut** — Platform shortcuts (Cmd+L, Alt+L) 3. **🎤 Speak** — "Lambda" in ANY language (envisioned)
4. **✍️ Draw** — Handwriting recognition on tablets (envisioned)
5. **⚡ Shortcut** — Platform shortcuts (envisioned)
<details> <details>
<summary>🔧 Technical details (click to expand)</summary> <summary>🔧 Technical details (click to expand)</summary>
### Unicode implementation ### Unicode implementation
- Full UTF-8 support with 70+ mathematical operators - Full Unicode support, including supplementary-plane symbols (𝓜, 𝔹, 🖫)
- Bidirectional text support for RTL languages - Every glyph has exactly one ASCII escape ([glyph-escapes.md](glyph-escapes.md))
- Font fallback system ensuring symbol visibility
### Parser architecture ### Parser architecture
``` ```
Input Methods → Unicode Stream → ANTLR 4 Lexer → AST → Input Methods → Unicode Stream → ANTLR 4 Lexer → Parse Tree
→ Type Checker → Optimizer → Code Generation
``` ```
Type checking, optimization and code generation are planned, not built.
### Grammar specification ### Grammar specification
- Zero shift/reduce conflicts - Compiles with zero ANTLR errors and warnings (enforced in CI)
- Validated operator precedence - Operator precedence documented in [precedence.csv](precedence.csv)
- Complete coverage of programming paradigms
- [View full ANTLR grammar](src/main/antlr4/MPL.g4) - [View full ANTLR grammar](src/main/antlr4/MPL.g4)
</details> </details>
@ -178,37 +178,40 @@ Input Methods → Unicode Stream → ANTLR 4 Lexer → AST →
- **Cultural neutrality** — No linguistic imperialism - **Cultural neutrality** — No linguistic imperialism
- **Instant comprehension** — Symbols map to concepts directly - **Instant comprehension** — Symbols map to concepts directly
### 🎨 Multi-modal input ### 🎨 Multi-modal input (envisioned)
**Meet learners where they are** **Meet learners where they are**
Only ASCII escapes exist today; the rest is the tooling we want to build:
``` ```
┌─────────────┬─────────────┬─────────────┬─────────────┐ ┌─────────────┬─────────────┬─────────────┬─────────────┐
│ Visual │ Voice │ Keyboard │ Handwriting │ │ Visual │ Voice │ Keyboard │ Handwriting │
│ Palette │ Input │ Shortcuts │ Recognition │ │ Palette │ Input │ Escapes │ Recognition │
├─────────────┼─────────────┼─────────────┼─────────────┤ ├─────────────┼─────────────┼─────────────┼─────────────┤
│ Click λ │ Say "lambda"│ Type \lambda│ Draw λ │ │ Click λ │ Say "lambda"│ Type \lambda│ Draw λ │
│ from menu │ in any lang │ → λ appears │ on screen │ │ from menu │ in any lang │ (works now) │ on screen │
└─────────────┴─────────────┴─────────────┴─────────────┘ └─────────────┴─────────────┴─────────────┴─────────────┘
``` ```
- **Visual palette** — Click symbols like emoji - **ASCII escapes** — `\lambda`, `\forall`, … work in any editor today
- **Voice input** — Speak in your native language - **Visual palette** — Click symbols like emoji (envisioned)
- **Handwriting** — Natural for mathematical notation - **Voice input** — Speak in your native language (envisioned)
- **Smart shortcuts** — For power users - **Handwriting** — Natural for mathematical notation (envisioned)
### 📈 Progressive complexity ### 📈 Progressive complexity
**From arithmetic to algorithms** **From arithmetic to algorithms**
```mpl ```mpl
# Level 1: Basic math (everyone knows this!) -- Level 1: Basic math (everyone knows this!)
x ← 5 + 3 x ← 5 + 3;
y ← x × 2 y ← x × 2;
# Level 2: Logic (learned in school) -- Level 2: Logic (learned in school)
x > 10 ∧ y < 20 ? 📤("Success!") x > 10 ∧ y < 20 ⟹ ✎"Success!";
# Level 3: Advanced (natural progression) -- Level 3: Advanced (natural progression)
∑(i ∈ [1,100] : i²) → result squares ← 0;
∀ n ∈ [1, 2, 3, 4, 5] : squares ← squares + n × n;
``` ```
--- ---
@ -255,16 +258,18 @@ We envision students could progress like this:
**Starting point**: Basic math knowledge, no English **Starting point**: Basic math knowledge, no English
```mpl ```mpl
# Month 1: First program using familiar symbols -- Month 1: First program using familiar symbols
📤("Jambo!") # Hello in their language ✎"Jambo!" -- Hello in their language
``` ```
**Growing skills**: Applying math knowledge to programming **Growing skills**: Applying math knowledge to programming
```mpl ```mpl
# Month 6: Using mathematical concepts they know -- Month 6: Using mathematical concepts they know
data ← [23, 45, 67, 34, 89, 12] data ← [23, 45, 67, 34, 89, 12];
average ← (∑ x ∈ data : x) ÷ |data| total ← 0;
📤("Average: " + average) ∀ x ∈ data : total ← total + x;
average ← total ÷ 6;
✎("Average: " + average)
``` ```
**Sharing knowledge**: Teaching others in their community **Sharing knowledge**: Teaching others in their community
@ -277,72 +282,66 @@ average ← (∑ x ∈ data : x) ÷ |data|
## 💻 Code examples (Syntax Demonstration) ## 💻 Code examples (Syntax Demonstration)
**Note**: These examples show valid MPL syntax that our parser accepts. However, since we haven't built an interpreter yet, they cannot be executed. **Note**: These examples show valid MPL syntax that our parser accepts (a test extracts every code block on this page and parses it). However, since we haven't built an interpreter yet, they cannot be executed.
Some notation you might expect from math class — ∑, √, ², `%` (modulo), |x|, ranges like [1..10] — is deliberately absent: it is deferred to milestone M1, where each symbol will arrive together with defined semantics (see [DECISIONS.md](DECISIONS.md)).
### Level 1: Arithmetic thinking 🔢 ### Level 1: Arithmetic thinking 🔢
*What every child knows* *What every child knows*
```mpl ```mpl
# Store values (like math class!) -- Store values (like math class!)
# This syntax is valid and will parse ✓ length ← 5;
length ← 5 width ← 3;
width ← 3 area ← length × width;
area ← length × width ✎("Area = " + area);
📤("Area = " + area)
# Make decisions -- Make decisions: (condition ⟹ result) | fallback
# Parser accepts this, execution not implemented ✗ age ← 15;
age ← 15 (age ≥ 18 ⟹ ✎"Adult") | ✎"Minor";
age ≥ 18 ? 📤("Adult") : 📤("Minor")
``` ```
### Level 2: Logical reasoning 🧩 ### Level 2: Logical reasoning 🧩
*Natural progression from math* *Natural progression from math*
```mpl ```mpl
# Find all even numbers (∀ = "for all") -- Do something for every element (∀ = "for all")
∀ n ∈ [1,20] : ∀ n ∈ [1, 2, 3, 4, 5] : ✎(n × n);
n % 2 = 0 ? 📤(n)
# Sum of squares (just like ∑ in math!) -- Accumulate a running total
total ← ∑(i ∈ [1,10] : i²) total ← 0;
📤("Sum of squares: " + total) ∀ n ∈ [1, 2, 3, 4, 5] : total ← total + n;
✎("Total: " + total);
``` ```
### Level 3: Real-world applications 🌍 ### Level 3: Real-world applications 🌍
*Solving community problems* *Solving community problems*
```mpl ```mpl
# Weather data analysis -- Weather data analysis
temperatures ← [28, 30, 27, 31, 29, 33, 28] temperatures ← [28, 30, 27, 31, 29, 33, 28];
μ ← (∑ t ∈ temperatures : t) ÷ |temperatures| total ← 0;
σ ← √((∑ t ∈ temperatures : (t - μ)²) ÷ |temperatures|) ∀ t ∈ temperatures : total ← total + t;
μ ← total ÷ 7;
✎("Average: " + μ + "°C");
📤("Average: " + μ + "°C") -- Parallel processing (‖ = parallel)
📤("Std Dev: " + σ) results ← analyzeNorth() ‖ analyzeSouth() ‖ analyzeEast();
# Parallel processing (∥ = parallel)
results ← ∥ {
α: analyzeRegionNorth()
β: analyzeRegionSouth()
γ: analyzeRegionEast()
}
``` ```
### Level 4: Advanced concepts 🚀 ### Level 4: Advanced concepts 🚀
*For those ready to go deeper* *For those ready to go deeper*
```mpl ```mpl
# Neural network layer (yes, AI in symbols!) -- Function composition (∘, straight from math class)
layer ← λ(W, b, x): double ≜ λn: n × 2;
σ(W × x + b) # Matrix multiplication! addOne ≜ λn: n + 1;
where σ ← λz: 1 ÷ (1 + e^(-z)) transform ≜ double ∘ addOne;
✎(transform(5));
# Functional programming -- Higher-order functions
map ← λ(f, list): apply ≜ λf, x: f(x);
|list| = 0 ? [] : [f(list[0])] + map(f, list[1:]) ✎(apply(λn: n × n, 6));
∀ x ∈ map(λn: n², [1,2,3,4,5]) : 📤(x)
``` ```
--- ---
@ -352,9 +351,9 @@ map ← λ(f, list):
We believe the core innovation of MPL is proving that mathematical notation can replace English keywords. By releasing the parser, we demonstrate this is grammatically possible and invite the community to help build the rest. We believe the core innovation of MPL is proving that mathematical notation can replace English keywords. By releasing the parser, we demonstrate this is grammatically possible and invite the community to help build the rest.
The parser alone proves several key points: The parser alone proves several key points:
- Mathematical symbols can express all programming constructs - Mathematical symbols can express the core programming constructs (see the ten [examples](examples/))
- A language without English keywords is technically feasible - A language without English keywords is technically feasible
- The grammar handles real complexity with zero ambiguities - The grammar compiles with zero ANTLR errors and warnings, enforced in CI
- ASCII fallbacks make it universally typeable - ASCII fallbacks make it universally typeable
Sometimes the idea is more important than the implementation. By sharing MPL now, we hope to inspire others to think differently about programming languages and who they exclude. Sometimes the idea is more important than the implementation. By sharing MPL now, we hope to inspire others to think differently about programming languages and who they exclude.
@ -365,9 +364,10 @@ Sometimes the idea is more important than the implementation. By sharing MPL now
### Grammar specification ### Grammar specification
- **70+ operators** across 15 categories - Every symbol has exactly one meaning and one ASCII escape ([glyph-escapes.md](glyph-escapes.md))
- **Zero ambiguities** in ANTLR 4 grammar - Operator precedence is documented in [precedence.csv](precedence.csv) and exercised by the test suite
- **Proven precedence** through 1000+ test cases - The grammar compiles with zero ANTLR errors and warnings (`-Werror`, enforced in CI)
- 200+ syntax assertions across the lexer, parser, example, and documentation test suites
- [Full grammar specification](src/main/antlr4/MPL.g4) - [Full grammar specification](src/main/antlr4/MPL.g4)
### Implementation stack ### Implementation stack
@ -389,22 +389,17 @@ Sometimes the idea is more important than the implementation. By sharing MPL now
└────────────────────┬───────────────────────┘ └────────────────────┬───────────────────────┘
│ │
┌────────────────────▼───────────────────────┐ ┌────────────────────▼───────────────────────┐
│ Semantic Analysis │ │ Semantic Analysis (planned) │
│ Type Checking → Effect Analysis │ │ Type Checking → Effect Analysis │
└────────────────────┬───────────────────────┘ └────────────────────┬───────────────────────┘
│ │
┌────────────────────▼───────────────────────┐ ┌────────────────────▼───────────────────────┐
│ Code Generation │ │ Code Generation (planned) │
│ LLVM │ JVM │ JavaScript │ Python │ │ LLVM │ JVM │ JavaScript │ Python │
└────────────────────────────────────────────┘ └────────────────────────────────────────────┘
``` ```
### Performance metrics Only the parser stage exists today; the lower stages are the planned architecture. We publish no performance numbers until CI measures them.
- **Parse time**: <10ms for 1000 LOC
- **Memory usage**: O(n) with input size
- **Unicode handling**: Zero-copy string processing
- **Error recovery**: Continues parsing after errors
--- ---
@ -455,7 +450,7 @@ Sometimes the idea is more important than the implementation. By sharing MPL now
```bash ```bash
# Clone and build # Clone and build
git clone https://github.com/mpl-lang/mpl git clone https://github.com/developtheweb/mpl.git
cd mpl cd mpl
./gradlew build ./gradlew build
@ -473,7 +468,7 @@ cd mpl
- 🔧 Language features - 🔧 Language features
- 📱 Mobile applications - 📱 Mobile applications
[Contributing guidelines](CONTRIBUTING.md) | [Architecture docs](docs/ARCHITECTURE.md) | [Discord community](https://discord.gg/mpl-lang) [Contributing guidelines](CONTRIBUTING.md) | [Architecture docs](docs/ARCHITECTURE.md) | [GitHub issues](https://github.com/developtheweb/mpl/issues)
### For researchers 🔬 ### For researchers 🔬

42
src/test/java/com/mpl/test/DocumentationTest.java Normal file
View file

@ -0,0 +1,42 @@
package com.mpl.test;
import org.junit.Assert;
import org.junit.Test;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
/**
* Documentation-consistency test: every fenced ```mpl code block in the
* project documentation must parse with the shipped grammar. This keeps the
* docs and the grammar from describing different languages.
*/
public class DocumentationTest extends MPLTestBase {
private static final Pattern MPL_BLOCK =
Pattern.compile("```mpl\\R(.*?)```", Pattern.DOTALL);
@Test
public void testReadmeCodeBlocksParse() throws IOException {
assertAllMplBlocksParse(Paths.get("README.md"));
}
private void assertAllMplBlocksParse(Path doc) throws IOException {
String content = Files.readString(doc);
Matcher m = MPL_BLOCK.matcher(content);
int count = 0;
while (m.find()) {
count++;
String code = m.group(1);
ParseResult result = parseWithDiagnostics(code);
if (!result.errors.isEmpty()) {
Assert.fail(doc + " ```mpl block #" + count + " does not parse:\n"
+ code + "\nErrors:\n" + String.join("\n", result.errors));
}
}
Assert.assertTrue("No ```mpl blocks found in " + doc, count > 0);
}
}