@fgv/ts-bcp47 5.0.0-21 → 5.0.0-23

package/src/packlets/bcp47/languageTagParser.ts

@@ -1,307 +0,0 @@
-/*
- * Copyright (c) 2022 Erik Fortune
- *
- * Permission is hereby granted, free of charge, to any person obtaining a copy
- * of this software and associated documentation files (the "Software"), to deal
- * in the Software without restriction, including without limitation the rights
- * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
- * copies of the Software, and to permit persons to whom the Software is
- * furnished to do so, subject to the following conditions:
- *
- * The above copyright notice and this permission notice shall be included in all
- * copies or substantial portions of the Software.
- *
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
- * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
- * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
- * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
- * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
- * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
- * SOFTWARE.
- */
-
-import * as Iana from '../iana';
-
-import { Result, Success, allSucceed, fail, succeed } from '@fgv/ts-utils';
-
-import { Validate } from './bcp47Subtags';
-import { ExtensionSingleton, ExtensionSubtag } from './bcp47Subtags/model';
-import { ISubtags } from './common';
-
-/**
- * @internal
- */
-interface IParserState {
-  readonly iana: Iana.LanguageRegistries;
-  readonly tag: string;
-  readonly subtags: string[];
-  readonly parsedSubtags: ISubtags;
-  next?: string;
-}
-
-/**
- * @public
- */
-export class LanguageTagParser {
-  // eslint-disable-next-line @typescript-eslint/no-empty-function
-  /* c8 ignore next */
-  private constructor() {}
-
-  /**
-   * Parses a string representation of a BCP-47 ({@link https://www.rfc-editor.org/rfc/rfc5646.html | RFC 5646})
-   * language tag, to produce a {@link Bcp47.Subtags | Subtags} object which
-   * breaks out each of the subtags.
-   * @param tag - The `string` language tag to be parsed.
-   * @param iana - Optional {@link Iana.LanguageRegistries | IANA language registries}
-   * to be used.
-   * @returns `Success` with the resulting {@link Bcp47.Subtags | subtags}
-   * or `Failure` with details if an error occurs.
-   * @public
-   */
-  public static parse(tag: string, iana?: Iana.LanguageRegistries): Result<ISubtags> {
-    /* c8 ignore next */
-    iana = iana ?? Iana.DefaultRegistries.languageRegistries;
-    const status: IParserState = {
-      tag,
-      iana,
-      subtags: tag.split('-'),
-      parsedSubtags: {}
-    };
-    status.next = status.subtags.shift();
-
-    return allSucceed(
-      [
-        this._parseGrandfatheredTag(status),
-        this._parsePrimaryLanguage(status),
-        this._parseExtlang(status),
-        this._parseScript(status),
-        this._parseRegion(status),
-        this._parseVariants(status),
-        this._parseExtensions(status),
-        this._parsePrivateSubtags(status),
-        this._parseTagEnd(status)
-      ],
-      status
-    ).onSuccess(() => {
-      return succeed(status.parsedSubtags);
-    });
-  }
-
-  /**
-   * Determines if the entire tag matches a registered grandfathered tag.
-   * @param state - The {@link Bcp47.ParserState | current state} of the
-   * parse operation.
-   * @returns `Success` with the updated {@link Bcp47.Subtags | subtags}
-   * if a grandfathered tag is found, or `Success` with the supplied subtags
-   * if no matching grandfathered tag is found.
-   * @internal
-   */
-  protected static _parseGrandfatheredTag(state: IParserState): Success<ISubtags> {
-    const grandfathered = state.iana.subtags.grandfathered.tryGet(state.tag);
-    if (grandfathered) {
-      state.parsedSubtags.grandfathered = state.tag as Iana.LanguageSubtags.GrandfatheredTag;
-      // we consumed the whole thing
-      state.subtags.splice(0, state.subtags.length);
-      state.next = undefined;
-    }
-    return succeed(state.parsedSubtags);
-  }
-
-  /**
-   * Parses the primary language subtag of a supplied language tag.
-   * @param state - The {@link Bcp47.ParserState | current state} of the
-   * parse operation.
-   * @returns `Success` with supplied {@link Bcp47.Subtags | subtags}
-   * updated to include the primary language subtag, or `Failure` with details if an error
-   * occurs.
-   * @internal
-   */
-  protected static _parsePrimaryLanguage(state: IParserState): Result<ISubtags> {
-    // primary language subtag is required unless the entire tag is grandfathered or consists
-    // of only private tags
-    if (state.iana.subtags.languages.isWellFormed(state.next)) {
-      state.parsedSubtags.primaryLanguage = state.next;
-      state.next = state.subtags.shift();
-      return succeed(state.parsedSubtags);
-    } else if (state.parsedSubtags.grandfathered !== undefined) {
-      return succeed(state.parsedSubtags);
-    } else if (Validate.privateUsePrefix.isWellFormed(state.next)) {
-      // just return with no primary language and the private tag
-      // parser will be invoked by the parent flow.
-      return succeed(state.parsedSubtags);
-    }
-    return fail(`${state.tag}: no primary language subtag`);
-  }
-
-  /**
-   * Parses the extlang subtag(s) of a supplied language tag.
-   * @param state - The {@link Bcp47.ParserState | current state} of the
-   * parse operation.
-   * @returns `Success` with supplied {@link Bcp47.Subtags | subtags}
-   * updated to include extlang subtags if present, or `Failure` with details if an error
-   * occurs.
-   * @internal
-   */
-  protected static _parseExtlang(state: IParserState): Result<ISubtags> {
-    // optional extlangs subtags
-    while (state.iana.subtags.extlangs.isWellFormed(state.next)) {
-      if (state.parsedSubtags.extlangs === undefined) {
-        state.parsedSubtags.extlangs = [state.next];
-      } else if (state.parsedSubtags.extlangs.length < 3) {
-        state.parsedSubtags.extlangs.push(state.next);
-      } else {
-        return fail(`${state.next}: too many extlang subtags`);
-      }
-      state.next = state.subtags.shift();
-    }
-    return succeed(state.parsedSubtags);
-  }
-
-  /**
-   * Parses the script subtag of a supplied language tag.
-   * @param state - The {@link Bcp47.ParserState | current state} of the
-   * parse operation.
-   * @returns `Success` with supplied {@link Bcp47.Subtags | subtags}
-   * updated to include the script subtag if present, or `Failure` with details if an error
-   * occurs.
-   * @internal
-   */
-  protected static _parseScript(state: IParserState): Result<ISubtags> {
-    // optional script subtag
-    if (state.iana.subtags.scripts.isWellFormed(state.next)) {
-      state.parsedSubtags.script = state.next;
-      state.next = state.subtags.shift();
-    }
-    return succeed(state.parsedSubtags);
-  }
-
-  /**
-   * Parses the region subtag of a supplied language tag.
-   * @param state - The {@link Bcp47.ParserState | current state} of the
-   * parse operation.
-   * @returns `Success` with supplied {@link Bcp47.Subtags | subtags}
-   * updated to include the region subtag if present, or `Failure` with details if an error
-   * occurs.
-   * @internal
-   */
-  protected static _parseRegion(state: IParserState): Result<ISubtags> {
-    // optional region subtag
-    if (state.iana.subtags.regions.isWellFormed(state.next)) {
-      state.parsedSubtags.region = state.next;
-      state.next = state.subtags.shift();
-    }
-    return succeed(state.parsedSubtags);
-  }
-
-  /**
-   * Parses the variant subtag(s) of a supplied language tag.
-   * @param state - The {@link Bcp47.ParserState | current state} of the
-   * parse operation.
-   * @returns `Success` with supplied {@link Bcp47.Subtags | subtags}
-   * updated to include the variant subtags if present, or `Failure` with details if an error
-   * occurs.
-   * @internal
-   */
-  protected static _parseVariants(state: IParserState): Result<ISubtags> {
-    // optional variant subtags
-    while (state.iana.subtags.variants.isWellFormed(state.next)) {
-      if (state.parsedSubtags.variants === undefined) {
-        state.parsedSubtags.variants = [state.next];
-      } else {
-        state.parsedSubtags.variants.push(state.next);
-      }
-      state.next = state.subtags.shift();
-    }
-    return succeed(state.parsedSubtags);
-  }
-
-  /**
-   * Parses the extension subtag(s) of a supplied language tag.
-   * @param state - The {@link Bcp47.ParserState | current state} of the
-   * parse operation.
-   * @returns `Success` with supplied {@link Bcp47.Subtags | subtags}
-   * updated to include the extension subtags if present, or `Failure` with details if an error
-   * occurs.
-   * @internal
-   */
-  protected static _parseExtensions(state: IParserState): Result<ISubtags> {
-    // optional extension subtags
-    while (state.next !== undefined && Validate.extensionSingleton.isWellFormed(state.next)) {
-      const singleton: ExtensionSingleton = state.next as ExtensionSingleton;
-      const values: ExtensionSubtag[] = [];
-      state.next = state.subtags.shift();
-
-      while (Validate.extensionSubtag.isWellFormed(state.next)) {
-        values.push(state.next as ExtensionSubtag);
-        state.next = state.subtags.shift();
-      }
-      if (
-        state.next !== undefined &&
-        !Validate.extensionSingleton.isWellFormed(state.next) &&
-        !Validate.privateUsePrefix.isWellFormed(state.next)
-      ) {
-        return fail(`${state.next}: malformed extension subtag`);
-      } else if (values.length < 1) {
-        return fail(`${state.tag}: extension '${singleton}' must have at least one subtag.`);
-      }
-
-      const value = values.join('-') as ExtensionSubtag;
-      if (state.parsedSubtags.extensions === undefined) {
-        state.parsedSubtags.extensions = [{ singleton, value }];
-      } else {
-        state.parsedSubtags.extensions.push({ singleton, value });
-      }
-    }
-    return succeed(state.parsedSubtags);
-  }
-
-  /**
-   * Parses the private use subtags of a supplied language tag.
-   * @param state - The {@link Bcp47.ParserState | current state} of the
-   * parse operation.
-   * @returns `Success` with supplied {@link Bcp47.Subtags | subtags}
-   * updated to include the private-use subtags if present, or `Failure` with details if an error
-   * occurs.
-   * @internal
-   */
-  protected static _parsePrivateSubtags(state: IParserState): Result<ISubtags> {
-    // optional private use subtags
-    if (state.next !== undefined && Validate.privateUsePrefix.isWellFormed(state.next)) {
-      const values: string[] = [];
-      state.next = state.subtags.shift();
-
-      while (
-        state.next &&
-        state.next.length > 1 &&
-        Iana.LanguageSubtags.Validate.extendedLanguageRange.isWellFormed(state.next)
-      ) {
-        values.push(state.next);
-        state.next = state.subtags.shift();
-      }
-
-      if (state.next !== undefined) {
-        return fail(`${state.next}: malformed private-use subtag`);
-      } else if (values.length < 1) {
-        return fail(`${state.tag}: private-use tag must have at least one subtag.`);
-      }
-
-      state.parsedSubtags.privateUse = values as Iana.LanguageSubtags.ExtendedLanguageRange[];
-    }
-    return succeed(state.parsedSubtags);
-  }
-
-  /**
-   * Verifies {@link Bcp47.ParserState | parser state} at the end of a parse operation.
-   * @param state - The {@link Bcp47.ParserState | current state} of the
-   * parse operation.
-   * @returns `Success` if the tag was fully consumed, or `Failure` with details
-   * if unexpected subtags remain to be parsed.
-   * @internal
-   */
-  protected static _parseTagEnd(state: IParserState): Result<ISubtags> {
-    if (state.next !== undefined) {
-      return fail(`${state.next}: unexpected subtag`);
-    }
-    return succeed(state.parsedSubtags);
-  }
-}

