BibTeX-Ruby

The BibTeX-Ruby package contains a parser for BibTeX bibliography files and a class structure to manage BibTeX objects in Ruby. It is designed to support all BibTeX objects (including @comment and string-replacements via @string) and handles all content outside of BibTeX objects as ‘meta comments’ which may be included in post-processing.

Quickstart

  • require ‘bibtex’

  • bib = BibTeX::Bibliography.open(‘file.bib’)

Installation

If you just want to use it:

  • gem install bibtex-ruby

If you want to work with the sources:

Or, alternatively, fork the (project on github).

Requirements

  • The parser generator href="http://i.loveruby.net/en/projects/racc/"> is required to generate parser.

  • The minitest gem is required to run the tests in older Ruby versions (prior to 1.9).

Usage

Look at the ‘examples’ directory for a simple BibTeX to HTML converter.

The Parser

The BibTeX-Ruby parser is generated using the wonderful href="http://i.loveruby.net/en/projects/racc/"> parser generator.

The BibTeX Format

At first glance, the BibTeX file format seems very clear and simple; however, there are a number of peculiarities which warrant some explanation. The best place to start reading is probably at your closest ctan server where the original bibtex from 1988 still lives. Additionally, Xavier Decoret has written a great summary of the format; another invaluable source of information is Nicolas Markey’s website. Unfortunately, even after consulting these documents, a number of issues remain. Therefore, it is the purpose of this section to deliver the rationale that went into some of the design decision in BibTeX-Ruby.

A BibTeX bibliography is typically stored in a file with the file extension ‘.bib’. This file may contain any number of BibTeX objects; everything that is not a BibTeX object is assumed to be a comment and ignored.

The individual objects are discussed in further detail below. First, however, a number of general remarks:

  • BibTeX-Ruby begins in comment-mode, treating all text it encounters as comments. Normally these comments are ignored; however, if you wish the parser to include them, you can do so by adding the symbol :meta_comments to the :include array in the parser’s options.

  • Note that string literals in BibTeX are either contained in quotes or braces; nested quotes in a quoted literal are not escaped with a usual backslash but must be placed inside braces. Nested braces must be balanced in literals, regardless of whether they are surrounded by quotes or braces.

  • Quoted strings and string constants (which are defined by @string objects) can be concatted by the ‘#’ symbol. String literals in braces can not be concatted in this way.

  • The ‘@’ symbol may only occur in quoted string literals (not in braced out literals) in the original BibTeX; note, however, that this is not true for BibTeX-Ruby (i.e., it will parse any string containing an ‘@’).

@comment

The purpose of the @comment object is not entirely clear, because everything outside of an object is treated as a comment anyway. Nicolas Markay argues that a @comment makes it possible to quickly comment out a number of consecutive objects; however, as Xavier Decoret points out that this does not work with the original bibtex program (following a @comment, it simply ignores everything until the end of the line). Indeed, on page 13 of the original documentation, Oren Patashnik explains that @comment objects are not really necessary; they exist only for Scribe system compatibility.

Because they would be useless otherwise, BibTeX-Ruby treats @comment objects as Nicolas Markay describes them: thus, everything inside a @comment is treated as a comment and is ignored—everything, that is, until the object is closed. For this reason, BibTeX-Ruby assumes that braces inside a @comment are balanced! Obviously, BibTeX-Ruby differs from bibtex in that respect; though, the gain is, that it is now possible to comment out a sequence of entries, without removing their respective ‘@’ symbols.

@string

The @string object defines a single string constant (for multiple constant assignments, it is necessary to define separate @string objects). These constants can be used within string assignments in other @string or @preamble objects, as well as in regular BibTeX entries. For example, this is a valid constant definition and usage:

  • @string{ generator = “BibTeX-Ruby”}

  • @preamble{ “This bibliography was generated by ” # generator }

@preamble

Typically, the purpose of @preamble objects is to define LaTeX statements, which will be put into the ‘.bbl’ file by bibtex. A @preamble object may contain a single string literal, a single string constant (defined by a @string object), or a concatenation of literals and constants.

Entries

These represent proper BibTeX objects (e.g., @book, @collection, etc.).

Credits

The BibTeX-Ruby package was written by Sylvester Keil.

License

BibTeX-Ruby Copyright © 2010-2011 Sylvester Keil

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <www.gnu.org/licenses/>.