opstring v0.5.1

OpString

OpString is a JavaScript module for mapping and executing operations represented by character sequences.

Table of Contents

• Introduction
• Getting Started
• Usage
• Error Handling
• API
• Contributing
• License

Introduction

OpString simplifies the process of mapping characters to operations and values, and provides functionality to compose character sequences and execute the respective mapped operations.

OpString is particularly useful in scenarios where data saving is crucial. By representing operations using compact character sequences, OpString enables you to pack more functionality into less data, optimizing storage efficiency.

For example, let's say you have the operations circle(30, 30, 20) and rect(30, 20, 55, 55) that you would like to store as a string for later use. Your string could look something like this circle(30,30,20);rect(30,20,55,55) and would be 34 characters long. With OpString you could represent the same operations with the character sequence AaabBabcc, which would shorten it to 9 characters.

Getting Started

Using a bundler

Install OpString using npm:

npm install opstring

Import OpString into your project using the import statement.

import OpString from 'opstring';

Without a bundler

Download the latest version from Releases.

Import OpString into your project using the import statement, referencing opstring.js.

// app.js

import OpString from 'opstring.js';

Make sure that the <script> tag, which embeds the JavaScript file containing the import of OpString, has the attribute type="module".

<script src="app.js" type="module"></script>

Usage

When using OpString, there are mainly three steps involved: 1. Register operations and values 2. Compose character sequence 3. Execute character sequence

OpString provides flexibility in managing these steps. Below, you will find two approaches for using OpString, which can be combined as needed.

Approach 1: Define Everything When Creating the OpString Instance

With this approach, you register operations and values, and specify the character sequence when creating the OpString instance.

// Create a new instance and configure it with initial settings
const opString = new OpString({
    sequence: 'AaabBabcc',
    operations: {
        'A': (x, y, d) => { console.log(x, y, d); },
        'B': (x, y, w, h) => { console.log(x, y, w, h); },
    },
    values: {
        'a': 30,
        'b': 20,
        'c': 55,
    },
    labels: {
        'circle': 'A',
        'rect': 'B',
    },
    maxSequenceLength: 10,
    ignoreWarnings: false, // (default: false)
    strictMode: true, // (default: false)
});

// Execute the sequence 'AaabBabcc'
opString.execute();

// Execute a custom sequence
opString.execute('Babcc');

Note: The properties ignoreWarnings and strictMode can only be configured when creating an OpString instance. (see Error Handling)

Approach 2: Register Operations and Values as Needed

With this approach, you start with an empty OpString instance and register operations and values as needed. Then, you compose the character sequence by appending, inserting, prepending and removing operations and their corresponding values.

// Create an empty OpString instance
const opString = new OpString();

// Set the maximum sequence length
opString.setMaxSequenceLength(10);

// Register operations
opString.registerOperation('A', (x, y, d) => { console.log(x, y, d); });
opString.registerOperation('B', (x, y, w, h) => { console.log(x, y, w, h); });
// Alternatives: `registerOperations` and `setOperations`

// Register values
opString.registerValue('a', 30);
opString.registerValue('b', 20);
opString.registerValue('c', 55);
// Alternatives: `registerValues` and `setValues`

// Register labels
opString.registerLabel('circle', 'A');
opString.registerLabel('twenty', 'b');
// Alternatives: `registerLabels` and `setLabels`

// Get symbols for values
const char = opString.getCharForValue(55); // Returns: 'c'
const charCode = opString.getCharCodeForValue(55); // Returns: 99

// Get symbols for labels
const labelChar = opString.getCharForLabel('circle'); // Returns: 'A'
const labelCharCode = opString.getCharCodeForLabel('circle'); // Returns: 65

// Compose the character sequence
opString.append('A', ['a', 'a', 'b']);
opString.append('B', ['a', 'b', 'c', 'c']);
// Alternative: `setSequence`

// Insert an operation at a specific position
const operationId = opString.insert(1, 'X', ['x', 'y', 'z']);

console.debug(opString.getSequence());
// Expected output: 'AaabXxyzBabcc'

// Remove an operation by its id
opString.remove(operationId);

console.debug(opString.getSequence());
// Expected output: 'AaabBabcc'

// Execute the composed sequence
opString.execute();

// Execute a custom sequence
opString.execute('Babcc');

Error Handling

OpString aims to handle errors gracefully, providing warnings without interrupting its functionality.

ignoreWarnings

To ignore warnings, you can set ignoreWarnings to true when creating an OpString instance. When ignoreWarnings is true and errors occur, warnings will not be logged to the console.

