bds.js

bds.js

Run and simulate string-based BDScript language in JavaScript

Prerequisites

This project requires a JavaScript runtime which supports ES2020 and ESModules.

Changelog v1.1.1

Added / New

• Rewritten code for easy to use
• Reworked Context
• Reworked Lexer
• Reworked Parser
• Added Evaluator
• Added Runtime
• Fixed operator type breaks punctuations
• Readded some utility calls
• Added $async, $wait, $safejs, $if

Breaking

• Removed FNHandler
• Removed Script
• Removed Nodes

Table of Contents

• bds.js
  • Prerequisites
  • Changelog v1.1.1
    • Added / New
    • Breaking
  • Table of Contents
  • Installation
  • API & Usage
    • Example
    • Runtime
    • Evaluator
    • Context
    • Variables
    • Global Variables
  • Goals
  • MIT License

Installation

Install bds.js with npm:

$ npm install bds.js

or getting releases from github

API & Usage

Example

const lib = require('bds.js');
const runtime = new lib.Runtime();

const input = '$async[$swait $print[Hello world!]] This bottom text is async output!'
const result = runtime.runInput('helloWorld.bds', input);
result.then(output => console.log(output));

Runtime

v1.1 is using Runtime and Evaluator, different from v1.0 This approach is used for the reason; Runtime error and error tracing within code for easier debugging

const runtime = new lib.Runtime();
const input = "$print[Hello World!]";
// Running an input
runtime.runInput('myInput.js', input);

Evaluator

Currently v1.1 use Interpreter system which can impact the performance for large-scale productions. Later versions to be improved, can also be a change of system.

// Creating a AST
const input = "> This is the code$print[> Hello World!]"
const lexer = new lib.Lexer(input);
const parser = new lib.Parser();
const Ast = parser.parseToAst(lexer.main() /* Tokenizing input */) // Parsing tokens to AST

// Evaluating the AST as simple as possible
const evaluator = lib.Evaluator.singleton // One instance is for one process
const result = evaluator.evaluate(Ast) // Evaluating AST

// Printing the output of input
result.then(output => console.log(output))

Context

Context instance are usually used to handle functions in code

const env = new lib.Environment();
env.set('luckyfn', async (context) => {
  context.argsCheck(1); // Check if has required arguments (1), throws error if below from required
  const arguments = context.getArgs() // Getting arguments
  const minimum_chance = await context.evaluateArgs(arguments)[0] // Get the first argument of evaluated arguments
  // Calling other identifiers (Advanced use)
  const chance = await context.callIdentifier({type: "call", value: "$random"}) * 100;
  if (chance > minimum_chance) {
    return 'You are lucky!'
  } else {
    return 'A sad day for no luck...'
  }
});

Variables

In bds.js, variables are accessed from the Environment class instance

const os = require("node:os");
const env = new lib.Environment();
// Creating static variables
env.set('myname', 'Nivry'); // result in string
env.set('myage', 14); // result in number
env.set('mycats', ['Kitty', 'Rivi']) // result in array
env.set('totalmem', os.totalmem); // Run function
env.set('lowercase', async (ctx) => {
  ctx.argsCheck(1); // Built-in args check, automatically throws error if arguments size is below the required
  const arguments = ctx.getArgs();
  // Evaluate / Run the arguments beforehand
  const text = await ctx.evaluateArgs(arguments)[0] // The first compiled arg
  return text.toLowerCase();
});

Global Variables

Global variables are sourced from Runtime.global, allowing many codes to access the global environment while also keeping its own.

const runtime = new lib.Runtime();
runtime.global.set('$helloWorld', 'Hello World!');

Goals

• Usable
• Basic utility Functions (4%)
• Conditions / Logic support
• Arithmetic support
• Compile-able code to JavaScript
• Friendly-code for beginners
• Native code (JavaScript) support
• Import & Export
• Runtime Error
• Async promise support

MIT License

License can be found here