Metadata-Version: 2.4
Name: nexus-dsl
Version: 1.0.0
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 [Example 4].

Developed as a breakthrough milestone during the First-Year Passed Industrial Training 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
```

*(Note: If the name 'nexus' is already reserved on PyPI, it is standard convention to register it as `nexus-dsl` or `nexus-runtime` while keeping the package import name as `nexus`.)*

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

---

## 💻 Python Integration API

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

```python
from nexus import nexus

# Simply pass the path of your .nxs script file to the core execution engine
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 double quotes (`"..."`).

### 1. Console Operations & Core Logging
* **`Show [string]`**  
  Strips enclosing quote markers and prints clean string characters directly onto the active console view.  
  *Syntax:* `Show "Hello, World!"`
* **`Wait [seconds]`**  
  Pauses the script execution stream for an integer or floating-point timeline duration. Generates a high-contrast red error message if the parameter value is non-numeric.  
  *Syntax:* `Wait 1.5`
* **`Speak [string]`**  
  Hooks directly into your machine's hardware sound drivers to speak a line of text 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"`

### 2. 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 pattern matching (`match-case`) to convert 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_20260616_161022.txt`).  
  *Syntax:* `Backup data.txt`

### 3. 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`

### 4. Application Control & Cryptography
* **`Run [executable.exe]`**  
  Asynchronously spawns independent system application processes (like `notepad.exe`) 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 (`[██████░░░░]`) directly across the terminal row workspace console over X seconds.  
  *Syntax:* `Progress 5`
* **`Compress [folder_or_file_path]`**  
  Packages an independent text file or an entire nested directory workspace into a compressed binary `.zip` archive payload.  
  *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 proprietary substitution cipher dictionary matrix, 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 character window scanner module.  
  *Syntax:* `Decrypt secrets.txt`

---

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

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

# Manage backup files
Create telemetry.txt
Write telemetry.txt "NEXUS Automation Runtime"
MuteWrite telemetry.txt NewLine "LPU Industrial Passed First Year Assessment"
SizeOf kb telemetry.txt

# Run background applications and secure records
Run notepad.exe
Encrypt telemetry.txt
Speak "Process framework executed cleanly"
Notify "NEXUS" "Automation routine finished."
```
