Parse Bibliographies

Library parses BibTeX and BibLaTeX bibliography text into normalized Entry objects.

Python

import refkit as rk

source = (
    "@article{doe2024, title={Fast Citations}, journal={Citation Tests}, volume={12}, year={2024}}"
)
library = rk.Library.parse_bibtex(source)
print(library.get("doe2024").title)

TypeScript

import * as rk from "refkit-js";

const source = "@article{doe2024, title={Fast Citations}, journal={Citation Tests}, volume={12}, year={2024}}";
const library = rk.Library.parseBibtex(source);
console.log(library.get("doe2024")!.title);

Fast Citations

TypeScript examples run in Node.js after installation. In a browser, initialize RefKit before parsing. The remaining examples continue with library.

For Hayagriva YAML, a bibliography format with nested entry relationships, use Library.parse_yaml(source) in Python or Library.parseYaml(source) in TypeScript.

Inspect entries

Python

print(len(library))
print("doe2024" in library)

entry = library["doe2024"]
print(entry.key, entry.entry_type, entry.title)

TypeScript

console.log(library.size);
console.log(library.has("doe2024"));

const entry = library.get("doe2024")!;
console.log(entry.key, entry.entryType, entry.title);

get(key) returns None in Python or null in TypeScript for a missing key. Python indexing raises KeyError when the key is absent. get_many(keys) / getMany(keys) preserves the requested order and raises when a requested key is absent.

Use values() for normalized entries in library order. is_empty() / isEmpty() checks whether the library contains any entries.

Project records

Library.project returns a list of Python dictionaries or an array of TypeScript objects. Select fields and optionally limit and order the entries:

Python

rows = library.project(["key", "entry_type", "title", "date", "doi", "volume"])
selected_rows = library.project(["key", "title"], keys=["doe2024"])
print(selected_rows[0]["title"])

TypeScript

const rows = library.project(["key", "entryType", "title", "date", "doi", "volume"]);
const selectedRows = library.project(["key", "title"], { keys: ["doe2024"] });
console.log(selectedRows[0]!.title);

type is an alias for the entry type under that output key. Title, date, DOI, and volume values can be None / null. Data Shapes defines the normalized fields.

Select by bibliography structure

Library.select uses Hayagriva selectors to match normalized entries and their parent relationships:

Python

periodical_articles = library.select("article > periodical[volume]")
print([entry.key for entry in periodical_articles])

TypeScript

const periodicalArticles = library.select("article > periodical[volume]");
console.log(periodicalArticles.map(entry => entry.key));

This selector returns doe2024, whose periodical parent has a volume. Read Selectors for the grammar and result behavior.

Read a file

Python's path methods and the Node.js filesystem helpers select the parser from the extension. These examples read an existing references.bib file:

Python

file_library = rk.Library.read("references.bib")
print(file_library.keys())

TypeScript

import { readLibrary } from "refkit-js/node";

const fileLibrary = await readLibrary("references.bib");
console.log(fileLibrary.keys());

Extension	Input
.bib	BibTeX or BibLaTeX source.
.yaml, .yml	Hayagriva bibliography YAML.

RefKit decodes UTF-8 first. A file that requires the Windows-1252-compatible fallback receives a parser diagnostic so the encoding decision stays visible.

Keep recoverable entries

Report recovery keeps entries that can be parsed and records diagnostics beside them:

Python

recovered = rk.Library.parse_bibtex(source + "\n@book{broken", recovery="report")
for diagnostic in recovered.diagnostics:
    print(diagnostic["code"], diagnostic["message"])

TypeScript

const recovered = rk.Library.parseBibtex(source + "\n@book{broken", { recovery: "report" });
for (const diagnostic of recovered.diagnostics) {
  console.log(diagnostic.code, diagnostic.message);
}

The recovered library retains doe2024 and reports the malformed trailing block. The file readers accept the same recovery option. Keep the default "error" policy when subsequent work requires an exact parse. Recovery explains the diagnostic fields and recovery boundaries.