BibInternal provides the canonical bibliography model shared by the bibliography stack.

It keeps the core entry types, validation rules, diagnostics, and lossless document containers in one place so parsers and exporters can share the same data model.

const entries

List of possible entries (currently based on bibtex). Keep it sorted for readability.

const fields = [
    :address,
    :annote,
    :archivePrefix,
    :author,
    :booktitle,
    :chapter,
    :crossref,
    :edition,
    :editor,
    :eprint,
    :howpublished,
    :institution,
    :isbn,
    :issn,
    :journal,
    :key,
    :month,
    :note,
    :number,
    :organization,
    :pages,
    :primaryClass,
    :publisher,
    :school,
    :series,
    :title,
    :type,
    :volume,
    :year
]

List of possible fields (currently based on bibtex). Keep it sorted for readability

const maxfieldlength

For output formatting purpose, for instance, export to BibTeX format.

const rules = Dict([
    "article"       => ["author", "journal", "title", "year"]
    "book"          => [("author", "editor"), "publisher", "title", "year"]
    "booklet"       => ["title"]
    "eprint"        => ["author", "eprint", "title", "year"]
    "inbook"        => [("author", "editor"), ("chapter", "pages"), "publisher", "title", "year"]
    "incollection"  => ["author", "booktitle", "publisher", "title", "year"]
    "inproceedings" => ["author", "booktitle", "title", "year"]
    "manual"        => ["title"]
    "mastersthesis" => ["author", "school", "title", "year"]
    "misc"          => []
    "phdthesis"     => ["author", "school", "title", "year"]
    "proceedings"   => ["title", "year"]
    "techreport"    => ["author", "institution", "title", "year"]
    "unpublished"   => ["author", "note", "title"]
])

List of BibTeX rules bases on the entry type. A field value as a singleton represents a required field. A pair of values represents mutually exclusive required fields.

Base type for declarative and custom bibliography validation rules.

Third-party packages may subtype this type and extend validate_rule without modifying BibInternal's canonical field model.

Abstract entry supertype.

struct Access
    doi::String
    howpublished::String
    url::String
end

Store the online access of an entry as a String. Handles the fields doi and url and the arXiv entries. For additional fields or entries, please fill an issue or make a pull request.

Access(fields::Fields)

Construct the online access information based on the entry fields.

AlternativeRequiredField(names)

A requirement where at least one of the listed fields must be present.

BibliographyDocument

Lossless document-level container returned by parsers that need to preserve ordering, non-entry blocks, and parse diagnostics.

struct Date
    day::String
    month::String
    year::String
end

Store the date information as day, month, and year.

Date(fields::Fields)

Construct the date information based on the entry fields.

Diagnostic

Structured message attached to a bibliography document, raw entry, or field. The suggestion field is intentionally textual for now so command line tools and future GUIs can present a friendly next action without depending on a fix engine.

@enum DiagnosticSeverity diagnostic_info diagnostic_warning diagnostic_error

Severity level for structured diagnostics emitted while parsing, normalizing, or validating bibliography data.

struct Entry <: AbstractEntry
    access::Access
    authors::Names
    booktitle::String
    date::Date
    editors::Names
    eprint::Eprint
    id::String
    in::In
    fields::Dict{String,String}
    note::String
    title::String
    type::String
end

Generic Entry type. If some construction rules are required, it should be done beforehand. Check bibtex.jl as the example of rules implementation for BibTeX format.

Entry(id::String, fields::Fields)

Construct an entry with a unique id and a list of Fields.

EntryRule

Validation rule for one source entry type.

EntryRuleSet

Versioned collection of entry validation rules for a bibliography format. The aliases dictionary applies before entry-specific aliases, which makes it easy to share canonical field names across the whole format.

struct Eprint
    archive_prefix::String
    eprint::String
    primary_class::String
end

Store the information related to arXiv eprint format.

Eprint(fields::Fields)

Construct the eprint arXiv information based on the entry fields. Handle old and current arXiv format.

FieldCardinalityRule(name, minimum=0, maximum=nothing)

Constrain the number of values in a structured field. Flat string values count as one; parsers that preserve multiple values should pass a collection.

FieldSpec

Format-independent description of a canonical bibliography field. Parsers and exporters own source-format mappings; this catalog only describes the semantic field exposed to downstream consumers.

FieldTypeRule(name, value_kind)

Require a populated field to match a canonical value kind such as :integer, :year, :date, or :uri.

Fields = Dict{String, String}. Stores the fields name => value of an entry.

ForbiddenField(name)

Reject a field when it has a value.

struct In
    address::String
    chapter::String
    edition::String
    institution::String
    isbn::String
    issn:String
    journal::String
    number::String
    organization::String
    pages::String
    publisher::String
    school::String
    series::String
    volume::String
end

Store all the information related to how an entry was published.

In(fields::Fields)

Construct the information of how an entry was published based on its fields

