bscript-cli 1.0.0

package/Docs/REFERENCE.md

@@ -0,0 +1,602 @@
+# API Reference
+
+Here are described all **public** modules, classes, functions, constants, and other exported declarations available for developers.
+
+---
+
+## Guide
+
+<details>
+<summary>BScript</summary>
+
+## Parent
+[BScript.BScript](#BScriptBScript)
+
+### Constants
+- [perrmissionsKeys](#BScriptBScriptperrmissionsKeys)
+
+### Properties
+- [cmdRootPermissions](#BScriptBScriptcmdRootPermissions)
+- [commandHistory](#BScriptBScriptcommandHistory)
+- [returnCode](#BScriptBScriptreturnCode)
+
+### Methods
+- [bscript()](#BScriptBScriptbscript)
+- [Start()](#BScriptBScriptStart)
+- [updateCommands()](#BScriptBScriptupdateCommands)
+- [createCommand()](#BScriptBScriptcreateCommand)
+- [executeCommand()](#BScriptBScriptexecuteCommand)
+
+</details>
+
+<details>
+<summary>TerminalCommandController</summary>
+
+## Parent
+[TerminalCommandController.TerminalCommandController](#TerminalCommandControllerTerminalCommandController)
+
+### Methods
+- [ClearConsole()](#TerminalCommandControllerClearConsole)
+- [InitInput()](#TerminalCommandControllerInitInput)
+- [Write()](#TerminalCommandControllerWrite)
+- [Print()](#TerminalCommandControllerPrint)
+- [SetStdinListener()](#TerminalCommandControllerSetStdinListener)
+- [RemoveStdinListener()](#TerminalCommandControllerRemoveStdinListener)
+
+</details>
+
+---
+
+## Modules
+
+<a id="BScriptBScript"></a>
+
+## BScript.BScript
+
+### Opportunities
+
+- Create interactive CLI applications with minimal setup
+- Implement role-based command access control
+- Build extensible command systems with dynamic loading
+- Execute scripts with custom sandboxed contexts
+- Manage command history and navigation
+
+### Declaration
+
+```javascript
+class BScript extends EventEmitter
+```
+
+BScript is the main class for creating interactive command-line interfaces. It extends Node.js EventEmitter, allowing you to listen to and emit custom events. Use it to manage commands, control permissions, handle script execution, and interact with users through the terminal.
+
+---
+
+## Constants
+
+<table>
+<thead>
+<tr>
+<td>
+<h4>About Constant</h4>
+</td>
+<td>
+<h4>Example</h4>
+</td>
+</tr>
+</thead>
+
+<tbody>
+
+<a id="BScriptBScriptperrmissionsKeys"></a>
+
+<tr>
+<td width="70%">
+
+<h5>perrmissionsKeys</h5>
+
+```javascript
+const perrmissionsKeys = {
+  default: 0,
+  script: 999
+}
+```
+
+Predefined permission levels used for command access control. `default` (0) is for normal user commands, while `script` (999) is for high-privilege script execution contexts.
+
+</td>
+
+<td width="30%">
+<pre><code>
+const cmd = new BScript();
+console.log(cmd.perrmissionsKeys.default);
+// Output: 0
+console.log(cmd.perrmissionsKeys.script);
+// Output: 999
+</code></pre>
+</td>
+
+</tr>
+
+</tbody>
+</table>
+
+---
+
+## Properties
+
+<table>
+<thead>
+<tr>
+<td>
+<h4>About Property</h4>
+</td>
+<td>
+<h4>Example</h4>
+</td>
+</tr>
+</thead>
+
+<tbody>
+
+<a id="BScriptBScriptcmdRootPermissions"></a>
+
+<tr>
+<td width="70%">
+
+<h5>cmdRootPermissions</h5>
+
+```javascript
+cmd.cmdRootPermissions
+```
+
+An array of permission levels that determine which commands are available in the current context. Modify this array to control access to commands based on user roles.
+
+</td>
+
+<td width="30%">
+<pre><code>
+const cmd = new BScript();
+cmd.cmdRootPermissions = [
+  cmd.perrmissionsKeys.default
+];
+cmd.updateCommands();
+</code></pre>
+</td>
+
+</tr>
+
+<a id="BScriptBScriptcommandHistory"></a>
+
+<tr>
+<td width="70%">
+
+<h5>commandHistory</h5>
+
+```javascript
+cmd.commandHistory
+```
+
+An array containing the history of executed commands. Persisted across sessions and navigable during interactive mode using arrow keys.
+
+</td>
+
+<td width="30%">
+<pre><code>
+const cmd = new BScript();
+cmd.Start();
+// After executing commands, access history:
+console.log(cmd.commandHistory);
+</code></pre>
+</td>
+
+</tr>
+
+<a id="BScriptBScriptreturnCode"></a>
+
+<tr>
+<td width="70%">
+
+<h5>returnCode</h5>
+
+```javascript
+cmd.returnCode
+```
+
+Current return code of the script execution (-1 = loading, 1 = ready, other = error). Used to track the state of async operations.
+
+</td>
+
+<td width="30%">
+<pre><code>
+const cmd = new BScript();
+cmd.loader(async (done) => {
+  // When done, returnCode becomes 1
+  done();
+});
+</code></pre>
+</td>
+
+</tr>
+
+</tbody>
+</table>
+
+---
+
+## Methods
+
+<table>
+<thead>
+<tr>
+<td>
+<h4>About Method</h4>
+</td>
+<td>
+<h4>Example</h4>
+</td>
+</tr>
+</thead>
+
+<tbody>
+
+<a id="BScriptBScriptbscript"></a>
+
+<tr>
+<td width="70%">
+
+<h5>bscript()</h5>
+
+```javascript
+bscript(scriptCode)
+```
+
+Parses and returns an executable function for the given script code. Supports inline execution of BScript code. The returned function can be immediately invoked with `()`.
+
+</td>
+
+<td width="30%">
+<pre><code>
+const cmd = new BScript();
+cmd.cmdRootPermissions = [
+  cmd.perrmissionsKeys.default,
+  cmd.perrmissionsKeys.script
+];
+cmd.updateCommands();
+
+const scriptFn = cmd.bscript(
+  'echo "Hello World"'
+);
+scriptFn();
+</code></pre>
+</td>
+
+</tr>
+
+<a id="BScriptBScriptStart"></a>
+
+<tr>
+<td width="70%">
+
+<h5>Start()</h5>
+
+```javascript
+Start()
+```
+
+Initializes and starts the interactive command-line interface. Displays the command prompt and listens for user input. Commands are processed and executed in real-time.
+
+</td>
+
+<td width="30%">
+<pre><code>
+const cmd = new BScript();
+cmd.cmdRootPermissions = [
+  cmd.perrmissionsKeys.default
+];
+cmd.updateCommands();
+
+cmd.Start();
+// Interactive mode begins
+</code></pre>
+</td>
+
+</tr>
+
+<a id="BScriptBScriptupdateCommands"></a>
+
+<tr>
+<td width="70%">
+
+<h5>updateCommands()</h5>
+
+```javascript
+updateCommands()
+```
+
+Scans command directories and loads all command files. Respects permission settings and filters commands accordingly. Call this after changing permissions or adding new command files.
+
+</td>
+
+<td width="30%">
+<pre><code>
+const cmd = new BScript({
+  commandsPaths: [
+    './my-commands'
+  ]
+});
+
+cmd.cmdRootPermissions = [
+  cmd.perrmissionsKeys.default
+];
+
+cmd.updateCommands();
+</code></pre>
+</td>
+
+</tr>
+
+<a id="BScriptBScriptcreateCommand"></a>
+
+<tr>
+<td width="70%">
+
+<h5>createCommand()</h5>
+
+```javascript
+createCommand({
+  name,
+  execute,
+  description,
+  syntax
+})
+```
+
+Registers a new command in the system. Typically called internally when loading commands, but can be used to programmatically add commands at runtime.
+
+</td>
+
+<td width="30%">
+<pre><code>
+const cmd = new BScript();
+
+cmd.createCommand({
+  name: 'greet',
+  execute: (args) => {
+    console.log(`Hello, ${args[0]}!`);
+  },
+  description: 'Greet a user',
+  syntax: 'greet [name]'
+});
+</code></pre>
+</td>
+
+</tr>
+
+<a id="BScriptBScriptexecuteCommand"></a>
+
+<tr>
+<td width="70%">
+
+<h5>executeCommand()</h5>
+
+```javascript
+executeCommand(commandString)
+```
+
+Parses and executes a command string. Handles command routing, argument passing, and output. Called automatically during interactive mode.
+
+</td>
+
+<td width="30%">
+<pre><code>
+const cmd = new BScript();
+cmd.cmdRootPermissions = [
+  cmd.perrmissionsKeys.default
+];
+cmd.updateCommands();
+
+cmd.executeCommand('help');
+</code></pre>
+</td>
+
+</tr>
+
+</tbody>
+</table>
+
+---
+
+<a id="TerminalCommandControllerTerminalCommandController"></a>
+
+## TerminalCommandController.TerminalCommandController
+
+### Declaration
+
+```javascript
+class TerminalCommandController
+```
+
+Handles low-level terminal I/O operations. Manages cursor positioning, text output, input handling, and terminal formatting. Works closely with BScript to provide the interactive interface experience.
+
+---
+
+## Methods
+
+<table>
+<thead>
+<tr>
+<td>
+<h4>About Method</h4>
+</td>
+<td>
+<h4>Example</h4>
+</td>
+</tr>
+</thead>
+
+<tbody>
+
+<a id="TerminalCommandControllerClearConsole"></a>
+
+<tr>
+<td width="70%">
+
+<h5>ClearConsole()</h5>
+
+```javascript
+ClearConsole()
+```
+
+Clears the entire terminal screen and resets the cursor to the top-left position.
+
+</td>
+
+<td width="30%">
+<pre><code>
+const cmd = new BScript();
+cmd.commandController.ClearConsole();
+</code></pre>
+</td>
+
+</tr>
+
+<a id="TerminalCommandControllerInitInput"></a>
+
+<tr>
+<td width="70%">
+
+<h5>InitInput()</h5>
+
+```javascript
+InitInput(rawMode)
+```
+
+Initializes stdin for raw input mode. Set `rawMode` to `true` for character-by-character input, `false` for line-based input.
+
+</td>
+
+<td width="30%">
+<pre><code>
+const cmd = new BScript();
+cmd.commandController
+  .InitInput(true);
+</code></pre>
+</td>
+
+</tr>
+
+<a id="TerminalCommandControllerWrite"></a>
+
+<tr>
+<td width="70%">
+
+<h5>Write()</h5>
+
+```javascript
+Write(text)
+```
+
+Writes text to stdout without a newline. Useful for prompts and inline output.
+
+</td>
+
+<td width="30%">
+<pre><code>
+const cmd = new BScript();
+cmd.commandController
+  .Write("Enter command: ");
+</code></pre>
+</td>
+
+</tr>
+
+<a id="TerminalCommandControllerPrint"></a>
+
+<tr>
+<td width="70%">
+
+<h5>Print()</h5>
+
+```javascript
+Print(...text)
+```
+
+Prints one or more values to stdout with automatic formatting. Equivalent to `console.log()`.
+
+</td>
+
+<td width="30%">
+<pre><code>
+const cmd = new BScript();
+cmd.commandController
+  .Print("Command executed", 42);
+</code></pre>
+</td>
+
+</tr>
+
+<a id="TerminalCommandControllerSetStdinListener"></a>
+
+<tr>
+<td width="70%">
+
+<h5>SetStdinListener()</h5>
+
+```javascript
+SetStdinListener(eventName, callback)
+```
+
+Registers an event listener on stdin for the specified event. Useful for custom input handling.
+
+</td>
+
+<td width="30%">
+<pre><code>
+const cmd = new BScript();
+cmd.commandController
+  .SetStdinListener('data', (chunk) => {
+    console.log("Input:", chunk);
+  });
+</code></pre>
+</td>
+
+</tr>
+
+<a id="TerminalCommandControllerRemoveStdinListener"></a>
+
+<tr>
+<td width="70%">
+
+<h5>RemoveStdinListener()</h5>
+
+```javascript
+RemoveStdinListener(eventName, callback)
+```
+
+Removes a previously registered stdin event listener.
+
+</td>
+
+<td width="30%">
+<pre><code>
+const cmd = new BScript();
+const handler = (chunk) => {
+  console.log("Input:", chunk);
+};
+cmd.commandController
+  .SetStdinListener('data', handler);
+  
+// Later:
+cmd.commandController
+  .RemoveStdinListener('data', handler);
+</code></pre>
+</td>
+
+</tr>
+
+</tbody>
+</table>
+
+---
+
+**Made with ❤️ for the Node.js ecosystem**