// Create an OpString instance and ignore warnings
const opString = new OpString({
    ignoreWarnings: true, // (default: false)
});

strictMode

To enable strictMode, you can set strictMode to true when creating an OpString instance.

In strictMode OpString will log errors instead of warnings to the console. Furthermore, OpString will not be as graceful anymore and certain functionalities like setSequence or execute will not work when errors occur, such as exceeding the maxSequenceLength limit.

// Create an OpString instance with `strictMode` enabled
const opString = new OpString({
    strictMode: true, // (default: false)
});

Note: In strictMode the ignoreWarnings property is irrelevant as warnings are never logged.

API

Note: OpString is still in the initial development phase and the API can still change. Always review the release notes.

OpString exposes the following properties and methods:

Properties

Examples

// Access the version of OpString
console.log(opString.version);

// Output: '0.5.1'

Methods

Examples

// Create an empty OpString instance
const opString = new OpString();

// Create an OpString instance and enable `strictMode`
const opString = new OpString({
    strictMode: true, // (default: false)
});

// Create a new instance and configure it with initial settings
const opString = new OpString({
    sequence: 'AaabBabcc',
    operations: {
        'A': (x, y, d) => { console.log(x, y, d); },
        'B': (x, y, w, h) => { console.log(x, y, w, h); },
    },
    values: {
        'a': 30,
        'b': 20,
        'c': 55,
    },
    labels: {
        'circle': 'A',
        'rect': 'B',
    },
    maxSequenceLength: 10,
    ignoreWarnings: false, // (default: false)
    strictMode: true, // (default: false)
});

Parameters

Examples

// Get the next operation id
const nextId = opString.getNextId();

// Example output: 3

Returns

number - The next operation id

Examples

// Append an operation to the sequence and return its id
const operationId = opString.append('V');

// Specify the values to be passed to the operation. This will append 'Aaab' to the sequence.
opString.append('A', ['a', 'a', 'b']);

/**
 * Alternatively, you can use character codes instead of characters (e.g. 'A'.charCodeAt(0) => 65).
 * This will also append 'Aaab' to the sequence.
 */
opString.append(65, [97, 97, 98]);

Parameters

Returns

number|boolean - The id of the appended operation or false if the operation wasn't appended.

Examples

/**
 * Insert an operation at index 2 of the operations to be executed and returns 
 * its id. The operation will be the third one to be executed.
 */
const operationId = opString.insert(2, 'V');

/**
 * Specify the values to be passed to the operation.
 * 
 * The following example inserts the operation 'Aaab' at index 2 of the
 * operations to be executed, making it the third operation to be executed.
 */
opString.insert(2, 'A', ['a', 'a', 'b']);

/**
 * Alternatively, you can use character codes instead of characters (e.g. 'A'.charCodeAt(0) => 65).
 * This will also insert 'Aaab' at index 2 of the sequence.
 */
opString.insert(2, 65, [97, 97, 98]);

Parameters

Returns

number|boolean - The id of the inserted operation or false if the operation wasn't inserted.

Examples

// Prepend an operation to the sequence and return its id
const operationId = opString.prepend('V');

// Specify the values to be passed to the operation. This will prepend 'Aaab' to the sequence.
opString.prepend('A', ['a', 'a', 'b']);

/**
 * Alternatively, you can use character codes instead of characters (e.g. 'A'.charCodeAt(0) => 65).
 * This will also prepend 'Aaab' to the sequence.
 */
opString.prepend(65, [97, 97, 98]);

Parameters

Returns

number|boolean - The id of the prepended operation or false if the operation wasn't prepended.

Examples

// Remove operation with id 3 from the sequence
const removed = opString.remove(3);

Parameters

Returns

boolean - If the respective operation was removed true, otherwise false.

Examples

// Get the index of operation with id 3 in the sequence
const operationIndex = opString.index(3);

Parameters

Returns

number|undefined - Index of the operation in the sequence, or undefined if not found.

Examples

// Set the character sequence
opString.setSequence('AaabBabcc');

/**
 * Handling an unknown value character
 *
 * Suppose the sequence is 'Ba?c'. The '?' represents an unknown value character.
 * In this case, the unknown character will be registered with a value of `null`.
 * By registering it this way, the associated operation can still be executed.
 */
opString.setSequence('Ba?c');

Parameters

Examples

// Get the character sequence
const sequence = opString.getSequence();

// Example output: 'AaabBabcc'

Returns

string - The character sequence.

Examples

// Get the sequence data array
const sequenceData = opString.getSequenceData();

