bibtex-ruby 2.0.5 → 2.0.6

data/History.txt

@@ -1,4 +1,10 @@
-2.0.5 /
+2.0.6 / 2012-04-30
+==================
+
+* Added support for !=, /=, ~=, and ^= queries
+
+2.0.5 / 2012-04-19
+==================
 
 * Fixed Entry#dup (@JLimperg)
 * Implemented explicit caching of regular expressions (for MacRuby)

data/README.md

@@ -8,77 +8,87 @@ tokenizes correctly formatted names; BibTeX-Ruby recognizes BibTeX string
 replacements, joins values containing multiple strings or variables,
 supports cross-references, and decodes common LaTeX formatting
 instructions to unicode; if you are in a hurry, it also allows for easy
-export/conversion to formats such as YAML, JSON, CiteProc, and XML (BibTeXML).
+export/conversion to formats such as YAML, JSON, CiteProc/CSL, and
+XML (BibTeXML).
 
-For a list of projects using BibTeX-Ruby, see
-[the project wiki](https://github.com/inukshuk/bibtex-ruby/wiki/Projects-Using-BibTeX-Ruby).
+For a list of projects using BibTeX-Ruby, take a look at the
+[project wiki](https://github.com/inukshuk/bibtex-ruby/wiki/Projects-Using-BibTeX-Ruby).
 
 
 Quickstart
 ----------
 
+Install and load BibTeX-Ruby in an IRB session:
+
     $ [sudo] gem install bibtex-ruby
     $ irb
     >> require 'bibtex'
-    => true
-    >> b = BibTeX.open('./ruby.bib')
-    >> b['pickaxe']
-    => "2009"
-    >> b['pickaxe'].title
-    => "Programming Ruby 1.9: The Pragmatic Programmer's Guide"
-    >> b[:pickaxe].author.length
-    => 3
-    >> b[:pickaxe].author.to_s
-    => "Thomas, Dave and Fowler, Chad and Hunt, Andy"
-    >> b[:pickaxe].author[2].first
-    => "Andy"
-    >> b['@book'].length
-    => 3
-    >> b['@article'].length
-    => 0
-    >> b['@book[year=2009]'].length
-    => 1
-
-BibTeX-Ruby helps you convert your bibliography to JSON, XML, or YAML;
-alternatively, you can export to the JSON format used by
-[CSL](http://citationstyles.org) processors and render the bibliography in
-one of [many different styles](https://github.com/citation-style-language/styles)
-([previews](http://www.zotero.org/styles/)):
-
-    >> require 'citeproc'  # requires the citeproc-ruby gem
-    => true
-    >> CiteProc.process b[:pickaxe].to_citeproc, :style => :apa
-    => "Thomas, D., Fowler, C., & Hunt, A. (2009). Programming Ruby 1.9: The Pragmatic Programmer's
+
+Open a BibTeX bibliography:
+
+    b = BibTeX.open('./ruby.bib')
+
+Select a BibTeX entry and access individual fields:
+
+    b['pickaxe'].title
+    #=> "Programming Ruby 1.9: The Pragmatic Programmer's Guide"
+    b[:pickaxe].author.length
+    #=> 3
+    b[:pickaxe].author.to_s
+    #=> "Thomas, Dave and Fowler, Chad and Hunt, Andy"
+    b[:pickaxe].author[2].first
+    #=> "Andy"
+
+Query a bibliography:
+
+    b['@book'].length
+    #=> 3 - the number books in the bibliography
+    b['@article'].length
+    #=> 0 - the number of articles in the bibliography
+    b['@book[year=2009]'].length
+    #=> 1 - the number of books published in 2009
+
+Render your bibliography in one of
+[many different citation styles](https://github.com/citation-style-language/styles)
+(requires the **citeproc-ruby** gem):
+
+    require 'citeproc'
+    CiteProc.process b[:pickaxe].to_citeproc, :style => :apa
+    #=> "Thomas, D., Fowler, C., & Hunt, A. (2009). Programming Ruby 1.9: The Pragmatic Programmer's
       Guide. The Facets of Ruby. Raleigh, North Carolina: The Pragmatic Bookshelf."
-    >> CiteProc.process b[:pickaxe].to_citeproc, :style => 'chicago-author-date'
-    => "Thomas, Dave, Chad Fowler, and Andy Hunt. 2009. Programming Ruby 1.9: The Pragmatic
+    CiteProc.process b[:pickaxe].to_citeproc, :style => 'chicago-author-date'
+    #=> "Thomas, Dave, Chad Fowler, and Andy Hunt. 2009. Programming Ruby 1.9: The Pragmatic
       Programmer's Guide. The Facets of Ruby.Raleigh, North Carolina: The Pragmatic Bookshelf."
-    >> CiteProc.process b[:pickaxe].to_citeproc, :style => :mla
-    => "Thomas, Dave, Chad Fowler, and Andy Hunt. Programming Ruby 1.9: The Pragmatic Programmer's
+    CiteProc.process b[:pickaxe].to_citeproc, :style => :mla
+    #=> "Thomas, Dave, Chad Fowler, and Andy Hunt. Programming Ruby 1.9: The Pragmatic Programmer's
       Guide. Raleigh, North Carolina: The Pragmatic Bookshelf, 2009."
 
+Save a bibliography to a file:
 
+    b.save
+    #=> saves the original file
+    b.save_to(file)
+    #=> saves the bibliography in a new file
 
-Requirements
-------------
 
-The BibTeX-Ruby gem has been tested on Ruby 1.8 and 1.9; it has
-been confirmed to work with REE, JRuby, and Rubinius;
-however, there have been some [issues](https://github.com/inukshuk/bibtex-ruby/issues)
-with MacRuby implementations.
 
-The parser generator [racc](http://i.loveruby.net/en/projects/racc/) is
-required to generate the BibTeX parser and the name parser; you do not need
-to install it to use the bibtex-ruby gem.
+Compatibility
+-------------
+
+The BibTeX-Ruby gem has been developed and tested on Ruby 1.8 and 1.9; it has
+been confirmed to work with JRuby, Rubinius, and REE, however, there have
+been repeated [issues](https://github.com/inukshuk/bibtex-ruby/issues)
+(performance mostly) with MacRuby caused by MacRuby's current StringScanner
+implementation.
 
 
 
-Usage
------
+Documentation
+-------------
 
 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
+containing BibTeX contents. By default, BibTeX-Ruby will discard all text outside
 of regular BibTeX elements; however, if you wish to include everything, simply add
 `:include => [:meta_content]` to your invocation of **BibTeX.open** or **BibTeX.parse**.
 
@@ -102,32 +112,45 @@ Alternatively, BibTeX-Ruby accepts ghost methods to conveniently access an entry
 similar to **ActiveRecord::Base**. Therefore, it is equally possible to access the
 'author' field above as `b[:pickaxe].author`.
 
+BibTeX-Ruby wraps all values of fields in an entry are wrapped in Value objects.
+This is necessary to transparently handle different types of values (e.g., strings,
+dates, names etc.). These Value objects are designed to be hardly discernible
+from regular Ruby strings, however, if you ever run into a problem with a field's
+value, simply convert it to a string by calling the `#to_s` method.
+
 Instead of parsing strings you can also create BibTeX elements directly in Ruby:
 
     > bib = BibTeX::Bibliography.new
+    
+Using a Hash:
+
     > 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'
-    > })
+        :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'
+      })
+
+Or programmatically:
+
     > book = BibTeX::Entry.new
     > book.type = :book
     > book.key = :mybook
     > bib << book
 
+
 ### Cross References
 
 From version 2.0, BibTeX-Ruby correctly resolves entry cross-references, which
 are commonly used for entries with type `inbook`, `incollection`, and
-`inproceedings`. When an entry has a valid citation key in field `crossref`,
+`inproceedings`. When an entry has a valid citation key in the field `crossref`,
 BibTeX-Ruby will return any fields inherited from the parent entry:
 
     > b = BibTeX.parse <<-END
@@ -157,43 +180,49 @@ Additionally, you can access individual elements or groups of elements via
 their index using `Bibliography#[]`; this accessor also exposes some of the
 query functionality with the exception of yielding to a block. For instance:
 
-    >> bib[-1]
+    bib[-1]
     => Returns the last element of the Bibliography or nil
-    >> bib[1,2]
+    bib[1,2]
     => Returns the second and third elements or nil
-    >> bib[1..2]
-    >> Same as above
-    >> bib[:key]
+    bib[1..2]
+    => Same as above
+    bib[:key]
     => Returns the first entry with key 'key' or nil
-    >> bib['key']
+    bib['key']
     => Returns all entries with key 'key' or []
-    >> bib['@article']
+    bib['@article']
     => Returns all entries of type 'article' or []
-    >> bib['@preamble']
+    bib['@preamble']
     => Returns all preamble objects (this is the same as Bibliography#preambles) or []
-    >> bib[/ruby/]
+    bib[/ruby/]
     => Returns all objects that match 'ruby' anywhere or []
-    >> bib['@book[keywords=ruby]']
+    bib['@book[keywords=ruby]']
     => Returns all books whose keywords attribute equals 'ruby' or []
-    >> bib.query('@book') { |e| e.keywords.split(/,/).length > 1 }
+    bib['@book[keywords!=ruby]']
+    => Returns all books whose keywords attribute does not equal 'ruby'
+    bib['@book[keywords/=ruby]']
+    => Same as above
+    bib.q('@book[keywords^=ruby]')
+    => Returns all books whose keywords attribute matches /ruby/
+    bib.query('@book') { |e| e.keywords.split(/,/).length > 1 }
     => Returns all book entries with two or more keywords or []
 
 Queries offer syntactic sugar for common enumerator invocations:
 
-    >> bib.query(:all, '@book')
+    bib.query(:all, '@book')
     => same as bib.select { |b| b.has_type?(:book) }
-    >> bib.query('@book')
+    bib.query('@book')
     => same as above
-    >> bib.query(:first, '@book')
+    bib.query(:first, '@book')
     => same as bib.detect { |b| b.has_type?(:book) }
-    >> bib.query(:none, '@book')
+    bib.query(:none, '@book')
     => same as bib.reject { |b| b.has_type?(:book) }
 
 You can also use queries to delete entries in your bibliography:
 
-    >> bib.delete(/ruby/)
+    bib.delete(/ruby/)
     => deletes all object that match 'ruby' in their string representation
-    >> bib.delete('@comment')
+    bib.delete('@comment')
     => strips all BibTeX comments from the bibliography
 
 
@@ -257,13 +286,13 @@ symbols that cannot be replaced will not be parsed.
 In the following example, string replacement can take place, thus all names
 are parsed and can easily be mapped to their last names:
 
-    >> BibTeX.parse(<<-END)[1].author.map(&:last)
-       @string{ ht = "Nathaniel Hawthorne" }
-       @book{key,
-         author = ht # " and Melville, Herman"
-       }
-       END
-    => ["Hawthorne", "Melville"]
+    BibTeX.parse(<<-END)[1].author.map(&:last)
+      @string{ ht = "Nathaniel Hawthorne" }
+      @book{key,
+       author = ht # " and Melville, Herman"
+      }
+      END
+    #=> ["Hawthorne", "Melville"]
 
 Another useful method is `Bibliography#names` which returns all names in
 your bibliography (authors, editors, translators). For example, to quickly
@@ -271,7 +300,9 @@ expand the initials of a name across your entire bibliography, you could
 use the following snippet:
 
     b.names.each do |name|
-      name.first = 'Edgar Allen' if name.first =~ /E\.\s*A\./ and name.last == 'Poe'
+      if name.sort_order =~ /^Poe, E/
+        name.first = 'Edgar Allen'
+      end
     end
 
 
@@ -284,15 +315,18 @@ to a given filter. Starting with version 1.3.9 BibTeX-Ruby includes a
 LaTeX filter that depends on the
 [latex-decode gem](http://rubygems.org/gems/latex-decode). Example:
 
-    >> faust = '@book{faust, title = {Faust: Der Trag\"odie Erster Teil}}'
-    >> BibTeX.parse(faust).convert(:latex)[:faust].title
-    => "Faust: Der Tragödie Erster Teil"
+    faust = '@book{faust, title = {Faust: Der Trag\"odie Erster Teil}}'
+    BibTeX.parse(faust).convert(:latex)[:faust].title
+    #=> "Faust: Der Tragödie Erster Teil"
 
 Conditional conversions are also supported:
 
-    >> faust1 = '@book{faust1, title = {Faust: Der Trag\"odie Erster Teil}}'
-    >> faust2 = '@book{faust2, title = {Faust: Der Trag\"odie Zweiter Teil}}'
-    >> p BibTeX.parse(faust1 + faust2).convert(:latex) { |e| e.key == :faust2 }.to_s
+    faust1 = '@book{faust1, title = {Faust: Der Trag\"odie Erster Teil}}'
+    faust2 = '@book{faust2, title = {Faust: Der Trag\"odie Zweiter Teil}}'
+    p BibTeX.parse(faust1 + faust2).convert(:latex) { |e| e.key == :faust2 }.to_s
+    
+Returns:
+
     @book{faust1,
       title = {Faust: Der Trag\"odie Erster Teil}
     }
@@ -304,6 +338,13 @@ If you need to express a condition on the basis of individual fields, use the
 conversion methods of BibTeX::Entry with a block instead (the block will be
 passed the key and value of each field prior to conversion).
 
+When working with Bibliographies that contain LaTeX it is often best to
+apply the filter upon opening or parsing the Bibliography. You can do this,
+by passing the `:filter` option:
+
+   BibTeX.open 'references.bib', :filter => :latex
+   
+
 ### Exports
 
 Furthermore, BibTeX-Ruby allows you to export your bibliography for processing
@@ -423,6 +464,7 @@ look at the LALR grammar in the file
 For more information about the BibTeX format and the parser's idiosyncrasies
 [refer to the project wiki](https://github.com/inukshuk/bibtex-ruby/wiki/The-BibTeX-Format).
 
+
 Contributing
 ------------
 
@@ -440,6 +482,10 @@ useful examples, take a look at the cucumber features in the
 [features/issues/](https://github.com/inukshuk/bibtex-ruby/blob/master/features/issues)
 directory).
 
+The parser generator [racc](http://i.loveruby.net/en/projects/racc/) is
+required to generate the BibTeX parser and the name parser; you do not need
+to install it to use the bibtex-ruby gem.
+
 To run the tests and cucumber examples execute these commands (from within
 the bibtex-ruby directory):
 
@@ -457,8 +503,11 @@ To execute the test suite continuously while you're working run:
 Credits
 -------
 
-Copyright 2011 [Sylvester Keil](http://sylvester.keil.or.at/).
+Copyright 2011-2012 [Sylvester Keil](http://sylvester.keil.or.at/).
+
+See the [contributor page on GitHub](https://github.com/inukshuk/bibtex-ruby/contributors)
+for a list of all the awesome developers who have made BibTeX-Ruby
+possible.
 
-BibTeX-Ruby was written by many awesome [contributors](https://github.com/inukshuk/bibtex-ruby/contributors)
-and is distributed under the terms and conditions of the GNU GPL. See
+This software is distributed under the terms and conditions of the GNU GPL. See
 LICENSE for details.

data/lib/bibtex/elements.rb

@@ -105,8 +105,22 @@ module BibTeX
     # Returns true if the element meets all of the given conditions.
     def meets?(*conditions)
       conditions.flatten.all? do |condition|
-        property, value = condition.split(/\s*=\s*/)
-        property.nil? || (respond_to?(property) && send(property).to_s == value)
+        property, operator, value = condition.split(/\s*([!~\/\^]?=)\s*/)
+        
+        if property.nil?
+          true
+        else
+          case operator
+          when '!=', '/='
+            !respond_to?(property) || send(property).to_s != value
+          when '^='
+            respond_to?(property) && send(property).to_s.match("^#{value}")
+          when '~='
+            respond_to?(property) && send(property).to_s.match(value)
+          else
+            respond_to?(property) && send(property).to_s == value
+          end
+        end
       end
     end
     

data/lib/bibtex/version.rb

@@ -18,6 +18,6 @@
 
 module BibTeX
   module Version
-    STRING = '2.0.5'.freeze
+    STRING = '2.0.6'.freeze
   end
 end

data/test/bibtex/test_bibliography.rb

@@ -124,6 +124,19 @@ module BibTeX
         assert_equal 1, @bib['@book[keywords=ruby]'].length
       end
 
+      it 'supports queries with negative conditions' do
+        assert_equal 2, @bib['@*[keywords!=ruby]'].length
+      end
+
+      it 'supports queries with pattern conditions' do
+        assert_equal 1, @bib['@*[keywords~=rails]'].length
+      end
+
+      it 'supports queries with start-pattern conditions' do
+        assert_equal 2, @bib['@*[keywords^=ruby]'].length
+      end
+
+
       it 'supports queries by bibtex element' do
         entry = Entry.parse(<<-END).first
         @article{segaran2007,

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bibtex-ruby
 version: !ruby/object:Gem::Version
-  version: 2.0.5
+  version: 2.0.6
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-04-19 00:00:00.000000000 Z
+date: 2012-04-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: latex-decode
-  requirement: &70347703840520 !ruby/object:Gem::Requirement
+  requirement: &70204962101620 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: 0.0.6
   type: :runtime
   prerelease: false
-  version_requirements: *70347703840520
+  version_requirements: *70204962101620
 - !ruby/object:Gem::Dependency
   name: multi_json
-  requirement: &70347703829060 !ruby/object:Gem::Requirement
+  requirement: &70204962100860 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -32,10 +32,10 @@ dependencies:
         version: '1.3'
   type: :runtime
   prerelease: false
-  version_requirements: *70347703829060
+  version_requirements: *70204962100860
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &70347703826940 !ruby/object:Gem::Requirement
+  requirement: &70204962100340 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -43,10 +43,10 @@ dependencies:
         version: '0.9'
   type: :development
   prerelease: false
-  version_requirements: *70347703826940
+  version_requirements: *70204962100340
 - !ruby/object:Gem::Dependency
   name: racc
-  requirement: &70347703825800 !ruby/object:Gem::Requirement
+  requirement: &70204962099640 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -54,10 +54,10 @@ dependencies:
         version: '1.4'
   type: :development
   prerelease: false
-  version_requirements: *70347703825800
+  version_requirements: *70204962099640
 - !ruby/object:Gem::Dependency
   name: rdoc
-  requirement: &70347703823800 !ruby/object:Gem::Requirement
+  requirement: &70204962098520 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -65,7 +65,7 @@ dependencies:
         version: '3.9'
   type: :development
   prerelease: false
-  version_requirements: *70347703823800
+  version_requirements: *70204962098520
 description: ! "\t\tBibTeX-Ruby is the Rubyist's swiss-army-knife for all things BibTeX.
   It\n    includes a parser for all common BibTeX objects (@string, @preamble,\n    @comment
   and regular entries) and a sophisticated name parser that\n    tokenizes correctly
@@ -180,18 +180,12 @@ required_ruby_version: !ruby/object:Gem::Requirement
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
-      segments:
-      - 0
-      hash: -230691617197525967
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
-      segments:
-      - 0
-      hash: -230691617197525967
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.10