README.md in filmbuff-0.1.6 vs README.md in filmbuff-1.0.0
- old
+ new
@@ -1,28 +1,37 @@
# Film Buff - A Ruby wrapper for IMDb's JSON API
+[](https://rubygems.org/gems/filmbuff)
+[](https://travis-ci.org/sachse/filmbuff)
+[](https://gemnasium.com/sachse/filmbuff)
+[](https://coveralls.io/r/sachse/filmbuff)
+[](https://inch-ci.org/github/sachse/filmbuff/)
+
## Description
Film Buff provides a Ruby wrapper for IMDb's JSON API, which is the fastest and easiest way to get information from IMDb.
-## Installation
+Film Buff supports IMDb's different locales, so information can be retrieved in different languages. See [Locales](#locales) for more information.
-### RubyGems
+## Usage
-You can install the latest Film Buff gem using RubyGems
+Film Buff 1.0.x provides two ways to return information on a movie or TV show. First, set up an IMDb instance:
- gem install filmbuff
+ require 'filmbuff'
+ imdb = FilmBuff.new
-### GitHub
+### look_up_id
-Alternatively you can check out the latest code directly from Github
+If you know the movie or TV show's IMDb ID you can return an object with the IMDb information:
- git clone http://github.com/sachse/filmbuff.git
+ movie = imdb.look_up_id('tt0032138')
-## Usage
+ movie.title => "The Wizard of Oz"
+ movie.rating => 8.2
+ movie.genres => ["Adventure", Family", "Fantasy", "Musical"]
-Accessible title information is:
+Accessible information for an object returned by `look_up_id` is:
- Title
- Tagline
- Plot
- Runtime
@@ -31,57 +40,126 @@
- Poster URL
- Genres
- Release date
- IMDb ID
-### Examples
+### search_for_title
-Film Buff 0.1.x provides two easy ways to return an object with information on a movie or TV show. First, set up an IMDb instance:
+You can also search for a movie or TV show by its title. This will return an array with results from IMDb's search feature:
- require 'filmbuff'
- imdb = FilmBuff::IMDb.new
+ results = imdb.search_for_title('The Wizard of Oz')
-You can then find a movie by its title. This will return the first result from IMDb's search feature:
+ results => [
+ {
+ :type => "title_popular",
+ :imdb_id => "tt0032138",
+ :title => "The Wizard of Oz",
+ :release_year => "1939"
+ },
- movie = imdb.find_by_title("The Wizard of Oz")
-
- movie.title => "The Wizard of Oz"
- movie.rating => 8.3
- movie.genres => ["Adventure", "Comedy", "Family", "Fantasy", "Musical"]
+ {
+ :type => "title_exact",
+ :imdb_id => "tt0016544",
+ :title => "The Wizard of Oz",
+ :release_year => "1925"
+ },
-If you know the movie's IMDb ID you can get the information as well:
+ {
+ :type=>"title_exact",
+ :imdb_id=>"tt0001463",
+ :title=>"The Wonderful Wizard of Oz",
+ :release_year=>"1910"
+ },
- movie = imdb.find_by_id("tt0032138")
-
- movie.title => "The Wizard of Oz"
- movie.rating => 8.3
- movie.genres => ["Adventure", "Comedy", "Family", "Fantasy", "Musical"]
+ etc.
-To retrieve information in a different language, set the instance variable locale to your wanted locale:
+ ]
- imdb.locale = "de_DE"
- movie = imdb.find_by_id("tt0032138")
-
- movie.title => "Das zauberhafte Land"
- movie.rating => 8.3
- movie.genres => ["Abenteuer", "Komödie", "Familie", "Fantasy", "Musical"]
+### Configuration
+When initializing a new `FilmBuff` instance keyword arguments can passed to change default behaviours:
+
+- SSL is used by default when communicating with IMDb but it can be turned off by setting `ssl` to false.
+- Locale defaults to `en_US` but this behaviour can be changed by passing `locale` with a different value. Locale can also be changed as necessary during runtime. See [Locales](#locales) for more information.
+
+`search_for_title` also takes keyword arguments that can be used to change the default behaviours on a per search basis.
+
+- `limit` limits the amount of results returned.
+- `types` decides the types of titles IMDb will search. Valid settings are:
+ - title_popular
+ - title_exact
+ - title_approx
+ - title_substring
+
+#### Examples
+
+Return only 2 results:
+
+ results = imdb.search_for_title('The Wizard of Oz', limit: 2)
+
+ results => [
+ {
+ :type => "title_popular",
+ :imdb_id => "tt0032138",
+ :title => "The Wizard of Oz",
+ :release_year => "1939"
+ },
+
+ {
+ :type => "title_exact",
+ :imdb_id => "tt0016544",
+ :title => "The Wizard of Oz",
+ :release_year => "1925"
+ }
+ ]
+
+
+Only return popular results related to the title provided:
+
+ result = imdb.search_for_title('The Wizard of Oz', types: %w(title_popular))
+
+ result => [
+ {
+ :type => "title_popular",
+ :imdb_id => "tt0032138",
+ :title => "The Wizard of Oz",
+ :release_year => "1939"
+ }
+ ]
+
+#### Locales
+
+To retrieve information in a different language, either pass locale as as keyword argument when setting up an instance of `imdb` or set the instance variable `locale` to your wanted locale once the instance has already been created:
+
+ imdb.locale = 'fr_FR'
+ movie = imdb.look_up_id('tt0032138')
+
+ movie.title => "Le magicien d'Oz"
+ movie.rating => 8.2
+ movie.genres => ["Aventure", "Famille", "Fantasy", "Musical"]
+
Supported locales are
- de_DE (German)
- en_US (English) (Default)
- es_ES (Spanish)
- fr_FR (French)
- it_IT (Italian)
- pt_PT (Portuguese)
+## Links
+
+- [Public git repository](https://github.com/sachse/filmbuff)
+- [Online documentation](http://rubydoc.info/gems/filmbuff/frames)
+- [Issue tracker](https://github.com/sachse/filmbuff/issues)
+- [Film Buff on RubyGems](https://rubygems.org/gems/filmbuff)
+
## Authors
-* [Kristoffer Sachse](https://github.com/sachse)
+- [Kristoffer Sachse](https://github.com/sachse)
## Contribute
-Fork the project, implement your changes in it's own branch, and send
-a pull request to me. I'll gladly consider any help or ideas.
+You can contribute either with code by forking the project, implementing your changes in its own branch, and sending a pull request, or you can report issues and ideas for changes [on the issues page](https://github.com/sachse/filmbuff/issues).
### Contributors
-- Jon Maddox (https://github.com/maddox) inspired the 0.1.0 rewrite through the imdb_party gem.
+- [Jon Maddox](https://github.com/maddox) inspired the 0.1.0 rewrite through his imdb_party gem.