// Example output for sequence 'AaabBabcc':
// [
//   { id: 1, operation: 65, values: [ 97, 97, 98 ] },
//   { id: 2, operation: 66, values: [ 97, 98, 99, 99 ] }
// ]

Returns

Array<Object> - The sequence data array

Examples

// Register an operation mapping
opString.registerOperation('X', () => console.log('Operation X'));

// Register an operation mapping using character code
opString.registerOperation(88, () => console.log('Operation X'));

Parameters

Examples

// Register additional operation mappings
opString.registerOperations({
    'D': () => { /*...*/ },
    'E': () => { /*...*/ },
    'F': () => { /*...*/ },
});

// Register additional operation mappings using chracter codes
opString.registerOperations({
    68: () => { /*...*/ },
    69: () => { /*...*/ },
    70: () => { /*...*/ },
});

Parameters

Examples

// Set new operation mappings
opString.setOperations({
    'A': () => { /*...*/ },
    'B': () => { /*...*/ },
    'C': () => { /*...*/ },
});

Parameters

Examples

// Get the registered operations
const operations = opString.getOperations();

// Example output:
// { '65': [Function: A], '66': [Function: B] }

Returns

Object - The registered operations

Examples

// Register a value mapping
opString.registerValue('x', 10);

// Register a value mapping using character code
opString.registerValue(120, 10);

Parameters

Examples

// Register additional value mappings
opString.registerValues({
    'x': 10,
    'y': 11,
    'z': 12,
});

// Alternatively, you can register additional value mappings using character codes
opString.registerValues({
    120: 10,
    121: 11,
    122: 12,
});

Parameters

Examples

// Set new value mappings
opString.setValues({
    'a': 1,
    'b': 2,
    'c': 3,
});

// Alternatively, you can set new value mappings using character codes
opString.setValues({
    97: 1,
    98: 2,
    99: 3,
});

Parameters

Examples

// Get the registered values
const values = opString.getValues();

// Example output:
// { '97': 30, '98': 20, '99': 55 }

Returns

Object - The registered values.

Examples

// Get the corresponding character for the provided value
const char = opString.getCharCodeForValue(55);

// Example output: 'c'

Parameters

Returns

string|undefined - If the value is registered, the corresponding character is returned; otherwise undefined.

Examples

// Get the corresponding charCode for the provided value
const charCode = opString.getCharCodeForValue(55);

// Example output: 99

Parameters

Returns

number|undefined - If the value is registered, the corresponding character code is returned; otherwise undefined.

Examples

// Register a label mapping
opString.registerLabel('circle', 'A');

// Register a label mapping using character code
opString.registerLabel('circle', 65);

Parameters

Examples

// Register additional label mappings
opString.registerLabels({
    'circle': 'A',
    'rect': 'B',
    'ten': 'x',
});

// Alternatively, you can register additional label mappings using character codes
opString.registerLabels({
    'circle': 65,
    'rect': 66,
    'ten': 120,
});

Parameters

Examples

// Set new label mappings
opString.setLabels({
    'circle': 'A',
    'rect': 'B',
    'ten': 'x',
});

// Alternatively, you can set new label mappings using character codes
opString.setLabels({
    'circle': 65,
    'rect': 66,
    'ten': 120,
});

Parameters

Examples

// Get the registered labels
const labels = opString.getLabels();

// Example output:
// { 'circle': 65, 'rect': 66, 'ten': 120 }

Returns

Object - The registered labels.

Examples

// Get the corresponding character for the provided label
const char = opString.getCharCodeForLabel('circle');

// Example output: 'A'

Parameters

Returns

string|undefined - If the label is registered, the corresponding character is returned; otherwise undefined.

Examples

// Get the corresponding charCode for the provided label
const charCode = opString.getCharCodeForLabel('circle');

// Example output: 65

Parameters

Returns

number|undefined - If the label is registered, the corresponding character code is returned; otherwise undefined.

Examples

// Set the maximum sequence length to 100
opString.setMaxSequenceLength(100);

Parameters

Examples

// Get the max sequence length
const maxSequenceLength = opString.getMaxSequenceLength();

// Example output, if configured: 100

// Output, if not configured: undefined

Returns

number|undefined - The configured maxSequenceLength value, or undefined if not configured.

Examples

// Execute the character sequence of the current instance
opString.execute();

// Execute a provided character sequence
opString.execute('XxxyYxyzz');

Parameters

Contributing

Are you considering contributing to OpString? Check out our contributing guidelines.

License

OpString is MIT licensed.