scholar 0.1.0 → 0.1.1

data/.travis.yml

@@ -1,10 +1,9 @@
-branches:
-  only:
-    - master
 rvm:
   - 1.9.2
   - 1.9.3
   - 2.0.0
+  - jruby-19mode
+  - rbx-19mode
 script: bundle exec rspec spec
 notifications:
   email:

data/Gemfile

@@ -3,18 +3,21 @@ source 'https://rubygems.org'
 gemspec
 
 group :development, :test do
-  gem 'rake'
-  gem 'pry'
-  gem 'log_buddy'
+  gem 'rake', '~> 10.0'
+  gem 'pry', '~> 0.9.11'
+  gem 'log_buddy', '~> 0.7.0'
 end
 
 group :test do
-  gem 'rspec'
+  gem 'rspec', '~> 2.12.0'
 
-  gem 'factory_girl'
+  gem 'vcr', '~> 2.4.0'
+  gem 'webmock', '~> 1.8.0'
 
-  gem 'spork'
-  gem 'fuubar'
+  gem 'factory_girl', '~> 4.2.0'
 
-  gem 'cane'
+  gem 'spork', '~> 0.9.2'
+  gem 'fuubar', '~> 1.1.0'
+
+  gem 'cane', :platforms => :mri
 end

data/Gemfile.lock

@@ -1,8 +1,10 @@
 PATH
   remote: .
   specs:
-    scholar (0.1.0)
+    scholar (0.1.1)
       activesupport (~> 3.2.11)
+      faraday (~> 0.8.7)
+      faraday_middleware (~> 0.9.0)
 
 GEM
   remote: https://rubygems.org/
@@ -10,12 +12,19 @@ GEM
     activesupport (3.2.11)
       i18n (~> 0.6)
       multi_json (~> 1.0)
+    addressable (2.3.3)
     cane (2.5.0)
       parallel
     coderay (1.0.8)
+    crack (0.3.2)
     diff-lcs (1.1.3)
     factory_girl (4.2.0)
       activesupport (>= 3.0.0)
+    faraday (0.8.7)
+      multipart-post (~> 1.1)
+    faraday_middleware (0.9.0)
+      faraday (>= 0.7.4, < 0.9)
+    ffi (1.6.0-java)
     fuubar (1.1.0)
       rspec (~> 2.0)
       rspec-instafail (~> 0.2.0)
@@ -24,11 +33,17 @@ GEM
     log_buddy (0.7.0)
     method_source (0.8.1)
     multi_json (1.5.0)
+    multipart-post (1.2.0)
     parallel (0.6.1)
     pry (0.9.11.4)
       coderay (~> 1.0.5)
       method_source (~> 0.8)
       slop (~> 3.4)
+    pry (0.9.11.4-java)
+      coderay (~> 1.0.5)
+      method_source (~> 0.8)
+      slop (~> 3.4)
+      spoon (~> 0.0)
     rake (10.0.3)
     rspec (2.12.0)
       rspec-core (~> 2.12.0)
@@ -38,21 +53,30 @@ GEM
     rspec-expectations (2.12.1)
       diff-lcs (~> 1.1.3)
     rspec-instafail (0.2.4)
-    rspec-mocks (2.12.1)
+    rspec-mocks (2.12.2)
     ruby-progressbar (1.0.2)
     slop (3.4.3)
+    spoon (0.0.3)
+      ffi
     spork (0.9.2)
+    vcr (2.4.0)
+    webmock (1.8.11)
+      addressable (>= 2.2.7)
+      crack (>= 0.1.7)
 
 PLATFORMS
+  java
   ruby
 
 DEPENDENCIES
   cane
-  factory_girl
-  fuubar
-  log_buddy
-  pry
-  rake
-  rspec
+  factory_girl (~> 4.2.0)
+  fuubar (~> 1.1.0)
+  log_buddy (~> 0.7.0)
+  pry (~> 0.9.11)
+  rake (~> 10.0)
+  rspec (~> 2.12.0)
   scholar!
-  spork
+  spork (~> 0.9.2)
+  vcr (~> 2.4.0)
+  webmock (~> 1.8.0)

data/README.md

@@ -1,6 +1,32 @@
 # Scholar [![Build Status](https://secure.travis-ci.org/noted/scholar.png)](https://travis-ci.org/noted/scholar)
 
