Class: Hallon::PlaylistContainer

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

Overview

PlaylistContainers are the objects that hold playlists. Each User in libspotify has a container for its’ starred and published playlists, and every logged in user has its’ own container.

See Also:

Defined Under Namespace

Classes: Contents, Folder

Instance Attribute Summary

Attributes inherited from Base

#pointer

Instance Method Summary collapse

Methods included from Observable::PlaylistContainer

container_loaded_callback, extended, initialize_callbacks, playlist_added_callback, playlist_moved_callback, playlist_removed_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(pointer) ⇒ PlaylistContainer

Wrap an existing PlaylistContainer pointer in an object.

Parameters:

  • pointer (Spotify::PlaylistContainer) 


142
143
144
145
146
147
148
149
 
# File 'lib/hallon/playlist_container.rb', line 142

def initialize(pointer)
  @pointer = to_pointer(pointer, Spotify::PlaylistContainer)

  subscribe_for_callbacks do |callbacks|
    Spotify.playlistcontainer_remove_callbacks(pointer, callbacks, nil)
    Spotify.playlistcontainer_add_callbacks(pointer, callbacks, nil)
  end
end

Instance Method Details

#add(playlist, force_create = false) ⇒ Playlist?

Add the given playlist to the end of the container.

If the given name is a valid spotify playlist URI, Hallon will add the existing playlist to the container. To always create a new playlist, set force_create to true.

Examples:

create a new playlist

container.add "New playlist"

create a new playlist even if it’s a valid playlist URI

container.add "spotify:user:burgestrand:playlist:07AX9IY9Hqmj1RqltcG0fi", force: true

add existing playlist

playlist = container.add "spotify:user:burgestrand:playlist:07AX9IY9Hqmj1RqltcG0fi"

playlist = Hallon::Playlist.new("spotify:user:burgestrand:playlist:07AX9IY9Hqmj1RqltcG0fi")
container.add playlist

link = Hallon::Link.new("spotify:user:burgestrand:playlist:07AX9IY9Hqmj1RqltcG0fi")
playlist = container.add link

Parameters:

  • playlist (String, Playlist, Link)
  • force_create (Boolean) (defaults to: false) —

    force creation of a new playlist

Returns:

  • (Playlist, nil) —

    the added playlist, or nil if the operation failed



196
197
198
199
200
201
202
203
204
205
206
207
208
209
 
# File 'lib/hallon/playlist_container.rb', line 196

def add(playlist, force_create = false)
  resource = if force_create or not Link.valid?(playlist) and playlist.is_a?(String)
    unless error = Playlist.invalid_name?(playlist)
      Spotify.playlistcontainer_add_new_playlist(pointer, playlist)
    else
      raise ArgumentError, error
    end
  else
    link = Link.new(playlist)
    Spotify.playlistcontainer_add_playlist(pointer, link.pointer)
  end

  Playlist.from(resource)
end

#add_folder(name) ⇒ Folder

Create a new folder with the given name at the end of the container.

Parameters:

  • name (String)

Returns:

Raises:

  • (Error) —

    if the operation failed

See Also:



217
218
219
 
# File 'lib/hallon/playlist_container.rb', line 217

def add_folder(name)
  insert_folder(size, name)
end

#can_move?(from, to) ⇒ Boolean

Control if if the item at index from can be moved to infront_of.

Parameters:

  • from (Integer) —

    index to move from

  • to (Integer) —

    index the item will end up at

Returns:

  • (Boolean) —

    true if the operation can be performed



285
286
287
288
289
290
 
# File 'lib/hallon/playlist_container.rb', line 285

def can_move?(from, to)
  dry_run = true
  error   = move_playlist(from, to, dry_run)
  _, symbol = Error.disambiguate(error)
  symbol == :ok
end

#clear_unseen_tracks_for(playlist) ⇒ PlaylistContainer

Note:

in libspotify v11.1.60, this method appears to do nothing

Clears the unseen tracks for the given playlist.

Parameters:

Returns:



323
324
325
326
327
328
 
# File 'lib/hallon/playlist_container.rb', line 323

def clear_unseen_tracks_for(playlist)
  tap do
    result = Spotify.playlistcontainer_clear_unseen_tracks(pointer, playlist.pointer)
    raise OperationFailedError if result < 0
  end
end

#contents ⇒ Contents

Returns an enumerator of folders and playlists.

Returns:

  • (Contents) —

    an enumerator of folders and playlists.



168
169
170
 
# File 'lib/hallon/playlist_container.rb', line 168

def contents
  Contents.new(self)
end

#insert_folder(index, name) ⇒ Object

Create a new folder with the given name at the specified index.

Parameters:

  • index (Integer)
  • name (String)

Raises:

  • (Error) —

    if the operation failed



226
227
228
229
230
 
