@retorquere/bibtex-parser 7.0.16 → 8.0.0

package/index.d.ts

@@ -1,130 +1,12 @@
-import * as bibtex from './grammar';
-import * as chunker from './chunker';
-import * as jabref from './jabref';
-import { JabRefMetadata } from './jabref';
+import { Node } from '@unified-latex/unified-latex-types';
+import * as bibtex from './verbatim';
+import * as JabRef from './jabref';
 export { toSentenceCase } from './sentence-case';
-type Node = bibtex.Bibliography | bibtex.Math | bibtex.Environment | bibtex.Block | bibtex.RegularCommand | bibtex.DiacriticCommand | bibtex.Entry | bibtex.Field | bibtex.NumberValue | bibtex.StringDeclaration | bibtex.StringReference | bibtex.SubscriptCommand | bibtex.SuperscriptCommand | bibtex.SymbolCommand | bibtex.TextValue | bibtex.PreambleExpression | bibtex.BracedComment | bibtex.LineComment | bibtex.Markup | bibtex.NonEntryText;
-export interface Name {
-    /**
-     * If the name is a literal (surrounded by braces) it will be in this property, and none of the other properties will be set
-     */
-    literal?: string;
-    /**
-     * Family name
-     */
-    lastName?: string;
-    /**
-     * available when parsing biblatex extended name format
-     */
-    useprefix?: boolean;
-    /**
-     * available when parsing biblatex extended name format
-     */
-    juniorcomma?: boolean;
-    /**
-     * given name. Will include middle names and initials.
-     */
-    firstName?: string;
-    /**
-     * Initials.
-     */
-    initial?: string;
-    /**
-     * things like `Jr.`, `III`, etc
-     */
-    suffix?: string;
-    /**
-     * things like `von`, `van der`, etc
-     */
-    prefix?: string;
-}
-export interface Entry {
-    /**
-     * citation key
-     */
-    key: string;
-    /**
-     * entry type
-     */
-    type: string;
-    /**
-     * entry fields. The keys are always in lowercase
-     */
-    fields: {
-        [key: string]: string[];
-    };
-    /**
-     * authors, editors, by creator type. Name order within the creator-type is retained.
-     */
-    creators: {
-        [type: string]: Name[];
-    };
-    /**
-     * will be set to `true` if sentence casing was applied to the entry
-     */
-    sentenceCased?: boolean;
-    /**
-     * list of fields that have been inherited/donated using crossref/xdata
-     */
-    crossref: {
-        donated: string[];
-        inherited: string[];
-    };
-}
-/**
- * Markup mapping. As the bibtex file is parsed, markup will be transformed according to this table
- */
-export interface MarkupMapping {
-    sub?: {
-        open: string;
-        close: string;
-    };
-    sup?: {
-        open: string;
-        close: string;
-    };
-    bold?: {
-        open: string;
-        close: string;
-    };
-    italics?: {
-        open: string;
-        close: string;
-    };
-    smallCaps?: {
-        open: string;
-        close: string;
-    };
-    caseProtect?: {
-        open: string;
-        close: string;
-    };
-    enquote?: {
-        open: string;
-        close: string;
-    };
-    h1?: {
-        open: string;
-        close: string;
-    };
-    h2?: {
-        open: string;
-        close: string;
-    };
-    roman?: {
-        open: string;
-        close: string;
-    };
-    fixedWidth?: {
-        open: string;
-        close: string;
-    };
-}
 export interface Bibliography {
     /**
      * errors found while parsing
      */
-    errors: ParseError[];
+    errors: bibtex.ParseError[];
     /**
      * entries in the order in which they are found, omitting those which could not be parsed.
      */
@@ -144,114 +26,87 @@ export interface Bibliography {
     /**
      * jabref metadata (such as groups information) found in the bibtex file
      */
-    jabref: JabRefMetadata;
-}
-export interface ParseError {
-    /**
-     * error message
-     */
-    message: string;
-    /**
-     * text block that was parsed where the error was found
-     */
-    source?: string;
-    /**
-     * Error line number within the bibtex file
-     */
-    line?: number;
-    /**
-     * Error column number within the bibtex file
-     */
-    column?: number;
+    jabref: JabRef.JabRefMetadata;
 }
-export declare const fields: {
-    creator: string[];
-    title: string[];
-    unnest: string[];
-    verbatim: string[];
-    html: string[];
-    unabbrev: string[];
-};
-export interface ParserOptions {
-    /**
-     * BibTeX files are expected to store title-type fields in Sentence Case, where other reference managers (such as Zotero) expect them to be stored as Sentence case. When there is no language field, or the language field
-     * is one of the languages (case insensitive) passed in this option, the parser will attempt to sentence-case title-type fields as they are being parsed. This uses heuristics and does not employ any kind of natural
-     * language processing, so you should always inspect the results. Default languages to sentenceCase are:
-     *
-     * - american
-     * - british
-     * - canadian
-     * - english
-     * - australian
-     * - newzealand
-     * - usenglish
-     * - ukenglish
-     * - en
-     * - eng
-     * - en-au
-     * - en-bz
-     * - en-ca
-     * - en-cb
-     * - en-gb
-     * - en-ie
-     * - en-jm
-     * - en-nz
-     * - en-ph
-     * - en-tt
-     * - en-us
-     * - en-za
-     * - en-zw
-     *
-     * If you pass an empty array, or `false`, no sentence casing will be applied (even when there's no language field).
-     */
-    sentenceCase?: string[] | boolean;
-    /**
-     * If you have sentence-casing on, you can independently choose whether quoted titles within a title are preserved as-is (true) or also sentence-cased(false)
-     */
-    sentenceCasePreserveQuoted?: boolean;
-    /**
-     * Some bibtex has titles in sentence case, or all-uppercase. If this is on, and there is a field that would normally have sentence-casing applied in which more words are all-`X`case
-     * (where `X` is either lower or upper) than mixed-case, it is assumed that you want them this way, and no sentence-casing will be applied to that field
-     */
-    guessAlreadySentenceCased?: boolean;
+export interface Options {
+    sentenceCase?: {
+        /**
+         * BibTeX files are expected to store title-type fields in Sentence Case, where other reference managers (such as Zotero) expect them to be stored as Sentence case. When there is no language field, or the language field
+         * is one of the languages (case insensitive) passed in this option, the parser will attempt to sentence-case title-type fields as they are being parsed. This uses heuristics and does not employ any kind of natural
+         * language processing, so you should always inspect the results. Default languages to sentenceCase are:
+         *
+         * - american
+         * - british
+         * - canadian
+         * - english
+         * - australian
+         * - newzealand
+         * - usenglish
+         * - ukenglish
+         * - en
+         * - eng
+         * - en-au
+         * - en-bz
+         * - en-ca
+         * - en-cb
+         * - en-gb
+         * - en-ie
+         * - en-jm
+         * - en-nz
+         * - en-ph
+         * - en-tt
+         * - en-us
+         * - en-za
+         * - en-zw
+         *
+         * If you pass an empty array, or `false`, no sentence casing will be applied (even when there's no language field).
+         */
+        langids?: string[] | boolean;
+        /**
+          * By default, `langid` and `hyphenation` are used to determine whether an entry should be sentence-cased, but some sources (ab)use the `language` field
+          * for this. If you turn on this option, this field will also be taken into account as a source for `langid`.
+          */
+        language?: boolean;
+        /**
+         * Some bibtex files will have titles in sentence case, or all-uppercase. If this is on, and there is a field that would normally have sentence-casing applied in which more words are all-`X`case
+         * (where `X` is either lower or upper) than mixed-case, it is assumed that you want them this way, and no sentence-casing will be applied to that field
+         */
+        guess?: boolean;
+        /**
+         * Capitalize sub-sentences after colons. Given the input title "Structured Interviewing For OCB: Construct Validity, Faking, And The Effects Of Question Type":
+         * - when `true`, sentence-cases to "Structured interviewing for OCB: Construct validity, faking, and the effects of question type"
+         * - when `false`, sentence-cases to "Structured interviewing for OCB: construct validity, faking, and the effects of question type"
+         */
+        subSentence?: boolean;
+        /**
+         * If you have sentence-casing on, you can independently choose whether quoted titles within a title are preserved as-is (true) or also sentence-cased(false)
+         */
+        preserveQuoted?: boolean;
+    };
     /**
-     * translate braced parts of text into a case-protected counterpart; uses the [[MarkupMapping]] table in `markup`. Default == true == as-needed.
+     * translate braced parts of text into a case-protected counterpart; Default == true == as-needed.
      * In as-needed mode the parser will assume that words that have capitals in them imply "nocase" behavior in the consuming application. If you don't want this, turn this option on, and you'll get
      * case protection exactly as the input has it
      */
     caseProtection?: 'as-needed' | 'strict' | boolean;
     /**
-     * The parser can change TeX markup (\\textsc, \\emph, etc) to a text equivalent. The defaults are HTML-oriented, but you can pass in your own configuration here
-     */
-    markup?: MarkupMapping;
-    /**
-     * By default, when an unexpected parsing error is found (such as a TeX command which the parser does not know about), the parser will throw an error. You can pass a function to handle the error instead,
-     * where you can log it, display it, or even still throw an error
-     */
-    errorHandler?: false | ((err: Error) => void);
-    /**
-     * By default, when a TeX command is encountered which the parser does not know about, the parser will throw an error. You can pass a function here to return the appropriate AST for the command.
+     * By default, when a TeX command is encountered which the parser does not know about, the parser will throw an error. You can pass a function here to return the appropriate text output for the command.
      */
-    unknownCommandHandler?: false | ((node: bibtex.RegularCommand) => Node);
+    unsupported?: 'ignore' | unsupportedHandler;
     /**
      * 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.
      */
     verbatimFields?: (string | RegExp)[];
-    /**
-     * Some commands 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.
-     */
-    verbatimCommands?: 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.
      */
-    unnestFields?: string[];
-    unnestMode?: 'preserve' | 'unwrap';
+    removeOuterBraces?: string[];
     /**
-     * Some note-like fields may have more rich formatting. If listed here, more HTML conversions will be applied.
+     * Specify parsing mode for specific fields
      */
-    htmlFields?: string[];
+    fieldMode?: Record<string, ParseMode>;
     /**
      * If this flag is set entries will be returned without conversion of LaTeX to unicode equivalents.
      */
@@ -263,20 +118,58 @@ export interface ParserOptions {
     /**
      * BibTeX files may have abbreviations in the journal field. If you provide a dictionary, journal names that are found in the dictionary are replaced with the attached full name
      */
-    unabbreviate?: Record<string, string>;
+    unabbreviations?: boolean | Record<string, string>;
     /**
      * Apply crossref inheritance
      */
     applyCrossRef?: boolean;
 }
-/**
- * parse bibtex. This will try to convert TeX commands into unicode equivalents, and apply `@string` expansion
- */
-export declare function parse(input: string, options?: ParserOptions): Bibliography;
-export declare function ast(input: string, options?: ParserOptions, clean?: boolean): Node[];
-export declare const promises: {
-    parse(input: string, options?: ParserOptions): Promise<Bibliography>;
+interface Creator {
+    name?: string;
+    lastName?: string;
+    firstName?: string;
+    prefix?: string;
+    suffix?: string;
+    initial?: string;
+    useprefix?: boolean;
+    juniorcomma?: boolean;
+}
+interface Entry {
+    type: string;
+    key: string;
+    fields: {
+        author?: Creator[];
+        bookauthor?: Creator[];
+        collaborator?: Creator[];
+        commentator?: Creator[];
+        director?: Creator[];
+        editor?: Creator[];
+        editora?: Creator[];
+        editorb?: Creator[];
+        editors?: Creator[];
+        holder?: Creator[];
+        scriptwriter?: Creator[];
+        translator?: Creator[];
+        keywords?: string[];
+        institution?: string[];
+        publisher?: string[];
+        origpublisher?: string[];
+        organization?: string[];
+        location?: string[];
+        origlocation?: string[];
+        [key: string]: number | string | string[] | Creator[];
+    };
+}
+export declare const FieldMode: {
+    creator: string[];
+    title: string[];
+    verbatim: (string | RegExp)[];
+    richtext: string[];
+    commalist: string[];
+    literallist: string[];
 };
-export { chunker };
-export { jabref };
+type ParseMode = keyof typeof FieldMode | 'literal';
+type unsupportedHandler = (node: Node, tex?: string, entry?: Entry) => string | undefined;
+export declare function parse(input: string, options?: Options): Bibliography;
+export declare function parseAsync(input: string, options?: Options): Promise<Bibliography>;
 //# sourceMappingURL=index.d.ts.map