-Scholar is a Ruby library for building [MLA citations](http://www.mla.org/) for scholarly works.
+Scholar is a Ruby library for building [MLA citations](http://www.mla.org/) for scholarly works. Just pass Scholar your data and it'll do the rest.
+
+## Installation
+
+Add this line to your `Gemfile`:
+
+```ruby
+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.
 
 ```ruby
 salinger = Scholar::Citation.new({
@@ -22,18 +48,20 @@ salinger = Scholar::Citation.new({
 salinger.html # => Salinger, J. D. <em>Catcher in the Rye</em>. Boston: Little, Brown, 1995.
 ```
 
-## Usage
+`Scholar::Citation.new` only takes a `Hash` with the attributes associated with the source.
 
-To create a citation, you pass `Scholar::Citation` a hash with the attributes associated with the source. See the specific type on [the wiki](https://github.com/noted/scholar/wiki/Supported-Types) for the attributes available.
+### Required Keys
 
-### Global Attributes
+#### Global Attributes
 
-All source types can take these fields.
+All source types can (and must) take these fields.
 
-* `:type` &mdash; The type of publication you're citing ([see the wiki for a list of supported types](https://github.com/noted/scholar/wiki/Supported-Types)).
-* `:contributors` &mdash; An array of contributors (see below for details).
+Key             | Description
+----------------|-----------------------------------------
+`:type`         | The type of publication you're citing ([see the wiki for a list of supported types](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
+##### Contributors
 
 The `:contributors` key is an array of hashes that define contributors. Here's an example.
 
@@ -69,13 +97,26 @@ The `:contributors` key is an array of hashes that define contributors. Here's a
 ]
 ```
 
-Each hash can take the following fields:
+Each hash can take the following key-values:
 
-* `:role` &mdash; Can be `:author`, `:editor`, `:translator`, `:compiler`.
-* `:first` &mdash; The person's name.
-* `:middle` &mdash; The person's middle name (will convert to middle initial).
-* `:last` &mdash; The person's surname.
-* `:suffix` &mdash; Any suffixes the person has ("PhD", "Esq", "Jr", etc). Omit periods.
+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.
+
+## Supported Ruby Versions
+
+Scholar is tested on MRI version 1.9.2, 1.9.3, and 2.0.0.
+
+### Search
+
+```ruby
+search = Scholar::Search.new("harry potter")
+search.results # => [#<Scholar::Citation>, #<Scholar::Citation>, ...]
+```
 
 ## Contributing
 
@@ -89,6 +130,7 @@ Each hash can take the following fields:
 8. Add, commit, and push your changes.
 9. [Submit a pull request.][pr]
 
+[types]: https://github.com/noted/scholar/wiki/Supported-Types
 [fork]: http://help.github.com/fork-a-repo/
 [branch]: http://learn.github.com/p/branching.html
 [pr]: http://help.github.com/send-pull-requests/

data/lib/scholar/citation.rb

@@ -4,6 +4,9 @@ module Scholar
   # citation and the HTML citation itself.
   class Citation
 
+    # The raw hash given Citation.
+    attr_reader :raw
+
     # The pieces of data in the Citation.
     attr_reader :attributes
 
@@ -41,9 +44,13 @@ module Scholar
       source = "Scholar::Sources::#{options[:type].to_s.camelize}".constantize
 
       @attributes = options
+      @raw = @attributes.clone
       @attributes.delete(:type)
 
-      @attributes = Scholar::Utilities.contributors!(@attributes)
+      if @attributes[:contributors]
+        @attributes = Scholar::Utilities.contributors!(@attributes)
+      end
+
       @attributes = Scholar::Utilities.order!(@attributes, source.sequence)
 
       attributes = @attributes.clone
@@ -51,5 +58,21 @@ module Scholar
 
       @html = Scholar::Utilities.concatenate!(attributes)
     end
+
+    # Returns the Citation object in Hash form.
+    def to_hash
+      hash = {}
+
+      instance_variables.each do |v|
+        hash[v.to_s[1..-1].to_sym] = instance_variable_get(v)
+      end
+
+      hash
+    end
+
+    # Returns the Citation object in JSON form.
+    def to_json
+      hash = self.to_hash.to_json
+    end
   end
 end

data/lib/scholar/search.rb

@@ -0,0 +1,75 @@
+module Scholar
+
+  # A Search object containing search results
+  # for a query (currently only searches the
+  # Google Books API).
+  class Search
+
+    # The query performed.
+    attr_reader :query
+
+    # The results of the query.
+    attr_reader :results
+
+    # Searches for sources in Google Books.
+    #
+    # ==== Attributes
+    #
+    # * +query+ - The search term.
+    def initialize(query)
+      @@connection = Faraday.new(:url => "https://www.googleapis.com") do |f|
+        f.request  :json
+        f.response :json, :content_type => /\bjson$/
+        f.adapter  Faraday.default_adapter
+      end
+
+      # Remember the query.
+      @query = query
+
+      # Get the raw data.
+      @results = perform!(query)
+
+      # Turn that data into something a Citation class can understand.
+      @results = format!(@results)
+
+      self
+    end
+
+    private
+
+    def perform!(query)
+      request = @@connection.get do |r|
+        r.url "/books/v1/volumes", :q => query
+      end
+
+      request.body
+    end
+
+    def format!(hash)
+      arr = []
+
+      hash["items"].each do |i|
+        vol = i["volumeInfo"]
+
+        authors = vol["authors"]
+
+        contributors = []
+        authors.each do |a|
+          contributors << Scholar::Utilities::Contributor.new(a).attributes
+        end
+
+        citation = Scholar::Citation.new({
+          :type => :book,
+          :contributors => contributors,
+          :title => vol["title"],
+          :publisher => vol["publisher"],
+          :year => vol["publishedDate"][0,4]
+        })
+
+        arr << citation
+      end
+
+      arr
+    end
+  end
+end

data/lib/scholar/source.rb

@@ -9,7 +9,8 @@ module Scholar
       #
       # ==== Attributes
       #
-      # * +arr+ - Array of Symbols (keys). This is the order the hash's key will be in.
+      # * +arr+ - Array of Symbols (keys). This is the order the hash's key
+      #   will be in.
       def sequence(arr = nil)
         unless arr.nil?
           @@sequence = arr
@@ -22,7 +23,8 @@ module Scholar
       #
       # ==== Attributes
       #
-      # * +block+ - A block of +rule+ definitions. The rule definition should call a method in Scholar::Utilities::Formatters.
+      # * +block+ - A block of +rule+ definitions. The rule definition should
+      #   call a method in Scholar::Utilities::Formatters.
       #
       # ==== Example
       #
@@ -44,7 +46,8 @@ module Scholar
       # ==== Attributes
       #
       # * +key+ - The key of the hash to take the action on. Symbol.
-      # * +action+ - The action to take on the key. Should be a method within Scholar::Utilities::Formatters.
+      # * +action+ - The action to take on the key. Should be a method within
+      #   Scholar::Utilities::Formatters.
       def rule(key, &action)
         @@rules << [key, action]
       end

data/lib/scholar/utilities/contributor.rb

@@ -1,4 +1,6 @@
 module Scholar
+
+  # Generic utilities.
   class Utilities
 
     # A person associated with a work.
@@ -14,23 +16,33 @@ module Scholar
       #
       # ==== Attributes
       #
-      # * +hash+ - The data associated with the Contributor.
+      # * +data+ - The data associated with the Contributor.
       # * +order+ - Last-name first (+:last+) or first-name first (+:first+).
       #
       # ==== Options
       #
       # * +:first+ - The name of the Contributor.
-      # * +:middle+ - The middle name of the Contributor. Will be shortened to an initial.
+      # * +:middle+ - The middle name of the Contributor.
+      #   Will be shortened to an initial.
       # * +:last+ - The surname of the Contributor.
       # * +:suffix+ - The suffix of the Contributor (PhD, Esq, etc).
       #
       # ==== Examples
       #
-      #   Scholar::Utilities::Contributor.new({:first => "Douglas", :last => "Adams"})
-      def initialize(hash, order = :first)
+      #   Scholar::Utilities::Contributor.new({
+      #     :first => "Douglas",
+      #     :last => "Adams"
+      #   })
+      def initialize(data, order = :first)
+        if data.is_a?(String)
+          data = hash!(data)
+
+          data[:role] = :author
+        end
+
         @order = order
 
-        @attributes = order!(hash)
+        @attributes = order!(data)
         @name = name!(@attributes)
       end
 
@@ -54,6 +66,23 @@ module Scholar
 
       private
 
+      # Make a Hash out of a String.
+      def hash!(str)
+        data = str.split(" ")
+
+        result = Hash.new
+
+        result[:first] = data.first
+
+        result[:last] = data.last
+
+        if data[2]
+          result[:middle] = data[1]
+        end
+
+        result
+      end
+
       # Order according to the sequence.
       def order!(hash, method = @order)
         if method == :last

data/lib/scholar/utilities/contributor_list.rb

@@ -1,4 +1,6 @@
 module Scholar
+
+  # Generic utilities.
   class Utilities
 
     # A list of Contributors.

data/lib/scholar/utilities/data.rb

@@ -1,4 +1,6 @@
 module Scholar
+
+  # Generic utilities.
   class Utilities
 
     # Utilities for dealing with hashes and actually creating the

data/lib/scholar/utilities/formatters.rb

@@ -1,4 +1,6 @@
 module Scholar
+
+  # Generic utilities.
   class Utilities
 
     # String formatters.

data/lib/scholar.rb

@@ -1,9 +1,14 @@
 require 'json'
+
 require 'active_support/all'
 
+require 'faraday'
+require 'faraday_middleware'
+
 require_relative 'scholar/utilities'
 require_relative 'scholar/citation'
 require_relative 'scholar/source'
+require_relative 'scholar/search'
 
 # Allows for the creation of scholarly MLA citations.
 module Scholar

data/scholar.gemspec

@@ -5,7 +5,7 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 
 Gem::Specification.new do |gem|
   gem.name          = "scholar"
-  gem.version       = "0.1.0"
+  gem.version       = "0.1.1"
   gem.authors       = ["Ethan Turkeltaub"]
   gem.email         = ["ethan.turkeltaub@gmail.com"]
   gem.description   = %q{Generate valid MLA citations.}
@@ -19,4 +19,6 @@ Gem::Specification.new do |gem|
   gem.require_paths = ["lib"]
 
   gem.add_dependency 'activesupport', '~> 3.2.11'
+  gem.add_dependency 'faraday', '~> 0.8.7'
+  gem.add_dependency 'faraday_middleware', '~> 0.9.0'
 end

data/spec/scholar/search_spec.rb

@@ -0,0 +1,21 @@
+require 'spec_helper'
+
+describe Scholar::Search do
+  before do
+    VCR.insert_cassette 'search', :record => :all
+  end
+
+  describe ".new" do
+    let(:search) do
+      Scholar::Search.new("foobar")
+    end
+
+    it { search.query.should eql "foobar" }
+    it { search.results.should be_an_instance_of Array }
+    it { search.results[0].should be_an_instance_of Scholar::Citation }
+  end
+
+  after do
+    VCR.eject_cassette
+  end
+end

data/spec/scholar/utilities/data_spec.rb

@@ -81,7 +81,7 @@ describe Scholar::Utilities::Data do
 
   describe "#order!" do
     let(:hash) do
-      { :foobar => "Foo to the bar to the foo.", :bar => "Hello there.", :abc => "123" }
+      { :foobar => "Foobar.", :bar => "Hello there.", :abc => "123" }
     end
 
     let(:sequence) do

data/spec/spec_helper.rb

@@ -2,6 +2,9 @@ require 'spork'
 
 Spork.prefork do
   require 'rspec'
+  require 'vcr'
+  require 'webmock/rspec'
+
   require 'factory_girl'
 
   require 'log_buddy'
@@ -13,4 +16,12 @@ Spork.prefork do
   RSpec.configure do |c|
     c.include FactoryGirl::Syntax::Methods
   end
+
+  VCR.configure do |c|
+    c.configure_rspec_metadata!
+
+    c.cassette_library_dir = 'spec/cassettes'
+    c.default_cassette_options = { :record => :new_episodes }
+    c.hook_into :webmock
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: scholar
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-03-11 00:00:00.000000000 Z
+date: 2013-03-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -27,6 +27,38 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: 3.2.11
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.8.7
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.8.7
+- !ruby/object:Gem::Dependency
+  name: faraday_middleware
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.9.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.9.0
 description: Generate valid MLA citations.
 email:
 - ethan.turkeltaub@gmail.com
@@ -45,6 +77,7 @@ files:
 - Rakefile
 - lib/scholar.rb
 - lib/scholar/citation.rb
+- lib/scholar/search.rb
 - lib/scholar/source.rb
 - lib/scholar/sources/book.rb
 - lib/scholar/utilities.rb
@@ -55,6 +88,7 @@ files:
 - scholar.gemspec
 - spec/factories/contributor.rb
 - spec/factories/contributor_list.rb
+- spec/scholar/search_spec.rb
 - spec/scholar/source_spec.rb
 - spec/scholar/sources/book_spec.rb
 - spec/scholar/utilities/contributor_list_spec.rb
@@ -77,7 +111,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -551428721
+      hash: 1067264813
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -86,7 +120,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -551428721
+      hash: 1067264813
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.25
@@ -96,6 +130,7 @@ summary: Generate valid MLA citations.
 test_files:
 - spec/factories/contributor.rb
 - spec/factories/contributor_list.rb
+- spec/scholar/search_spec.rb
 - spec/scholar/source_spec.rb
 - spec/scholar/sources/book_spec.rb
 - spec/scholar/utilities/contributor_list_spec.rb