# File 'lib/hallon/playlist_container.rb', line 226

def insert_folder(index, name)
  error = Spotify.playlistcontainer_add_folder(pointer, index, name.to_s)
  Error.maybe_raise(error)
  contents[index]
end

#loaded? ⇒ Boolean

Returns true if the container is loaded.

Returns:

  • (Boolean) —

    true if the container is loaded.



152
153
154
 
# File 'lib/hallon/playlist_container.rb', line 152

def loaded?
  Spotify.playlistcontainer_is_loaded(pointer)
end

#move(from, to) ⇒ Playlist, Folder

Note:

If moving a folder, only that end of the folder is moved. The folder size will change!

Move a playlist or a folder.

Examples:

an illustration of how contents are moved

# given a container like this:
# A, B, C, D

container.move(0, 1)
  # => B, A, C, D

container.move(0, 3)
  # => B, C, D, A

container.move(3, 1)
  # => A, D, B, C

Parameters:

  • from (Integer) —

    index to move from

  • to (Integer) —

    index the item will end up at

Returns:

Raises:

  • (Error) —

    if the operation failed



275
276
277
278
279
 
# File 'lib/hallon/playlist_container.rb', line 275

def move(from, to)
  error = move_playlist(from, to, false)
  Error.maybe_raise(error)
  contents[to]
end

#move_playlist(from, infront_of, dry_run) ⇒ Integer (protected)

Wrapper for original API; adjusts indices accordingly.

Parameters:

  • from (Integer)
  • infront_of (Integer)
  • dry_run (Boolean)

Returns:

  • (Integer) —

    error



337
338
339
340
 
# File 'lib/hallon/playlist_container.rb', line 337

def move_playlist(from, infront_of, dry_run)
  infront_of += 1 if from < infront_of
  Spotify.playlistcontainer_move_playlist(pointer, from, infront_of, dry_run)
end

#owner ⇒ User?

Returns owner of the container (nil if unknown or no owner).

Returns:

  • (User, nil) —

    owner of the container (nil if unknown or no owner).



157
158
159
160
 
# File 'lib/hallon/playlist_container.rb', line 157

def owner
  owner = Spotify.playlistcontainer_owner(pointer)
  User.from(owner)
end

#remove(index) ⇒ PlaylistContainer

Note:

When removing a folder, both its’ start and end is removed.

Remove a playlist or a folder (but not its’ contents).

Parameters:

  • index (Integer)

Returns:

Raises:

  • (Error) —

    if the index is out of range



238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
 
# File 'lib/hallon/playlist_container.rb', line 238

def remove(index)
  remove = proc { |idx| Spotify.playlistcontainer_remove_playlist(pointer, idx) }

  error = case Spotify.playlistcontainer_playlist_type(pointer, index)
  when :start_folder, :end_folder
    folder = contents[index]

    Error.maybe_raise(remove[folder.begin])
    remove[folder.end - 1] # ^ everything moves down one step
  else
    remove[index]
  end

  tap { Error.maybe_raise(error) }
end

#size ⇒ Integer

Returns number of playlists and folders in this container.

Returns:

  • (Integer) —

    number of playlists and folders in this container.



163
164
165
 
# File 'lib/hallon/playlist_container.rb', line 163

def size
  Spotify.playlistcontainer_num_playlists(pointer)
end

#unseen_tracks_count_for(playlist) ⇒ Integer

Retrieve the number of unseen tracks for the given playlist.

Parameters:

Returns:

  • (Integer) —

    number of unseen tracks



296
297
298
299
300
 
# File 'lib/hallon/playlist_container.rb', line 296

def unseen_tracks_count_for(playlist)
  Spotify.playlistcontainer_get_unseen_tracks(pointer, playlist.pointer, nil, 0).tap do |count|
    raise OperationFailedError if count < 0
  end
end

#unseen_tracks_for(playlist, count = unseen_tracks_count_for(playlist)) ⇒ Array<Track>

Note:

The playlist must be in this container, or this method will fail.

Retrieve the unseen tracks for the given playlist.

Parameters:

Returns:

  • (Array<Track>) —

    array of unseen tracks.

Raises:

See Also:



308
309
310
311
312
313
314
315
316
 
# File 'lib/hallon/playlist_container.rb', line 308

def unseen_tracks_for(playlist, count = unseen_tracks_count_for(playlist))
  tracks_ary = FFI::MemoryPointer.new(:pointer, count)
  real_count = Spotify.playlistcontainer_get_unseen_tracks(pointer, playlist.pointer, tracks_ary, count)
  raise OperationFailedError if real_count < 0
  tracks_ary.read_array_of_pointer([real_count, count].min).map do |track|
    track_pointer = Spotify::Track.retaining_class.new(track)
    Hallon::Track.new(track_pointer)
  end
end