Class: SpotifyWeb::Resource

Inherits:
Object
  • Object
show all
Extended by:
Assertions
Includes:
Assertions
Defined in:
lib/spotify_web/resource.rb

Overview

Represents an object that’s been created using content from Spotify. This encapsulates responsibilities such as reading and writing attributes.

Direct Known Subclasses

Album, Artist, Playlist, Restriction, Song, User

Constant Summary collapse

BASE62_CHARS =

The characters to encoding / decoding in base62

('0'..'9').to_a + ('a'..'z').to_a + ('A'..'Z').to_a

Class Attribute Summary collapse

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Assertions

assert_valid_keys, assert_valid_values

Constructor Details

#initialize(client, attributes = {}, *args) ⇒ Resource

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Initializes this resources with the given attributes. This will continue to call the superclass’s constructor with any additional arguments that get specified.



135
136
137
138
139
140
141
 
# File 'lib/spotify_web/resource.rb', line 135

def initialize(client, attributes = {}, *args)
  @loaded = false
  @metadata_loaded = false
  @client = client
  self.attributes = attributes
  super(*args)
end

Class Attribute Details

.metadata_schema ⇒ Class

The metadata schema to use for loading data for this resource

Returns:

  • (Class) 


93
94
95
 
# File 'lib/spotify_web/resource.rb', line 93

def metadata_schema
  @metadata_schema
end

.resource_name ⇒ String

Provides a default resource name if one isn’t specified

Returns:

  • (String) 


89
90
91
 
# File 'lib/spotify_web/resource.rb', line 89

def resource_name
  @resource_name
end

Instance Attribute Details

#gid ⇒ String (readonly)

The unique group identifier, represented as bytes in base 16

Examples:

“xE1x98|x10xDBxC3OMx8BxE1xB1x1DxDFxD6xBB1”

Returns:

  • (String) —

    The group id



118
 
# File 'lib/spotify_web/resource.rb', line 118

attribute :gid, :load => false

#id ⇒ String (readonly)

The unique identifier, represented in base16

Returns:

  • (String) —

    The Spotify ID for the resource



113
 
# File 'lib/spotify_web/resource.rb', line 113

attribute :id, :load => false

#uri ⇒ String (readonly)

The unique URI representing this resource in Spotify

Examples:

“spotify:track:6RGXtkDeWNP2gyASlfjzTr”

Returns:

  • (String) —

    The URI for the resource



123
 
# File 'lib/spotify_web/resource.rb', line 123

attribute :uri, :load => false

#uri_id ⇒ String (readonly)

The id used within the resource’s URI, represented in base62.

Examples:

“6RGXtkDeWNP2gyASlfjzTr”

Returns:

  • (String) —

    The URI’s id



128
 
# File 'lib/spotify_web/resource.rb', line 128

attribute :uri_id, :load => false

Class Method Details

.attribute(name, *spotify_names, &block) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Defines a new Spotify attribute on this class. By default, the name of the attribute is assumed to be the same name that Spotify specifies in its API. If the names are different, this can be overridden on a per-attribute basis.

Examples:

# Define a "name" attribute that maps to a Spotify "name" attribute
attribute :name

# Define an "id" attribute that maps to a Spotify "_id" attribute
attribute :id, :_id

# Define an "user_id" attribute that maps to both a Spotify "user_id" and "userid" attribute
attribute :user_id, :user_id, :userid

# Define a "time" attribute that maps to a Spotify "time" attribute
# and converts the value to a Time object
attribute :time do |value|
  Time.at(value)
end

# Define a "created_at" attribute that maps to a Spotify "time" attribute
# and converts the value to a Time object
attribute :created_at, :time do |value|
  Time.at(value)
end

# Define a "songs" attribute that does *not* get loaded from Spotify
# when accessed
attribute :songs, :load => false

Parameters:

  • name (String) —

    The name for the attribute

  • options (Hash) —

    The configuration options

Raises:

  • (ArgumentError) —

    if an invalid option is specified



53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
 
# File 'lib/spotify_web/resource.rb', line 53

