muzak 0.0.11 → 0.0.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: bfec18a0835cc1c148e9bf4c1ee3c9770143ba46
-  data.tar.gz: 44f5b96244563e8161d6c9950079551b4554d80a
+  metadata.gz: cdbf4e0b472fdf7499bbd25915c178c00ea427f2
+  data.tar.gz: e0b39265673163d195dde538960beb7819e2ebbe
 SHA512:
-  metadata.gz: 4c8c79d444285e835e753fe1582147a30de11bf96a9d3d18f2af54b116ff315937000a88ab1a2a8b1c89de767ac0692d95125bbbc01557cd42ed808c96173d68
-  data.tar.gz: bbe8db2c4bdbe6f0df3eea079de83795ef4638437268ef779d5231ea8c3afde337e437335ff30a6899ab92d1defb8760f384f02b72c59524b842beefcd67b151
+  metadata.gz: 18ae7d00640668f375390afc84d2ec0aec1fde26970d9e1636c943a7a29415267b97cf5c433efc2967ad630726525f617493a77e30cc2072646af95406078de1
+  data.tar.gz: 51f3a12b1e2018fb52c118cbd79afdc47a22a9a0a7feaf724960baffc9604b77042aafd60d3b0e7117e8b37bd9c12475c0653ffc71befc722c43c3289229b5f6

data/.yardopts

@@ -0,0 +1 @@
+--tag command:"muzak command" --tag cmdexample:"example invocation" --no-private --markup-provider=redcarpet --markup=markdown - README.md LICENSE

data/lib/muzak/album.rb

@@ -1,10 +1,17 @@
 module Muzak
+  # Represents a collection of songs for muzak.
   class Album
-    attr_reader :title, :songs, :cover_art
+    # @return [String] the album's title
+    attr_reader :title
 
-    # instead of passing an album hash directly from the index,
-    # this should really just take a title and an array of Song
-    # objects.
+    # @return [Array<Muzak::Song>] the album's songs
+    attr_reader :songs
+
+    # @return [String] the path to the album's cover art
+    attr_reader :cover_art
+
+    # @note instead of passing an album hash directly from the index, this
+    #   should really just take a title and an array of Song objects.
     def initialize(title, album_hash)
       @title = title
       @cover_art = album_hash["cover"]

data/lib/muzak/cmd.rb

@@ -5,6 +5,7 @@ module Muzak
     # load commands included by the user
     Dir.glob(File.join(USER_COMMAND_DIR, "*")) { |file| require file }
 
+    # @return [Array<String>] all valid muzak commands
     def self.commands
       commands = instance_methods.map(&:to_s).reject { |m| m.start_with?("_") }
       commands.map { |c| Utils.resolve_method c }

data/lib/muzak/cmd/config.rb

@@ -2,6 +2,9 @@ require "yaml"
 
 module Muzak
   module Cmd
+    # Query the {Muzak::Config} for a given key.
+    # @command `config-get <key>`
+    # @cmdexample `muzak> config-get player`
     def config_get(*args)
       fail_arity(args, 1)
       key = args.shift

data/lib/muzak/cmd/index.rb

@@ -1,5 +1,8 @@
 module Muzak
   module Cmd
+    # Rebuild the current instance's index.
+    # @command `index-build`
+    # @cmdexample `muzak> index-build`
     def index_build(*args)
       warn_arity(args, 0)
 
@@ -8,18 +11,27 @@ module Muzak
       index.build!
     end
 
+    # List all artists in the index.
+    # @command `list-artists`
+    # @cmdexample `muzak> list-artists`
     def list_artists(*args)
       warn_arity(args, 0)
 
       puts index.artists.join("\n")
     end
 
+    # List all albums in the index.
+    # @command `list-albums`
+    # @cmdexample `muzak> list-albums`
     def list_albums(*args)
       warn_arity(args, 0)
 
       puts index.album_names.join("\n")
     end
 
+    # List all albums by the given artist in the index.
+    # @command `albums-by-artist <artist name>`
+    # @cmdexample `muzak> albums-by-artist Your Favorite Artist`
     def albums_by_artist(*args)
       artist = args.join(" ")
       return if artist.nil?
@@ -27,6 +39,9 @@ module Muzak
       puts index.albums_by(artist).map(&:title)
     end
 
+    # List all songs by the given artist in the index.
+    # @command `songs-by-artist <artist name>`
+    # @cmdexample `muzak> songs-by-artist Your Next Favorite Artist`
     def songs_by_artist(*args)
       artist = args.join(" ")
       return if artist.nil?

