taraskevizer 7.1.1 → 8.0.0

package/dist/index.d.ts

@@ -1,3 +1,17 @@
+declare const cyrillic: {
+    readonly lower: readonly [];
+    readonly upper: readonly [];
+};
+
+declare const latin: {
+    lower: (readonly [RegExp, string])[];
+    upper: (readonly [RegExp, string])[];
+};
+declare const latinJi: {
+    lower: (readonly [RegExp, string])[];
+    upper: (readonly [RegExp, string])[];
+};
+
 declare const gobj: {
     readonly г: "ґ";
     readonly Г: "Ґ";
@@ -5,142 +19,239 @@ declare const gobj: {
     readonly Ґ: "Г";
 };
 
-declare const wordlist: (readonly [RegExp, string])[];
-
 type Dict<T = RegExp> = readonly (readonly [T, string])[];
+/**
+ * Useful if you want to modify the dictionary.
+ *
+ * Consider converting it to the type {@link Dict}
+ * if you no longer need to modify it.
+ */
 type WritableDict<T = RegExp> = [T, string][];
+/**
+ * useful if you use variables in patterns.
+ *
+ * Don't forget to convert it to the type {@link Dict},
+ * {@link lib.dictFrom} can help you with this.
+ */
 type RawDict = WritableDict<string | RegExp>;
 
+declare const wordlist: Dict;
+
 declare const noSoften: Dict;
 declare const softeners: Dict;
 
-declare const cyrillic: {
-    lower: never[];
-    upper: never[];
-};
-
-declare const latin: {
-    lower: (readonly [RegExp, string])[];
-    upper: (readonly [RegExp, string])[];
-};
-declare const latinJi: {
-    lower: (readonly [RegExp, string])[];
-    upper: (readonly [RegExp, string])[];
-};
+type index$3_Dict<T = RegExp> = Dict<T>;
+type index$3_RawDict = RawDict;
+type index$3_WritableDict<T = RegExp> = WritableDict<T>;
+declare const index$3_gobj: typeof gobj;
+declare const index$3_noSoften: typeof noSoften;
+declare const index$3_softeners: typeof softeners;
+declare const index$3_wordlist: typeof wordlist;
+declare namespace index$3 {
+  export { type index$3_Dict as Dict, type index$3_RawDict as RawDict, type index$3_WritableDict as WritableDict, index$2 as alphabets, index$3_gobj as gobj, index$3_noSoften as noSoften, index$3_softeners as softeners, index$3_wordlist as wordlist };
+}
 
 declare const arabic: {
     lower: Dict;
 };
 
-declare const index$3_arabic: typeof arabic;
-declare const index$3_cyrillic: typeof cyrillic;
-declare const index$3_latin: typeof latin;
-declare const index$3_latinJi: typeof latinJi;
-declare namespace index$3 {
-  export { index$3_arabic as arabic, index$3_cyrillic as cyrillic, index$3_latin as latin, index$3_latinJi as latinJi };
-}
-
+/**
+ * If {@link Alphabet.upper} in not defined,
+ * it is assumed that the alphabet is case-insensitive,
+ * so {@link Alphabet.lower} should replace both
+ * upper and lower case letters.
+ */
 type Alphabet = {
     lower: Dict;
     upper?: Dict;
 };
 
 type index$2_Alphabet = Alphabet;
-declare const index$2_gobj: typeof gobj;
-declare const index$2_noSoften: typeof noSoften;
-declare const index$2_softeners: typeof softeners;
-declare const index$2_wordlist: typeof wordlist;
+declare const index$2_arabic: typeof arabic;
+declare const index$2_cyrillic: typeof cyrillic;
+declare const index$2_latin: typeof latin;
+declare const index$2_latinJi: typeof latinJi;
 declare namespace index$2 {
-  export { type index$2_Alphabet as Alphabet, index$3 as alphabets, index$2_gobj as gobj, index$2_noSoften as noSoften, index$2_softeners as softeners, index$2_wordlist as wordlist };
+  export { type index$2_Alphabet as Alphabet, index$2_arabic as arabic, index$2_cyrillic as cyrillic, index$2_latin as latin, index$2_latinJi as latinJi };
 }
 
-type ModifyObjectType<T, TResultObj> = T extends object ? T extends (...args: any[]) => any ? T : TResultObj : T;
-type DeepPartialReadonly<T> = ModifyObjectType<T, {
-    readonly [P in keyof T]?: DeepPartialReadonly<T[P]>;
-}>;
-type OptionJ = 0 | 1 | 2;
-type Variation = 0 | 1 | 2;
+declare const REPLACE_J: {
+    readonly NEVER: 0;
+    readonly RANDOM: 1;
+    readonly ALWAYS: 2;
+};
+declare const VARIATION: {
+    readonly NO: 0;
+    readonly FIRST: 1;
+    readonly ALL: 2;
+};
+type ValueOf<T> = T[keyof T];
+type OptionJ = ValueOf<typeof REPLACE_J>;
+type Variation = ValueOf<typeof VARIATION>;
+
+type PartialReadonly<T> = {
+    readonly [P in keyof T]?: T[P];
+};
 type TaraskOptions = {
-    doEscapeCapitalized: boolean;
+    /**
+     * Any object that implements the {@link Alphabet} interface.
+     *
+     * The set of defined alphabets can be found in {@link dicts.alphabets}.
+     *
+     * @default alphabets.cyrillic
+     */
     abc: Alphabet;
+    /**
+     * | Value | When to replace `і`(`i`) by `й`(`j`) after vowels | Example                  |
+     * | ----- | ------------------------------------------------- | ------------------------ |
+     * |       |                                                   | `яна і ён`               |
+     * | 0     | never                                             | `яна і ён`               |
+     * | 1     | random                                            | `яна і ён` or `яна й ён` |
+     * | 2     | always                                            | `яна й ён`               |
+     *
+     * Has no effect with abc set to {@link dicts.alphabets.latinJi}.
+     *
+     * @default REPLACE_J.NEVER
+     */
     j: OptionJ;
+    /**
+     * If set to false, may cause unwanted changes in acronyms.
+     *
+     * @default true
+     */
+    doEscapeCapitalized: boolean;
 };
 type NonHtmlOptions = {
+    /** @default false */
     ansiColors: boolean;
+    /**
+     * Do replace ґ(g) by г(h) in cyrillic alphabet?
+     *
+     * | Value | Example     |
+     * | ----- | ----------- |
+     * | true  | Ґвалт ґвалт |
+     * | false | Гвалт гвалт |
+     *
+     * @default false
+     */
     h: boolean;
+    /**
+     * | Value | Which variation is used if a part of word is variable | Example           |
+     * | ----- | ----------------------------------------------------- | ----------------- |
+     * |       |                                                       | Гродна            |
+     * | 0     | main                                                  | Гродна            |
+     * | 1     | first                                                 | Горадня           |
+     * | 2     | all                                                   | (Гродна\|Горадня) |
+     *
+     * @default VARIATION.ALL
+     */
     variations: Variation;
 };
 type HtmlOptions = {
+    /**
+     * Do replace `г`(`h`) by `ґ`(`g`) in cyrillic alphabet?
+     *
+     * | Value | Example                                 |
+     * | ----- | --------------------------------------- |
+     * | true  | `<tarH>г</tarH>валт <tarH>Г</tarH>валт` |
+     * | false | `<tarH>ґ</tarH>валт <tarH>Ґ</tarH>валт` |
+     *
+     * @default false
+     */
     g: boolean;
 };
-type ExtendedDict = readonly (readonly [
-    RegExp,
-    string | ((...substrings: string[]) => string)
-])[];
 
 declare class TaraskConfig {
-    constructor(options?: DeepPartialReadonly<{
-        general: TaraskOptions;
-        html: HtmlOptions;
-        nonHtml: NonHtmlOptions;
+    constructor(options?: PartialReadonly<{
+        general: PartialReadonly<TaraskOptions>;
+        html: PartialReadonly<HtmlOptions>;
+        nonHtml: PartialReadonly<NonHtmlOptions>;
     }>);
-    general: {
-        abc: Alphabet;
-        j: OptionJ;
-        doEscapeCapitalized: boolean;
-    };
-    html: {
-        g: boolean;
-    };
-    nonHtml: {
-        h: boolean;
-        ansiColors: boolean;
-        variations: Variation;
-    };
+    /** @see {@link TaraskOptions} */
+    general: TaraskOptions;
+    /** @see {@link HtmlOptions} */
+    html: HtmlOptions;
+    /** @see {@link NonHtmlOptions} */
+    nonHtml: NonHtmlOptions;
 }
-declare const REPLACE_J: {
-    readonly NEVER: 0;
-    readonly RANDOM: 1;
-    readonly ALWAYS: 2;
-};
-declare const VARIATION: {
-    readonly NO: 0;
-    readonly FIRST: 1;
-    readonly ALL: 2;
-};
 
-type TaraskStep<Storage = {}> = (text: string, args: {
+type TaraskStep<Storage = {}> = (args: {
+    text: string;
     storage: Storage;
     cfg: TaraskConfig;
-}) => string;
+}) => void;
 type SplittedTextStorage = {
-    text: string[];
-    orig: readonly string[];
+    textArr: string[];
+    origArr: readonly string[];
 };
 
 declare const convertAlphabet: TaraskStep;
 declare const convertAlphabetLowerCase: TaraskStep;
 
+/**
+ * Uses {@link highlightDiff}
+ */
 declare const highlightDiffStep: (highlight: (content: string) => string) => TaraskStep<SplittedTextStorage>;
-declare const highlightDiffNonHtmlStep: TaraskStep<SplittedTextStorage>;
-
-declare const applyHtmlVariations: TaraskStep;
-declare const applyHtmlG: TaraskStep;
+/**
+ * Uses {@link highlightDiff}
+ */
+declare const highlightDiffStepNonHtml: TaraskStep<SplittedTextStorage>;
 
 declare const replaceIbyJ: TaraskStep;
 
 declare const joinSplittedText: TaraskStep<SplittedTextStorage>;
 
-declare const applyNonHtmlVariations: TaraskStep;
-declare const applyNonHtmlG: TaraskStep;
+declare const applyGHtml: TaraskStep;
+declare const applyGNonHtml: TaraskStep;
+
+/**
+ * @param callback - A function that takes an
+ * array of variable parts and returns a string.
+ *
+ * The step replaces strings like `"(a|b|c)"`
+ * with the result of the callback.
+ *
+ * @see {@link applyVariationsHtml}
+ * @see {@link applyVariationsNonHtml}
+ */
+declare const applyVariableParts: (callback: (arr: string[]) => string) => TaraskStep;
+/**
+ * Uses {@link applyVariableParts}
+ *
+ * @example
+ * applyVariationsHtml({text: "a(b|c)d"});
+ * // {text: "a<tarL data-l='c'>b</tarL>d"}
+ */
+declare const applyVariationsHtml: TaraskStep;
+/**
+ * Uses {@link applyVariableParts}
+ */
+declare const applyVariationsNonHtml: TaraskStep;
 
 declare const prepare: TaraskStep;
 
-declare const applyNoFix: TaraskStep<SpecialSyntaxStorage>;
-declare const applyVariableParts: (callback: (arr: string[]) => string) => TaraskStep;
+/**
+ * Created in {@link resolveSpecialSyntax}.
+ *
+ * Emptied in {@link applyNoFix}.
+ */
 type SpecialSyntaxStorage = {
     noFixArr: string[];
 };
+/**
+ * Brings parts from {@link SpecialSyntaxStorage} back to the text.
+ *
+ * Empties {@link SpecialSyntaxStorage.noFixArr}.
+ */
+declare const applyNoFix: TaraskStep<SpecialSyntaxStorage>;
+/**
+ * Captures noFix parts and stores them in {@link SpecialSyntaxStorage.noFixArr}.
+ * Places a special character `" \ue0fe "` in their place.
+ *
+ * Use {@link applyNoFix} to bring the parts back to the text.
+ *
+ * Creates storage: {@link SpecialSyntaxStorage}.
+ */
 declare const resolveSpecialSyntax: (leftAngleBracket: string) => TaraskStep<SpecialSyntaxStorage>;
 
 declare const restoreCaseStep: TaraskStep<SplittedTextStorage>;
@@ -151,63 +262,131 @@ declare const storeSplittedText: TaraskStep<SplittedTextStorage>;
 
 declare const taraskevize: TaraskStep;
 
+/**
+ * Created in {@link whitespacesToSpaces}.
+ *
+ * Emptied in {@link restoreWhitespaces}.
+ */
 type WhiteSpaceStorage = {
     spaces: string[];
 };
+/**
+ * Captures all whitespaces and replaces them with a single space.
+ *
+ * Creates storage: {@link WhiteSpaceStorage}.
+ */
 declare const whitespacesToSpaces: TaraskStep<WhiteSpaceStorage>;
+/**
+ * Brings original whitespaces back to the text.
+ *
+ * Empties {@link WhiteSpaceStorage.spaces}.
+ */
 declare const restoreWhitespaces: TaraskStep<WhiteSpaceStorage>;
 
 declare const trim: TaraskStep;
 
+declare const restoreParentheses: TaraskStep;
+declare const afterJoin: TaraskStep;
+declare const finalize: (newLine: string) => TaraskStep;
+declare const toLowerCase: TaraskStep;
+
+/**
+ * This module exports all the steps
+ * that are used in builtin pipelines.
+ *
+ * A step implements the {@link TaraskStep} type.
+ *
+ * Some steps are configurable, they take
+ * additional arguments and return a {@link TaraskStep},
+ * for example {@link resolveSpecialSyntax}.
+ *
+ * @module
+ */
+
+type index$1_SpecialSyntaxStorage = SpecialSyntaxStorage;
 type index$1_SplittedTextStorage = SplittedTextStorage;
 type index$1_TaraskStep<Storage = {}> = TaraskStep<Storage>;
-declare const index$1_applyHtmlG: typeof applyHtmlG;
-declare const index$1_applyHtmlVariations: typeof applyHtmlVariations;
+type index$1_WhiteSpaceStorage = WhiteSpaceStorage;
+declare const index$1_afterJoin: typeof afterJoin;
+declare const index$1_applyGHtml: typeof applyGHtml;
+declare const index$1_applyGNonHtml: typeof applyGNonHtml;
 declare const index$1_applyNoFix: typeof applyNoFix;
-declare const index$1_applyNonHtmlG: typeof applyNonHtmlG;
-declare const index$1_applyNonHtmlVariations: typeof applyNonHtmlVariations;
 declare const index$1_applyVariableParts: typeof applyVariableParts;
+declare const index$1_applyVariationsHtml: typeof applyVariationsHtml;
+declare const index$1_applyVariationsNonHtml: typeof applyVariationsNonHtml;
 declare const index$1_convertAlphabet: typeof convertAlphabet;
 declare const index$1_convertAlphabetLowerCase: typeof convertAlphabetLowerCase;
-declare const index$1_highlightDiffNonHtmlStep: typeof highlightDiffNonHtmlStep;
+declare const index$1_finalize: typeof finalize;
 declare const index$1_highlightDiffStep: typeof highlightDiffStep;
+declare const index$1_highlightDiffStepNonHtml: typeof highlightDiffStepNonHtml;
 declare const index$1_joinSplittedText: typeof joinSplittedText;
 declare const index$1_prepare: typeof prepare;
 declare const index$1_replaceIbyJ: typeof replaceIbyJ;
 declare const index$1_resolveSpecialSyntax: typeof resolveSpecialSyntax;
 declare const index$1_restoreCaseStep: typeof restoreCaseStep;
+declare const index$1_restoreParentheses: typeof restoreParentheses;
 declare const index$1_restoreWhitespaces: typeof restoreWhitespaces;
 declare const index$1_storeSplittedAbcConvertedOrig: typeof storeSplittedAbcConvertedOrig;
 declare const index$1_storeSplittedText: typeof storeSplittedText;
 declare const index$1_taraskevize: typeof taraskevize;
+declare const index$1_toLowerCase: typeof toLowerCase;
 declare const index$1_trim: typeof trim;
 declare const index$1_whitespacesToSpaces: typeof whitespacesToSpaces;
 declare namespace index$1 {
-  export { type index$1_SplittedTextStorage as SplittedTextStorage, type index$1_TaraskStep as TaraskStep, index$1_applyHtmlG as applyHtmlG, index$1_applyHtmlVariations as applyHtmlVariations, index$1_applyNoFix as applyNoFix, index$1_applyNonHtmlG as applyNonHtmlG, index$1_applyNonHtmlVariations as applyNonHtmlVariations, index$1_applyVariableParts as applyVariableParts, index$1_convertAlphabet as convertAlphabet, index$1_convertAlphabetLowerCase as convertAlphabetLowerCase, index$1_highlightDiffNonHtmlStep as highlightDiffNonHtmlStep, index$1_highlightDiffStep as highlightDiffStep, index$1_joinSplittedText as joinSplittedText, index$1_prepare as prepare, index$1_replaceIbyJ as replaceIbyJ, index$1_resolveSpecialSyntax as resolveSpecialSyntax, index$1_restoreCaseStep as restoreCaseStep, index$1_restoreWhitespaces as restoreWhitespaces, index$1_storeSplittedAbcConvertedOrig as storeSplittedAbcConvertedOrig, index$1_storeSplittedText as storeSplittedText, index$1_taraskevize as taraskevize, index$1_trim as trim, index$1_whitespacesToSpaces as whitespacesToSpaces };
+  export { type index$1_SpecialSyntaxStorage as SpecialSyntaxStorage, type index$1_SplittedTextStorage as SplittedTextStorage, type index$1_TaraskStep as TaraskStep, type index$1_WhiteSpaceStorage as WhiteSpaceStorage, index$1_afterJoin as afterJoin, index$1_applyGHtml as applyGHtml, index$1_applyGNonHtml as applyGNonHtml, index$1_applyNoFix as applyNoFix, index$1_applyVariableParts as applyVariableParts, index$1_applyVariationsHtml as applyVariationsHtml, index$1_applyVariationsNonHtml as applyVariationsNonHtml, index$1_convertAlphabet as convertAlphabet, index$1_convertAlphabetLowerCase as convertAlphabetLowerCase, index$1_finalize as finalize, index$1_highlightDiffStep as highlightDiffStep, index$1_highlightDiffStepNonHtml as highlightDiffStepNonHtml, index$1_joinSplittedText as joinSplittedText, index$1_prepare as prepare, index$1_replaceIbyJ as replaceIbyJ, index$1_resolveSpecialSyntax as resolveSpecialSyntax, index$1_restoreCaseStep as restoreCaseStep, index$1_restoreParentheses as restoreParentheses, index$1_restoreWhitespaces as restoreWhitespaces, index$1_storeSplittedAbcConvertedOrig as storeSplittedAbcConvertedOrig, index$1_storeSplittedText as storeSplittedText, index$1_taraskevize as taraskevize, index$1_toLowerCase as toLowerCase, index$1_trim as trim, index$1_whitespacesToSpaces as whitespacesToSpaces };
 }
 
-declare const tarask: (text: string, pipeline: TaraskStep<any>[], cfg?: TaraskConfig) => string;
-
-declare const abcOnlyPipeline: (TaraskStep<{
-    noFixArr: string[];
-}> | TaraskStep<{
-    spaces: string[];
-}> | ((_: string, { storage, cfg: { general } }: {
-    storage: {
-        doEscapeCapitalized: boolean;
-    };
+/**
+ * @returns converted text
+ *
+ * @example
+ * tarask("планета", plainTextPipeline);
+ * // "плянэта"
+ */
+declare const tarask: (text: string, pipeline: TaraskStep<any>[], cfg?: Readonly<TaraskConfig>) => string;
+
+/**
+ * Storage for the pipeline {@link abcOnly}.
+ */
+type AbcOnlyStorage = {
+    doEscapeCapitalized: boolean;
+};
+/**
+ * Pipeline for changing only the alphabet.
+ *
+ * The property `cfg.general.doEscapeCapitalized` is set to `false` during the pipeline execution.
+ *
+ * To see the full list of steps, check the source code.
+ */
+declare const abcOnly: (TaraskStep<SpecialSyntaxStorage> | TaraskStep<WhiteSpaceStorage> | (({ storage, cfg: { general } }: {
+    text: string;
+    storage: AbcOnlyStorage;
     cfg: TaraskConfig;
-}) => string))[];
-declare const plainTextPipeline: (TaraskStep<SplittedTextStorage> | TaraskStep<{
-    noFixArr: string[];
-}> | TaraskStep<{
-    spaces: string[];
-}>)[];
-declare const htmlPipeline: (TaraskStep<SplittedTextStorage> | TaraskStep<{
-    noFixArr: string[];
-}> | TaraskStep<{
-    spaces: string[];
-}>)[];
+}) => void))[];
+/**
+ * Pipeline for taraskevizing into plain text.
+ *
+ * To see the full list of steps, check the source code.
+ */
+declare const plainText: (TaraskStep<SplittedTextStorage> | TaraskStep<SpecialSyntaxStorage> | TaraskStep<WhiteSpaceStorage>)[];
+/**
+ * Pipeline for taraskevizing into HTML.
+ *
+ * To see the full list of steps, check the source code.
+ */
+declare const html: (TaraskStep<SplittedTextStorage> | TaraskStep<SpecialSyntaxStorage> | TaraskStep<WhiteSpaceStorage>)[];
+
+declare const pipelines_abcOnly: typeof abcOnly;
+declare const pipelines_html: typeof html;
+declare const pipelines_plainText: typeof plainText;
+declare namespace pipelines {
+  export { pipelines_abcOnly as abcOnly, pipelines_html as html, pipelines_plainText as plainText };
+}
+
+type ExtendedDict = readonly (readonly [
+    RegExp,
+    string | ((...substrings: string[]) => string)
+])[];
 
 declare const afterTarask: ExtendedDict;
 
@@ -220,19 +399,26 @@ declare const replaceWithDict: (text: string, dict?: ExtendedDict) => string;
 declare const restoreCase: (text: string[], orig: readonly string[]) => string[];
 
 declare const htmlWrappers: {
-    fix: (content: string) => string;
-    letterH: (content: string) => string;
+    fix: (content: string) => `<tarF>${string}</tarF>`;
+    letterH: (content: string) => `<tarH>${string}</tarH>`;
 };
 declare const ansiColorWrappers: {
     fix: (content: string) => string;
     variable: (content: string) => string;
 };
 
+/**
+ * Collection of functions that help to work with dictionaries.
+ */
 declare const dictFrom: {
     raw: (dict: RawDict, additionalFlags?: string) => Dict;
+    /**
+     * Adds the global flag to all patterns in the dictionary.
+     */
     nonGlobal: (dict: WritableDict) => Dict;
 };
 
+type index_ExtendedDict = ExtendedDict;
 declare const index_afterTarask: typeof afterTarask;
 declare const index_ansiColorWrappers: typeof ansiColorWrappers;
 declare const index_dictFrom: typeof dictFrom;
@@ -242,7 +428,7 @@ declare const index_replaceG: typeof replaceG;
 declare const index_replaceWithDict: typeof replaceWithDict;
 declare const index_restoreCase: typeof restoreCase;
 declare namespace index {
-  export { index_afterTarask as afterTarask, index_ansiColorWrappers as ansiColorWrappers, index_dictFrom as dictFrom, index_highlightDiff as highlightDiff, index_htmlWrappers as htmlWrappers, index_replaceG as replaceG, index_replaceWithDict as replaceWithDict, index_restoreCase as restoreCase };
+  export { type index_ExtendedDict as ExtendedDict, index_afterTarask as afterTarask, index_ansiColorWrappers as ansiColorWrappers, index_dictFrom as dictFrom, index_highlightDiff as highlightDiff, index_htmlWrappers as htmlWrappers, index_replaceG as replaceG, index_replaceWithDict as replaceWithDict, index_restoreCase as restoreCase };
 }
 
-export { type Alphabet, type HtmlOptions, type NonHtmlOptions, REPLACE_J, TaraskConfig, type TaraskOptions, VARIATION, abcOnlyPipeline, index$3 as alphabets, index$2 as dicts, gobj, htmlPipeline, index as lib, noSoften, plainTextPipeline, softeners, index$1 as steps, tarask, wordlist };
+export { type HtmlOptions, type NonHtmlOptions, REPLACE_J, TaraskConfig, type TaraskOptions, VARIATION, index$3 as dicts, index as lib, pipelines, index$1 as steps, tarask };