bibtex(n)

✨ NAME ✨

bibtex — parse bibtex files. That's it, that's the whole vibe. This is the bibtex manual page from the n section (Tcl gang rise up), shipped with tcllib 💅

---

🎀 SYNOPSIS 🎀

package require Tcl 8.5 9
package require bibtex ?0.8?

::bibtex::parse ?options? ?text?

::bibtex::parse text

::bibtex::parse ?-command cmd? -channel chan

::bibtex::parse ?-recordcommand recordcmd? ?-preamblecommand preamblecmd? ?-stringcommand stringcmd? ?-commentcommand commentcmd? ?-progresscommand progresscmd? ?-casesensitivestrings bool? (text | -channel chan)

::bibtex::wait token

::bibtex::destroy token

::bibtex::addStrings token stringdict

---

💖 DESCRIPTION 💖

Okay so bestie, this package hands you the commands you need to parse bibliographies in BibTeX format. Periodt. Let's go through every single one 🦋

🌸 ::bibtex::parse ?options? ?text?

This is the general form of the parse command. Depending on which options you invoke it with, it'll either give you back a token for the parser, or the actual parsed entries of the input bibliography. And instead of just doing an immediate parse and handing you a predefined format, it can also slide into an event-based parsing style where all the relevant entries in the input get reported through callback commands — very SAX of it, ngl.

🌈 ::bibtex::parse text

In this form, the command assumes the text you gave it is a bibliography in BibTeX format, parses it, and then returns a list with one element per record found in the bibliography.

Heads up: comments, string definitions, preambles, etc. will not show up in the result. They're just not invited to the party 🙈

Each element of that list is itself a list containing record type, bibliography key, and record data, in that exact order. The record data is a dictionary — its keys are the keys of the record, with their associated values. Slay.

🦋 ::bibtex::parse ?-command cmd? -channel chan

In this form the command reads the bibliography from the Tcl channel you name in chan, and then returns the same data structure described above. Iconic.

But if you specify the -command option, the result becomes a handle for the parser instead, and all the processing goes incremental and happens in the background. When the input is fully exhausted, the callback cmd gets invoked with the result of the parse. The exact callback definition is:

cmd token parseresult

The parse result will have the structure explained above, same as the simpler forms of the parser.

⚠️ Important bestie: the parser will not close the channel after it's exhausted it. Closing it is still your responsibility, as the user of the parser. Don't leave it hanging 💀

💜 ::bibtex::parse ?-recordcommand recordcmd? ?-preamblecommand preamblecmd? ?-stringcommand stringcmd? ?-commentcommand commentcmd? ?-progresscommand progresscmd? ?-casesensitivestrings bool? (text | -channel chan)

This right here is the most low-level form of the parser. The result you get back will be a handle for the parser. During processing it invokes the specified callback commands for each type of data it finds in the bibliography. Main character energy fr fr.

The processing will be incremental and happen in the background if, and only if a Tcl channel chan is specified. For a text, the processing happens immediately and all the callbacks get invoked before the command itself even returns.

The callbacks — those *cmd things — are all command prefixes, and they get invoked with additional arguments appended to them. What those arguments mean depends on the callback, and it's all explained below. One thing that's always true though: the first argument is always the handle of the parser that's invoking the callback. Consistency, we love her 💅

⭐ -casesensitivestrings

This option takes a boolean value. When it's set, string macro processing becomes case-sensitive. The default is case-insensitive string macro processing.

🍓 recordcmd token type key recorddict

This callback fires whenever the parser detects a bibliography record in the input. Its arguments are the record type, the bibliography key for the record, and a dictionary containing the keys and values describing the record. Any string macros the parser already knows about have already been expanded by this point. No cap.

🧚 preamblecmd token preambletext

This callback fires whenever the parser detects an @preamble block in the input. The only extra argument is the text found in that preamble block. By default, such entries are ignored.

🌸 stringcmd token stringdict

This callback fires whenever the parser detects an @string-based macro definition in the input. The argument is a dictionary with the macro names as keys and their replacement strings as values. By default, such definitions are added to the parser state so they can be used in future bibliography records.

🌈 commentcmd token commenttext

This callback fires whenever the parser detects a comment in the input. The only extra argument is the comment text. By default, such entries are ignored.

💜 progresscmd token percent

This callback fires during processing to let you know how far along things are. Its argument is the percentage of data processed, as an integer number between 0 and 100. In the case of incremental processing the percentage will always be -1, because the total number of entries isn't known beforehand. We're all just vibing without the full picture 🫶

👑 ::bibtex::wait token

This command waits for the parser represented by the token to complete, and then returns. The result it gives back is the empty string.

💀 ::bibtex::destroy token

This command cleans up all internal state associated with the parser represented by the handle token, effectively destroying it. You can even call this from inside the parser callbacks to terminate processing. So dramatic, so useful.

🎀 ::bibtex::addStrings token stringdict

This command adds the macro definitions stored in the dictionary stringdict to the parser represented by the handle token.

The dictionary keys are the macro names and the values are their replacement strings. And the best part? This command has the exact correct signature for use as a -stringcommand callback in an invocation of the command ::bibtex::parse. It was literally made for it, iykyk ✨

---

🙈 BUGS, IDEAS, FEEDBACK 🙈

Okay so real talk: this document, and the package it describes, will undoubtedly contain bugs and other problems. That's just how it is. Please report such things in the category bibtex of the Tcllib Trackers at [http://core.tcl.tk/tcllib/reportlist]. And please also report any ideas for enhancements you may have for either the package and/or the documentation — we want them 🫶

When proposing code changes, please provide unified diffs, i.e. the output of diff -u.

Note further that attachments are strongly preferred over inlined patches. You can make an attachment by going to the Edit form of the ticket immediately after its creation, and then using the left-most button in the secondary navigation bar. Easy.

---

⭐ KEYWORDS ⭐

bibliography, bibtex, parsing, text processing

---

🌸 CATEGORY 🌸

Text processing

---

💜 COPYRIGHT 💜

Copyright (c) 2005 for documentation, Andreas Kupries <andreas_kupries@users.sourceforge.net>

---

And that's the whole thing bestie 💖 This was bibtex(n), version 0.8, brought to you by tcllib. Go forth and parse those bibliographies, you absolute legend 👑✨