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.


145
146
147
148
149
150
151
# File 'lib/spotify_web/resource.rb', line 145

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

Class Attribute Details

.metadata_schemaClass

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
end

.resource_nameString

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

#gidString (readonly)

The unique group identifier, represented as bytes in base 16

Examples:

“xE1x98|x10xDBxC3OMx8BxE1xB1x1DxDFxD6xBB1”

Returns:

  • (String)

    The group id


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

attribute :gid, :load => false

#idString (readonly)

The unique identifier, represented in base16

Returns:

  • (String)

    The Spotify ID for the resource


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

attribute :id, :load => false

#uriString (readonly)

The unique URI representing this resource in Spotify

Examples:

“spotify:track:6RGXtkDeWNP2gyASlfjzTr”

Returns:

  • (String)

    The URI for the resource


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

attribute :uri, :load => false

#uri_idString (readonly)

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

Examples:

“6RGXtkDeWNP2gyASlfjzTr”

Returns:

  • (String)

    The URI's id


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

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

.from_search_result(client, attributes) ⇒ SpotifyWeb::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.

Builds an instance of this resource from the given search result attributes. This data often differs from typical metdata results and, as a result, must be transformed before an instance can be built.


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

def from_search_result(client, attributes)
  new(client, attributes)
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


294
295
296
297
298
299
300
# File 'lib/spotify_web/resource.rb', line 294

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


262
263
264
265
266
267
268
269
# File 'lib/spotify_web/resource.rb', line 262

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

#hashFixnum

Generates a hash for this resource based on the unique identifier

Returns:

  • (Fixnum)

306
307
308
# File 'lib/spotify_web/resource.rb', line 306

def hash
  id.hash
end

#loadtrue 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)

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

def load
  
  @loaded = true
end

#load_metadataObject?

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


217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
# File 'lib/spotify_web/resource.rb', line 217

def 
  if self.class. && !@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 => ,
        :response_schema => self.class.
      )
      self. = 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


209
210
211
# File 'lib/spotify_web/resource.rb', line 209

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


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

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

#metadata_uriString?

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


251
252
253
254
255
# File 'lib/spotify_web/resource.rb', line 251

def 
  if self.class.
    "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)

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

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

#pretty_print_instance_variablesArray<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>)

285
286
287
# File 'lib/spotify_web/resource.rb', line 285

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