novascript-x 1.0.0

NovaScript-X - A lightweight, modern programming language runtime

NovaScript-X - A Lightweight Programming Language Runtime

A Python-based interpreter for the NovaScript programming language, designed as a modern, lightweight alternative to Node.js. Write full-stack applications with a unified language runtime.

Package Name: novascript-x
CLI Command: novax
Current Version: 1.0.0
Status: Beta (Core language features complete, web runtime in development)

🚀 Quick Start

Installation

Install NovaScript-X globally via pip:

# From PyPI (recommended)
pip install novascript-x

# Or from source (development mode)
cd NovaScript
pip install -e .

After installation, the novax command will be available globally on your system.

Run Your First Program

Create a file called hello.nova:

print("Hello, Nova!")

var name = "World"
print("Welcome to " + name)

Run it:

novax hello.nova

Interactive REPL

Start the interactive interpreter:

novax

Type NovaScript code and see results instantly:

nova> var x = 10
nova> print(x + 5)
15
nova> exit

📖 Language Features

Variables

var name = "Alice"
var age = 25
var pi = 3.14159

Functions

function greet(person):
{
    print("Hello, " + person)
}

greet("Bob")

function add(a, b):
{
    return a + b
}

var sum = add(3, 5)

Control Flow

# If / Else
if (age >= 18): {
    print("Adult")
} else: {
    print("Minor")
}

# While loop
var count = 0
while (count < 5): {
    print(count)
    count = count + 1
}

# For loop
for (var i = 1 : i <= 5 : i = i + 1): {
    print("Number: " + i)
}

Operators

• Arithmetic: +, -, *, /, %
• Comparison: ==, !=, <, >, <=, >=
• Logical: and, or, !

Advanced Features

• Recursion
• String concatenation with automatic type coercion
• Comments with #

🛠️ CLI Commands

The novax command supports various options:

Run a Script

novax script.nova

Interactive REPL

novax

Watch Mode (Auto-run on Changes)

novax --watch script.nova
# or
novax -w script.nova

Execute Code Inline

novax -c 'print("Hello NovaScript-X")'

Debug Mode

novax --debug script.nova

Show Version

novax --version
# or
novax -v

Display Help

nova --help
# or
nova -h

📦 Standard Library (In Development)

NovaScript includes a standard library for common tasks. Import modules using require():

Available Modules

fs - File System

var fs = require("fs")

# Write to file
fs.writeFile("test.txt", "Hello")

# Read from file
var content = fs.readFile("test.txt")

# Check if file exists
if (fs.fileExists("test.txt")): {
    print("File exists")
}

console - Logging

var console = require("console")

console.log("Regular message")
console.warn("Warning!")
console.error("Error occurred")
console.info("Info")
console.debug("Debug message")

math - Mathematics

var math = require("math")

print(math.sqrt(16))        # 4.0
print(math.pow(2, 3))       # 8
print(math.abs(-5))         # 5
print(math.floor(4.7))      # 4
print(math.pi)              # 3.14159...

random - Random Numbers

var random = require("random")

var n = random.randInt(1, 100)      # Random int 1-100
var f = random.randFloat()           # Random 0.0-1.0

date - Date/Time

var date = require("date")

print(date.now())           # Current timestamp
print(date.format("%Y-%m-%d"))   # Formatted date
print(date.addDays(5))      # Date 5 days from now

http - HTTP Requests

var http = require("http")

# GET request
var response = http.get("https://api.example.com/data")

# POST request
var result = http.post("https://api.example.com", {key: "value"})

📂 Project Structure

nova/
├── __init__.py              # Package initialization
├── interpreter.py           # Core language interpreter
│   ├── Lexer              # Tokenizes source code
│   ├── Parser             # Builds AST
│   └── Executor           # Executes code
└── stdlib/                  # Standard library
    ├── fs.py              # File system
    ├── console.py         # Logging
    ├── math.py            # Math functions
    ├── random.py          # Random numbers
    ├── date.py            # Date/time
    └── http.py            # HTTP requests

nova_cli.py                 # Command-line interface
setup.py                    # Installation configuration
examples/                   # Example programs

🚀 Examples

See the examples/ directory for complete working programs:

