CiteProc-Ruby

CiteProc-Ruby is a CSL 1.0 (Citation Style Language) Processor written in Ruby.

A word of caution: this release of CiteProc-Ruby is purely experimental; the API is not complete and liable to change frequently. This release is expected to work in Ruby version 1.9.2. only. CiteProc-Ruby currently passes approximately 350 of the 550 tests in the citeproc-test suite.

Note: the citeproc-ruby gem is going to be integrated with the separate citeproc and citeproc-js gems; meanwhile, however, these gems are not compatible, so if you want to use the current citeproc-ruby gem, make sure that neither of the other gems is installed.

Unicode support may be provided by the unicode-utils gem (on Ruby 1.9 only), by ActiveSupport, by the unicode gem (on Ruby 1.8 only), by the Java-based support in JRuby, or naively by the upcase and downcase methods present in Ruby by default. These gems are not installed automatically; install one manually if you want enhanced Unicode support.

Quickstart

    $ [sudo] gem install citeproc-ruby
    $ [sudo] gem install unicode-utils # Ruby 1.9
    $ [sudo] gem install unicode # Ruby 1.8
    $ irb
    >> require 'citeproc'
    >> book = {
        'author' => [{ 'given' => 'Edgar Allen', 'family' => 'Poe' }],
        'title' => 'Poetry, Tales, and Selected Essays',
        'type' => 'book',
        'issued' => { 'date-parts' => [[1996]] },
        'editor' => [{ 'family' => 'Quinn', 'given' => 'Patrick F.'}, { 'family' => 'Thompson', 'given' => 'G.R.' }],
        'publisher' => 'Library of America',
        'publisher-place' => 'New York'
    }
    >> CiteProc.process(book)
    => "Poe, E. A. (1996). Poetry, Tales, and Selected Essays.  (P. F. Quinn & G. R. Thompson, Eds.). New York: Library of America."
    >> CiteProc.process(book, :format => :html)
    => "Poe, E. A. (1996). <i>Poetry, Tales, and Selected Essays</i>.  (P. F. Quinn &#38; G. R. Thompson, Eds.). New York: Library of America."
    >> CiteProc.process(book, :mode => :citation)
    => ["(Poe, 1996)"]
    >> CiteProc.process(book, :style => "https://github.com/citation-style-language/styles/raw/master/chicago-author-date.csl")
    => "Poe, Edgar Allen. 1996. Poetry, Tales, and Selected Essays. Ed. Patrick F. Quinn and G.R. Thompson. New York: Library of America."

The RSpec examples are a valuable resource of usage examples.

Credits

CiteProc-Ruby was written by Sylvester Keil; thanks to the excellent documentation and specifications of the CSL, citeproc-js, the citeproc-test suite, and the kind feedback and support at the xbiblio mailing list.

License

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

The views and conclusions contained in the software and documentation are those of the authors and should not be interpreted as representing official policies, either expressed or implied, of the copyright holder.