Fetchworks
A simple gem for fetching information about works and authors from various open databases. Today, Internet Archive's Open Library is supported.
Installation
Install the gem and add to the application's Gemfile by executing:
$ bundle add fetchworks
If bundler is not being used to manage dependencies, install the gem by executing:
$ gem install fetchworks
Usage
# Works are fetched by initializing them with an ISBN
donquixote = OpenLibraryBook.new("9780062391667")
# OpenLibraryBook.data returns a hash of the OpenLibrary JSON reply
donquixote.data
# => { "title": "Don Quixote Deluxe Edition", "number_of_pages": "992" [...] }
donquixote.data["title"]
# => "Don Quixote Deluxe Edition"
# With one method, fetch JSON entries for all the author id's attached to a work
authors = donquixote.fetch_authors
# => [#<OpenLibraryAuthor:0x01 @data={...}>, #<OpenLibraryAuthor:0x02 @data={...}> ...]
cervantes = authors[0]
# => #<OpenLibraryAuthor:0x01>
cervantes.data
# => { "personal_name"=>"Miguel de Cervantes Saavedra",
# "birth_date"=>"29 Sep 1547" ... }
cervantes.data["personal_name"]
# => "Miguel de Cervantes Saavedra"
# JSON data for OpenLibraryBook and OpenLibraryAuthor can be accessed with methods:
donquixote.number_of_pages # => "992"
cervantes.bio # => "Miguel de Cervantes Saavedra was a Spanish novelist, poet, [...]"Dates
Given the partial nature of historical dates (oftentimes a year is known but a
month or day isn't), we provide a class PartialDate to represent dates returned
by methods
cervantes.birth_date # => #<PartialDate:0x01 @day=29, @month=9, @year=1547>
cervantes.birth_date.year # => 1547
donquixote.publish_date # => #<PartialDate:0x02 @day=16, @month=6, @year=2015>
donquixote.publish_date.day # => 16If you still want to access the original string format of a date that
OpenLibrary provides, you can through the @data hash.
cervantes.data["birth_date"] # => "29 Sep 1547"PartialDate is furnished with the instance methods: #year, #month, and #day, which
work as expected when a value is present, and return nil when one isn't. We also provide
convenience methods #to_date and #to_time which will return a ruby builtin Date or Time
object with the smallest possible values for the unknown attributes of the date.
# The unparsed OpenLibrary date string:
chaucer["birth_date"] # => "1343"
chaucer.birth_date # => #<PartialDate:0x01 @day=nil, @month=nil, @year=1343>
chaucer.birth_date.month # => nil
chaucer.birth_date.day # => nil
ruby_date = chaucer.birth_date.to_date # => #<Date:...>
ruby_date.month # => 1
ruby_date.day # => 1
ruby_time = chaucer.birth_date.to_time # => #<Time:...>
ruby_time.hour => 0
ruby_time.sec => 0Development
After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/davidgumberg/fetchworks.