rspotify 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4b8f239c93e7f8445a6ab7963b82551dae8d2fa5
-  data.tar.gz: 0201d9d38995ffcd8b7d218402e5ef047898b890
+  metadata.gz: 099ef6df09a9e5e69ec2765409c9d4262f4e5e30
+  data.tar.gz: 9f00aa8931f67d946b158391c7afa99e05fad61b
 SHA512:
-  metadata.gz: 318e529c2896ad7563d85c64b74833df356d2987a78fabb1f207f9ba7eb8ecd8f2a94d78797f1eb316c46964a48c110d7a35723c4db8a633e90c0fd29133f3b7
-  data.tar.gz: 0433cdf3d380e6d945ba3b3ee7357111a127b2d2d1f2d043f9f498e9ca14646f065116994e6823491b1c5cdcd7e3738418615c8668f240714155af45c165ed8c
+  metadata.gz: 451f177d91bcf3cb1025cac3d448b0a69a0216faf51c0f6285a0499ce36435fc6aa04b5d1de6890617339f3f50164e0c71ffaa9697430eb2429e0f8e05d98e9e
+  data.tar.gz: 759310516f92db6b07e71e8afd8ca4b4da649376fff85580d19ea394d0f0d6b34245e68dd1e5bafb27abd55950eee5c3ee32f3e3258802af5f8a025bef91ea1c

data/README.md