1. hello_world/ - Basic variables and printing
2. functions_loops/ - Functions, loops, recursion, and conditions

Run examples:

nova examples/hello_world/main.nova
nova examples/functions_loops/main.nova

🔧 Features & Roadmap

✅ Completed (v1.0)

• Core language interpreter (Lexer, Parser, Executor)
• CLI with argparse support
• Watch mode for development
• Standard library modules (fs, console, math, random, date, http)
• REPL mode
• Cross-platform (Windows, macOS, Linux)
• pip installation support

🚧 In Development

• require() function for module imports
• Web server/HTTP routing support
• Web framework with nova create scaffold
• Server-side rendering
• Hot reloading

📋 Planned (v1.1+)

• Array/List support
• Object/Dictionary support
• Classes and OOP
• Async/await
• Package manager
• Type system
• Testing framework
• Build tools

🎓 Tutorial & Documentation

Your First Program

Create script.nova:

# Variables and printing
var greeting = "Welcome to NovaScript"
print(greeting)

# Functions
function multiply(a, b):
{
    return a * b
}

# Using the function
var result = multiply(6, 7)
print("6 * 7 = " + result)

# Loops
for (var i = 1 : i <= 3 : i = i + 1): {
    print("Iteration " + i)
}

Run it:

nova script.nova

Conditionals

var score = 85

if (score >= 90): {
    print("Grade A")
} else: {
    if (score >= 80): {
        print("Grade B")
    } else: {
        print("Grade C")  
    }
}

Recursion

# Calculate factorial
function factorial(n):
{
    if (n <= 1): {
        return 1
    }
    return n * factorial(n - 1)
}

print(factorial(5))  # 120

🔌 Web Runtime (Coming Soon)

In future versions, run NovaScript as an HTTP server:

# Start web server
nova --serve app.nova

# app.nova
function handleRequest(req, res):
{
    res.send("Hello from NovaScript!")
}

🐛 Troubleshooting

Command not found: nova

Make sure you installed NovaScript:

pip install -e .

Verify installation:

which nova
nova --version

Import errors

Make sure you're in the correct directory and the nova package is properly installed:

pip install -e .
python -c "import nova; print(nova.__version__)"

File not found

Use absolute paths or relative paths from your current directory:

# Absolute path
nova /full/path/to/script.nova

# Relative path
nova ./scripts/script.nova

📄 License

MIT License - See LICENSE file for details

🤝 Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

📞 Support

For issues and questions:

• Open an issue on GitHub
• Check documentation in examples/ directory
• Review test files in tests/ directory

🎉 Acknowledgments

NovaScript is inspired by Node.js, Python, and JavaScript, bringing together the best features of modern runtimes into a lightweight, easy-to-learn language.

Features

• Variables: Declare variables with var
• Functions: Create functions with function keyword and return statements
• Print: Output values with print()
• Conditionals: if/else statements with boolean logic
• Loops: while and for loops
• Arithmetic: Full arithmetic operations (+, -, *, /, %)
• String Concatenation: Use + operator to concatenate strings
• Operators: Comparison (==, !=, <, >, <=, >=), logical (and, or), unary (!, -)

Usage

Running a NovaScript File

python nova_interpreter.py program.nova

Interactive REPL Mode

python nova_interpreter.py

Then type NovaScript commands at the nova> prompt. Type exit to quit.

Syntax

Variables

var name = value
var x = 10
var greeting = "Hello"

Functions

function functionName(param1, param2):
{
    # Function body
    return result
}

Example:

function add(a, b):
{
    return a + b
}

var result = add(5, 3)
print("Result: " + result)  # Output: Result: 8

Print Statement

print("Hello, World")
print("Value: " + x)
print("Sum: " + (5 + 3))

Conditionals

if (condition): {
    # Then body
} else: {
    # Else body
}

Example:

var age = 25
if (age >= 18): {
    print("Adult")
} else: {
    print("Minor")
}

While Loop

while (condition): {
    # Loop body
}

Example:

var count = 1
while (count <= 3): {
    print("Count: " + count)
    count = count + 1
}

For Loop

for (init : condition : update): {
    # Loop body
}

Example:

