@retorquere/bibtex-parser 12.1.13 → 13.0.2

package/dist/{types → esm}/index.d.ts

@@ -12,6 +12,7 @@ export type { Options as SentenceCaseOptions } from './sentence-case.js';
 /** Splits text into classified tokens with source offsets. */
 export { tokenize } from './tokenizer.js';
 export type { Token } from './tokenizer.js';
+/** Known creator-list fields, each returned as an array of parsed {@link Creator} values. */
 export type CreatorFields = {
     author?: Creator[];
     bookauthor?: Creator[];
@@ -26,6 +27,7 @@ export type CreatorFields = {
     scriptwriter?: Creator[];
     translator?: Creator[];
 };
+/** Known multi-value fields whose elements remain strings. */
 export type ArrayFields = {
     keywords?: string[];
     institution?: string[];
@@ -35,44 +37,52 @@ export type ArrayFields = {
     location?: string[];
     origlocation?: string[];
 };
+/** The known creator-list and string-list fields in a normalized entry. */
 export type TypedFields = CreatorFields & ArrayFields;
+/** BibTeX field names mapped to normalized values; fields outside the known lists are strings. */
 export type Fields = TypedFields & Omit<Record<string, string>, keyof TypedFields>;
 /** A normalized BibTeX entry returned by {@link parse}. */
 export type Entry = {
+    /** Entry type from the source, such as `article` or `inproceedings`. */
     type: string;
+    /** Citation key identifying this entry. */
     key: string;
+    /** Parsed field values, with known creator and list fields represented as arrays. */
     fields: Fields;
+    /** Parsing mode used for each field; see {@link ParseMode}. */
     mode: Record<string, ParseMode>;
+    /** For fields inherited through `crossref`, records the parent entry key and source field name. */
     crossref?: Record<string, {
         parent: string;
         field: string;
     }>;
+    /** Source text for this entry. */
     input: string;
 };
 /** The parsed contents of a BibTeX library. */
 export interface Library {
     /**
-     * errors found while parsing
+     * Diagnostics collected while parsing. Recoverable errors do not necessarily prevent entries from being returned.
      */
     errors: bibtex.ParseError[];
     /**
-     * entries in the order in which they are found, omitting those which could not be parsed.
+     * Successfully parsed entries, in source order; entries that could not be parsed are omitted.
      */
     entries: Entry[];
     /**
-     * `@comment`s found in the bibtex file.
+     * Text from `@comment` directives.
      */
     comments: string[];
     /**
-     * `@string`s found in the bibtex file.
+     * Resolved values declared by `@string` directives.
      */
     strings: Record<string, string>;
     /**
-     * `@preamble` declarations found in the bibtex file
+     * Values from `@preamble` directives, in source order.
      */
     preambles: string[];
     /**
-     * jabref metadata (such as groups information) found in the bibtex file
+     * JabRef metadata extracted from the library, including groups and file settings.
      */
     jabref: JabRef.JabRefMetadata;
 }
@@ -146,6 +156,8 @@ export interface Options {
      * case protection exactly as the input has it
      */
     caseProtection?: 'as-needed' | 'strict' | boolean;
+    /** Render URL commands as HTML links (default true), or as case-protected destinations. */
+    richURL?: boolean;
     /**
      * How to handle unknown TeX commands and environments: `tex` wraps the command in a script
      * element, `text` returns the command without its backslash, `ignore` omits it, and `throw`
@@ -154,10 +166,10 @@ export interface Options {
      */
     unsupported?: 'tex' | 'text' | 'ignore' | 'throw';
     /**
-     * Some fields such as `url` are parsed in what is called "verbatim mode" where pretty much everything except braces is treated as regular text, not TeX commands. You can change the default list here if you want,
-     * for example to help parse Mendeley `file` fields, which against spec are not in verbatim mode.
+     * Fields parsed in verbatim mode. Selectors use wildflower globs (`?`, `*`, and `\\`) and match
+     * complete field names.
      */
-    verbatimFields?: (string | RegExp)[];
+    verbatimFields?: string[];
     /**
      * In the past many bibtex entries would just always wrap a field in double braces, likely because whomever was writing them couldn't figure out the case meddling rules (and who could
      * blame them). Fields listed here will either have one outer layer of braces treated as case-preserve, or have the outer braced be ignored completely, if this is detected.
@@ -182,13 +194,21 @@ export interface Options {
 }
 /** A parsed personal or organizational name. */
 export interface Creator {
+    /** Complete name when the parser cannot safely separate it into components. */
     name?: string;
+    /** Family name, including any parsed name prefix. */
     lastName?: string;
+    /** Given name. */
     firstName?: string;
+    /** Name particle, such as "von" or "de", when separated from the family name. */
     prefix?: string;
+    /** Generational or other name suffix. */
     suffix?: string;
+    /** Initials of the given name. */
     initial?: string;
+    /** Whether the parsed family name includes a name prefix. */
     useprefix?: boolean;
+    /** Whether the source separated the suffix from the name with a comma. */
     juniorcomma?: boolean;
 }
 export declare const FieldMode: {
@@ -198,11 +218,20 @@ export declare const FieldMode: {
     richtext: string[];
     literallist: string[];
 };
-/** Controls how a field's TeX content is interpreted. */
+/** Controls how a field's TeX content is interpreted and which normalized value shape it receives. */
 export type ParseMode = keyof typeof FieldMode | 'literal' | 'verbatimlist';
 export declare const English: string[];
-/** Parses BibTeX or BibLaTeX source into a normalized library. */
+/**
+ * Parses BibTeX or BibLaTeX source into normalized entries and field values.
+ * Recoverable problems are reported in `Library.errors`; set `unsupported: 'throw'` to throw on unsupported TeX commands or environments.
+ *
+ * @example
+ * ```ts
+ * const { entries, errors } = parse('@article{example, author={Ada Lovelace}, title={A title}}')
+ * const title = entries[0]?.fields.title
+ * ```
+ */
 export declare function parse(input: string, options?: Options): Library;
-/** Asynchronous variant of {@link parse}, yielding periodically for large libraries. */
+/** Asynchronous variant of {@link parse}; returns the same result shape and yields periodically for large libraries. */
 export declare function parseAsync(input: string, options?: Options): Promise<Library>;
 //# sourceMappingURL=index.d.ts.map

package/dist/esm/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../js/index.ts"],"names":[],"mappings":"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"}

package/dist/esm/index.js

@@ -234,6 +234,7 @@ class BibTeXParser {
     __publicField(this, "english");
     __publicField(this, "options");
     __publicField(this, "fieldMode");
+    __publicField(this, "verbatimFieldPatterns");
     __publicField(this, "newcommands", {});
     __publicField(this, "bib");
     __publicField(this, "unhandled", /* @__PURE__ */ new Set());
@@ -510,7 +511,7 @@ class BibTeXParser {
           url = node.args[0];
           label = node.args[node.content === "url" ? 0 : 1];
         }
-        return `<a href="${this.stringify(url, context)}">${this.stringify(label, context)}</a>`;
+        return this.options.richURL === false ? `<span class="nocase">${this.stringify(url, { ...context, caseProtected: true })}</span>` : `<a href="${this.stringify(url, { ...context, caseProtected: true })}">${this.stringify(label, { ...context, caseProtected: true })}</a>`;
       case "relax":
       case "aftergroup":
       case "ignorespaces":
@@ -653,13 +654,33 @@ class BibTeXParser {
     return node.content[0].type !== "macro";
   }
   mode(field) {
-    if (this.options.verbatimFields && this.options.verbatimFields.find((name) => typeof name === "string" ? name === field : field.match(name))) return "verbatim";
+    if (this.verbatimFieldPatterns.some((pattern) => field.match(pattern))) return "verbatim";
     let mode = "literal";
     for (const [selected, fields] of Object.entries(this.fieldMode)) {
       if (fields.find((match) => typeof match === "string" ? field === match : field.match(match))) mode = selected;
     }
     return mode;
   }
+  wildcardPattern(pattern) {
+    let source = "^";
+    let escaped = false;
+    for (const character of pattern.toLowerCase()) {
+      const literal = character.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      if (escaped) {
+        source += literal;
+        escaped = false;
+      } else if (character === "\\") {
+        escaped = true;
+      } else if (character === "?") {
+        source += ".";
+      } else if (character === "*") {
+        source += ".*?";
+      } else {
+        source += literal;
+      }
+    }
+    return new RegExp(`${source}$`, "iu");
+  }
   restoreMarkup(s) {
     if (!s.includes("")) return s;
     const restored = [s.replace(/\x0E\/?ncx\x0F/ig, "")];
@@ -915,7 +936,10 @@ class BibTeXParser {
       }
     });
     if (this.options.caseProtection === true) this.options.caseProtection = "as-needed";
-    if (this.options.verbatimFields) this.options.verbatimFields = this.options.verbatimFields.map((f) => typeof f === "string" ? f.toLowerCase() : new RegExp(f.source, f.flags + (f.flags.includes("i") ? "" : "i")));
+    this.verbatimFieldPatterns = (this.options.verbatimFields ?? []).map((pattern) => {
+      if (typeof pattern !== "string") throw new TypeError("verbatimFields entries must be glob strings");
+      return this.wildcardPattern(pattern);
+    });
     if (typeof this.options.english === "boolean") this.options.english = this.options.english ? English : [];
     this.options.english = this.options.english.map((langid) => langid.toLowerCase());
     this.fieldMode = Object.entries(FieldMode).reduce((acc, [mode, test]) => {