beats-client 0.2.0 → 0.2.1

data/.gitignore

@@ -2,3 +2,5 @@
 .bundle
 Gemfile.lock
 pkg/*
+.yardoc/
+doc/

data/.rvmrc

@@ -1 +1 @@
-rvm 1.8.7@beats-ruby-client --create
+rvm 1.9.2@beats-ruby-client --create

data/.yardopts

@@ -0,0 +1,2 @@
+--markup-provider=redcarpet
+--markup=markdown

data/HISTORY.md

@@ -1,4 +1,12 @@
 
+### 0.2.1 (2012-02-09)
+
+* Much improved documentation (using YARD)
+
+### 0.2.0 (2012-02-01)
+
+* Added a "sentence" command
+
 ### 0.1.1 (2012-01-31)
 
 * Secure handling of password input

data/README.md

@@ -1,3 +1,58 @@
-# Beats Client
+Beats Client
+============
 
-A CLI client and SDK for Beats API.
+A CLI client and SDK for the Beats API.
+
+Setup
+-----
+
+Both the command line client and the SDK is packaged as a Ruby gem called
+"beats-client". It's available from rubygems.org, so simply install it with
+the gem command or using bundler:
+
+    $ gem install beats-client
+
+Example usage
+-------------
+
+```ruby
+require 'beats-client'
+
+# Create a client object
+client = Beats::Client.new
+
+# Create an authenticated client object
+client = Beats::Client.new(:access_token => '...')
+
+client.account # => { ... }
+client.resource('Arthur-Russell') # => { "uri" => "Arthur-Russell", "name" => "Arthur Russell", "type" => "Artist", ... }
+client.search('death metal') # => { "tracks" => [...], ... }
+```
+
+Development
+-----------
+
+If you want to make your own changes to beats-client, first clone the repo and
+run the tests:
+
+    git clone git://github.com/ProjectDaisy/beats-ruby-client.git
+    cd beats-ruby-client
+    bundle install
+    rake test
+
+Contributing
+------------
+
+Once you've made your great commits:
+
+1. Fork the repo
+2. Create a topic branch - git checkout -b my_branch
+3. Push to your branch - git push origin my_branch
+4. Create a Pull Request from your branch
+5. That's it!
+
+Author
+------
+
+Copyright ©2012 Beats Music Europe AB.
+Created by Niklas Holmgren (niklas@sutajio.se).

data/beats-client.gemspec

@@ -20,4 +20,7 @@ Gem::Specification.new do |s|
   s.add_dependency 'multi_json'
   s.add_dependency 'json_pure'
   s.add_development_dependency 'rake'
+  s.add_development_dependency 'yard'
+  s.add_development_dependency 'redcarpet'
+  s.add_development_dependency 'github-markup'
 end

data/lib/beats/auth.rb

@@ -1,15 +1,27 @@
 module Beats
+  # Helper class for asking for and handling authentication credentials. The
+  # CLI interface uses this class to prompt the user for her credentials when
+  # she tries to access a protected resource.
+  # @note Credentials are stored in a users home directiory in the file
+  #   ~/.beats/credentials.yml.
   class Auth
     class << self
 
+      # Prompt the user for her credentials. Will display an interactive
+      # command line prompt. If the credentials are valid they will be cached
+      # in the ~/.beats/credentials.yml file (as an access token).
       def login
         ask_for_credentials
       end
 
+      # Wipe the current users credentials from the system.
       def logout
         delete_credentials
       end
 
+      # Reads the users access token from her credentials file.
+      # @return [String] An access token, or nil if the user hasn't
+      #   authenticated yet.
       def access_token
         @credentials ||= read_credentials
         if @credentials

data/lib/beats/client.rb

@@ -24,30 +24,49 @@ module Beats
       @access_token = options[:access_token]
     end
 
+    # Retrieves the resource discovery index. The index is a set of links
+    # to other resources.
+    # @return [Hash] A hash with a "links" field (an array of hashes
+    #   representing the links).
     def index
       get(@base_url)
     rescue RestClient::MultipleChoices => e
       @index ||= decode_json(e.response.body)
     end
 
+    # Retrieves the representation of the currently authenticated user.
+    # Requires authentication.
+    # @return [Hash] A hash with info about the current user.
     def account
       decode_json(get(resolve_uri(@base_url, href(:account))))
     end
 
+    # Retrieves the representation of a resource.
+    # @param [String] uri A relative or absolute URI that names the resource.
+    # @return [Hash] A hash with at least the fields "uri", "name" and "type".
     def resource(uri)
       decode_json(get(resolve_uri(@base_url, uri)))
     end
 
+    # Performs a search in the music catalogue and returns the results.
+    # @param [String] query A search query, like "the beatles".
+    # @return [Hash] A hash with array fields for the different kinds of
+    #   resource types found.
     def search(query)
       decode_json(get(resolve_uri(@base_url, href(:search)),
         :params => { :q => query }))
     end
 
+    # Adds a resource (e.g. a track) to the currently authenticated users
+    # history. Requires authentication.
+    # @param [String] uri The *relative* URI for a resource (usually a track).
     def add_history(uri)
       post(resolve_uri(@base_url, href(:history)),
         :uri => uri)
     end
 
+    # Retrieves the building blocks for "The Sentence".
+    # @return [Hash] The bulding blocks for the sentence.
     def sentence
       decode_json(get(resolve_uri(@base_url, href(:sentence))))
     end

data/lib/beats/commands/base.rb

@@ -3,6 +3,11 @@ require 'yaml'
 
 module Beats
   module Command
+    # @abstract
+    # Beats::Command::Base is the base class for all commands.
+    # subclass it and add public methods that will become commands. Methods
+    # named like the subclass will become the default command for that
+    # command group.
     class Base
 
       attr_reader :args

data/lib/beats/version.rb

@@ -1,3 +1,3 @@
 module Beats
-  VERSION = '0.2.0'
+  VERSION = '0.2.1'
 end

metadata

@@ -1,90 +1,104 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: beats-client
-version: !ruby/object:Gem::Version 
-  hash: 23
+version: !ruby/object:Gem::Version
+  version: 0.2.1
   prerelease: 
-  segments: 
-  - 0
-  - 2
-  - 0
-  version: 0.2.0
 platform: ruby
-authors: 
+authors:
 - Niklas Holmgren
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2012-02-01 00:00:00 Z
-dependencies: 
-- !ruby/object:Gem::Dependency 
+date: 2012-02-21 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: rest-client
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
+  requirement: &70303674723960 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :runtime
-  version_requirements: *id001
-- !ruby/object:Gem::Dependency 
-  name: multi_json
   prerelease: false
-  requirement: &id002 !ruby/object:Gem::Requirement 
+  version_requirements: *70303674723960
+- !ruby/object:Gem::Dependency
+  name: multi_json
+  requirement: &70303674723540 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :runtime
-  version_requirements: *id002
-- !ruby/object:Gem::Dependency 
-  name: json_pure
   prerelease: false
-  requirement: &id003 !ruby/object:Gem::Requirement 
+  version_requirements: *70303674723540
+- !ruby/object:Gem::Dependency
+  name: json_pure
+  requirement: &70303674723120 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :runtime
-  version_requirements: *id003
-- !ruby/object:Gem::Dependency 
+  prerelease: false
+  version_requirements: *70303674723120
+- !ruby/object:Gem::Dependency
   name: rake
+  requirement: &70303674722700 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
   prerelease: false
-  requirement: &id004 !ruby/object:Gem::Requirement 
+  version_requirements: *70303674722700
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: &70303674722280 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :development
-  version_requirements: *id004
+  prerelease: false
+  version_requirements: *70303674722280
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: &70303674721860 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70303674721860
+- !ruby/object:Gem::Dependency
+  name: github-markup
+  requirement: &70303674721440 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70303674721440
 description: A CLI client and SDK for Beats API
-email: 
+email:
 - niklas@sutajio.se
-executables: 
+executables:
 - beats
 extensions: []
-
 extra_rdoc_files: []
-
-files: 
+files:
 - .gitignore
 - .rvmrc
+- .yardopts
 - Gemfile
 - HISTORY.md
 - README.md
@@ -108,38 +122,30 @@ files:
 - test/test_helper.rb
 homepage: https://github.com/ProjectDaisy/beats-ruby-client
 licenses: []
-
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
 rubyforge_project: 
-rubygems_version: 1.8.8
+rubygems_version: 1.8.15
 signing_key: 
 specification_version: 3
 summary: A CLI client and SDK for Beats API
-test_files: 
+test_files:
 - test/client_test.rb
 - test/command_test.rb
 - test/test_helper.rb
+has_rdoc: