Crate serde_bibtex

Serde BibTex

This crate is under active development and the public API may change substantially on every minor version change. The (de)serialization API is relatively stable, but some of the publicly-exposed internal state, particularly concerning error handling, may change or be removed in the future. Until this is stabilized, use at your own risk!

The .bib format is a common format for storing bibliographic data originally popularized by the BibTex bibliography management software.

@article{key,
  title = {Title},
  author = {One, Author},
  year = 2024,
}

This module provides a serde interface for deserializing .bib files into strongly typed data structures. The interface is intentionally flexible to support a variety of use-cases in a first-class manner.

Unfortunately, .bib files do not have a well-defined syntax and while there are generally agreed-upon conventions for syntax, different programs will treat your input in subtly different ways. Visit the syntax module for more information as well as an explicit pest grammar for the file format accepted by this crate.

Basic Deserialization

The most convenient entrypoint is to construct a Deserializer and use the API provided by into_iter_regular_entry. For more complex deserialization use-cases, and a full description of available deserialization features, see the documentation for the de module.

use serde::Deserialize;
use serde_bibtex::de::Deserializer;
use std::collections::BTreeMap;

#[derive(Debug, PartialEq, Deserialize)]
struct Record {
    entry_type: String,
    entry_key: String,
    fields: BTreeMap<String, String>
}

let input = r#"
    @string{t = {Title}}
    @article{key,
      title = t,
      author = {One, Author},
      year = 2024,
    }
"#;

let de = Deserializer::from_str(input);
let mut entry_iter = de.into_iter_regular_entry::<Record>();

let expected_fields = BTreeMap::from([
    ("title".into(), "Title".into()),
    ("author".into(), "One, Author".into()),
    ("year".into(), "2024".into()),
]);
let expected = Record {
    entry_type: "article".into(),
    entry_key: "key".into(),
    fields: expected_fields
};

assert!(matches!(
    entry_iter.next(),
    Some(Ok(record)) if record == expected,
));

Basic Serialization

The most convenient entrypoint is to use one of the convenience methods, such as to_string or to_writer, or one of the ‘compact’ or ‘unchecked’ variants. Since BibTeX is a relatively rigid output format, your types must be in a relatively rigid format. For examples, and for a detailed description of the conventions used for serialization, see the ser module.

use std::collections::BTreeMap;
use serde::Serialize;
use serde_bibtex::to_string;

#[derive(Debug, Serialize)]
struct Record {
    entry_type: String,
    entry_key: String,
    fields: BTreeMap<String, String>,
}

let mut fields = BTreeMap::new();
fields.insert("author".to_owned(), "Last, First".to_owned());
fields.insert("year".to_owned(), "2023".to_owned());

let bibliography = vec![
    Record {
        entry_type: "article".to_owned(),
        entry_key: "FirstLast2023".to_owned(),
        fields,
    },
];

let output = to_string(&bibliography).unwrap();

assert_eq!(
    output,
    "@article{FirstLast2023,\n  author = {Last, First},\n  year = {2023},\n}\n"
);

Representation and validation of types

The token module contains a variety of types which can be used to represent components of a BibTeX bibliography in your own code. This module also contains a variety of methods for checking if some given input satisfies the requirements of a certain BibTeX component.

use serde_bibtex::token::{check_variable, is_variable, TokenError, Variable};

// `var` is a valid variable name
assert!(Variable::new("var").is_ok());

// A variable cannot contain a character in `{}(),=\#%"`
assert_eq!(check_variable("var{"), Err(TokenError::InvalidChar('{')));

// A variable cannot be empty
assert!(!is_variable(""));

Re-exports

pub use crate::error::Error;

pub use crate::error::Result;

Modules

de

Deserializer implementation

entryentry

Built-in types

error

Errors for serialization and deserialization.

ser

Serializer implementation

syntaxsyntax

Description of the bibliography syntax

token

Types to represent various components of a bibliography.

Structs

MacroDictionary

A dictionary used to expand uncaptured macros during deserialization.

SliceReader

StrReader

Traits

Read

A trait to represent a type which can be parsed as BibTeX.

Functions

from_bytes

Deserialize an instance of type D from bytes of BibTeX.

from_str

Deserialize an instance of type D from string of BibTeX.

to_string

Serialize as BibTeX into a string.

to_string_compact

Serialize the given data structure as BibTeX into a string with no extra whitespace.

to_string_unchecked

Serialize the given data structure as BibTeX into a string without checking that the output is valid BibTeX.

to_vec

Serialize as BibTeX into a byte vector.

to_vec_compact

Serialize as BibTeX into a byte vector with no extra whitespace.

to_vec_unchecked

Serialize as BibTeX into a byte vector without checking that the output is valid BibTeX.

to_writer

Serialize as BibTeX into the I/O stream.

to_writer_compact

Serialize as BibTeX into the I/O stream with no extra whitespace.

to_writer_unchecked

Serialize as BibTeX into the I/O stream without checking that the output is valid BibTex.