The source is natural language. The compiled artifact can be Python or TypeScript.
NLS is a programming language where specifications are written in natural language that anyone can read—managers, auditors, domain experts—not just programmers. The nlsc compiler translates .nl files into executable Python or TypeScript with type hints, validation, and documentation.
# Install from PyPI
pip install nlsc
# With tree-sitter parser (faster, better error recovery)
pip install "nlsc[treesitter]"
# For development (from source)
git clone https://github.com/Mnehmos/mnehmos.nls.lang.git
cd mnehmos.nls.lang
pip install -e ".[dev,treesitter]"Get custom icons for .nl files in Windows Explorer:
# Download and run the installer from GitHub Releases
# Or use the CLI:
nlsc assoc --user # Current user (no admin)
nlsc assoc # System-wide (requires admin)Then right-click any .nl file → Open with → select the NLS launcher and check "Always use this app".
# Initialize a new project
nlsc init my-project
cd my-project
# Create your first .nl file
cat > src/calculator.nl << 'EOF'
@module calculator
@target python
[add]
PURPOSE: Add two numbers together
INPUTS:
- a: number
- b: number
RETURNS: a + b
[divide]
PURPOSE: Divide two numbers safely
INPUTS:
- numerator: number
- divisor: number
GUARDS:
- divisor must not be zero -> ValueError("Cannot divide by zero")
RETURNS: numerator / divisor
@test [add] {
add(2, 3) == 5
add(-1, 1) == 0
}
EOF
# Compile to Python
nlsc compile src/calculator.nl
# Compile the same spec to TypeScript
nlsc compile src/calculator.nl -t typescript
# Run the tests
nlsc test src/calculator.nlInput: math.nl
@module math
@version 1.0.0
@target python
@type Point {
x: number
y: number
}
[distance]
PURPOSE: Calculate distance between two points
INPUTS:
- p1: Point
- p2: Point
LOGIC:
1. dx = p2.x - p1.x
2. dy = p2.y - p1.y
3. squared = dx * dx + dy * dy
RETURNS: sqrt(squared)
DEPENDS: [sqrt]
@test [distance] {
distance(Point(0, 0), Point(3, 4)) == 5.0
}
Output: math.py
"""math module - Generated by nlsc"""
from dataclasses import dataclass
from math import sqrt
@dataclass
class Point:
"""Point type"""
x: float
y: float
def distance(p1: Point, p2: Point) -> float:
"""Calculate distance between two points"""
dx = p2.x - p1.x
dy = p2.y - p1.y
squared = dx * dx + dy * dy
return sqrt(squared)| Command | Description |
|---|---|
nlsc init <path> |
Initialize new NLS project |
nlsc compile <file> |
Compile .nl to Python |
nlsc verify <file> |
Validate syntax and dependencies |
nlsc test <file> |
Run @test specifications |
nlsc graph <file> |
Generate dependency diagrams |
nlsc diff <file> |
Show changes since last compile |
nlsc watch <dir> |
Continuous compilation on file changes |
nlsc atomize <file.py> |
Extract ANLUs from existing Python |
nlsc assoc |
Install Windows file association |
nlsc lsp |
Start the NLS language server |
nlsc lsp --json emits structured startup diagnostics for missing optional LSP dependencies (ELSP001) and server-start failures (ELSP002).
--parser {auto,regex,treesitter} # Parser backend (default: auto)
--version # Show version
--help # Show help# Compile with tree-sitter parser
nlsc --parser treesitter compile src/auth.nl
# Compile to TypeScript
nlsc compile src/auth.nl -t typescript
# Generate Mermaid dependency diagram
nlsc graph src/order.nl --format mermaid
# Visualize dataflow for specific function
nlsc graph src/order.nl --anlu process-order --dataflow
# Watch directory and run tests on changes
nlsc watch src/ --test
# Show what changed since last compile
nlsc diff src/api.nl --fullUse the NLS Compiler Action in your CI/CD pipelines for zero-config validation:
# .github/workflows/nls.yml
name: NLS Validation
on: [push, pull_request]
jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: Mnehmos/mnehmos.nls.lang/action@master
with:
verify: 'true' # Verify all .nl files parse correctly
compile: 'false' # Compile .nl files to Python
test: 'false' # Run @test blocks
lock-check: 'false' # Verify lockfiles are current
path: '.' # Path to search for .nl files| Input | Default | Description |
|---|---|---|
verify |
true |
Verify all .nl files parse correctly |
compile |
false |
Compile .nl files to target language |
test |
false |
Run @test blocks from .nl files |
lock-check |
false |
Check that lockfiles are up to date |
path |
. |
Path to search for .nl files |
python-version |
3.12 |
Python version to use |
fail-on-warning |
false |
Fail the action if there are warnings |
| Output | Description |
|---|---|
verified-files |
Number of verified .nl files |
compiled-files |
List of compiled output files |
test-results |
Test pass/fail summary |
warnings |
Number of warnings |
[function-name]
PURPOSE: What this function does
INPUTS:
- param1: type
- param2: type, optional
GUARDS:
- validation condition -> ErrorType("message")
LOGIC:
1. step description -> variable
2. another step
EDGE CASES:
- condition -> behavior
RETURNS: expression
DEPENDS: [other-function], [another]
@type Order {
id: string, required
items: list of OrderItem
total: number, "Order total in cents"
status: string
}
@type OrderItem extends BaseItem {
quantity: number
price: number
}
@test [add] {
add(1, 2) == 3
add(0, 0) == 0
add(-5, 5) == 0
}
@property [add] {
add(a, b) == add(b, a) # commutativity
add(a, 0) == a # identity
forall x: number -> add(x, -x) == 0
}
@type Account {
balance: number
owner: string
}
@invariant Account {
balance >= 0
len(owner) > 0
}
@module name # Module name
@version 1.0.0 # Semantic version
@target python # Target language
@imports other_module # Import dependencies
@use math.core # Stdlib domain dependency (Issue #90)
"The conversation is the programming. The
.nlfile is the receipt. The code is the artifact."
.nlfiles — Human-readable specifications anyone can review.pyfiles — Compiled artifacts (like assembly from C).nl.lockfiles — Deterministic hashes for reproducible builds
- Readable by everyone — Non-programmers can review business logic
- Auditable — Clear mapping from intent to implementation
- Testable — Specifications include test cases
- Versionable — Lock files ensure reproducibility
- Toolable — Tree-sitter grammar enables IDE support
| Component | Status |
|---|---|
| Parser (regex) | ✅ Complete |
| Parser (tree-sitter) | ✅ Complete |
| Python emitter | ✅ Complete |
| Type generation | ✅ Complete |
| Guard validation | ✅ Complete |
| Dataflow analysis | ✅ Complete |
| Test runner | ✅ Complete |
| Property-based testing | ✅ Complete |
| Type invariants | ✅ Complete |
| Watch mode | ✅ Complete |
| GitHub Action | ✅ Complete |
| PyPI distribution | ✅ Complete |
| VS Code extension | ✅ Complete |
| LSP server | ✅ Complete |
| Windows installer | ✅ Complete |
| TypeScript target | ✅ Initial compile support |
239 tests passing — Production-ready for Python target. See GitHub Issues for roadmap.
📚 Full Documentation — Hosted on GitHub Pages
# Clone and install
git clone https://github.com/Mnehmos/mnehmos.nls.lang.git
cd mnehmos.nls.lang
pip install -e ".[dev,treesitter]"
# Run tests
pytest tests/ -v
# Run tree-sitter grammar tests
cd tree-sitter-nl && npx tree-sitter testMIT