data/lib/muzak/cmd/meta.rb

@@ -1,15 +1,26 @@
 module Muzak
   module Cmd
+    # Print a "helpful" listing of commands.
+    # @command `help`
+    # @cmdexample `muzak> help`
     def help(*args)
       commands = Muzak::Cmd.commands.join(", ")
       info "available commands: #{commands}"
     end
 
+    # List all available plugins.
+    # @command `list-plugins`
+    # @cmdexample `muzak> list-plugins`
+    # @note This list will differ from loaded plugins, if not all available
+    #   plugins are configured.
     def list_plugins
       plugins = Plugin.plugin_names.join(", ")
       puts "available plugins: #{plugins}"
     end
 
+    # Terminates the muzak instance (**not** just the client).
+    # @command `quit`
+    # @cmdexample `muzak> quit`
     def quit
       verbose "muzak is quitting..."
       player.deactivate!

data/lib/muzak/cmd/player.rb

@@ -1,5 +1,9 @@
 module Muzak
   module Cmd
+    # Activate the configured player.
+    # @command `player-activate`
+    # @cmdexample `muzak> player-activate`
+    # @note Many playback commands will automatically activate the player.
     def player_activate
       if player.running?
         warn "player is already running"
@@ -9,6 +13,10 @@ module Muzak
       player.activate!
     end
 
+    # Deactivate the configured player.
+    # @command `player-deactivate`
+    # @cmdexample `muzak> player-deactivate`
+    # @note Deactivating the player (usually) ends playback immediately.
     def player_deactivate
       warn "player is not running" unless player.running?
 
@@ -16,14 +24,23 @@ module Muzak
       player.deactivate!
     end
 
+    # Tell the player to begin playback.
+    # @command `play`
+    # @cmdexample `muzak> play`
     def play
       player.play
     end
 
+    # Tell the player to pause.
+    # @command `pause`
+    # @cmdexample `muzak> pause`
     def pause
       player.pause
     end
 
+    # Tell the player to toggle its playback state.
+    # @command `toggle`
+    # @cmdexample `muzak> toggle`
     def toggle
       if player.playing?
         player.pause
@@ -32,14 +49,23 @@ module Muzak
       end
     end
 
+    # Tell the player to load the next song.
+    # @command `next`
+    # @cmdexample `muzak> next`
     def next
       player.next_song
     end
 
+    # Tell the player to load the previous song.
+    # @command `previous`
+    # @cmdexample `muzak> previous`
     def previous
       player.previous_song
     end
 
+    # Tell the player to enqueue all songs by the given artist.
+    # @command `enqueue-artist <artist name>`
+    # @cmdexample `muzak> enqueue-artist Your Favorite Artist`
     def enqueue_artist(*args)
       artist = args.join(" ")
       return if artist.nil?
@@ -52,6 +78,9 @@ module Muzak
       end
     end
 
+    # Tell the player to enqueue the given album.
+    # @command `enqueue-album <album name>`
+    # @cmdexample `muzak> enqueue-album Your Favorite Album`
     def enqueue_album(*args)
       album_name = args.join(" ")
       return if album_name.nil?
@@ -64,6 +93,9 @@ module Muzak
       player.enqueue_album album
     end
 
+    # Tell the player to load the given number of random songs.
+    # @command `jukebox [count]`
+    # @cmdexample `muzak> jukebox 150`
     def jukebox(*args)
       count = args.shift || Config.jukebox_size
 
@@ -72,18 +104,31 @@ module Muzak
       songs.each { |s| player.enqueue_song s }
     end
 
+    # Tell the player to list its internal queue.
+    # @command `list-queue`
+    # @cmdexample `muzak> list-queue`
     def list_queue
       puts player.list_queue.map(&:title)
     end
 
+    # Tell the player to shuffle its internal queue.
+    # @command `shuffle-queue`
+    # @cmdexample `muzak> shuffle-queue`
     def shuffle_queue
       player.shuffle_queue
     end
 
+    # Tell the player to clear its internal queue.
+    # @command `clear-queue`
+    # @cmdexample `muzak> clear-queue`
+    # @note This does not (usually) stop the current song.
     def clear_queue
       player.clear_queue
     end
 
+    # Retrieve the currently playing song from the player and print it.
+    # @command `now-playing`
+    # @cmdexample `muzak> now-playing`
     def now_playing
       return unless player.playing?
 

data/lib/muzak/cmd/playlist.rb

