bibtex-ruby 1.1.2 → 1.2.0

data/Gemfile

@@ -0,0 +1,2 @@
+source :rubygems
+gemspec

data/Gemfile.lock

@@ -0,0 +1,20 @@
+PATH
+  remote: .
+  specs:
+    bibtex-ruby (1.1.2)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    json (1.5.1)
+    minitest (2.0.2)
+    racc (1.4.6)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bibtex-ruby!
+  json (>= 1.5.0)
+  minitest (>= 2.0.2)
+  racc (>= 1.4.6)

data/Manifest

@@ -1,8 +1,11 @@
+Gemfile
+Gemfile.lock
 History.txt
 LICENSE
 Manifest
 README.md
 Rakefile
+bibtex-ruby.gemspec
 examples
 examples/bib2html.rb
 examples/bib2yaml.rb
@@ -14,10 +17,11 @@ lib/bibtex/bibtex.y
 lib/bibtex/elements.rb
 lib/bibtex/entry.rb
 lib/bibtex/error.rb
+lib/bibtex/extensions.rb
 lib/bibtex/lexer.rb
 lib/bibtex/parser.output
 lib/bibtex/parser.rb
-lib/bibtex/string_replacement.rb
+lib/bibtex/utilities.rb
 lib/bibtex/version.rb
 lib/bibtex.rb
 test
@@ -33,9 +37,12 @@ test/bib/07_entry.bib
 test/bib/08_decoret.bib
 test/bib/09_errors.bib
 test/bib/10_bibdesk.bib
+test/bib/11_roundtrip.bib
+test/helper.rb
 test/test_bibtex.rb
 test/test_comment.rb
 test/test_entry.rb
 test/test_export.rb
 test/test_preamble.rb
-test/test_string.rb
+test/test_string.rb
+test/test_utilities.rb

data/README.md

@@ -2,36 +2,38 @@ 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, string-replacements via @string, as well
-as string concatenation using '#') and handles all content outside of BibTeX
-objects as 'meta comments' which may or may not be included in post-processing.
+class structure to manage or convert BibTeX objects in Ruby. It is designed to
+support all BibTeX objects (including @comment, string-replacements via @string,
+as well as string concatenation using '#') and handles all content outside of
+BibTeX objects as 'meta comments' which may or may not be included in
+post-processing.
 
 
 Quickstart
 ----------
 
-		$ irb
-		> require 'bibtex'
-		 => true
-		> bib = BibTeX::Bibliography.open('./ruby.bib')
-		 => book{pickaxe,
-		  address  {Raleigh, North Carolina},
-		  author  {Thomas, Dave, and Fowler, Chad, and Hunt, Andy},
-		  date-added  {2010-08-05 09:54:07 0200},
-		  date-modified  {2010-08-05 10:07:01 0200},
-		  keywords  {ruby},
-		  publisher  {The Pragmatic Bookshelf},
-		  series  {The Facets of Ruby},
-		  title  {Programming Ruby 1.9: The Pragmatic Programmers Guide},
-		  year  {2009}
-		}
-		> bib[:pickaxe][:author]
-		 => ["Thomas, Dave, and Fowler, Chad, and Hunt, Andy"]
-		> bib[:pickaxe].author
-		 => ["Thomas, Dave, and Fowler, Chad, and Hunt, Andy"]
-		> bib[:pickaxe].author = ['Thomas, D., Fowler, C., and Hunt, A.']
-		 => ["Thomas, D., and Fowler, C., and Hunt, A."]
+    $ [sudo] gem install bibtex-ruby
+    $ irb
+    > require 'bibtex'
+     => true
+    > bib = BibTeX.open('./ruby.bib')
+     => book{pickaxe,
+      address  {Raleigh, North Carolina},
+      author  {Thomas, Dave, and Fowler, Chad, and Hunt, Andy},
+      date-added  {2010-08-05 09:54:07 0200},
+      date-modified  {2010-08-05 10:07:01 0200},
+      keywords  {ruby},
+      publisher  {The Pragmatic Bookshelf},
+      series  {The Facets of Ruby},
+      title  {Programming Ruby 1.9: The Pragmatic Programmers Guide},
+      year  {2009}
+    }
+    > bib[:pickaxe].year
+     => "2009"
+    > bib[:pickaxe][:title]
+     => "Programming Ruby 1.9: The Pragmatic Programmer's Guide"
+    > bib[:pickaxe].author = 'Thomas, D., Fowler, C., and Hunt, A.'
+     => "Thomas, D., and Fowler, C., and Hunt, A."
 
 
 Installation
