BoardGameGem 0.1.5 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 595da194a9ed8fd8cf200463247c600a87e29e79
-  data.tar.gz: 7a2292976753fde54678aa9d25e19ee351df971b
+  metadata.gz: f37eaa1b94b6fb0d31a7d65756b3c020d46e11cf
+  data.tar.gz: 47327435fb477799e0edea1f61618237493164f3
 SHA512:
-  metadata.gz: 71b49cf8e32632ff33f65cea8fc42aacaa6cb13e2498c8d96ae1c3f49f69ecb686078d47d9ba18c67e4444758652526824d052561e35c848e0ba36461ff36d8c
-  data.tar.gz: e6bd6af6413e4cbf44be2baca02c31df14b71724bb70f82bc9405b5c560ab3d9eed584f1ac9a1381c5fb9cd07b0d138e5481b7b39145787bed4d6c859b22b16c
+  metadata.gz: bf13ab6669adf49a0ad29c80a9948f59f0e0ab01bdd0f0638f8bed7b48c83b0d74d33003479106a857139b2311452b69d6328957a2662d4f790a35fad8a01f58
+  data.tar.gz: 9f65f21102d46cae68f37be9d6f95b297da379fdba017981a592149c36bcef761f01aee2d8c028c132b1e99cf05e815324830aa8ae518b0154676a14b36e6d66

data/README.md

