bibtex-ruby 1.0.0

data/Manifest

@@ -0,0 +1,34 @@
+History.txt
+LICENSE
+Manifest
+README.rdoc
+Rakefile
+examples/bib2html.rb
+examples/markdown.bib
+lib/bibtex.rb
+lib/bibtex/bibliography.rb
+lib/bibtex/bibtex.y
+lib/bibtex/elements.rb
+lib/bibtex/entry.rb
+lib/bibtex/error.rb
+lib/bibtex/lexer.rb
+lib/bibtex/parser.output
+lib/bibtex/parser.rb
+lib/bibtex/string_replacement.rb
+lib/extensions/core.rb
+test/bib/00_empty.bib
+test/bib/01_no_bibtex.bib
+test/bib/02_string.bib
+test/bib/03_string.bib
+test/bib/04_string_replacement.bib
+test/bib/05_comment.bib
+test/bib/06_preamble.bib
+test/bib/07_entry.bib
+test/bib/08_decoret.bib
+test/bib/09_errors.bib
+test/bib/10_bibdesk.bib
+test/test_bibtex.rb
+test/test_comment.rb
+test/test_entry.rb
+test/test_preamble.rb
+test/test_string.rb

data/README.rdoc

@@ -0,0 +1,152 @@
+= 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:
+
+* gem install racc
+* git clone http://github.com/inukshuk/bibtex-ruby.git
+* cd bibtex-ruby
+* rake racc
+* rake rdoc
+* rake test
+
+Or, alternatively, fork the (project on github)[http://github.com/inukshuk/bibtex-ruby.git].
+
+
+== Requirements
+
+* The parser generator {+racc+}[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
+{+racc+}[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}[http://www.ctan.org/get/biblio/bibtex/] where
+the original +bibtex+ from 1988 still lives. Additionally, Xavier Decoret
+has written
+{a great summary}[http://artis.imag.fr/~Xavier.Decoret/resources/xdkbibtex/bibtex_summary.html]
+of the format; another invaluable source of information is Nicolas Markey's
+website[http://www.lsv.ens-cachan.fr/~markey/bibla.php]. 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}[http://www.ctan.org/get/biblio/bibtex/contrib/doc/btxdoc.pdf],
+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}[http://sylvester.keil.or.at/].
+
+== License
+
+BibTeX-Ruby
+Copyright (C) 2010-2011 {Sylvester Keil}[http://sylvester.keil.or.at]
+
+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 <http://www.gnu.org/licenses/>.

data/Rakefile

@@ -0,0 +1,54 @@
+# -*- ruby -*-
+
+require 'rubygems'
+require 'rake'
+require 'rake/clean'
+require 'rake/rdoctask'
+require 'rake/testtask'
+require 'echoe'
+
+Echoe.new('bibtex-ruby', '1.0.0') do |p|
+  p.description    = "A BibTeX parser written in Ruby"
+  p.url            = "http://github.com/inukshuk/bibtex-ruby"
+  p.author         = "Sylvester Keil"
+  p.email          = "http://sylvester.keil.or.at"
+  p.ignore_pattern = []
+  p.development_dependencies = [['racc', '>=1.4.6']]
+  p.need_tgz       = true
+  p.rdoc_options   = ["--line-numbers", "--inline-source", "--title", "BibTeX-Ruby Documentation", "--main", "README.rdoc"]
+end
+
+Rake::RDocTask.new(:rdoc_task) do |rd|
+  rd.main = 'README.rdoc'
+  rd.title = "BibTeX-Ruby Documentation"
+  rd.rdoc_files.include('README.rdoc',"lib/**/*.rb")
+  rd.rdoc_dir = "doc/html"
+  rd.options << '--webcvs=http://github.com/inukshuk/bibtex-ruby/tree/master/'
+end
+
+Rake::TestTask.new(:test_task) do |t|
+  t.libs << "test"
+  t.test_files = FileList['test/test*.rb']
+  t.verbose = true
+end
+
+task :default => ['racc']
+
+desc 'Generates the BibTeX parser'
+task :racc => ['lib/bibtex/parser.rb']
+
+desc 'Generates RDoc documentation for BibTeX-Ruby'
+task :rdoc => ['clean','racc','rdoc_task']
+
+task :test => ['racc','test_task']
+
+file 'lib/bibtex/parser.rb' => ['lib/bibtex/bibtex.y'] do
+  sh 'racc -v -g -o lib/bibtex/parser.rb lib/bibtex/bibtex.y'
+end
+
+CLEAN.include('lib/bibtex/parser.rb')
+CLEAN.include('lib/bibtex/parser.output')
+CLEAN.include('doc/html')
+
+
+# vim: syntax=ruby

data/bibtex-ruby.gemspec

@@ -0,0 +1,36 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{bibtex-ruby}
+  s.version = "1.0.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Sylvester Keil"]
+  s.cert_chain = ["/Users/sylvester/.gem/keys/gem-public_cert.pem"]
+  s.date = %q{2011-01-18}
+  s.description = %q{A (fairly complete) BibTeX parser written in Ruby}
+  s.email = %q{http://sylvester.keil.or.at}
+  s.extra_rdoc_files = ["LICENSE", "README.rdoc", "lib/bibtex.rb", "lib/bibtex/bibliography.rb", "lib/bibtex/bibtex.y", "lib/bibtex/elements.rb", "lib/bibtex/entry.rb", "lib/bibtex/error.rb", "lib/bibtex/lexer.rb", "lib/bibtex/parser.output", "lib/bibtex/parser.rb", "lib/bibtex/string_replacement.rb", "lib/extensions/core.rb"]
+  s.files = ["History.txt", "LICENSE", "Manifest", "README.rdoc", "Rakefile", "examples/bib2html.rb", "examples/markdown.bib", "lib/bibtex.rb", "lib/bibtex/bibliography.rb", "lib/bibtex/bibtex.y", "lib/bibtex/elements.rb", "lib/bibtex/entry.rb", "lib/bibtex/error.rb", "lib/bibtex/lexer.rb", "lib/bibtex/parser.output", "lib/bibtex/parser.rb", "lib/bibtex/string_replacement.rb", "lib/extensions/core.rb", "test/bib/00_empty.bib", "test/bib/01_no_bibtex.bib", "test/bib/02_string.bib", "test/bib/03_string.bib", "test/bib/04_string_replacement.bib", "test/bib/05_comment.bib", "test/bib/06_preamble.bib", "test/bib/07_entry.bib", "test/bib/08_decoret.bib", "test/bib/09_errors.bib", "test/bib/10_bibdesk.bib", "test/test_bibtex.rb", "test/test_comment.rb", "test/test_entry.rb", "test/test_preamble.rb", "test/test_string.rb", "bibtex-ruby.gemspec"]
+  s.homepage = %q{http://github.com/inukshuk/bibtex-ruby}
+  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "BibTeX-Ruby Documentation", "--main", "README.rdoc"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{bibtex-ruby}
+  s.rubygems_version = %q{1.3.7}
+  s.signing_key = %q{/Users/sylvester/.gem/keys/gem-private_key.pem}
+  s.summary = %q{A BibTeX parser written in Ruby}
+  s.test_files = ["test/test_bibtex.rb", "test/test_comment.rb", "test/test_entry.rb", "test/test_preamble.rb", "test/test_string.rb"]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<racc>, [">= 1.4.6"])
+    else
+      s.add_dependency(%q<racc>, [">= 1.4.6"])
+    end
+  else
+    s.add_dependency(%q<racc>, [">= 1.4.6"])
+  end
+end

data/examples/bib2html.rb

@@ -0,0 +1,28 @@
+require 'rubygems'
+require 'bibtex'
+
+
+# Open a bibliography file
+bib = BibTeX::Bibliography.open(File.expand_path('../markdown.bib',__FILE__),
+  :include => [:meta_comments])
+
+
+# Convert the BibTeX entries into a simple text format
+content = bib.data.map do |d|
+  result = ''
+  
+  if d.class == BibTeX::Entry
+    d.replace!(bib.strings)
+    result = [d[:author], '. ', d[:title], '. ', d[:publisher], ': ', d[:address], ', ', d[:year], '.'].join
+  end
+  
+  if d.class == BibTeX::MetaComment
+    result = d.to_s
+  end
+  
+  result
+end
+
+# Convert all non BibTeX text (i.e., the `meta comments') using the maruku gem
+require 'maruku'
+puts Maruku.new(content.join).to_html_document

data/examples/markdown.bib

@@ -0,0 +1,39 @@
+Bibliography
+============
+
+Here is a little bibliography to illustrate how *BibTeX* and
+*Markdown* can be seamlessly integrated. This is a _valid_ BibTex
+File; at the same time its comments are written using Markdown
+markup. For example, this is a list:
+
+* More interestingly, though, we can also include
+* any BibTeX object we want.
+
+It will not show up in the HTML, but here we define a string:
+
+@string{ thoreau = "Thoreau, Henry David" }
+@string{ nyc = "New York" }
+
+Now we can add a few BibTeX entries and convert them to text
+for inclusion.
+
+In the HTML version we will print the BibTeX entries in a simple
+text format instead.
+
+@book{key,
+  author = thoreau,
+  title = {Walden; or Life in the Woods},
+  publisher = "Dover",
+  address = nyc,
+  year = 1995
+}
+
+@book{poe,
+	author = {Poe, Edgar Allen},
+	title = "Poetry, Tales, and Selected Essays",
+	address = nyc,
+	publisher = "Library of America",
+	year = 1996
+}
+
+Neat, huh?

data/lib/bibtex.rb

@@ -0,0 +1,51 @@
+#--
+# BibTeX-Ruby
+# Copyright (C) 2010-2011	Sylvester Keil <sylvester.keil.or.at>
+# 
+# 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 <http://www.gnu.org/licenses/>.
+#++
+#
+# = BibTeX
+#
+# This module encompasses a parser for BibTeX files and
+# auxiliary classes to model the individual
+# BibTeX objects: +String+, +Preamble+, +Comment+, and
+# +Entry+.
+#
+# Author:: {Sylvester Keil}[http://sylvester.keil.or.at]
+# Copyright:: Copyright (c) 2010 Sylvester Keil
+# License:: GNU GPL 3.0
+#
+module BibTeX
+	require 'logger'
+
+	# The current library version.
+	VERSION = '1.0.0'
+
+	#
+	# An instance of the Ruby core class +Logger+.
+	# Used for logging by BibTeX-Ruby.
+	#
+	Log = Logger.new(STDERR)
+	Log.level = ENV.has_key?('DEBUG') ? Logger::DEBUG : Logger::WARN
+	Log.datetime_format = "%Y-%m-%d %H:%M:%S"
+
+  require 'bibtex/string_replacement'
+  require 'bibtex/elements'
+  require 'bibtex/entry'
+  require 'bibtex/error'
+  require 'bibtex/parser'
+  require 'bibtex/bibliography'
+
+end

data/lib/bibtex/bibliography.rb

@@ -0,0 +1,175 @@
+#--
+# BibTeX-Ruby
+# Copyright (C) 2010  Sylvester Keil <sylvester.keil.or.at>
+# 
+# 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 <http://www.gnu.org/licenses/>.
+#++
+
+module BibTeX
+
+  #
+  # The Bibliography class models a BibTeX bibliography;
+  # typically, it corresponds to a `.bib' file.
+  #
+  class Bibliography
+
+    attr_accessor :path
+    attr_reader :data, :strings, :entries, :errors
+
+    #
+    # Opens and parses the `.bib' file at the given +path+. Returns
+    # a new Bibliography instance corresponding to the file.
+    #
+    # The options argument is passed on to BibTeX::Parser.new.
+    #
+    def self.open(path, options={})
+      Log.debug('Opening file ' + path.to_s)
+      BibTeX::Parser.new(options).parse(File.read(path))
+    end
+    
+    #
+    # Creates a new bibliography; empty if no path is specified, otherwise
+    # by parsing the file at the given path.
+    #
+    def initialize(data=[])
+      @path = path
+      @data = []
+      @strings = {}
+      @entries = {}
+      @errors = []
+      add(data)
+    end
+    
+    # Adds a new element, or a list of new elements to the bibliography.
+    def add(data)
+      raise(ArgumentError,'BibTeX::Bibliography.add data expected to be enumerable or of type BibTeX::Element; was: ' + data.class.name) unless data.respond_to?(:each) || data.kind_of?(Element)
+      data.kind_of?(Element) ? self << data : data.each { |d| self << d }
+      self
+    end
+    
+    # Saves the bibliography to the current path.
+    def save
+      save_to(@path)
+    end
+    
+    # Saves the bibliography to a file at the given path.
+    def save_to(path)
+      File.write(path,to_s)
+    end
+    
+    # Add an object to the bibliography. Returns the bibliography.
+    def <<(obj)
+      raise(ArgumentError, 'A BibTeX::Bibliography can contain only BibTeX::Elements; was: ' + obj.class.name) unless obj.kind_of?(Element)
+      @data << obj.added_to_bibliography(self)
+      self
+    end
+    
+    # Delete an object from the bibliography. Returns the object, or nil
+    # if the object was not part of the bibliography.
+    def delete(obj)
+      @data.delete(obj.removed_from_bibliography(self))
+    end
+    
+    def delete_all
+      @data.each { |obj| obj.removed_from_bibliography(self) }
+      @data = []
+    end
+    
+    # Returns all @preamble objects.
+    def preamble
+      find_by_type(BibTeX::Preamble)
+    end
+    
+    # Returns the first entry with a given key.
+    def [](key)
+      @entries[key.to_s]
+    end
+
+    # Returns all @comment objects.
+    def comments
+      find_by_type(BibTeX::Comment)
+    end
+
+    # Returns all meta comments, i.e., all text outside of BibTeX objects.
+    def meta_comments
+      find_by_type(BibTeX::MetaComment)
+    end
+
+    # Returns all objects which could not be parsed successfully.
+    def errors
+      @errors
+    end
+
+    # Returns true if there are object which could not be parsed.
+    def errors?
+      !errors.empty?
+    end
+
+    # Replaces all string constants which are defined in the bibliography.
+    #
+    # By default constants in @string, @preamble and entries are defined; this
+    # behaviour can be changed using the options argument by setting
+    # the :include option to a list of types.
+    #
+    # Note that strings are replaced in the order in which they occur in the
+    # bibliography.
+    #
+    # call-seq:
+    # replace_strings
+    # replace_strings({ :include => [BibTeX::String,BibTeX::Preamble]})
+    #
+    def replace_strings(options={})
+      options[:include] ||= [BibTeX::String, BibTeX::Preamble, BibTeX::Entry]
+      find_by_type(options[:include]).each { |e| e.replace!(@strings) if e.respond_to?(:replace!)}
+    end
+
+    # Returns true if the bibliography is currently empty.
+    def empty?
+      @data.empty?
+    end
+    
+    # Returns the number of objects in the bibliography (including meta comments).
+    def length
+      @data.length
+    end
+
+    # Returns a string representation of the bibliography.
+    def to_s
+      @data.map(&:to_s).join
+    end
+    
+    def to_yaml
+      @data.map(&:to_yaml).join
+    end
+    
+    def to_xml
+      xml = REXML::Document.new
+      xml << REXML::XMLDecl.new('1.0','UTF-8')
+      root = REXML::Element.new('bibliography')
+      @data.each { |e| root.add_element(e.to_xml) }
+      xml << root
+      xml
+    end
+    
+    private
+
+    def find_by_type(type)
+      @data.find_all { |x| type.respond_to?(:inject) ? type.inject(false) { |s,n| s || x.kind_of?(n) } : x.kind_of?(type) }
+    end
+    
+    def find_entry(key)
+      entries.find { |e| e.key == key.to_s }
+    end
+  end
+end