for (var i = 1 : i <= 5 : i = i + 1): {
    print("i = " + i)
}

Arithmetic Operators

• +: Addition and string concatenation
• -: Subtraction
• *: Multiplication
• /: Division (integer division for integers)
• %: Modulo

Comparison Operators

• ==: Equal to
• !=: Not equal to
• <: Less than
• >: Greater than
• <=: Less than or equal to
• >=: Greater than or equal to

Logical Operators

• and: Logical AND
• or: Logical OR
• !: Logical NOT

Comments

# This is a comment

Interpreter Architecture

The interpreter is modular with three main components:

1. Lexer: Tokenizes NovaScript source code

   • Recognizes keywords, operators, literals, and identifiers
   • Handles string literals with escape sequences
   • Produces a stream of Token objects

2. Parser: Parses tokens into an abstract syntax tree (AST)

   • Implements recursive descent parsing with operator precedence
   • Produces a list of statement dictionaries
   • Handles all NovaScript language constructs

3. Executor: Executes the parsed AST

   • Manages global and local scope
   • Evaluates expressions and executes statements
   • Handles function calls and returns

Example Program

# Variables
var name = "NovaScript"
print("Language: " + name)

# Functions
function greet(person):
{
    print("Hello, " + person)
}

greet("World")

# Fibonacci with recursion
function fibonacci(n):
{
    if (n <= 1): {
        return n
    }
    return fibonacci(n - 1) + fibonacci(n - 2)
}

print("Fibonacci(7) = " + fibonacci(7))

# Loops
for (var i = 1 : i <= 5 : i = i + 1): {
    var square = i * i
    print("Square of " + i + " = " + square)
}

# Conditionals
var score = 85
if (score >= 90): {
    print("Grade: A")
} else: {
    if (score >= 80): {
        print("Grade: B")
    } else: {
        print("Grade: C")
    }
}

Project File Structure

Core Interpreter

• nova_interpreter.py (893 lines)
  • Lexer class: Tokenizes source code, handles keywords, operators, strings, numbers
  • Parser class: Recursive descent parser, builds abstract syntax tree (AST)
  • Executor class: Executes AST, manages scopes, evaluates expressions
  • REPL mode for interactive execution

Web IDE Backend

• server.py (152 lines)
  • Flask web server configuration
  • GET / route: Serves the IDE interface (index.html)
  • POST /api/execute route: Receives code, executes it, captures output, returns JSON
  • GET /api/highlight-keywords route: Returns language keywords for syntax highlighting
  • Error handling and output capture with io.StringIO

Web IDE Frontend

• templates/index.html

  • CodeMirror 5 editor integration for syntax highlighting
  • Dark theme styling
  • Output console for displaying results
  • Buttons: Run Code (Ctrl+Enter), Clear, Reset
  • AJAX communication with Flask backend

• static/style.css (700+ lines)

  • Professional dark theme (GitHub dark mode inspired)
  • CSS variables for theming and layout control
  • Responsive grid layout (editor + console)
  • Terminal-style console output styling

• static/script.js (300+ lines)

  • CodeMirror editor initialization and configuration
  • AJAX request/response handling for code execution
  • Console message formatting and display
  • Event listeners for Run, Clear, Reset buttons
  • Keyboard shortcuts (Ctrl+Enter to run)

Configuration Files

• requirements.txt: Python dependencies (Flask==2.3.3, Werkzeug==2.3.7)
• test.nova: Sample NovaScript program for testing

Extending the Interpreter

The modular design makes it easy to add new features:

1. Add Keywords: Add to Lexer.KEYWORDS and create a parse method
2. Add Operators: Extend the binary/unary operator parsing and evaluation
3. Add Data Types: Add new value types to the executor
4. Add Built-in Functions: Add to the executor for built-in functions

Limitations

• Requires braces for multi-statement blocks (indentation-based syntax can be added)
• No array/list support yet (can be added)
• No object/dictionary support yet (can be added)
• No file I/O support yet (can be added)
• No module/import system yet (can be added)

Error Handling

The interpreter provides helpful error messages:

• Syntax errors from the lexer and parser
• Runtime errors from the executor
• Type errors for invalid operations
• Name errors for undefined variables/functions