@@ -1,8 +1,5 @@
-# Boardgamegem
-
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/boardgamegem`. To experiment with that code, run `bin/console` for an interactive prompt.
-
-TODO: Delete this and the text above, and describe your gem
+# BoardGameGem
+BoardGameGem provides a Ruby interface to the [BoardGameGeek XML API](http://www.boardgamegeek.com/xmlapi2) (version 2). It's designed to work with the Rails cache to reduce the number of requests when working with Rails.
 
 ## Installation
 
@@ -22,17 +19,79 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+Requests to retrieve data can be made using any of the methods in the BoardGameGem module. Arguments in brackets are optional.
+
+The `options` argument is a hash which allows any other parameter. For example, if you wished to limit a collection by subtype, you could pass the hash `{ subtype: "boardgame" }` as `options`.
+
+---
+
+`get_item(id, [statistics], [options])`: Retreive a specific item from BGG by ID. Within the BGG API, this is called a 'thing' rather than an 'item'. If an item with that ID is not found, `nil` is returned.
+
+If `statistics` is true, averages, weights, and rankings will be retrieved as well. By default, `statistics` is false.
+
+`get_item` returns a `BGGItem` object, which has the following attributes:
+`:id, :type, :thumbnail, :name, :description, :year_published, :min_players, :max_players,
+:playing_time, :min_playing_time, :max_playing_time, :statistics`. 
+
+`:statistics` is a hash, with the following keys: `:user_ratings, :average, :bayes, :ranks, :stddev, :median, :owned, :trading, :wanted, :wishing, :num_comments, :num_weights, :average_weight`. Within this, `:ranks` is an array, containing hashes with the following keys: `:type, :name, :friendly_name, :value, :bayes`.
+
+---
+
+`get_family(id, [options])`: Retrieves information on a data family. Returns a `BGGFamily` object, which has the following attributes: `:id, :thumbnail, :image, :name, :alternate_names, :description`. Within this, `:alternate_names` is an array of strings. If a family with that ID is not found, `nil` is returned.
+
+---
+
+`get_user(username, [options])`: Retreives information on a specific user by name. If a user with that name does not exist, `nil` is returned.
+
+`get_user` returns a `BGGUser` object, which has the following attributes: `:id, :name, :avatar, :year_registered, :last_login, :state, :trade_rating`
+
+#### Methods
+`get_collection`: Returns this user's collection, as if `BoardGameGem.get_collection` was called using this user's name.
+
+---
+
+`get_collection(username, [options])`: Returns a user's collection by username. Returns a `BGGCollection` object, which has two attributes: `:count`, the number of items in the collection, and `:items`, an array consisting of many `BGGCollectionItem` objects.
+
+The BGG API queues requests to retrieve a user's collection, returning a 202 status code and a 'please wait' message. When BoardGameGem makes a request and sees a 202 code, it waits a short time before issuing the request again. After 10 tries, BoardGameGem will give up and return `nil`. **You should not make multiple `get_collection` requests to handle queueing yourself.**
+
+#### Methods
+`get_owned`: Returns itmes in this collection that are flagged as 'owned'.
+
+`get_previously_owned`: Returns items in this collection that are flagged as 'previously owned'.
+
+`get_wants`: Returns items in this collection that are flagged as 'want'.
+
+`get_want_to_play`: Returns items in this collection that are flagged as 'want to play'.
+
+`get_want_to_buy`: Returns items in this collection that are flagged as 'want to buy'.
+
+`get_wishlist`: Returns items in this collection that are on the collection owner's wishlist.
+
+`get_preordered`: Returns items in this collection that are flagged as 'preordered'.
+
+#### BGGCollectionItem
+
+The BGG API returns a subset of an item's data when including it in a collection request. As a result, a `BGGCollectionItem` contains the following attributes: `:id, :type, :name, :year_published, :image, :thumbnail, :num_players, :status, :num_plays`. Within this, `:status` is a hash containing the following keys: `:own, :prev_owned, :for_trade, :want, :want_to_play, :want_to_buy, :wishlist, :preordered:, :last_modified`. 
+
+`BGGCollectionItem` contains one other method, `to_item([statistics])`, which returns the `BGGItem` version of this object.
+
+---
+
+`search(query, [options])`: Performs a search request, returning any items which are like the query. Returns a hash with the keys `:total`, the number of items found in the search, and `:items`, an array of `BGGSearchResult` objects.
+
+#### BGGSearchResult
+
+Much like `BGGCollectionItem`, `BGGSearchResult` is a subset of `BGGItem`, and contains the following attributes: `:id, :type, :name, :year_published`.
 
-## Development
+A `BGGItem` version of this object can be requested with `to_item([statistics])`.
 
-After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+### But the BGG API has more than just this!
 
-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 tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+I made this gem to help make requests for another one of my projects, [Math Trade Manager](http://www.github.com/acceptableice/math-trade-manager), and thus haven't finished implementing the other BGG API features that Math Trade Manager didn't require. If you need something specific for your application, log an issue, message me on Twitter ([@AcceptableIce](http://www.twitter.com/acceptableice)), or email me at [jakeroussel@mac.com](mailto:jakeroussel@mac.com). This is my first gem, so there are probably some issues. Let me know!
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/boardgamegem. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+Bug reports and pull requests are welcome on GitHub at https://github.com/acceptableice/boardgamegem. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
 
 
 ## License

data/boardgamegem.gemspec

@@ -24,7 +24,19 @@ Gem::Specification.new do |spec|
   spec.bindir        = "exe"
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
+  
+  dependencies = [
+    # Examples:
+    [:runtime,     "nokogiri"],
+    [:development, "bundler"],
+    [:development, "rake"]
+  ]
 
-  spec.add_development_dependency "bundler", "~> 1.12"
-  spec.add_development_dependency "rake", "~> 10.0"
+  dependencies.each do |type, name, version|
+    if spec.respond_to?("add_#{type}_dependency")
+      spec.send("add_#{type}_dependency", name, version)
+    else
+      spec.add_dependency(name, version)
+    end
+  end
 end

data/lib/bgg_collection_item.rb

@@ -19,6 +19,7 @@ module BoardGameGem
 				:want_to_play => get_boolean(xml, "status", "wanttoplay"),
 				:want_to_buy => get_boolean(xml, "status", "wanttobuy"),
 				:wishlist => get_boolean(xml, "status", "wishlist"),
+				:wishlist_priority => get_integer(xml, "status", "wishlistpriority"),
 				:preordered => get_boolean(xml, "status", "preordered"),
 				:last_modified => get_datetime(xml, "status", "lastmodified")
 			}

data/lib/boardgamegem/version.rb

@@ -1,3 +1,3 @@
 module BoardGameGem
-  VERSION = "0.1.5"
+  VERSION = "0.1.6"
 end

metadata

@@ -1,43 +1,57 @@
 --- !ruby/object:Gem::Specification
 name: BoardGameGem
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.1.6
 platform: ruby
 authors:
 - Jake Roussel
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-05-09 00:00:00.000000000 Z
+date: 2016-05-11 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.12'
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.12'
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '0'
 description: 
 email:
 - jakeroussel@mac.com