Class: Hallon::Toplist

Inherits:
Base
  • Object
show all
Extended by:
Observable::Toplist
Includes:
Loadable
Defined in:
lib/hallon/toplist.rb

Overview

Toplists are what they sound like. They’re collections of artists, albums or tracks popular in a certain area either by country, user or everywhere.

Defined Under Namespace

Classes: Albums, Artists, Tracks

Instance Attribute Summary collapse

Attributes inherited from Base

#pointer

Instance Method Summary collapse

Methods included from Observable::Toplist

extended, initialize_callbacks, load_callback

Methods included from Loadable

#load

Methods inherited from Base

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

Constructor Details

#initialize(type, username) ⇒ Toplist #initialize(type, country) ⇒ Toplist #initialize(type) ⇒ Toplist

Create a Toplist browsing object.

Examples:

with a given username

toplist = Hallon::Toplist.new(:artists, "burgestrand")

with a given country

toplist = Hallon::Toplist.new(:tracks, :se)

everywhere

toplist = Hallon::Toplist.new(:albums)

Parameters:

  • type (Symbol)

    one of :artists, :albums or :tracks

  • region (String, Symbol, nil) (defaults to: nil)

    username, 2-letter country code or nil


62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
# File 'lib/hallon/toplist.rb', line 62

def initialize(type, region = nil)
  case region
  when String
    user   = region
    region = :user
  when NilClass
    region = :everywhere
  when Symbol
    region = to_country(region)
  end

  subscribe_for_callbacks do |callback|
    @type    = type
    @pointer = Spotify.toplistbrowse_create(session.pointer, type, region, user, callback, nil)
  end
end

Instance Attribute Details

#typeSymbol (readonly)

Returns type of toplist request (one of :artists, :albums or :tracks).

Returns:

  • (Symbol)

    type of toplist request (one of :artists, :albums or :tracks)


43
44
45
# File 'lib/hallon/toplist.rb', line 43

def type
  @type
end

Instance Method Details

#loaded?Boolean

Returns true if the toplist is loaded.

Returns:

  • (Boolean)

    true if the toplist is loaded.


80
81
82
# File 'lib/hallon/toplist.rb', line 80

def loaded?
  Spotify.toplistbrowse_is_loaded(pointer)
end

#request_durationRational

Note:

If the object is not loaded, the result is undefined.

Returns time it took for the toplistbrowse request to complete (in seconds).

Returns:

  • (Rational)

    time it took for the toplistbrowse request to complete (in seconds).


107
108
109
110
111
# File 'lib/hallon/toplist.rb', line 107

def request_duration
  duration = Spotify.toplistbrowse_backend_request_duration(pointer)
  duration = 0 if duration < 0
  Rational(duration, 1000)
end

#resultsArtists, ...

Note:

the returned enumerator corresponds to the #type of Toplist.

Returns an enumerator over the collection of results.

Returns:


92
93
94
95
96
97
98
99
100
101
102
103
# File 'lib/hallon/toplist.rb', line 92

def results
  klass = case type
  when :artists
    Artists
  when :albums
    Albums
  when :tracks
    Tracks
  end

  klass.new(self)
end

#statusSymbol

Returns toplist error status.

Returns:

  • (Symbol)

    toplist error status.

See Also:

  • Error.explain

86
87
88
# File 'lib/hallon/toplist.rb', line 86

def status
  Spotify.toplistbrowse_error(pointer)
end

#to_country(region) ⇒ Integer (private)

Convert a given two-character region to a Spotify compliant region (encoded in a 16bit integer).

Parameters:

Returns:

  • (Integer)

119
120
121
122
123
# File 'lib/hallon/toplist.rb', line 119

def to_country(region)
  code = region.to_s.upcase
  high, low = code.bytes.take(2)
  (high << 8) | low
end