package/src/packlets/bcp47/match/chooser.ts

@@ -1,164 +0,0 @@
-/*
- * Copyright (c) 2022 Erik Fortune
- *
- * Permission is hereby granted, free of charge, to any person obtaining a copy
- * of this software and associated documentation files (the "Software"), to deal
- * in the Software without restriction, including without limitation the rights
- * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
- * copies of the Software, and to permit persons to whom the Software is
- * furnished to do so, subject to the following conditions:
- *
- * The above copyright notice and this permission notice shall be included in all
- * copies or substantial portions of the Software.
- *
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
- * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
- * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
- * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
- * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
- * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
- * SOFTWARE.
- */
-
-import * as Iana from '../../iana';
-
-import { ISubtags } from '../common';
-import { LanguageTag } from '../languageTag';
-import { LanguageSimilarityMatcher } from './similarity';
-
-/**
- * Represents a single matching filtered language.
- * @public
- */
-export interface IMatchingLanguage {
-  /**
-   * Numeric indication of how well the language matches,
-   * from perfect (`1.0`) to not at all (`0.0`).  When
-   * matching an ordered list, languages at the front of
-   * the desired language list are always higher quality.
-   */
-  quality: number;
-  /**
-   * The `string` tag of the matched language.
-   */
-  tag: string;
-  /**
-   * The matched {@link Bcp47.LanguageTag | language tag}.
-   */
-  languageTag: LanguageTag;
-}
-
-/**
- * Options for {@link Bcp47.choose | language tag list filter} functions.
- * @public
- */
-export interface ILanguageChooserOptions {
-  /**
-   * Indicates whether to return the matching language from the
-   * desired list or the available list. Default is `'availableLanguage'`.
-   */
-  use?: 'desiredLanguage' | 'availableLanguage';
-
-  /**
-   * Indicates how to filter the language list - `'primaryLanguage'`
-   * indicates the each primary language should appear only once in
-   * the list in its most similar form.  A filter value of `'none'`
-   * reports all matching variants of any primary language in order
-   * of similarity.  Default is `'primaryLanguage'`
-   */
-  filter?: 'primaryLanguage' | 'none';
-
-  /**
-   * An optional {@link Bcp47.LanguageSpec | language specification}
-   * indicating a language to be returned if the filter call would
-   * otherwise return an empty list (i.e. no languages match).
-   */
-  ultimateFallback?: string | ISubtags | LanguageTag;
-}
-
-/**
- * Default values for a{@link Bcp47.LanguageFilterOptions}.
- * @public
- */
-export const defaultLanguageChooserOptions: ILanguageChooserOptions = Object.freeze({
-  use: 'availableLanguage',
-  filter: 'primaryLanguage'
-});
-
-/**
- * Helper to compare a list of 'desired' languages to a list of 'available' language
- * and return the intersection in order of preference, taking tag semantics into account.
- * @public
- */
-export class LanguageChooser {
-  /**
-   * @internal
-   */
-  protected readonly _matcher: LanguageSimilarityMatcher;
-
-  public constructor(iana?: Iana.LanguageRegistries) {
-    this._matcher = new LanguageSimilarityMatcher(iana);
-  }
-
-  public chooseLanguageTagsWithDetails(
-    desiredLanguages: LanguageTag[],
-    availableLanguages: LanguageTag[],
-    options?: ILanguageChooserOptions
-  ): IMatchingLanguage[] {
-    const matched = new Map<string, IMatchingLanguage>();
-    const decrement = desiredLanguages.length < 10 ? 0.1 : 1.0 / desiredLanguages.length;
-    let base = 1.0;
-
-    // fill any missing fields from the default
-    options = { ...defaultLanguageChooserOptions, ...options };
-
-    for (const want of desiredLanguages) {
-      base -= decrement;
-      for (const have of availableLanguages) {
-        const similarity = this._matcher.matchLanguageTags(want, have);
-        if (similarity > 0.0) {
-          const quality = base + similarity * decrement;
-          const languageTag = options.use === 'availableLanguage' ? have : want;
-          const tag = languageTag.tag;
-          const key = options.filter === 'primaryLanguage' ? languageTag.subtags.primaryLanguage ?? tag : tag;
-
-          const match: IMatchingLanguage = {
-            quality,
-            tag,
-            languageTag
-          };
-
-          const existing = matched.get(key);
-          if (!existing || existing.quality < quality) {
-            matched.set(key, match);
-          }
-        }
-      }
-    }
-
-    const values = Array.from(matched.values());
-    if (values.length > 1) {
-      // want descending order
-      values.sort((m1, m2) => m2.quality - m1.quality);
-    } else if (values.length === 0 && options.ultimateFallback) {
-      const languageTag =
-        options.ultimateFallback instanceof LanguageTag
-          ? options.ultimateFallback
-          : LanguageTag.create(options.ultimateFallback).orDefault();
-      if (languageTag) {
-        return [{ languageTag, tag: languageTag.tag, quality: 0 }];
-      }
-    }
-    return values;
-  }
-
-  public filterLanguageTags(
-    desiredLanguages: LanguageTag[],
-    availableLanguages: LanguageTag[],
-    options?: ILanguageChooserOptions
-  ): LanguageTag[] {
-    return this.chooseLanguageTagsWithDetails(desiredLanguages, availableLanguages, options).map(
-      (t) => t.languageTag
-    );
-  }
-}