@@ -137,22 +137,24 @@ get '/auth/spotify/callback', to: 'users#spotify'
 
 Remember you need to tell Spotify this address is white-listed. You can do this by adding it to the Redirect URIs list in your [application page](https://developer.spotify.com/my-applications). An example of Redirect URI would be http://localhost:3000/auth/spotify/callback.
 
-Finally, create a new RSpotify User with the token received:
+Finally, create a new RSpotify User with the response received:
 
 ```ruby
 class UsersController < ApplicationController
   def spotify
     spotify_user = RSpotify::User.new(request.env['omniauth.auth'])
-    # Now you can create playlists for the user and much more!
+    # Now you can access user's private data, create playlists and much more
 
+    # Access private data (Check doc for all attributes)
+    spotify_user.country #=> "US"
+    spotify_user.email   #=> "example@email.com"
+
+    # Create playlist in user's Spotify account
     playlist = spotify_user.create_playlist!('my-awesome-playlist')
-    # Directly creates playlist in user's Spotify account and returns it
 
+    # Add tracks to a playlist in user's Spotify account
     tracks = RSpotify::Track.search('Know')
-
     playlist.add_tracks!(tracks)
-    # user's Spotify account now has a playlist with songs containing "Know" in the name
-
     playlist.tracks.first.name #=> "Somebody That I Used To Know"
   end
 end

data/lib/rspotify/album.rb

@@ -2,13 +2,13 @@ module RSpotify
 
   # @attr [String]        album_type             The type of the album (album, single, compilation)
   # @attr [Array<Artist>] artists                The artists of the album
-  # @attr [Array<String>] available_markets      The markets in which the album is available: {http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 ISO 3166-1 alpha-2 country codes}
+  # @attr [Array<String>] available_markets      The markets in which the album is available. See {http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 ISO 3166-1 alpha-2 country codes}
   # @attr [Hash]          external_ids           Known external IDs for the album
-  # @attr [Array<String>] genres                 A list of the genres used to classify the album (If not yet classified, the array is empty)
+  # @attr [Array<String>] genres                 A list of the genres used to classify the album. If not yet classified, the array is empty
   # @attr [Array<Hash>]   images                 The cover art for the album in various sizes, widest first
   # @attr [String]        name                   The name of the album
-  # @attr [Integer]       popularity             The popularity of the album - The value will be between 0 and 100, with 100 being the most popular
-  # @attr [String]        release_date           The date the album was first released, for example "1981-12-15" - Depending on the precision, it might be shown as "1981" or "1981-12"
+  # @attr [Integer]       popularity             The popularity of the album. The value will be between 0 and 100, with 100 being the most popular
+  # @attr [String]        release_date           The date the album was first released, for example "1981-12-15". Depending on the precision, it might be shown as "1981" or "1981-12"
   # @attr [String]        release_date_precision The precision with which release_date value is known: "year", "month", or "day"
   # @attr [Array<Track>]  tracks                 The tracks of the album.
   class Album < Base
@@ -33,7 +33,7 @@ module RSpotify
 
     # Returns array of Album objects matching the query, ordered by popularity
     #
-    # @param query  [String]  The search query's keywords.
+    # @param query  [String]  The search query's keywords. See the q description in {https://developer.spotify.com/web-api/search-item here} for details.
     # @param limit  [Integer] Maximum number of albums to return. Minimum: 1. Maximum: 50.
     # @param offset [Integer] The index of the first album to return. Use with limit to get the next set of albums.
     # @return [Array<Album>]

data/lib/rspotify/artist.rb

@@ -1,9 +1,9 @@
 module RSpotify
 
-  # @attr [Array<String>] genres     A list of the genres used to classify the album (If not yet classified, the array is empty)
+  # @attr [Array<String>] genres     A list of the genres used to classify the album. If not yet classified, the array is empty.
   # @attr [Array<Hash>]   images     The cover art for the album in various sizes, widest first
   # @attr [String]        name       The name of the album
-  # @attr [Integer]       popularity The popularity of the album - The value will be between 0 and 100, with 100 being the most popular
+  # @attr [Integer]       popularity The popularity of the album. The value will be between 0 and 100, with 100 being the most popular
   class Artist < Base
 
     # Returns Artist object(s) with id(s) provided
@@ -26,7 +26,7 @@ module RSpotify
 
     # Returns array of Artist objects matching the query, ordered by popularity
     #
-    # @param query  [String]  The search query's keywords.
+    # @param query  [String]  The search query's keywords. See the q description in {https://developer.spotify.com/web-api/search-item here} for details.
     # @param limit  [Integer] Maximum number of artists to return. Minimum: 1. Maximum: 50.
     # @param offset [Integer] The index of the first artist to return. Use with limit to get the next set of artists.
     # @return [Array<Artist>]

data/lib/rspotify/base.rb

@@ -42,20 +42,18 @@ module RSpotify
     end
 
     def self.find_many(ids, type)
-      pluralized_type = "#{type}s"
       type_class = RSpotify.const_get(type.capitalize)
 
-      path = "#{pluralized_type}?ids=#{ids.join ','}"
+      path = "#{type}s?ids=#{ids.join ','}"
       json = RSpotify.get path
-      json[pluralized_type].map { |t| type_class.new t }
+      json["#{type}s"].map { |t| type_class.new t }
     end
     private_class_method :find_many
 
     def self.find_one(id, type)
-      pluralized_type = "#{type}s"
       type_class = RSpotify.const_get(type.capitalize)
 
-      path = "#{pluralized_type}/#{id}"
+      path = "#{type}s/#{id}"
       json = RSpotify.get path
       type_class.new json
     end
@@ -63,11 +61,11 @@ module RSpotify
 
     # Returns array of RSpotify objects matching the query, ordered by popularity
     #
-    # @param query  [String]  The search query's keywords.
-    # @param type   [String]  Valid types are: album, artist and track
+    # @param query  [String]  The search query's keywords. See the q description in {https://developer.spotify.com/web-api/search-item here} for details.
+    # @param type   [String]  Valid types are: album, artist and track. Separate multiple types with commas.
     # @param limit  [Integer] Maximum number of objects to return. Minimum: 1. Maximum: 50.
     # @param offset [Integer] The index of the first object to return. Use with limit to get the next set of objects.
-    # @return [Array<Album>, Array<Artist>, Array<Track>]
+    # @return [Array<Base>]
     #
     # @example
     #           artists = RSpotify::Base.search('Arctic', 'artist')
@@ -77,25 +75,26 @@ module RSpotify
     #
     #           albums = RSpotify::Base.search('AM', 'album', 10)
     #           albums.size #=> 10
-    def self.search(query, type, limit = 20, offset = 0)
+    def self.search(query, types, limit = 20, offset = 0)
       if limit < 1 || limit > 50
         warn 'Limit must be between 1 and 50'
         return false
       end
 
-      pluralized_type = "#{type}s"
-      type_class = RSpotify.const_get(type.capitalize)
+      types.gsub!(/\s+/, '')
 
       json = RSpotify.get 'search',
         params: {
           q:      query,
-          type:   type,
+          type:   types,
           limit:  limit,
           offset: offset
         }
 
-      items = json[pluralized_type]['items']
-      items.map { |item| type_class.new item }
+      types.split(',').flat_map do |type|
+        type_class = RSpotify.const_get(type.capitalize)
+        json["#{type}s"]['items'].map { |item| type_class.new item }
+      end
     end
 
     def initialize(options = {})
@@ -117,8 +116,7 @@ module RSpotify
     #           track.complete!
     #           track.instance_variable_get("@popularity") #=> 62
     def complete!
-      pluralized_type = "#{@type}s"
-      initialize RSpotify.get("#{pluralized_type}/#{@id}")
+      initialize RSpotify.get("#{type}s/#{@id}")
     end
 
     # Used internally to retrieve an object's instance variable. If instance

data/lib/rspotify/playlist.rb

@@ -50,7 +50,23 @@ module RSpotify
       super(options)
     end
 
-    #TODO doc
+    # Adds one or more tracks to a playlist in user's Spotify account. This method is only available when
+    # the current user has granted access to the *playlist-modify* and *playlist-modify-private* scopes.
+    # 
+    # @param tracks [Array<Track>] Tracks to be added. Maximum: 100 per request
+    # @param position [Integer, NilClass] The position to insert the tracks, a zero-based index. Default: tracks are appended to the playlist
+    # @return [NilClass]
+    #
+    # @example
+    #           tracks = RSpotify::Track.search('Know', 30)
+    #           playlist = user.create_playlist!('my-awesome-playlist')
+    #
+    #           playlist.add_tracks!(tracks)
+    #           playlist.tracks.size       #=> 30
+    #           playlist.tracks.first.name #=> "Somebody That I Used To Know"
+    #
+    #           playlist.add_tracks!(tracks, position: 20)
+    #           playlist.tracks[20].name #=> "Somebody That I Used To Know"
     def add_tracks!(tracks, position: nil)
       if tracks.size > 100
         warn 'Too many tracks requested. Maximum: 100'

data/lib/rspotify/track.rb

@@ -2,15 +2,15 @@ module RSpotify
 
   # @attr [Album]         album             The album on which the track appears
   # @attr [Array<Artist>] artists           The artists who performed the track
-  # @attr [Array<String>] available_markets The markets in which the track can be played: {http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 ISO 3166-1 alpha-2 country codes}
-  # @attr [Integer]       disc_number       The disc number (usually 1 unless the album consists of more than one disc)
+  # @attr [Array<String>] available_markets The markets in which the track can be played. See {http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 ISO 3166-1 alpha-2 country codes}
+  # @attr [Integer]       disc_number       The disc number. Usually 1 unless the album consists of more than one disc
   # @attr [Integer]       duration_ms       The track length in milliseconds
-  # @attr [Boolean]       explicit          Whether or not the track has explicit lyrics (true = yes it does; false = no it does not OR unknown)
+  # @attr [Boolean]       explicit          Whether or not the track has explicit lyrics. true = yes it does; false = no it does not OR unknown
   # @attr [Hash]          external_ids      Known external IDs for the track
   # @attr [String]        name              The name of the track
-  # @attr [Integer]       popularity        The popularity of the track - The value will be between 0 and 100, with 100 being the most popular
+  # @attr [Integer]       popularity        The popularity of the track. The value will be between 0 and 100, with 100 being the most popular
   # @attr [String]        preview_url       A link to a 30 second preview (MP3 format) of the track
-  # @attr [Integer]       track_number      The number of the track - If an album has several discs, the track number is the number on the specified disc
+  # @attr [Integer]       track_number      The number of the track. If an album has several discs, the track number is the number on the specified disc
   class Track < Base
 
     # Returns Track object(s) with id(s) provided
@@ -33,7 +33,7 @@ module RSpotify
 
     # Returns array of Track objects matching the query, ordered by popularity
     #
-    # @param query  [String]  The search query's keywords.
+    # @param query  [String]  The search query's keywords. See the q description in {https://developer.spotify.com/web-api/search-item here} for details.
     # @param limit  [Integer] Maximum number of tracks to return. Minimum: 1. Maximum: 50.
     # @param offset [Integer] The index of the first track to return. Use with limit to get the next set of tracks.
     # @return [Array<Track>]

data/lib/rspotify/user.rb

@@ -1,5 +1,10 @@
 module RSpotify
 
+  # @attr [String] country      The country of the user, as set in the user's account profile. An {http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 ISO 3166-1 alpha-2 country code}. This field is only available when the current user has granted access to the *user-read-private* scope.
+  # @attr [String] display_name The name displayed on the user's profile. This field is only available when the current user has granted access to the *user-read-private* scope.
+  # @attr [String] email        The user's email address. This field is only available when the current user has granted access to the *user-read-email* scope.
+  # @attr [Array]  images       The user's profile image. This field is only available when the current user has granted access to the *user-read-private* scope.
+  # @attr [String] product      The user's Spotify subscription level: "premium", "free", etc. This field is only available when the current user has granted access to the *user-read-private* scope.
   class User < Base
 
     # Returns User object with id provided
@@ -47,7 +52,21 @@ module RSpotify
       end
     end
 
-    #TODO doc
+    # Creates a playlist in user's Spotify account. This method is only available when the current user
+    # has granted access to the *playlist-modify* and *playlist-modify-private* scopes.
+    #
+    # @param name [String] The name for the new playlist
+    # @param public [Boolean] Whether the playlist is public or private. Default: true
+    # @return [Playlist]
+    #
+    # @example
+    #           user.create_playlist!('my-first-playlist')
+    #           user.playlists.last.name   #=> "my-first-playlist"
+    #           user.playlists.last.public #=> true
+    #
+    #           playlist = user.create_playlist!('my-second-playlist', public: false)
+    #           playlist.name   #=> "my-second-playlist"
+    #           playlist.public #=> false
     def create_playlist!(name, public: true)
       url = "users/#{@id}/playlists"
       request_data = %Q({"name":"#{name}", "public":#{public}})

data/lib/rspotify/version.rb

@@ -1,3 +1,3 @@
 module RSpotify
-  VERSION = '0.9.0'
+  VERSION = '0.10.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rspotify
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Guilherme Sad
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-07-07 00:00:00.000000000 Z
+date: 2014-07-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: omniauth-oauth2