@@ -1,15 +1,17 @@
 module Muzak
   module Cmd
-    def _playlists_loaded?
-      !!playlists
-    end
-
+    # List all currently available playlists.
+    # @command `list-playlists`
+    # @cmdexample `muzak> list-playlists`
     def list_playlists(*args)
       Playlist.playlist_names.each do |playlist|
         info playlist
       end
     end
 
+    # Delete the given playlist.
+    # @command `playlist-delete <playlist>`
+    # @cmdexample `muzak> playlist-delete favorites`
     def playlist_delete(*args)
       fail_arity(args, 1)
       pname = args.shift
@@ -20,8 +22,10 @@ module Muzak
       playlists[pname] = nil
     end
 
+    # Add the given playlist to the player's queue.
+    # @command `enqueue-playlist <playlist>`
+    # @cmdexample `muzak> enqueue-playlist favorites`
     def enqueue_playlist(*args)
-      return unless _playlists_loaded?
       fail_arity(args, 1)
       pname = args.shift
 
@@ -29,9 +33,10 @@ module Muzak
       event :playlist_enqueued, playlists[pname]
     end
 
+    # Add the given album to the given playlist.
+    # @command `playlist-add-album <playlist> <album name>`
+    # @cmdexample `muzak> playlist-add-album favorites Your Favorite Album`
     def playlist_add_album(*args)
-      return unless _playlists_loaded?
-
       pname = args.shift
       return if pname.nil?
 
@@ -44,9 +49,10 @@ module Muzak
       playlists[pname].add(album.songs)
     end
 
+    # Add the given artist to the given playlist.
+    # @command `playlist-add-artist <playlist> <artist name>`
+    # @cmdexample `muzak> playlist-add-artist dad-rock The Rolling Stones`
     def playlist_add_artist(*args)
-      return unless _playlists_loaded?
-
       pname = args.shift
       return if pname.nil?
 
@@ -56,8 +62,12 @@ module Muzak
       playlists[pname].add(index.songs_by(artist))
     end
 
+    # Add the currently playing song to the given playlist.
+    # @see Muzak::Player::StubPlayer#now_playing
+    # @command `playlist-add-current <playlist>`
+    # @cmdexample `muzak> playlist-add-current favorites`
     def playlist_add_current(*args)
-      return unless player.running? && _playlists_loaded?
+      return unless player.running?
 
       pname = args.shift
       return if pname.nil?
@@ -65,8 +75,12 @@ module Muzak
       playlists[pname].add player.now_playing
     end
 
+    # Deletes the currently playing song from the given playlist.
+    # @see Muzak::Player::StubPlayer#now_playing
+    # @command `playlist-del-current <playlist>`
+    # @cmdexample `muzak> playlist-del-current favorites`
     def playlist_del_current(*args)
-      return unless player.running? && _playlists_loaded?
+      return unless player.running?
 
       pname = args.shift
       return if pname.nil?
@@ -74,9 +88,11 @@ module Muzak
       playlists[pname].delete player.now_playing
     end
 
+    # Shuffle the given playlist.
+    # @see Muzak::Playlist#shuffle!
+    # @command `playlist-shuffle <playlist>`
+    # @cmdexample `muzak> playlist-shuffle dad-rock`
     def playlist_shuffle(*args)
-      return unless _playlists_loaded?
-
       pname = args.shift
       return if pname.nil?
 

data/lib/muzak/config.rb

@@ -1,6 +1,12 @@
 require "yaml"
 
 module Muzak
+  # Muzak's static configuration dumping ground.
+  # Key-value pairs are loaded from {CONFIG_FILE} and translated from
+  # kebab-case to snake_case methods.
+  # @example
+  #   # corresponds to `art-geometry: 300x300` in configuration
+  #   Config.art_geometry # => "300x300"
   class Config
     if File.exist?(CONFIG_FILE)
       @config = YAML::load_file(CONFIG_FILE)
@@ -24,11 +30,15 @@ module Muzak
       end
     end
 
-    # if a key doesn't exist, assume it's false
+    # Catches all undefined configuration keys and defaults them to false.
+    # @return [false]
     def self.method_missing(method, *args)
       false
     end
 
+    # @return [Boolean] whether or not the given plugin is configured
+    # @note the truth-value of this method is used to determine which
+    #   plugins should be loaded.
     def self.plugin?(pname)
       respond_to? "plugin_#{pname}"
     end

data/lib/muzak/const.rb

@@ -1,17 +1,32 @@
 module Muzak
