.eng - Programming in Plain English

Write code that reads like natural English. .eng is a first-class programming language for Node.js that compiles to TypeScript/JavaScript, with full npm ecosystem support and native React/JSX integration.

// Hello World in plain English
say "Hello, World!"

// Variables with natural syntax
set name to "Alice"
set [count, setCount] to React.useState(0)

// Exported React component with multi-line JSX
export default define function Hero
  return
    container with class "hero"
      heading "Welcome, " and name
      paragraph "Count is " and count
      button with class "btn" and onclick {() => setCount(count + 1)} "Increment"

🚀 Quick Start

Option 1: Create a New Project (Recommended)

# Create a new englang project
npx create-eng-app my-app

# Navigate to project
cd my-app

# Install dependencies
npm install

# Start developing
npm run dev

Choose from multiple templates:

• --template basic - Simple console application (default)
• --template react - React app with Vite
• --template express - Express web server

Option 2: Single File Execution

Install globally:

npm install -g englang

Create hello.eng:

say "Hello from .eng!"
set name to "World"
say "Hello, " and name and "!"

Run it directly (like Python):

eng hello.eng

That's it! No compilation step needed - .eng files run directly.

✨ Key Features

🗣️ Natural English Syntax

• 11 output synonyms: say, print, show, display, output, log, write, echo, tell, announce, shout
• 6 variable synonyms: set, create, make, assign, put, let...be
• Destructuring with English verbs: set [x, y] to point, create {name, age} as user
• Natural operators: is greater than, equals, is not equal to, contains, starts with
• 10+ loop synonyms: loop N times, repeat, iterate, for each, go through

⚛️ React/JSX Integration

• 180+ HTML element synonyms: Use container instead of div, heading instead of h1
• Natural attributes: button with class "btn" saying "Click"
• Multi-line JSX returns & expressions: return on one line followed by indented JSX blocks
• JSX-ready destructuring: set [value, setValue] to React.useState(0) works out of the box
• Ready for Next.js: Works seamlessly with React frameworks

🔧 First-Class Node.js Integration

• Zero-config execution: Run .eng files directly with custom Node.js loader
• Full npm ecosystem: Import any npm package
• TypeScript output: Generated code is readable TypeScript
• Source maps: Full debugging support with original line numbers

🛠️ Professional Tooling

• Build system: Compile to TypeScript, JavaScript, or hybrid
• Type checking: Optional TypeScript validation
• Caching: Fast content-hash based compilation cache
• CLI tools: Complete command-line interface

📚 Language Features

Variables & Output

set message to "Hello"
create count to 42
make items to [1, 2, 3]
let total be 0

say message
output "Count: " and count

Conditionals

if score is greater than 90
  say "Grade: A"
else if score is greater than 80
  say "Grade: B"
else
  say "Grade: C"

if name equals "Alice" and age is greater than 18
  say "Welcome, Adult Alice!"

Loops

// Counted loops
loop 10 times
  say i

repeat 5 times
  say "Iteration " and i

// Collection iteration
for each item in items
  say item

iterate through color in colors
  say color

// While loops
while count is less than 10
  count = count + 1

Functions

define greet with name
  say "Hello, " and name and "!"

define add with x and y
  return x + y

// Async functions
async define fetchData with url
  wait for response
  return data

Classes

define class Person
  constructor with name and age
    set this.name to name
    set this.age to age
  
  method introduce
    say "I'm " and this.name and ", age " and this.age

set person to new Person("Bob", 30)
person.introduce()

Error Handling

try
  risky_operation()
catch error
  say "Error: " and error.message
finally
  cleanup()

React/JSX

container with class "app"
  header with class "top"
    navigation
      link with href "/" "Home"
      link with href "/about" "About"
  
  main with class "content"
    heading "Welcome"
    paragraph "This is plain English JSX!"
    
    button with class "btn primary" saying "Click Me"
    
    list
      item "Natural syntax"
      item "Clean JSX output"
      item "React ready"

🎯 Use Cases

✅ Perfect For

• Learning programming: Syntax is immediately understandable
• Prototyping: Write code faster with natural language
• React apps: Build UIs with readable JSX
• Scripts & automation: Cleaner than Bash, more readable than Python
• Teaching: Students can focus on logic, not syntax
• Internal tools: Code that non-programmers can read

🤔 Consider Alternatives For

• Performance-critical applications (though generated code is fast)
• Teams heavily invested in existing languages
• Projects requiring specific language features not yet in .eng

📖 Documentation

• Docs Hub: packages/englang/docs/index.md
• Quick Start: packages/englang/docs/getting-started.md
• Language Guide: packages/englang/docs/language-guide.md
• Compiler Capabilities: packages/englang/docs/compiler-capabilities.md
• Examples: packages/englang/examples

