@serenity-js/core/lib/io/format.js

The core Serenity/JS framework, providing the Screenplay Pattern interfaces, as well as the test reporting and integration infrastructure

"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
exports.d = exports.f = void 0;
exports.format = format;
const stringified_1 = require("./stringified");
/**
 * `format` is a factory function returning
 * a [tag function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#Tagged_template_literals)
 * that produces a human-readable `string` description of a template containing
 * one or more [answerables](https://serenity-js.org/api/core/#Answerable).
 *
 * Typically, you'll want to use `d` and `f` shorthands instead, or the modern alternative - `the`:
 * - the [`d`](https://serenity-js.org/api/core/function/d/) function works best for generating a **static description** of a parameterised [`Activity`](https://serenity-js.org/api/core/class/Activity/)
 * - the [`f`](https://serenity-js.org/api/core/function/f/) function is better suited for debugging
 * - the [`the`](https://serenity-js.org/api/core/function/f/) function works best for generating a **dynamic description** of a parameterised [`Activity`](https://serenity-js.org/api/core/class/Activity/)
 *
 * :::tip Use `the` instead of `format`
 * `format`, `d` and `f` are the original Serenity/JS string formatting functions,
 * still present in the framework for backwards compatibility purposes.
 *
 * To generate a dynamic description of a `Question` or `Interaction`,
 * use [`the`](https://serenity-js.org/api/core/function/the/) function instead.
 * :::
 *
 * ## Using `format`
 *
 * ```ts
 * import { format, Question } from '@serenity-js/core'
 *
 * const someQuestion = () =>
 *   Question.about('some question', actor => 'some value')
 *
 * format({ markQuestions: true }) `actor answers ${ question() }`
 *  // returns: actor answers <<some question>>
 *
 * format({ markQuestions: false }) `actor answers ${ question() }`
 *  // returns: actor answers some question
 * ```
 *
 * ## Using `d`
 *
 * ```ts
 * import { d, Question } from '@serenity-js/core'
 *
 * const someQuestion = () =>
 *   Question.about('some question', actor => 'some value')
 *
 * d`actor answers ${ question() }`
 *  // returns: actor answers <<some question>>
 * ```
 *
 * ## Using `f`
 *
 * ```ts
 * import { f, Question } from '@serenity-js/core'
 *
 * const someQuestion = () =>
 *   Question.about('some question', actor => 'some value')
 *
 * f`actor answers ${ question() }`
 *  // returns: actor answers <<some question>>
 *
 * format({ markQuestions: false }) `actor answers ${ question() }`
 *  // returns: actor answers <<some question>>
 * ```
 *
 * @param config
 *  `markQuestions`: boolean - if set to true, descriptions of questions passed in as arguments will be surrounded with double angled brackets, i.e. `<<description>>`
 *
 * @group Questions
 */
function format(config) {
    return (templates, ...placeholders) => {
        return templates
            .map((template, i) => i < placeholders.length
            ? [template, (0, stringified_1.stringified)(placeholders[i], { inline: true, markQuestions: config.markQuestions })]
            : [template])
            .reduce((acc, tuple) => acc.concat(tuple), [])
            .join('');
    };
}
/** @group Questions */
exports.f = format({ markQuestions: true });
/** @group Questions */
exports.d = format({ markQuestions: false });
//# sourceMappingURL=format.js.map