Metadata-Version: 2.4
Name: nexus-dsl
Version: 1.0.3
Summary: NEXUS: A Custom Domain-Specific Scripting Language (DSL) for local automation
Author-email: Yuvneil <yuvneiledu44@gmail.com>
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: colorama>=0.4.6
Requires-Dist: plyer>=2.1.0
Requires-Dist: pyttsx3>=2.90

# NEXUS: A Custom Domain-Specific Scripting Language (DSL)

NEXUS is an elegant, cross-platform, domain-specific scripting language engineered entirely in Python. It abstracts complex localized operating system tasks, directory architectures, cryptographic transformations, and core machine telemetry workflows into a highly readable, human-centric syntax layout.

Developed as a breakthrough milestone during the First-Year curriculum at Lovely Professional University (LPU), Jalandhar, this framework implements a modular token parsing architecture that lets you automate system scripts natively.

---

## 🚀 Installation & Setup

Install the stable release of the NEXUS engine directly from PyPI using `pip`:

```bash
pip install nexus-dsl
```

### External Dependencies
NEXUS requires a few lightweight libraries to power its native notification toaster, text layout engines, and hardware audio modules:
```bash
pip install colorama plyer pyttsx3
```

---

## 💻 Python Integration API

The project architecture is decoupled across three main structural modules:
* `main.py`: File validator, reader loop, and core runtime entry point.
* `function_passer.py`: Syntax token interpreter, router loop, and input parameter slicer.
* `function_executors.py`: Core execution engine handling files, systems, memory state, and data parsing.

You can easily load and run `.nxs` automation scripts straight from your standard Python files.

```python
from nexus import nexus

# Simply trigger the core engine loop by providing your script path
nexus.nexus("main.nxs")
```

---

## 📖 Keyword Reference Manual & Syntax Specs

NEXUS statement expressions read line-by-line. Comments must begin with a `#` token. Any multi-word string parameters containing spaces must be cleanly wrapped inside typographic double quotes (`”...”`).

### 1. Variables & Memory Engine (New)
* **`Set [variable_name] = [value]`**  
  Declares or overwrites a dynamic variable inside runtime memory. It supports variable-to-variable assignments and automatically casts literals.
  * **String Literal:** Wrapped in double quotes (`”b”`). Skips lookups and saves as a raw string text asset.
  * **Numeric/Boolean Literal:** Unquoted strings like `5`, `12.4`, or `True` automatically evaluate into proper data types (`int`, `float`, `bool`).
  * **Variable Reference:** Unquoted words check memory state. If the variable name exists, its assigned value is copied. If it doesn't exist, it displays a missing definition error and exits.
  * *Syntax:* `Set a = ”b”` | `Set x = 5` | `Set y = x`

### 2. Console Operations & Core Logging
* **`Show [expression / variable]`**  
  Strips enclosing quote markers from strings, converts numbers, checks variable memory references, and prints the result cleanly to the console.  
  *Syntax:* `Show ”Hello, World!”` or `Show a`
* **`Wait [seconds]`**  
  Pauses the script execution stream for an integer or floating-point duration. Generates a high-contrast red error message if the parameter value is non-numeric.  
  *Syntax:* `Wait 1.5`
* **`Speak [string / variable]`**  
  Hooks directly into your machine's hardware sound drivers to speak a line of text or variable value out loud natively using offline speech synthesis.  
  *Syntax:* `Speak ”Automation sequence initiated”`
* **`Notify ”[Title]” ”[Message]”`**  
  Uses a token slice delimiter to push a real, native desktop notification toast banner into the system screen space. Requires both parameters to be wrapped in double quotes.  
  *Syntax:* `Notify ”NEXUS Core” ”Task Completed Successfully”`

### 3. File & Storage Operations
* **`Create [filename]`**  
  Safely generates an empty file inside your active working workspace folder if it doesn't already exist.  
  *Syntax:* `Create log.txt`
* **`Write [filename] [string]`**  
  Completely overwrites a file with a fresh text payload, wiping any trailing historical characters out of the file buffer.  
  *Syntax:* `Write log.txt ”Initial Payload”`
* **`MuteWrite [filename] [Line / NewLine] [string]`**  
  Appends text data onto the end of a file. Use `Line` to paste characters on the active row, or `NewLine` to prefix a line break.  
  *Syntax:* `MuteWrite log.txt NewLine ”Appended system note.”`
