Class: Hallon::Search

Inherits:
Base
  • Object
show all
Extended by:
Observable::Search
Includes:
Linkable, Loadable
Defined in:
lib/hallon/search.rb

Overview

Search allows you to search Spotify for tracks, albums and artists, just like in the client.

See Also:

Defined Under Namespace

Classes: Albums, Artists, Images, PlaylistEnumerator, PlaylistImageUris, PlaylistNames, PlaylistUris, Playlists, Tracks

Instance Attribute Summary

Attributes inherited from Base

#pointer

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Observable::Search

extended, initialize_callbacks, load_callback

Methods included from Loadable

#load

Methods included from Linkable

#===, included, #to_str

Methods inherited from Base

#==, from, from_link, #is_linkable?, #session, to_link, #to_pointer, #to_s

Constructor Details

#initialize(search, options = {}) ⇒ Search

Construct a new search with given query.

Given enough results for a given query, all searches are paginated by libspotify. If the current number of results (say search.tracks.size) is less than the total number of results (search.tracks.total), there are more results available. To retrieve the additional tracks, you’ll need to do the same search query again, but with a higher tracks_offset.

Examples:

searching tracks by offset

search = Hallon::Search.new("genre:rock", tracks: 10, tracks_offset: 0).load
search.tracks.size # => 10
search.tracks.total # => 17

again  = Hallon::Search.new("genre:rock", tracks: 10, tracks_offset: 10).load
again.tracks.size # => 7
again.tracks.total # => 17

Parameters:

  • search (String, Link) —

    search query or spotify URI

  • options (Hash) (defaults to: {}) —

    additional search options

Options Hash (options):

  • :type (Symbol) — default: :standard —

    search type, either standard or suggest

  • :tracks (#to_i) — default: 25 —

    max number of tracks you want in result

  • :albums (#to_i) — default: 25 —

    max number of albums you want in result

  • :artists (#to_i) — default: 25 —

    max number of artists you want in result

  • :playlists (#to_i) — default: 25 —

    max number of playlists you want in result

  • :tracks_offset (#to_i) — default: 0 —

    offset of tracks in search result

  • :albums_offset (#to_i) — default: 0 —

    offset of albums in search result

  • :artists_offset (#to_i) — default: 0 —

    offset of artists in search result

  • :playlists_offset (#to_i) — default: 0 —

    offset of playlists in search result

See Also:



155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
 
# File 'lib/hallon/search.rb', line 155

def initialize(search, options = {})
  opts = Search.defaults.merge(options)
  type = opts.delete(:type)
  opts = opts.values_at(:tracks_offset, :tracks, :albums_offset, :albums, :artists_offset, :artists, :playlists_offset, :playlists).map(&:to_i)
  search = from_link(search) if Link.valid?(search)

  subscribe_for_callbacks do |callback|
    @pointer = if search.is_a?(Spotify::Search)
      search
    else
      Spotify.search_create(session.pointer, search, *opts, type, callback, nil)
    end

    raise ArgumentError, "search with #{search} failed" if @pointer.null?
  end
end

Class Method Details

.defaults ⇒ Hash

Returns default search parameters.

Returns:

  • (Hash) —

    default search parameters



112
113
114
115
116
117
118
119
120
121
122
123
124
 
# File 'lib/hallon/search.rb', line 112

def self.defaults
  @defaults ||= {
    :tracks  => 25,
    :albums  => 25,
    :artists => 25,
    :playlists => 25,
    :tracks_offset  => 0,
    :albums_offset  => 0,
    :artists_offset => 0,
    :playlists_offset => 0,
    :type => :standard
  }
end

Instance Method Details

#albums ⇒ Albums

Returns list of all albums in the search result.

Returns:

  • (Albums) —

    list of all albums in the search result.



199
200
201
 
# File 'lib/hallon/search.rb', line 199

def albums
  Albums.new(self)
end

#artists ⇒ Artists

Returns list of all artists in the search result.

Returns:

  • (Artists) —

    list of all artists in the search result.



204
205
206
 
# File 'lib/hallon/search.rb', line 204

def artists
  Artists.new(self)
end

#did_you_mean ⇒ String

Returns “did you mean?” suggestion for current search.

Returns:

  • (String) —

    “did you mean?” suggestion for current search.



189
190
191
 
# File 'lib/hallon/search.rb', line 189

def did_you_mean
  Spotify.search_did_you_mean(pointer).to_s
end

#from_link ⇒ Spotify::Link (private)

Returns pointer representation of given link.

Parameters:

Returns:

  • (Spotify::Link) —

    pointer representation of given link.



103
104
105
106
 
# File 'lib/hallon/search.rb', line 103

from_link :search do |link|
  link = Link.new(link).to_uri
  ::CGI.unescape(link[/\Aspotify:search:(.+)\z/m, 1])
end

#loaded? ⇒ Boolean

Returns true if the search has been fully loaded.

Returns:

  • (Boolean) —

    true if the search has been fully loaded.



173
174
175
 
# File 'lib/hallon/search.rb', line 173

def loaded?
  Spotify.search_is_loaded(pointer)
end

#playlist_image_uris ⇒ PlaylistImageUris

Returns list of all playlist image uris in the search result.

Returns:



219
220
221
 
# File 'lib/hallon/search.rb', line 219

def playlist_image_uris
  PlaylistImageUris.new(self)
end

#playlist_images ⇒ Images

Returns list of all images in the search result.

Returns:

  • (Images) —

    list of all images in the search result.



229
230
231
 
# File 'lib/hallon/search.rb', line 229

def playlist_images
  Images.new(self)
end

#playlist_names ⇒ PlaylistNames

Returns list of all playlist names in the search result.

Returns:

  • (PlaylistNames) —

    list of all playlist names in the search result.



209
210
211
 
# File 'lib/hallon/search.rb', line 209

def playlist_names
  PlaylistNames.new(self)
end

#playlist_uris ⇒ PlaylistUris

Returns list of all playlist uris in the search result.

Returns:

  • (PlaylistUris) —

    list of all playlist uris in the search result.



214
215
216
 
# File 'lib/hallon/search.rb', line 214

def playlist_uris
  PlaylistUris.new(self)
end

#playlists ⇒ Playlists

Returns list of all playlists in the search result.

Returns:

  • (Playlists) —

    list of all playlists in the search result.



224
225
226
 
# File 'lib/hallon/search.rb', line 224

def playlists
  Playlists.new(self)
end

#query ⇒ String

Returns search query this search was created with.

Returns:

  • (String) —

    search query this search was created with.



184
185
186
 
# File 'lib/hallon/search.rb', line 184

def query
  Spotify.search_query(pointer).to_s
end

#status ⇒ Symbol

Returns search error status.

Returns:

  • (Symbol) —

    search error status.

See Also:

  • Error.explain


179
180
181
 
# File 'lib/hallon/search.rb', line 179

def status
  Spotify.search_error(pointer)
end

#to_link ⇒ Hallon::Link

Returns Link for the current object.

Returns:



101
 
# File 'lib/hallon/search.rb', line 101

to_link :from_search

#tracks ⇒ Tracks

Returns list of all tracks in the search result.

Returns:

  • (Tracks) —

    list of all tracks in the search result.



194
195
196
 
# File 'lib/hallon/search.rb', line 194

def tracks
  Tracks.new(self)
end