🏗️ Project Structure

eng-lang/
├── src/                 # Compiler source (TypeScript)
│   ├── compiler.ts      # .eng → TypeScript transpiler
│   ├── cli.ts          # Command-line interface
│   ├── loader.ts       # Node.js ESM loader
│   └── build.ts        # Build system
├── examples/           # 18 example .eng programs
├── tests/              # 103 passing Jest tests
├── docs/               # Comprehensive documentation
└── dist/               # Compiled CLI (npm package)

🧪 Examples

Hello World

say "Hello, World!"

Variables & Math

set x to 10
set y to 5
say "Sum: " and (x + y)
say "Product: " and (x * y)

Loops & Conditionals

loop 5 times
  if i is greater than 2
    say "i is " and i
  else
    say "i is small"

React Component

container with class "card"
  heading "Product Name"
  paragraph "Description goes here"
  button with class "btn" saying "Buy Now"

See examples/ for 18 complete programs including:

• Async/await patterns
• Error handling
• Web servers
• React components
• Full HTML/JSX demos

🛠️ CLI Commands

# Run a .eng file directly (like Python)
eng main.eng
eng src/app.eng
eng run                    # Run project entry point

# Create new projects
npx create-eng-app my-app
npx create-eng-app my-react-app --template react
npx create-eng-app my-server --template express

# Transpile to TypeScript/JavaScript
eng transpile file.eng --out ts
eng transpile file.eng --out js

# Build project
eng build                  # Emit compiled files
eng build --typecheck      # With type checking
eng build --out hybrid     # Both TS and JS

# Manage cache
eng cache clear
eng cache stats

# Get help
eng --help
eng --version

🎨 Language Philosophy

Natural Over Technical

• say instead of console.log()
• is greater than instead of >
• loop 5 times instead of for(let i=0; i<5; i++)

Keywords Over HTML

• break exits loops (use next-line or line-break for <br>)
• output prints to console (use output-field for <output>)
• Programming constructs take priority over HTML elements

Multiple Ways to Express

• Choose what reads best in context
• say vs print vs output - all work the same
• set vs create vs make - pick what feels natural

Readable Generated Code

• Compiles to clean TypeScript
• Source maps for debugging
• Can mix with regular JavaScript

📊 Status

Version: 0.3.4
Status: Production Ready (Compiler & Language), Active Development (Tooling)

Implemented

✅ Core language features (variables, conditionals, loops, classes, async)
✅ Destructuring with English syntax (arrays & objects)
✅ Export statements and multi-line JSX returns
✅ React/JSX support with 180+ synonyms
✅ CLI commands & build system
✅ Node.js loader with caching and source maps
✅ 103 Jest tests with ~82% statement coverage

In Progress

🔨 VSCode extension & language server
🔨 Watch mode for eng build
🔨 CI/CD workflow hardening

See STATUS_OCT_21_V2.md for detailed status notes.

🤝 Contributing

Contributions welcome! The codebase is clean, well-tested TypeScript.

git clone https://github.com/Surebob/eng-lang
cd eng-lang
npm install
npm run build
npm test

See CONTRIBUTING.md for guidelines.

📝 License

MIT License - see LICENSE for details.

🌟 Why .eng?

"Code should be readable by humans first, computers second."

Most programming languages were designed for computers with human readability as an afterthought. .eng flips this: it's designed for human readability first, with compilation to efficient JavaScript as the implementation detail.

The result is code that:

• Reads like prose: "loop 5 times, say i" is immediately clear
• Requires no translation: Non-programmers can understand it
• Reduces cognitive load: Focus on logic, not syntax
• Runs everywhere: Compiles to standard JavaScript/TypeScript

Perfect for teaching, prototyping, internal tools, and any project where code clarity matters more than syntactic tradition.

🔗 Links

• Documentation: docs/index.md
• Examples: examples/README.md
• Language Guide: docs/language-guide.md
• CLI Reference: docs/cli-reference.md
• GitHub: Surebob/eng-lang
• npm: englang | create-eng-app

Start writing code in plain English today! 🚀

npm install -g englang
eng --version

The project includes 103 automated tests across 7 suites:

• tests/compiler/basic.test.ts – Core language constructs
• tests/compiler/switch.test.ts – Switch statements and matching
• tests/compiler/jsx.test.ts – JSX/HTML compilation
• tests/compiler/synonyms.test.ts – Keyword and element synonym coverage
• tests/compiler/features.test.ts – Async, errors, operators, control flow
• tests/compiler/advanced.test.ts – Exports, multi-line JSX returns, destructuring
• tests/cli/build.test.ts – Build pipeline integration

Coverage: ~82% statement coverage on the compiler (see npm test -- --coverage).