-  VERSION = "0.0.11".freeze
+  # Muzak's current version
+  VERSION = "0.0.12".freeze
 
+  # The root directory for all user configuration, data, etc
   CONFIG_DIR = File.expand_path("~/.config/muzak").freeze
+
+  # Muzak's primary configuration file
+  # @see Muzak::Config
   CONFIG_FILE = File.join(CONFIG_DIR, "muzak.yml").freeze
+
+  # Muzak's music index
   INDEX_FILE = File.join(CONFIG_DIR, "index.dat").freeze
+
+  # The directory for all user playlists
   PLAYLIST_DIR = File.join(CONFIG_DIR, "playlists").freeze
+
+  # The directory for all user plugins
   USER_PLUGIN_DIR = File.join(CONFIG_DIR, "plugins").freeze
+
+  # The directory for all user commands
   USER_COMMAND_DIR = File.join(CONFIG_DIR, "commands").freeze
 
+  # All events currently propagated by {Muzak::Instance#event}
   PLUGIN_EVENTS = [
     :player_activated,
     :player_deactivated,
     :song_loaded,
+    :song_unloaded,
     :playlist_enqueued
   ]
 end

data/lib/muzak/index.rb

@@ -1,8 +1,22 @@
 module Muzak
+  # Represents muzak's music index.
   class Index
     include Utils
-    attr_accessor :tree, :deep, :hash
 
+    # @return [String] the path of the root of the music tree
+    attr_accessor :tree
+
+    # @return [Boolean] whether the index is "deep" (includes metadata) or not
+    attr_accessor :deep
+
+    # @return [Hash] the index hash
+    attr_accessor :hash
+
+    # @param tree [String] the root to begin indexing from
+    # @param deep [Boolean] whether to build a "deep" index
+    # @note if the index ({Muzak::INDEX_FILE}) already exists and is not
+    #   outdated, no building is performed.
+    # @see #build!
     def initialize(tree, deep: false)
       @tree = tree
       @deep = deep
@@ -16,6 +30,8 @@ module Muzak
       build!
     end
 
+    # (Re)builds and saves the index ({Muzak::INDEX_FILE}) to disk.
+    # @note This method can be expensive.
     def build!
       @hash = build_index_hash!
 
@@ -24,22 +40,30 @@ module Muzak
       File.open(INDEX_FILE, "w") { |io| io.write Marshal::dump @hash }
     end
 
+    # @return [Boolean] whether or not the current index is deep
     def deep?
       deep
     end
 
+    # @return [Integer] the UNIX timestamp from when the index was built
     def timestamp
       @hash["timestamp"]
     end
 
+    # @return [Boolean] whether or not the index is currently out of date
+    # @note The behavior of this method is affected by the value of
+    #   {Muzak::Config.index_autobuild}.
     def outdated?
       Time.now.to_i - timestamp >= Config.index_autobuild
     end
 
+    # @return [Array<String>] a list of all artists in the index
     def artists
       @artists ||= @hash["artists"].keys
     end
 
+    # @return [Hash{String => Album}] a hash of all album names with their
+    #   {Album} objects
     def albums
       @albums_hash ||= begin
         albums_hash = {}
@@ -54,10 +78,15 @@ module Muzak
       end
     end
 
+    # @return [Array<String>] a list of all albums in the index
+    # @note albums with the same name will appear, but can't be disambiguated
+    #   from here
     def album_names
       artists.map { |a| @hash["artists"][a]["albums"].keys }.flatten
     end
 
+    # @param artist [String] the artist's name
+    # @return [Array<Album>] all albums by the given artist
     def albums_by(artist)
       if artists.include?(artist)
         @hash["artists"][artist]["albums"].map { |title, album| Album.new(title, album) }
@@ -67,6 +96,9 @@ module Muzak
       end
     end
 
+    # Produces a 'jukebox' of random songs.
+    # @param count [Integer] the number of random songs to return
+    # @return [Array<Song>] an array of randomly chosen songs
     def jukebox(count = 50)
       @all_albums ||= @hash["artists"].map { |_, a| a["albums"] }.flatten
 
@@ -79,6 +111,10 @@ module Muzak
       end
     end
 
+    # @param artist [String] the artist's name
+    # @return [Array<Song>] an array of all the artist's songs
+    # @note no inter-album order is guaranteed. songs within an album are
+    #   generally sorted by track number.
     def songs_by(artist)
       error "no such artist: '#{artist}'" unless @hash["artists"].key?(artist)