@@ -39,63 +41,134 @@ Installation
 
 If you just want to use it:
 
-		$ [sudo] gem install bibtex-ruby
+    $ [sudo] gem install bibtex-ruby
 
 If you want to work with the sources:
 
-		$ [sudo] gem install racc
-		$ git clone http://github.com/inukshuk/bibtex-ruby.git
-		$ cd bibtex-ruby
-		$ rake racc
-		$ rake rdoc
-		$ rake test
+    $ git clone http://github.com/inukshuk/bibtex-ruby.git
+    $ cd bibtex-ruby
+    $ [sudo] bundle install
+    $ rake racc
+    $ rake rdoc
+    $ rake test
 
-Or, alternatively, fork the [project on github](http://github.com/inukshuk/bibtex-ruby.git).
+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).
-* The *json* gem is required on older ruby versions for JSON export (prior to 1.9).
+* 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.
+* The *json* gem is required on older Ruby versions for JSON export.
+
+The bibtex-ruby gem has been tested on Ruby versions 1.8.7 and 1.9.2; it has
+been confirmed to work with REE 1.8.7 x86_64 and JRuby 1.5.6 x86_64-java. It
+does not work with MacRuby 0.8 because of a bug in MacRuby's implementation
+of the *StringScanner* class, however, this has been fixed in SVN (see
+[#1](https://github.com/inukshuk/bibtex-ruby/issues/closed#issue/1) for details).
+
 
 
 Usage
 -----
 
-It is very easy to use BibTeX-Ruby. You can use the class method `BibTeX::Bibliography.open`
-to open a '.bib' file. Normally, BibTeX-Ruby will discard all content outside of
-regular BibTeX elements; however, if you wish to include everything, simply add
-`:include => [:meta_comments]` to your invocation of `BibTeX::Bibliography.open`.
+It is very easy to use BibTeX-Ruby. You can use the top level utility methods
+**BibTeX.open** and **BibTeX.parse** to open a '.bib' file or to parse a string
+containing BibTeX contents. Normally, BibTeX-Ruby will discard all text outside
+of regular BibTeX elements; however, if you wish to include everything, simply add
+`:include => [:meta_comments]` to your invocation of **BibTeX.open** or **BibTeX.parse**.
 
 Once BibTeX-Ruby has parsed your '.bib' file, you can easily access individual entries.
-For example, if your bibliography object `bib` contained the following entry:
-
-		@book{pickaxe,
-		  address = {Raleigh, North Carolina},
-		  author = {Thomas, Dave, and Fowler, Chad, and Hunt, Andy},
-		  date-added = {2010-08-05 09:54:07 +0200},
-		  date-modified = {2010-08-05 10:07:01 +0200},
-		  keywords = {ruby},
-		  publisher = {The Pragmatic Bookshelf},
-		  series = {The Facets of Ruby},
-		  title = {Programming Ruby 1.9: The Pragmatic Programmer's Guide},
-		  year = {2009}
-		}
-		
+For example, if you set up your bibliography as follows:
+
+    bib = BibTeX.parse <<-END
+    @book{pickaxe,
+      address = {Raleigh, North Carolina},
+      author = {Thomas, Dave, and Fowler, Chad, and Hunt, Andy},
+      date-added = {2010-08-05 09:54:07 +0200},
+      date-modified = {2010-08-05 10:07:01 +0200},
+      keywords = {ruby},
+      publisher = {The Pragmatic Bookshelf},
+      series = {The Facets of Ruby},
+      title = {Programming Ruby 1.9: The Pragmatic Programmer's Guide},
+      year = {2009}
+    }
+    END
+    
 You could easily access it, using the entry's key, 'pickaxe', like so: `bib[:pickaxe]`;
-you also have easy access to individual fields, for example: `bib[:pickaxe](:author)`.
+you also have easy access to individual fields, for example: `bib[:pickaxe][:author]`.
+Alternatively, BibTeX-Ruby accepts ghost methods to conveniently access an entry's fields,
+similar to **ActiveRecord::Base**. Therefore, it is equally possible to access the
+'author' field above as `bib[:pickaxe].author`.
+
+Instead of parsing strings you can also create BibTeX elements by using Ruby:
+
+    > bib = BibTeX::Bibliography.new
+    > bib << BibTeX::Entry.new({
+    >   :type => :book,
+    >   :key => 'rails',
+    >   :address => 'Raleigh, North Carolina',
+    >   :author => 'Ruby, Sam, and Thomas, Dave, and Hansson, David Heinemeier',
+    >   :booktitle => 'Agile Web Development with Rails',
+    >   :edition => 'third',
+    >   :keywords => 'ruby, rails',
+    >   :publisher => 'The Pragmatic Bookshelf',
+    >   :series => 'The Facets of Ruby',
+    >   :title => 'Agile Web Development with Rails',
+    >   :year => '2009'
+    > })
+    > book = BibTeX::Entry.new
+    > book.type = :book
+    > book.key = 'mybook'
+    > bib << book
+
+
+
+### String Replacement
 
 If your bibliography contains BibTeX @string objects, you can let BibTeX-Ruby
 replace the strings for you. You have access to a bibliography's strings via
-`BibTeX::Bibliography#strings` and you can replace the strings of an entry using
-the `BibTeX::Entry#replace!` method. Thus, to replace all strings defined in your
-bibliography object `bib` your could use this code:
-
-		bib.entries.each do |entry|
-			entry.replace!(bib.strings)
-		end
+**BibTeX::Bibliography#strings** and you can replace the strings of an entry using
+the **BibTeX::Entry#replace!** method. Thus, to replace all strings defined in your
+bibliography object **bib** your could use this code:
+
+    bib.entries.each do |entry|
+      entry.replace!(bib.strings)
+    end
+    
+A shorthand version for replacing all strings in a given bibliography is the
+`Bibliography#replace_strings` method. Similarly, you can use the
+`Bibliography#join_strings` method to join individual strings together. For instance:
+
+    > bib = BibTeX::Bibliography.new
+    > bib.add BibTeX::Element.parse '@string{ foo = "foo" }'
+    > bib.add BibTeX::Element.parse '@string{ bar = "bar" }'
+    > bib.add BibTeX::Element.parse <<-END
+    >  @book{abook,
+    >    author = foo # "Author",
+    >    title = foo # bar
+    >  }
+    > END
+    > puts bib[:abook].to_s
+    @book{abook,
+      author = foo # "Author",
+      title = foo # bar
+    }
+    > bib.replace_strings
+    > puts bib[:abook].to_s
+    @book{abook,
+      author = "foo" # "Author",
+      title = "foo" # "bar"
+    }
+    > bib.join_strings
+    @book{abook,
+      author = {fooAuthor},
+      title = {foobar}
+    }
+
+### Conversions
 
 Furthermore, BibTeX-Ruby allows you to export your bibliography for processing
 by other tools. Currently supported formats include YAML, JSON, and XML.
@@ -104,10 +177,15 @@ Of course, you can also export your bibliography back to BibTeX; if you include
 except for whitespace, blank lines and letter case (BibTeX-Ruby will downcase
 all keys).
 
-In order to export your bibliography use `#to_s`, `#to_yaml`, `#to_json`, or
-`#to_xml`, respectively.
+In order to export your bibliography use **#to\_s**, **#to\_yaml**, **#to\_json**, or
+**#to\_xml**, respectively. For example, the following line constitutes a simple
+BibTeX to YAML converter:
+
+    BibTeX.open('example.bib').to_yaml
+
+Look at the 'examples' directory for more elaborate examples of a BibTeX to YAML
+and a BibTeX to HTML converter.
 
-Look at the 'examples' directory for a simple BibTeX to YAML and BibTeX to HTML converter.
 
 
 The Parser
@@ -143,7 +221,7 @@ 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
+  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
@@ -185,8 +263,8 @@ 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 }
+    @string{ generator = "BibTeX-Ruby"}
+    @preamble{ "This bibliography was generated by " # generator }
 
 
 ### @preamble

data/Rakefile

@@ -1,62 +1,13 @@
 # -*- ruby -*-
+$LOAD_PATH.unshift File.expand_path("../lib", __FILE__)
 
 require 'rubygems'
 require 'rake'
 require 'rake/clean'
 require 'rake/testtask'
 require 'rake/rdoctask'
-require 'rake/gempackagetask'
 
-require './lib/bibtex/version.rb'
-
-
-spec = Gem::Specification.new do |s|
-  s.platform          = Gem::Platform::RUBY
-  s.name              = 'bibtex-ruby'
-  s.rubyforge_project = s.name
-  s.version           = BibTeX::Version::STRING
-  s.summary           = "A BibTeX parser written in Ruby"
-  s.description       = "A (fairly complete) BibTeX parser written in Ruby. Supports regular BibTeX entries, @comments, string replacement via @string, and simple export formats (e.g. YAML)."
-  s.homepage          = 'http://inukshuk.github.com/bibtex-ruby'
-  s.authors           = ["Sylvester Keil"]
-  s.email             = 'http://sylvester.keil.or.at'
-  s.cert_chain        = ["/Users/sylvester/.gem/keys/gem-public_cert.pem"]
-  s.signing_key       = '/Users/sylvester/.gem/keys/gem-private_key.pem'
-  s.has_rdoc          = true
-  s.rdoc_options      = ["--line-numbers", "--inline-source", "--title", "BibTeX-Ruby Documentation", "--main", "README.rdoc"]
-  s.extra_rdoc_files  = ["README.md"]
-  s.files             = File.open('Manifest').readlines.map(&:chomp)
-  s.test_files        = FileList['test/test*.rb']
-  s.require_paths     = ["lib"]
-  s.date              = Time.now
-  s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
-  
-  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('racc', [">= 1.4.6"])
-      s.add_development_dependency('minitest', [">= 2.0.2"])
-      s.add_development_dependency('json', [">= 1.5.0"])
-    else
-      s.add_dependency('racc', [">= 1.4.6"])
-      s.add_dependency('minitest', [">= 2.0.2"])
-      s.add_dependency('json', [">= 1.5.0"])
-    end
-  else
-    s.add_dependency('racc', [">= 1.4.6"])
-    s.add_dependency('minitest', [">= 2.0.2"])
-    s.add_dependency('json', [">= 1.5.0"])
-  end
-  
-end
-
-Rake::GemPackageTask.new(spec) do |pkg|
-  pkg.need_zip = true
-  pkg.need_tar = true
-  pkg.package_dir = 'build'
-end
+require 'bibtex/version'
 
 Rake::RDocTask.new(:rdoc_task) do |rd|
   rd.main = 'README.md'
@@ -68,7 +19,7 @@ end
 
 Rake::TestTask.new(:test_task) do |t|
   t.libs << "test"
-  t.test_files = FileList['test/test*.rb']
+  t.test_files = FileList['test/test_*.rb']
   t.verbose = true
 end
 
@@ -94,11 +45,19 @@ task :manifest => ['clean', 'racc'] do
   m.close
 end
 
+desc 'Builds the gem file'
+task :build => ['manifest'] do
+  system 'gem build bibtex-ruby.gemspec'
+end
+
+desc 'Pushes the gem file to rubygems.org'
+task :release => ['build'] do
+  system "gem push bibtex-ruby-#{BibTeX::Version::STRING}"
+end
 
 CLEAN.include('lib/bibtex/parser.rb')
 CLEAN.include('lib/bibtex/parser.output')
 CLEAN.include('doc/html')
-CLEAN.include('build')
-
+CLEAN.include('*.gem')
 
 # vim: syntax=ruby

data/bibtex-ruby.gemspec

@@ -0,0 +1,36 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib/', __FILE__)
+$:.unshift lib unless $:.include?(lib)
+
+require 'bibtex/version'
+
+Gem::Specification.new do |s|
+  s.name              = 'bibtex-ruby'
+  s.version           = BibTeX::Version::STRING
+  s.platform          = Gem::Platform::RUBY
+  s.authors           = ['Sylvester Keil']
+  s.email             = 'http://sylvester.keil.or.at'
+  s.homepage          = 'http://inukshuk.github.com/bibtex-ruby'
+  s.summary           = 'A BibTeX parser and converter written in Ruby.'
+  s.description       = 'A (fairly complete) BibTeX parser written in Ruby. Supports regular BibTeX entries, @comments, string replacement via @string. Allows for easy export/conversion to formats such as YAML, JSON, and XML.'
+  s.date              = Time.now
+
+  s.required_rubygems_version = '>= 1.3.6'
+  s.rubyforge_project = s.name
+
+  s.add_development_dependency('racc', ['>= 1.4.6'])
+  s.add_development_dependency('minitest', ['>= 2.0.2'])
+  s.add_development_dependency('json', ['>= 1.5.0'])
+
+  s.files             = File.open('Manifest').readlines.map(&:chomp)
+  s.test_files        = Dir.glob('test/test*.rb')
+  s.executables       = []
+  s.require_path      = 'lib'
+
+  s.has_rdoc          = true
+  s.rdoc_options      = %w{--line-numbers --inline-source --title "BibTeX-Ruby Documentation" --main README.md --webcvs=http://github.com/inukshuk/bibtex-ruby/tree/master/}
+  s.extra_rdoc_files  = %w{README.md}
+  
+end
+
+# vim: syntax=ruby