package bibfmt

  1. Overview
  2. Docs
package bibfmt
Legend:
Page
Library
Module
Module type
Parameter
Class
Class type
Source

Module BibtexSource

BibTeX Parser and Pretty Printer

This module provides comprehensive functionality for parsing, manipulating, and formatting BibTeX bibliographic entries. It supports all standard BibTeX entry types and provides robust error handling for malformed input.

Sourcetype field_value =
  1. | QuotedStringValue of string
    (*

    Value enclosed in double quotes

    *)
  2. | BracedStringValue of string
    (*

    Value enclosed in curly braces

    *)
  3. | UnquotedStringValue of string
    (*

    Raw unquoted value

    *)
  4. | NumberValue of int
    (*

    Numeric value

    *)

Type representing different ways field values can be formatted in BibTeX

Sourcetype field = {
  1. name : string;
  2. value : field_value;
}

A BibTeX field with name and value

Sourcetype entry_type =
  1. | Article
    (*

    Journal article

    *)
  2. | Book
    (*

    Book with explicit publisher

    *)
  3. | Booklet
    (*

    Work that is printed and bound, but without a named publisher

    *)
  4. | Conference
    (*

    Conference proceedings entry

    *)
  5. | InBook
    (*

    Part of a book (chapter, section, etc.)

    *)
  6. | InCollection
    (*

    Part of a book having its own title

    *)
  7. | InProceedings
    (*

    Article in conference proceedings

    *)
  8. | Manual
    (*

    Technical documentation

    *)
  9. | MastersThesis
    (*

    Master's thesis

    *)
  10. | Misc
    (*

    Miscellaneous entry type

    *)
  11. | PhdThesis
    (*

    PhD thesis

    *)
  12. | Proceedings
    (*

    Conference proceedings

    *)
  13. | TechReport
    (*

    Technical report

    *)
  14. | Unpublished
    (*

    Document having an author and title, but not formally published

    *)

Standard BibTeX entry types

Sourcetype entry_content =
  1. | Field of field
    (*

    A field-value pair

    *)
  2. | EntryComment of string
    (*

    Comment within an entry

    *)

Content within a BibTeX entry

Sourcetype bibtex_entry = {
  1. entry_type : entry_type;
    (*

    Type of the entry

    *)
  2. citekey : string;
    (*

    Citation key/identifier

    *)
  3. contents : entry_content list;
    (*

    List of fields and comments

    *)
}

Complete BibTeX entry

Sourcetype bibtex_item =
  1. | Entry of bibtex_entry
    (*

    A bibliographic entry

    *)
  2. | Comment of string
    (*

    A comment line

    *)

Top-level BibTeX item

Sourcetype parse_error = {
  1. line : int;
  2. position : int;
  3. message : string;
}

Parse error information

Sourcetype parse_result = {
  1. items : bibtex_item list;
  2. errors : parse_error list;
}

Result of parsing with potential errors

Parsing Functions

Sourceval parse_bibtex : string -> bibtex_item list

parse_bibtex input parses a BibTeX string into a list of items. This function ignores parse errors and returns only successfully parsed items.

  • parameter input

    The BibTeX content as a string

  • returns

    List of parsed BibTeX items

Sourceval parse_bibtex_with_errors : string -> parse_result

parse_bibtex_with_errors input parses a BibTeX string and returns both successfully parsed items and any errors encountered.

  • parameter input

    The BibTeX content as a string

  • returns

    Parse result containing items and errors

Sourceval has_parse_errors : parse_result -> bool

has_parse_errors result checks if a parse result contains any errors.

  • parameter result

    The parse result to check

  • returns

    true if there are errors, false otherwise

Sourceval get_parse_errors : parse_result -> parse_error list

get_parse_errors result extracts the list of parse errors.

  • parameter result

    The parse result

  • returns

    List of parse errors

Sourceval get_parsed_items : parse_result -> bibtex_item list

get_parsed_items result extracts the list of successfully parsed items.

  • parameter result

    The parse result

  • returns

    List of parsed BibTeX items

Pretty Printers

Sourcetype options = {
  1. capitalize_names : bool;
  2. strict : bool;
  3. align_entries : bool;
}

