Bibliography is the high-level bibliography interface for the Humans of Julia stack.

It combines BibParser.jl and BibInternal.jl into a single package that can import, validate, filter, sort, and export bibliographic data.

const sorting_rules = Dict{Symbol, Vector{Symbol}}(
				:nty  => [:authors; :title; :date],
				:nyt  => [:authors; :date; :title],
				:nety => [:authors; :editors; :title; :date],
				:neyt => [:authors; :editors; :date; :title],

:y => [:date], );

Implemented sorting rules for bibliography entry sorting.

See also sort_bibliography!.

Publication

A structure to store all the information necessary for web export.

Publication(entry)

Construct a Publication for the lightweight web projection.

access_to_bibtex!(fields, a)

Transform the how-to-access field to a BibTeX string.

bibliography_entries(bibliography)

Return an ordered dictionary of canonical entries keyed by entry id.

bibtex_to_web(source::String)

Convert a BibTeX file to the lightweight web projection returned by export_web.

export_cff(e::Entry, destination::String="CITATION.cff", version::String="1.2.0", add_preferred::Bool=true) -> Dict{String, Any}

Export an Entry to a CFF file (default is CITATION.cff).

compose_rule_profiles(format, overlays...; name)

Compose a destination format profile with product, project, or institution overlays.

date_to_bibtex!(fields, date)

Convert a date to a BibTeX string.

eprint_to_bibtex!(fields, eprint)

Convert eprint information to a BibTeX string.

export_biblatex(bibliography)

Export a bibliography to BibLaTeX format.

export_bibtex(target, bibliography)

Export a bibliography to BibTeX format.

export_bibtex(bibliography)

Export a bibliography to a BibTeX string.

export_bibtex(e::Entry)

Export an Entry to a BibTeX string.

export_cff(e::Entry; destination::String = "CITATION.cff",
           version::String = "1.2.0", add_preferred::Bool = true)

Export an Entry to a CFF file and return the generated dictionary.

export_cff_collection(bibliography; destination, version="1.2.0",
                      add_preferred=true) -> Vector{String}

Export every bibliography entry as an independent, specification-compliant CFF document in destination. Files are named <entry-id>.cff; the returned vector contains their paths in bibliography order.

export_csl(args...)

Placeholder for the CSL writer extension. Install the corresponding extension package to enable it.

export_endnote(args...)

Placeholder for the EndNote writer extension. Install the corresponding extension package to enable it.

export_mods(args...)

Placeholder for the MODS writer extension. Install the corresponding extension package to enable it.

export_web(bibliography::DataStructures.OrderedDict{String,BibInternal.Entry})

Export a bibliography in internal format to a lightweight web projection. The same representation is also used by DocumenterCitations.jl.

field_to_bibtex(key, value)

Convert an entry field to BibTeX format.

fileio_load(file; check)
fileio_load(stream; check)

The FileIO interface to import a BibTeX file or parse a BibTeX string and convert it to the internal bibliography format. The check keyword argument can be set to :none (or nothing), :warn, or :error to raise appropriate logs.

fileio_save(file, data)
fileio_save(stream, data)

Export a bibliography as a BibTeX string to a file or stream.

filter_bibliography(bibliography, predicate)

Filter entries with predicate(entry), preserving document metadata when the input is a lossless document.

import_bibtex(input; check = :none)

Import a BibTeX file or parse a BibTeX string and convert it to the internal bibliography format. The check keyword argument can be set to :none (or nothing), :warn, or :error to raise appropriate logs.

import_cff(input; id="") -> Entry

Import a CFF file and convert it to the internal bibliography format.

When no identifier is supplied, a deterministic internal identifier is derived from the CFF title and release year. CFF itself has no citation-key field.

import_cff_collection(source) -> OrderedDict{String, Entry}

Import a collection of independent CFF documents. source can be a directory containing .cff files or a vector of file paths. Each file stem becomes the entry id, making directory export/import round-trips preserve bibliography keys without adding non-standard fields to the CFF documents.

in_to_bibtex!(fields::BibInternal.Fields, i::BibInternal.In)

Convert the "published in" information to a BibTeX string.

int_to_spaces(n)

Make a string of n spaces.

na_if_empty(str::AbstractString) -> AbstractString

Use placeholder value if string param is empty.

name_to_string(name::BibInternal.Name)

Convert a name in an Entry to a string.

names_to_strings(names)

Convert a collection of names to a BibTeX string.

read_bibliography(input; format = :auto, check = :error)

Read a bibliography from a path, stream, or string and return a lossless BibInternal.BibliographyDocument.

recursive_isless(a::Entry, b::Entry, fields::Tuple{Symbol},
                 depth::Int = 0)

Helper function for sort_bibliography!.

This function allows recursive checking if a < b with descending importance. The importance set for the comparison is defined by the argument fields. This argument is a tuple consisting of symbols denoting the fields of the data type BibInternal.Entry. The ordering implies the importance.

The depth argument is purely for iterating/recursive purposes.

rule_profile(format)

Return the canonical validation profile associated with a supported bibliography format. Exchange-format profiles deliberately validate the canonical input required by the current exporter; source schema validation remains the parser's responsibility.

select(
    bibliography::DataStructures.OrderedDict{String,Entry},
    selection::Vector{String};
    complementary::Bool = false
    )

Select a subset of bibliography entries by key.

If complementary is true, the keys in selection are excluded instead of kept.

sort_bibliography!(
    bibliography::DataStructures.OrderedDict{String,Entry},
    sorting_rule::Symbol = :key
    )

Sorts the bibliography in place.

The sorting order can be set by specifying the sorting_rule. The sorting is implemented via isless() functions. For detailed insight have a look at the isless() implementation of Julia and BibInternal.jl.

Supported symbols for sorting_rule are:

• :key (default): sort by bibliography keys e.g. BibTeX keys or :id
• the sorting rules defined in sorting_rules

validate(bibliography; ruleset=nothing, profile=nothing)

Validate a bibliography document or collection of entries and return a BibInternal.ValidationResult. With neither keyword, a document uses its format profile. ruleset remains available for compatibility; new consumers should use composable profile values.

write_bibliography([target], bibliography; format = :BibTeX, mode = :normalized)

Write or return a bibliography string. With mode = :original or mode = :preserved, a lossless document returns its original source when available. With mode = :normalized, entries are emitted from the canonical view.

xcite(entry)

Format the BibTeX cite output of an Entry for web export.

xfile(entry)

Format the downloadable path of an Entry file for web export.

xin(entry)

Format the appears-in field of an Entry for web export.

xlabels(entry)

Format the labels of an Entry for web export.

xlink(entry)

Format the download link of an Entry for web export.

xnames(entry, editors = false; names = :full)

Format the name of an Entry for web export.

Arguments:

• entry: an entry
• editors: true if the name describes editors
• names: :full (full names) or :last (last names + first name abbreviation)

xtitle(entry

Format the title of an Entry for web export.

xyear(entry)

Format the year of an Entry for web export.