* **`Truncate [filename]`**  
  Instantly clears and zeroes out all data content inside a document without dropping the file pointer from your storage.  
  *Syntax:* `Truncate log.txt`
* **`Delete [filename]`**  
  Hard-drops and permanently removes a targeted file path from your computer disk storage.  
  *Syntax:* `Delete obsolete.txt`
* **`Rename [old_filename] [new_filename]`**  
  Modifies the naming characteristics of a target file path in-place.  
  *Syntax:* `Rename records.txt old_records.txt`
* **`Copy [source_path] [destination_path]`**  
  Clones a localized file into a fresh directory lane safely.  
  *Syntax:* `Copy data.txt backup_data.txt`
* **`Move [filename] [directory_folder]`**  
  Relocates an asset file out of your active workspace directory and paths it into a target folder directory.  
  *Syntax:* `Move log.txt BackupsFolder`
* **`SizeOf [unit] [filename]`**  
  Uses match-case pattern mapping to calculate file weights into human-readable scales including `bytes`, `kb`, `mb`, `gb`, `tb`, `pb`, and `eb`.  
  *Syntax:* `SizeOf mb archive.zip`
* **`Backup [filename]`**  
  Creates an automated timestamped duplicate copy of the target file for recovery purposes (e.g., `data_20260624_161022.txt`).  
  *Syntax:* `Backup data.txt`

### 4. Directory Management
* **`MakeDir [base_directory] [new_folder_name]`**  
  Joins variables securely to deploy a new nested workspace directory folder.  
  *Syntax:* `MakeDir . ”BackupsFolder”`
* **`DelDir [directory_path]`**  
  Flashes an engine warning prompt asking for explicit terminal confirmation (`yes/no`) before wiping a directory.  
  *Syntax:* `DelDir BackupsFolder`

### 5. Application Control & Cryptography
* **`Run [command]`**  
  Asynchronously spawns independent system application processes or command lines without freezing your main interpreter loop.  
  *Syntax:* `Run notepad.exe`
* **`Open [filename]`**  
  Launches a text document natively inside the operating system's standard text editor (Notepad).  
  *Syntax:* `Open hello.txt`
* **`Browse [URL]`**  
  Triggers your default web browser tool to spin open and target a live web URL natively.  
  *Syntax:* `Browse https://lpu.in`
* **`Progress [seconds]`**  
  Renders an active graphical loading progress tracking bar loop (`[fifififi......]`) directly across the terminal row workspace console over X seconds.  
  *Syntax:* `Progress 5`
* **`Compress [folder_or_file_path]`**  
  Packages an independent text file into a `.zip` file archive, or directories using standard system zip-archive frameworks.  
  *Syntax:* `Compress ”MyProjectFolder”`
* **`Extract [source_archive.zip] [destination_folder]`**  
  Extracts compressed zip archives directly into a targeted folder destination directory path.  
  *Syntax:* `Extract archive.zip ExtractedFiles`
* **`SystemInfo`**  
  Pulls operational machine configurations, including kernel type, operating system version, processor architecture, and host network identity node parameters.  
  *Syntax:* `SystemInfo`
* **`Encrypt [filename]`**  
  Recursively strips newline markers, processes file lines through a custom hashing substitution module, and overwrites with the scrambled hash text payload.  
  *Syntax:* `Encrypt secrets.txt`
* **`Decrypt [filename]`**  
  Reverses encrypted files back into natural readable text using an advanced forward lookup reverse hashing transformation module.  
  *Syntax:* `Decrypt secrets.txt`

---

## 🛠️ Example Automation Script (`main.nxs`)

```text
# Boot diagnostic evaluation sequences
SystemInfo
Wait 1

# Variable manipulation
Set target_file = ”telemetry.txt”
Set delay_timer = 2

# Manage files dynamically using dynamic variable parameters
Create telemetry.txt
Write telemetry.txt ”NEXUS Automation Runtime Engine”
MuteWrite telemetry.txt NewLine ”LPU Automated System Script Engine Baseline”

# Output results and notify desktop environment
Show target_file
Wait delay_timer
Encrypt telemetry.txt
Speak ”Process framework executed cleanly”
Notify ”NEXUS Status” ”Automation routine finished structural processing.”
```