package/src/packlets/bcp47/match/common.ts

@@ -1,57 +0,0 @@
-/*
- * Copyright (c) 2022 Erik Fortune
- *
- * Permission is hereby granted, free of charge, to any person obtaining a copy
- * of this software and associated documentation files (the "Software"), to deal
- * in the Software without restriction, including without limitation the rights
- * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
- * copies of the Software, and to permit persons to whom the Software is
- * furnished to do so, subject to the following conditions:
- *
- * The above copyright notice and this permission notice shall be included in all
- * copies or substantial portions of the Software.
- *
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
- * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
- * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
- * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
- * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
- * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
- * SOFTWARE.
- */
-/* eslint-disable @rushstack/typedef-var */
-
-/**
- * Penalty for a mismatched value for some subtags.
- * @public
- */
-export const subtagMismatchPenalty = {
-  private: 0.05,
-  extension: 0.04,
-  variant: 0.1
-};
-
-/**
- * Common levels of match quality for a single language match.
- * @public
- */
-export const tagSimilarity = {
-  exact: 1.0,
-  variant: 0.9,
-  region: 0.8,
-  macroRegion: 0.65,
-  neutralRegion: 0.5,
-  preferredAffinity: 0.45,
-  affinity: 0.4,
-  preferredRegion: 0.35,
-  sibling: 0.3,
-  undetermined: 0.1,
-  none: 0
-};
-
-/**
- * Numeric representation of the quality of a language match.
- * Range is 0 (no match) to 1 (exact match).
- * @public
- */
-export type TagSimilarity = keyof typeof tagSimilarity;

package/src/packlets/bcp47/match/index.ts

@@ -1,26 +0,0 @@
-/*
- * Copyright (c) 2022 Erik Fortune
- *
- * Permission is hereby granted, free of charge, to any person obtaining a copy
- * of this software and associated documentation files (the "Software"), to deal
- * in the Software without restriction, including without limitation the rights
- * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
- * copies of the Software, and to permit persons to whom the Software is
- * furnished to do so, subject to the following conditions:
- *
- * The above copyright notice and this permission notice shall be included in all
- * copies or substantial portions of the Software.
- *
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
- * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
- * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
- * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
- * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
- * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
- * SOFTWARE.
- */
-// istanbul ignore file
-
-export { ILanguageChooserOptions, IMatchingLanguage, LanguageChooser } from './chooser';
-export * from './common';
-export { LanguageSimilarityMatcher } from './similarity';