Visus.BibTex 0.0.2-alpha

Visus.BibTex

A library for parsing and manipulating BibTex entries in .NET for use in Project Tiger.

Usage

Parsing

BibTex can be parsed from any TextReader, for instance a StringReader in the following example, and yields an enumeration of items of the requested type:

var bibtex = """
@Book{hershkovitz-62,
    author = "P. Hershkovitz",
    year = "1962",
    title = "Evolution of {Neotropical} cricetine rodents ({Muridae}) with special reference to the phyllotine group",
    series = "Fieldiana: Zoology",
    volume = "46",
    address = "Chicago",
    publisher = "Field Museum of Natural History"
}
""";
var item = BibTexParser.Parse(new StringReader(bibtex), BibTexParserOptions.Create()).Single();

BibItems

The library provides a Dictionary-based implementation of a BibTex entry in the form of the Visus.BibTex.BibItem class. However, callers can customise the parser to fill their own class by implementing Visus.BibTex.IBibItemBuilder for this class. Visus.BibTex.BibItemBuilder is the reference implementation for the default item type.

The BibItem allows for conversion to custom strings via IFormattable. The format string is split in two parts, the general format for the entry and the format for names (see below). Both parts are separated by a '.'. Possible format strings for the item are:

Note that if multiple conflicting formats are specified, the last one will be applied, i.e. "ts4" will use four spaces for indentation. The following example illustrates several formatting options:

var item = new BibItem(WellKnownTypes.InProceedings, "mueller:2022:power") {
    Author = [ new("Müller", "Christoph"), new("Heinemann", "Moritz"), new("Weiskopf", "Daniel"), new("Ertl", "Thomas") ],
    Title = "Power Overwhelming: Quantifying the Energy Cost of Visualisation",
    BookTitle = "Proceedings of the 2022 IEEE Workshop on Evaluation and Beyond – Methodological Approaches for Visualization (BELIV)",
    Month = "October",
    Year = "2022",
    Doi = "10.1109/BELIV57783.2022.00009",
    Pages = "38-46"
};


Console.WriteLine(item);

// Expected console output:
// @inproceedings{mueller:2022:power,
//    author = {Müller, Christoph and Heinemann, Moritz and Weiskopf, Daniel and Ertl, Thomas},
//    booktitle = {Proceedings of the 2022 IEEE Workshop on Evaluation and Beyond – Methodological Approaches for Visualization (BELIV)},
//    doi = {10.1109/BELIV57783.2022.00009},
//    month = {October},
//    pages = {38-46},
//    title = {Power Overwhelming: Quantifying the Energy Cost of Visualisation},
//    year = {2022}
// }


Console.WriteLine(item.ToString("C"));

// Expected console output:
// @inproceedings{mueller:2022:power, author = {Müller, Christoph and Heinemann, Moritz and Weiskopf, Daniel and Ertl, Thomas}, booktitle = {Proceedings of the 2022 IEEE Workshop on Evaluation and Beyond – Methodological Approaches for Visualization (BELIV)}, doi = {10.1109/BELIV57783.2022.00009}, month = {October}, pages = {38-46}, title = {Power Overwhelming: Quantifying the Energy Cost of Visualisation}, year = {2022}}


Console.WriteLine(item.ToString("cq"));

// Expected console output:
// @inproceedings{mueller:2022:power,author="Müller, Christoph and Heinemann, Moritz and Weiskopf, Daniel and Ertl, Thomas",booktitle="Proceedings of the 2022 IEEE Workshop on Evaluation and Beyond – Methodological Approaches for Visualization (BELIV)",doi="10.1109/BELIV57783.2022.00009",month="October",pages="38-46",title="Power Overwhelming: Quantifying the Energy Cost of Visualisation",year="2022"}


Console.WriteLine(item.ToString("s2q.cS"));

// Expected console output:
// @inproceedings{mueller:2022:power,
//   author = "C. Müller and M. Heinemann and D. Weiskopf and T. Ertl",
//   booktitle = "Proceedings of the 2022 IEEE Workshop on Evaluation and Beyond – Methodological Approaches for Visualization (BELIV)",
//   doi = "10.1109/BELIV57783.2022.00009",
//   month = "October",
//   pages = "38-46",
//   title = "Power Overwhelming: Quantifying the Energy Cost of Visualisation",
//   year = "2022"
//}

Authors and editors

The library parses people (Visus.BibTex.WellKnownFields.Author and Visus.BibTex.WellKnownFields.Editor) into structured objects of type Visus.BibTex.Name. You can use these object to process the details of a name like this:

var author = new Name("Ulbricht", "Walter");
Console.WriteLine(author.Surname);
Console.WriteLine(author.ChristianName);

// Expected console output:
// Ulbricht
// Walter

Names also support decomposition:

var author = new Name("Ulbricht", "Walter", "Ernst", "Paul");
var (surname, christianName, middleNames) = author;
Console.WriteLine(author.Surname);
Console.WriteLine(author.ChristianName);
Console.WriteLine(string.Join(" ", author.MiddleNames));

// Expected console output:
// Ulbricht
// Walter
// Ernst Paul

Name implements IFormattable and thus supports formatting using the formats defined in Visus.BibTex.NameFormats.

var author = new Name("Ulbricht", "Walter", "Ernst", "Paul");
Console.WriteLine(author.ToString(NameFormats.SurnameChristianNameMiddleNames));

// Expected console output:
// Ulbricht, Walter Ernst Paul

You can also combine the single-character formats to form custom ones:

var author = new Name("Ulbricht", "Walter", "Ernst", "Paul");
Console.WriteLine(author.ToString("SCm"));

// Expected console output:
// Ulbricht, Walter E. P.

The formats that can be combined are "S" for the surname, "C" for the Christian name, "M" for the middle names and "X" for a name suffix like "jr." All except for the suffix support abbreviation by specifying the lower-case variant.

Visus.BibTex.Name.Parse also supports the opposite direction, i.e. parsing a string into a list of names:

var authors = Name.Parse("Ulbricht, Walter and Honecker, Erich");
Console.Write(string.Join("; ", authors));

// Expected console output:
// Ulbricht, Walter; Honecker, Erich

The library makes best effort to recognise different formats of names, but it works best if authors are separated by the common "and":

var authors = Name.Parse("Walter Ulbricht and Erich Honecker");
Console.Write(string.Join("; ", authors));

// Expected console output:
// Ulbricht, Walter; Honecker, Erich

// The following should yield the same outputs, but is more error-prone for
// instance if surnames comprise of more than one token.
var authors = Name.Parse("Walter Ulbricht, Erich Honecker");
Console.Write(string.Join("; ", authors));

Note that the parser honours braces around names by not tokenising braced expressions:

var authors = Name.Parse("{Visualisierungsinstitut der Universität Suttgart}");
Console.Write(string.Join("; ", authors));

// Expected console output:
// {Visualisierungsinstitut der Universität Suttgart}

However, it will not remove the braces nor process any Latex instructions:

var authors = Name.Parse("{Visualisierungsinstitut der Universit\\\"at Suttgart}");
Console.Write(string.Join("; ", authors));

// Expected console output:
// {Visualisierungsinstitut der Universit\"at Suttgart}