Crate hayagriva

Hayagriva provides a YAML-backed format and data model for various bibliography items as well as a CSL processor formatting both in-text citations and reference lists based on these literature databases.

The crate is intended to assist scholarly writing and reference management and can be used both through a CLI and an API.

Below, there is an example of how to parse a YAML database and get a Modern Language Association-style citation.

Supported styles

Hayagriva supports all styles provided in the official Citation Style Language repository, currently over 2,600. You must provide your own style file, which can be obtained there.

Usage

use hayagriva::io::from_yaml_str;

let yaml = r#"
crazy-rich:
    type: Book
    title: Crazy Rich Asians
    author: Kwan, Kevin
    date: 2014
    publisher: Anchor Books
    location: New York, NY, US
"#;

// Parse a bibliography
let bib = from_yaml_str(yaml).unwrap();
assert_eq!(bib.get("crazy-rich").unwrap().date().unwrap().year, 2014);

// Format the reference
use std::fs;
use hayagriva::{
    BibliographyDriver, BibliographyRequest, BufWriteFormat,
    CitationItem, CitationRequest,
};
use hayagriva::citationberg::{LocaleFile, IndependentStyle};

let en_locale = fs::read_to_string("tests/data/locales-en-US.xml").unwrap();
let locales = [LocaleFile::from_xml(&en_locale).unwrap().into()];

let style = fs::read_to_string("tests/data/art-history.csl").unwrap();
let style = IndependentStyle::from_xml(&style).unwrap();

let mut driver = BibliographyDriver::new();

for entry in bib.iter() {
    let items = vec![CitationItem::with_entry(entry)];
    driver.citation(CitationRequest::from_items(items, &style, &locales));
}

let result = driver.finish(BibliographyRequest {
    style: &style,
    locale: None,
    locale_files: &locales,
});

for cite in result.citations {
    println!("{}", cite.citation.to_string())
}

To format entries, you need to wrap them in a CitationRequest. Each of these can reference multiple entries in their respective CitationItems. Use these with a BibliographyDriver to obtain formatted citations and bibliographies.

If the default features are enabled, Hayagriva supports BibTeX and BibLaTeX bibliographies. You can use io::from_biblatex_str to parse such bibliographies.

Should you need more manual control, the library’s native Entry struct also offers an implementation of the From<&biblatex::Entry>-Trait. You will need to depend on the biblatex crate to obtain its Entry. Therefore, you could also use your BibLaTeX content like this:

use hayagriva::Entry;
let converted: Entry = your_biblatex_entry.into();

If you do not need BibLaTeX compatibility, you can use Hayagriva without the default features by writing this in your Cargo.toml:

[dependencies]
hayagriva = { version = "0.2", default-features = false }

Selectors

Hayagriva uses a custom selector language that enables you to filter bibliographies by type of media. For more information about selectors, refer to the selectors.md file. While you can parse user-defined selectors using the function Selector::parse, you may instead want to use the selector macro to avoid the run time cost of parsing a selector when working with constant selectors.

use hayagriva::select;
use hayagriva::io::from_yaml_str;

let yaml = r#"
quantized-vortex:
    type: Article
    author: Gross, E. P.
    title: Structure of a Quantized Vortex in Boson Systems
    date: 1961-05
    page-range: 454-477
    serial-number:
        doi: 10.1007/BF02731494
    parent:
        issue: 3
        volume: 20
        title: Il Nuovo Cimento
"#;

let entries = from_yaml_str(yaml).unwrap();
let journal = select!((Article["date"]) > ("journal":Periodical));
assert!(journal.matches(entries.nth(0).unwrap()));

There are two ways to check if a selector matches an entry. You should use Selector::matches if you just want to know if an item matches a selector and Selector::apply to continue to work with the data from parents of a matching entry. Keep in mind that the latter function will return Some even if no sub-entry was bound / if the hash map is empty.

Re-exports

• pub use citationberg;

Modules

• archive
  Optional archive of included CSL styles.
• io
  Reading and writing YAML bibliographies.
• lang
  Language-dependant string transformations.
• types
  Base types for the bibliography items and their content.

Macros

• select
  Construct a Selector.

Structs

• BibliographyDriver
  This struct formats a set of citations according to a style.
• BibliographyRequest
  A request to render a bibliography. Use with BibliographyDriver::finish.
• CitationItem
  A reference to an crate::Entry within a CitationRequest.
• CitationRequest
  A citation request. A citation can contain references to multiple items.
• Elem
  A container for elements with useful methods.
• ElemChildren
  A container for element children with useful methods.
• Entry
  A citable item in a bibliography.
• Formatted
  A piece of formatted text.
• Formatting
  Some formatting information.
• Library
  A collection of bibliographic entries.
• Rendered
  The result of BibliographyDriver::finish.
• RenderedBibliography
  A fully rendered bibliography.
• RenderedCitation
  A fully rendered citation.
• SpecificLocator
  This struct allows to add context to where the information in a cite is found in the source.

Enums

• Brackets
  Describes the bracket preference of a citation style.
• BufWriteFormat
  The format with which to write an element.
• CitePurpose
  For what purpose to generate a citation.
• ElemChild
  Various formattable elements.
• ElemMeta
  Which CSL construct created an element.
• LocatorPayload
  The type of content a cs:text element should yield for a locator.
• Selector
  A selector used to filter bibliographies and match on entries.
• SelectorError
  The error when parsing a selector expression fails.

Functions

• standalone_citation
  Create a new citation with the given items. Bibliography-wide disambiguation and some other features will not be applied.