def attribute(name, *spotify_names, &block)
  options = spotify_names.last.is_a?(Hash) ? spotify_names.pop : {}
  assert_valid_keys(options, :load)
  options = {:load => true}.merge(options)

  # Reader
  define_method(name) do
    load if instance_variable_get("@#{name}").nil? && !loaded? && options[:load]
    instance_variable_get("@#{name}")
  end

  # Query
  define_method("#{name}?") do
    !!__send__(name)
  end

  # Typecasting
  block ||= lambda do |value|
    value.force_encoding('UTF-8') if value.is_a?(String)
    value
  end
  define_method("typecast_#{name}", &block)
  protected :"typecast_#{name}"

  # Attribute name conversion
  spotify_names = [name] if spotify_names.empty?
  spotify_names.each do |spotify_name|
    define_method("#{spotify_name}=") do |value|
      instance_variable_set("@#{name}", value.nil? ? nil : __send__("typecast_#{name}", value))
    end
    protected :"#{spotify_name}="
  end
end

Instance Method Details

#==(other) ⇒ Boolean Also known as: eql?

Determines whether this resource is equal to another based on their unique identifiers.

Parameters:

  • other (Object) —

    The object this resource is being compared against

Returns:

  • (Boolean) —

    true if the resource ids are equal, otherwise false



284
285
286
287
288
289
290
 
# File 'lib/spotify_web/resource.rb', line 284

def ==(other)
  if other && other.respond_to?(:id) && other.id
    other.id == id
  else
    false
  end
end

#attributes=(attributes) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Attempts to set attributes on the object only if they’ve been explicitly defined by the class.

Parameters:

  • attributes (Hash) —

    The updated attributes for the resource



252
253
254
255
256
257
258
259
 
# File 'lib/spotify_web/resource.rb', line 252

def attributes=(attributes)
  if attributes
    attributes.each do |attribute, value|
      attribute = attribute.to_s
      __send__("#{attribute}=", value) if respond_to?("#{attribute}=", true)
    end
  end
end

#hash ⇒ Fixnum

Generates a hash for this resource based on the unique identifier

Returns:

  • (Fixnum) 


296
297
298
 
# File 'lib/spotify_web/resource.rb', line 296

def hash
  id.hash
end

#load ⇒ true Also known as: reload

Loads the attributes for this resource from Spotify. By default this is a no-op and just marks the resource as loaded.

Returns:

  • (true) 


190
191
192
193
 
# File 'lib/spotify_web/resource.rb', line 190

def load
  load_metadata
  @loaded = true
end

#load_metadata ⇒ Object?

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Looks up the metadata associated with this resource.

Returns:

  • (Object, nil) —

    nil if there is no metadata schema associated, otherwise the result of the request



207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
 
# File 'lib/spotify_web/resource.rb', line 207

def load_metadata
  if self.class.metadata_schema && !@metadata_loaded
    if @metadata_loader
      # Load the metadata externally
      @metadata_loader.call
      @metadata_loader = nil
    else
      # Load the metadata just for this single resource
      response = api('request',
        :uri => metadata_uri,
        :response_schema => self.class.metadata_schema
      )
      self.metadata = response['result']
    end
  end
end

#loaded? ⇒ Boolean

Determines whether the current resource has been loaded from Spotify.

Returns:

  • (Boolean) —

    true if the resource has been loaded, otherwise false



199
200
201
 
# File 'lib/spotify_web/resource.rb', line 199

def loaded?
  @loaded
end

#metadata=(metadata) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Updates this resource based on the given metadata

Parameters:

  • metadata (Beefcake::Message, Proc) —

    The metadata to use or a proc for loading it



228
229
230
231
232
233
234
235
 
# File 'lib/spotify_web/resource.rb', line 228

def metadata=(metadata)
  if !metadata || metadata.is_a?(Proc)
    @metadata_loader = metadata
  else
    @metadata_loaded = true
    self.attributes = metadata.to_hash
  end
end

#metadata_uri ⇒ String?

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

The URI for looking up the resource’s metadata

Returns:

  • (String, nil) —

    nil if there is no metadata schema associated, otherwise the uri



241
242
243
244
245
 
# File 'lib/spotify_web/resource.rb', line 241

def metadata_uri
  if self.class.metadata_schema
    "hm://metadata/#{self.class.resource_name}/#{id}"
  end
end

#pretty_print(q) ⇒ String

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Forces this object to use PP’s implementation of inspection.

Returns:

  • (String) 


265
266
267
 
# File 'lib/spotify_web/resource.rb', line 265

def pretty_print(q)
  q.pp_object(self)
end

#pretty_print_instance_variables ⇒ Array<Symbol>

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Defines the instance variables that should be printed when inspecting this object. This ignores the @client and @loaded variables.

Returns:

  • (Array<Symbol>) 


275
276
277
 
# File 'lib/spotify_web/resource.rb', line 275

def pretty_print_instance_variables
  (instance_variables - [:'@client', :'@loaded', :'@metadata_loaded', :'@metadata_loader']).sort
end