Contents

• About
• Install
• Usage
• Packages
• Codeophon

About

programmatic text provides an evaluation context to allow users to input a text containing {variables} which will be replaced after evaluation with the results of the user-input code.

Considering the following user text input

simple {example} with one variable

and the following user code input in javascript

const example = 'fake world example';

return {
    example,
};

will evaluate to the content

simple fake world example with one variable

Install

npm install @plurid/programmatic-text

or

yarn add @plurid/programmatic-text

Usage

The evaluation language of the code is by default javascript

import ProgrammaticText from '@plurid/programmatic-text';


const main = async () => {
    const programmaticText = new ProgrammaticText();

    const evaluated = await programmaticText.evaluate(
        // text
        'This happened {x} years ago, that means {y} days ago.',
        // code
        `
        const x = new Date().getFullYear() - 2000;
        const y = x * 365;

        return {
            x,
            y,
        };
        `,
    ));
}

and it can also be python

import ProgrammaticText from '@plurid/programmatic-text';


const main = async () => {
    const programmaticText = new ProgrammaticText({
        language: 'python',
    });

    const evaluated = await programmaticText.evaluate(
        // text
        'This happened {x} years ago, that means {y} days ago.',
        // code
        `
        from datetime import date

        x = date.today().year - 2000;
        y = x * 365;

        values = {
            'x': x,
            'y': y,
        }
        `,
    ));
}

For javascript the code must simply return an object where the keys are the variable names from the text.

For python the code must contain a values dictionary which will be used to resolve the text.

For python, ProgrammaticText will load at the first evaluate request or at the preload call the pyodide package from a CDN script.

Setting usePyodideCDN: false requires pyodide to be preloaded on window.programmaticTextPyodide, otherwise ProgrammaticText will attempt to dynamically import the pyodide package from node_modules.

// preload pyodide before using ProgrammaticText
const pyodide = await loadPyodide();
window.programmaticTextPyodide = pyodide;

const programmaticText = new ProgrammaticText({
    language: 'python',
    usePyodideCDN: false,
});

or

const programmaticText = new ProgrammaticText({
    language: 'python',
    usePyodideCDN: true, // default for `python`
});
await programmaticText.preload();

Constructor Options

interface ProgrammaticTextOptions {
    /**
     * The evaluation language.
     */
    language: 'javascript' | 'python';

    /**
     * The evaluation type when `language` is `javascript`.
     */
    type: 'function' | 'variable';

    /**
     * Load `pyodide` for `python` from CDN.
     *
     * Default `true`
     */
    usePyodideCDN: boolean;

    /**
     * Timeout for the code evaluation.
     */
    timeout: number;

    /**
     * Replace undefined variables with a certain string.
     */
    replaceUndefined: string | undefined;

    /**
     * Catch errors from the evaluation of the code.
     *
     * Default `__error__`
     */
    errorKey: string;

    logger: ((error: any) => void) | undefined;
}

Packages

@plurid/programmatic-text

Codeophon

• licensing: delicense
• versioning: αver