Options for parsing and formatting BibTeX entries:

  • capitalize_names: If true, the field names are made upper capital.
  • strict: If true, parsing will be stricter and reject bibtex files with duplicate fields.
  • align_entries: If true, entries name and equal signs will be aligned for better readability.
Sourceval default_options : options

Default formatting options for BibTeX entries: capitalize_names: true, strict: false, align_entries: true

Sourceval pretty_print_bibtex : ?options:options -> bibtex_item list -> string

pretty_print_bibtex items formats a list of BibTeX items into a complete BibTeX string.

  • parameter options

    Formatting options

  • parameter items

    List of BibTeX items to format

  • returns

    Complete formatted BibTeX string

Sourceval clean_bibtex : ?options:options -> string -> string

clean_bibtex input parses and reformats BibTeX input, effectively cleaning and normalizing the formatting.

  • parameter options

    Formatting options (defaults to the value of default_options)

  • parameter input

    The BibTeX content to clean

  • returns

    Cleaned and reformatted BibTeX string

Utility Functions for custom formatting or editing

Sourceval string_of_entry_type : entry_type -> string

string_of_entry_type entry_type converts an entry type to its string representation (e.g., Article becomes "article").

Sourceval entry_type_of_string : string -> entry_type

entry_type_of_string str converts a string to an entry type.

  • parameter str

    The string representation (case-insensitive)

  • returns

    The corresponding entry type

Sourceval format_field_value : field_value -> string

format_field_value value formats a field value for output.

  • parameter value

    The field value to format

  • returns

    String representation of the value

Sourceval format_field_value_with_url_unescaping : string -> field_value -> string

format_field_value_with_url_unescaping field_name value formats a field value with URL unescaping and Unicode normalization applied. Special handling is applied to URL fields.

  • parameter field_name

    The name of the field (used to determine if URL processing is needed)

  • parameter value

    The field value to format

  • returns

    String representation with URLs unescaped if applicable

Sourceval format_field : bool -> field -> string

format_field field formats a complete field (name = value).

  • parameter field

    The field to format

  • returns

    String representation of the field

Sourceval format_entry_content : bool -> entry_content -> string

format_entry_content content formats entry content (field or comment).

  • parameter content

    The entry content to format

  • returns

    String representation of the content

Sourceval format_entry : options -> bibtex_entry -> string

format_entry entry formats a complete BibTeX entry.

  • parameter entry

    The entry to format

  • returns

    String representation of the entry

Sourceval format_bibtex_item : options -> bibtex_item -> string

format_bibtex_item item formats a BibTeX item (entry or comment).

  • parameter item

    The item to format

  • returns

    String representation of the item

Deduplication Functions

Sourcetype field_conflict = {
  1. field_name : string;
  2. values : (string * int) list;
    (*

    (value, entry_index) pairs

    *)
}

Type representing a field conflict between duplicate entries. Each value is paired with the index of the entry it came from.

Sourcetype duplicate_group = {
  1. entries : bibtex_entry list;
    (*

    The group of duplicate entries

    *)
  2. matching_keys : (string * string) list;
    (*

    Key-value pairs that match

    *)
  3. conflicts : field_conflict list;
    (*

    Fields that differ between entries

    *)
}

Type representing a group of duplicate entries identified by matching key fields

Sourceval find_duplicate_groups : ?keys:string list -> bibtex_entry list -> duplicate_group list

find_duplicate_groups ~keys entries identifies groups of duplicate entries without resolving them.

  • parameter keys

    List of field names to use for duplicate detection (default: ["title"; "author"; "year"]). Use "citekey" to match on citation keys.

  • parameter entries

    List of BibTeX entries to analyze

  • returns

    List of duplicate groups found

This is useful for inspecting duplicates before deciding how to handle them. Each group contains at least 2 entries that match on the specified keys.

Sourceval string_of_field_value : field_value -> string

string_of_field_value fv converts a field value to its string representation.

  • parameter fv

    The field value to convert

  • returns

    String representation of the field value

Sourceval make_field : string -> string -> entry_content

make_field name value creates a BibTeX field with the given name and value. The value is wrapped in braces.

  • parameter name

    Field name

  • parameter value

    Field value as a string

  • returns

    An entry_content Field with a BracedStringValue