LosslessEntry

Pair a stable canonical Entry with the raw source entry and diagnostics used to build it. This keeps existing consumers on Entry while enabling parsers and writers to preserve source information.

MutuallyExclusiveFields(names)

Allow at most one populated field in the group.

Name(str::String)

Decompose without ambiguities a name as particle (optional) last, junior (optional), first middle (optional) based on BibTeX possible input. As for BibTeX, the decomposition of a name in the form of first last is also possible, but ambiguities can occur.

RawBlock

Top-level source block that is not necessarily a bibliographic entry, such as a BibTeX comment, preamble, string definition, or free text.

RawEntry

Lossless representation of a parsed bibliography entry. kind is the source entry type, key is the citation key when the format has one, and fields preserves source order.

RawField

Lossless representation of a parsed field.

name and value contain the interpreted field pair, while raw preserves the source representation. span and diagnostics are optional metadata collected by parsers that keep source locations.

RequiredField(name)

A single required field in an entry rule.

RuleContext

Context passed to validate_rule. Custom rule packages can extend validate_rule(rule, fields, context) for their own AbstractBibliographyRule subtype.

RuleProfile

Named and versioned set of composable bibliography rules. A nothing supported_entry_types value means that the profile accepts every entry type; it is used for product or institution overlays.

SourceSpan

Optional source location for raw bibliography content and diagnostics. The span uses 1-based inclusive coordinates.

ValidationResult

Result of validating one entry or a bibliography document. ok is true when no diagnostic has diagnostic_error severity.

Base.isless(a::BibInternal.Date,b::BibInternal.Date)::Bool

Function to check for a < b on BibInternal.Date data types.

This function will throw an ArgumentError if the year can not parsed into Int. If it is not possible to parse month or day to Int those entries will be silently ignored for comparison. This function will not check if the date fields are given in a correct format all fields are parsed into and compared as Int (no checking if date format is correct or valid!).

Base.isless(a::BibInternal.Name,b::BibInternal.Name)::Bool

Function to check for a < b on BibInternal.Name data types.

This function will check the fields last, first and middle in this order of priority. The other fields are ignored for now. The field comparison is done by string comparison no advanced alphabetizing rules are used for now.

arxive_url(fields::Fields)

Make an arxiv url from an eprint entry. Work with both old and current arxiv BibTeX format.

canonical(entry)

Return the canonical Entry view of an entry-like object.

canonical_field_specs()

Return the canonical field catalog in stable display order.

check_entry(fields::Fields)

Check the validity of the fields of a BibTeX entry.

compose_profiles(profiles...; name)

Compose format, product, and institution profiles. Constraints accumulate. Conflicts are retained as error diagnostics on the resulting profile rather than being resolved through precedence.

diagnostics(entry)

Return the diagnostics attached to a lossless entry or document.

entry_fields(entry::Entry)

Convert a canonical Entry back into a flat field dictionary. This is the bridge used by validation and format conversion code.

erase_spaces(str::String)

Erase extra spaces, i.e. r"[ ]+", from str and return a new string.

field_spec(name)

Return the canonical specification for name, or nothing for a source-specific extra field.

get_delete!(fields::Fields, key::String)

Get the value of a field and delete it afterward.

handle_validation(result::ValidationResult, level)

Apply a validation policy. :error raises on errors, :warn logs warnings, and :none returns the result untouched.

make_biblatex_entry(id::String, fields::Fields; check = :error)

Make an entry using BibLaTeX field aliases and date conventions while preserving source-specific fields that are not part of the canonical view.

make_bibtex_entry(id::String, fields::Fields)

Make an entry if the entry follows the BibTeX guidelines. Throw an error otherwise.

names(str::String)

Decompose into parts a list of names in BibTeX compatible format. That is names separated by and.

profile_field_names(profile, entry_type)

Return fields made available by the profile for an entry type. Custom fields remain legal unless a profile explicitly forbids them.

profile_rules(profile, entry_type)

Return global rules followed by rules for the normalized entry type.

raw(entry)

Return the raw source representation attached to a lossless entry.

space(field::Symbol)

Return the amount of spaces needed to export entries, for instance to BibTeX format.

validate(entry::Entry, ruleset::EntryRuleSet = BIBTEX_RULESET)

Validate a canonical entry against a ruleset.

validate(entry::LosslessEntry, ruleset::EntryRuleSet = BIBTEX_RULESET)

Validate the canonical view of a lossless entry.

validate(document::BibliographyDocument, ruleset::EntryRuleSet)

Validate every entry stored in a lossless bibliography document.

validate_fields(fields::AbstractDict, ruleset::EntryRuleSet; id::AbstractString = "")

Validate one field dictionary against a ruleset and return structured diagnostics. The input dictionary can come from a parser or from a canonical entry converted back to fields.

validate_fields(fields, profile; id="")

Validate one entry against a composed rule profile.