/scholar

Search for and cite MLA sources.

Primary LanguageRubyMIT LicenseMIT

Scholar

Gem Version Build Status Code Climate Coverage Status

Scholar is a Ruby library for building MLA citations for scholarly works. Just pass Scholar your data and it'll do the rest.

Installation

Add this line to your Gemfile:

gem 'scholar'

And then run:

$ bundle install

Or install system-wide with:

$ gem install scholar

Usage

Citation

To create a citation, create a new Citation object.

salinger = Scholar::Citation.new({
  :type => :book,
  :media => :print,
  :title => "The Catcher in the Rye",
  :contributors => [
    {
      :role => :author,
      :first => "J",
      :middle => "D",
      :last => "Salinger"
    }
  ],
  :publisher => "Little, Brown",
  :city => "Boston",
  :year => "1995"
})
salinger.html # => Salinger, J. D. <em>Catcher in the Rye</em>. Boston: Little, Brown, 1995.

Scholar::Citation.new only takes a Hash with the attributes associated with the source.

Required Keys

Global Attributes

All source types can (and must) take these fields.

Key Description
:type The type of publication you're citing (see the wiki for a list of supported types). Must be a Symbol object.
:contributors An array of contributors (see below for details). If there are no contributors, pass an empty Array.
Contributors

The :contributors key is an array of hashes that define contributors. Here's an example.

:contributors => [
  {
    :role => :author,
    :first => "Douglas",
    :middle => "Noel",
    :last => "Adams"
  },
  {
    :role => :author,
    :first => "Eion",
    :last => "Colfer"
  },
  {
    :role => :editor,
    :first => "John",
    :last => "Sample",
    :suffix => "PhD"
  }
  {
    :role => :compiler,
    :first => "Steve",
    :last => "Jobs"
  },
  {
    :role => :translator,
    :first => "Bill",
    :last => "Gates"
  }
]

Each hash can take the following key-values:

Key Description
:role Must be :author, :editor, :translator, :compiler.
:first The contributor's first name (name).
:middle The contributor's middle name (will be shortened to a middle initial).
:last The contributor's last name (surname).
:suffix Any suffixes or titles the contributor has ("PhD", "Esq", "Jr", "KBD", et cetera). Omit any periods.

Search

search = Scholar::Search.new("harry potter")
search.results # => [#<Scholar::Citation>, #<Scholar::Citation>, ...]

Supported Ruby Versions

Scholar is tested on MRI versions 1.9.2, 1.9.3, and 2.0.0, JRuby 1.7.3, and Rubinius 2.0.0.

Contributing

  1. Fork the repository.
  2. Create a topic branch.
  3. Add tests for your unimplemented feature or bug fix.
  4. Write code until all tests (ran with bundle exec rspec) passes.
  5. Add documentation for your feature or bug fix.
  6. Add, commit, and push your changes.
  7. Submit a pull request.