[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[emms-help] Doc fixes to emms.el
|
From: |
Daniel Brockman |
|
Subject: |
[emms-help] Doc fixes to emms.el |
|
Date: |
Wed, 15 Jun 2005 02:05:39 +0200 |
|
User-agent: |
Gnus/5.11 (Gnus v5.11) Emacs/22.0.50 (gnu/linux) |
So I was going through emms.el, trying to figure out just how the hell
this "EMMS" thing works anyway. Before I knew it, I had changed a
bunch of stuff all over the place.
I'm attaching a bunch of doc fixes --- most importantly for
conformance to the complete-sentence-first-line rule.
There are also some changes that are purely cosmetical. I'm not sure
about those, so please don't hesitate to tell me to back off.
*** emms.el 14 Jun 2005 14:07:54 +0200 1.45
--- emms.el 15 Jun 2005 02:02:16 +0200
***************
*** 1,6 ****
! ;;; emms.el --- Emacs MultiMedia System
! ;; Copyright (C) 2003-2005 Jorgen Schäfer
;; Author: Jorgen Schäfer <address@hidden>
;; Keywords: emms, mp3, mpeg, multimedia
--- 1,6 ----
! ;;; emms.el --- The Emacs Multimedia System
! ;; Copyright (C) 2003, 2004, 2005 Jorgen Schäfer
;; Author: Jorgen Schäfer <address@hidden>
;; Keywords: emms, mp3, mpeg, multimedia
***************
*** 22,55 ****
;;; Commentary:
! ;; This is the very core of EMMS. It provides ways to play a track
;; using `emms-start', to go through the playlist using the commands
! ;; `emms-next' and `emms-previous', stop the playing using
! ;; `emms-stop', and see what is currently playing using `emms-show'.
! ;; But in itself, this core is useless. It does not know how to play
! ;; anything - you need players for this - nor does it know any way how
! ;; to get tracks to play - you need sources for this.
! ;; A sample configuration is offered in emms-defaults.el, so you might
;; just want to use that file.
;;; Code:
- ;; Version control
(defvar emms-version "1.1 $Revision: 1.45 $"
"EMMS version string.")
;; $Id: emms.el,v 1.45 2005/06/12 15:55:42 forcer Exp $
;;; User Customization
(defgroup emms nil
! "*EMMS, the Emacs MultiMedia System for playing multimedia tracks
! using external players."
:prefix "emms-"
:group 'applications)
(defgroup emms-player nil
! "*Players for EMMS."
:prefix "emms-player-"
:group 'emms)
--- 22,57 ----
;;; Commentary:
! ;; This is the very core of EMMS. It provides ways to play a track
;; using `emms-start', to go through the playlist using the commands
! ;; `emms-next' and `emms-previous', to stop the playback using
! ;; `emms-stop', and to see what's currently playing using `emms-show'.
! ;; But in itself, this core is useless, because it doesn't know how to
! ;; play any tracks --- you need players for this. In fact, it doesn't
! ;; even know how to find any tracks to consider playing --- for this,
! ;; you need sources.
! ;; A sample configuration is offered in emms-default.el, so you might
;; just want to use that file.
;;; Code:
(defvar emms-version "1.1 $Revision: 1.45 $"
"EMMS version string.")
;; $Id: emms.el,v 1.45 2005/06/12 15:55:42 forcer Exp $
+
;;; User Customization
+
(defgroup emms nil
! "*The Emacs Multimedia System."
:prefix "emms-"
+ :group 'multimedia
:group 'applications)
(defgroup emms-player nil
! "*Track players for EMMS."
:prefix "emms-player-"
:group 'emms)
***************
*** 59,187 ****
:group 'emms)
(defcustom emms-source-list nil
! "*A list of sources EMMS can get tracks from. You need to set this
! to use `emms-play-all'.
! For example, to play all the media files in ~/media/, you can use the
! following setting (this uses emms-source-file.el):
! (setq emms-source-list '((emms-source-directory-tree \"~/media\")))"
:group 'emms
:type '(repeat sexp))
(defcustom emms-player-list nil
! "*A list of players EMMS can use. You need to set this!"
:group 'emms
:type '(repeat function))
! (defcustom emms-show-format "Currently playing %s"
! "*The format to use for `emms-show'. The only argument is the string
! returned by `emms-track-description-function'."
:group 'emms
:type 'string)
(defcustom emms-repeat-playlist nil
! "*Non-nil for repeating the playlist after playing the last track."
:group 'emms
:type 'boolean)
(defcustom emms-track-description-function 'emms-track-description
! "*A function to be called to give a nice, user-friendly description
! of the track passed to it as an argument."
:group 'emms
:type 'function)
(defcustom emms-play-all-preparation-function 'identity
! "*A function that prepares the list of tracks for `emms-play-all'.
! This can be used to sort or shuffle."
:group 'emms
:type 'function
:options '(emms-play-all-sort
emms-play-all-shuffle))
(defcustom emms-play-all-except nil
! "*A list of functions that return non-nil if their argument track
! should not be played using `emms-play-all'."
:group 'emms
:type '(repeat function))
(defcustom emms-sort-lessp-function 'emms-sort-track-name-less-p
! "*A function that compares two tracks, and returns non-nil if the
! first track should be sorted before the second (see `sort')."
:group 'emms
:type 'function)
(defcustom emms-playlist-changed-hook nil
! "*A hook run when the playlist of EMMS has changed."
:group 'emms
:type 'hook)
(defcustom emms-playlist-current-changed-hook nil
! "*A hook run when the current track in the playlist of EMMS has
! changed."
:group 'emms
:type 'hook)
(defcustom emms-track-initialize-functions nil
! "*A list of functions to be run with a new track as their argument.
! This can be used to initialize a track with various info."
:group 'emms
:type 'hook)
(defcustom emms-player-started-hook nil
! "*A hook run when an EMMS player started playing."
:group 'emms
:type 'hook
:options '(emms-show))
(defcustom emms-player-stopped-hook nil
! "*A hook run when an EMMS player stopped playing.
See `emms-player-finished-hook'."
:group 'emms
:type 'hook)
(defcustom emms-player-finished-hook '(emms-next-noerror)
! "*A hook run when an EMMS player stopped playing.
Please pay attention to the differences between
! `emms-player-finished-hook' and `emms-player-stopped-hook'. The
! former is called when the player is stopped interactivly and the
! latter when the player returned."
:group 'emms
:type 'hook
:options '(emms-next-noerror))
(defvar emms-player-playing-p nil
! "Nil if there is no player playing right now. Else, it's the
! currently playing player.")
(defvar emms-playlist []
! "The current playlist, a vector of tracks.")
(defvar emms-playlist-current nil
! "The current track, or nil if there is no playlist.")
(defcustom emms-sort-on-file-add nil
! "*Controls the sorting of files added.
! If non-nil, then files are sorted before they are added to the
! current playlist."
:group 'emms
:type 'boolean)
;;; User Interface
(defun emms-start ()
! "Start EMMS and play the current track in the playlist."
(interactive)
(unless emms-player-playing-p
(emms-player-start (emms-playlist-current-track))))
(defun emms-stop ()
! "Stop EMMS."
(interactive)
(when emms-player-playing-p
(emms-player-stop)))
(defun emms-next ()
! "Play the next track in the playlist.
! This might behave funny in `emms-player-finished-hook', use
! `emms-next-noerror' instead for that."
(interactive)
(when emms-player-playing-p
(emms-stop))
--- 61,195 ----
:group 'emms)
(defcustom emms-source-list nil
! "*List of sources that EMMS can get tracks from.
! You need to set this if you want to use `emms-play-all'.
!
! For example, to set EMMS up to play all the media files in ~/media,
! you could use the following setting:
!
! (setq emms-source-list '((emms-source-directory-tree \"~/media\")))
! This uses the `directory-tree' source defined in emms-source-file.el."
:group 'emms
:type '(repeat sexp))
(defcustom emms-player-list nil
! "*List of players that EMMS can use. You need to set this!"
:group 'emms
:type '(repeat function))
! (defcustom emms-show-format "Currently playing: %s"
! "*The format to use for `emms-show'.
! Any \"%s\" is replaced by what `emms-track-description-function' returns
! for the currently playing track."
:group 'emms
:type 'string)
(defcustom emms-repeat-playlist nil
! "*Non-nil if the EMMS playlist should automatically repeat.
! If nil, playback will stop when the last track finishes playing.
! If non-nil, EMMS will wrap back to the first track when that happens."
:group 'emms
:type 'boolean)
(defcustom emms-track-description-function 'emms-track-description
! "*Function for describing an EMMS track in a user-friendly way."
:group 'emms
:type 'function)
(defcustom emms-play-all-preparation-function 'identity
! "*Function for preparing the list of tracks for `emms-play-all'.
! This can be used to, e.g., sort or shuffle the list."
:group 'emms
:type 'function
:options '(emms-play-all-sort
emms-play-all-shuffle))
(defcustom emms-play-all-except nil
! "*List of functions to filter what is played by `emms-play-all'.
! Each function should return nil if it is okay to play the track,
! or non-nil if the track should not be played."
:group 'emms
:type '(repeat function))
(defcustom emms-sort-lessp-function 'emms-sort-track-name-less-p
! "*Function for comparing two EMMS tracks.
! The function should return non-nil if and only if the first track
! sorts before the second (see `sort')."
:group 'emms
:type 'function)
(defcustom emms-playlist-changed-hook nil
! "*Hook run after the EMMS playlist changes."
:group 'emms
:type 'hook)
(defcustom emms-playlist-current-changed-hook nil
! "*Hook run after EMMS switches to a new track."
:group 'emms
:type 'hook)
(defcustom emms-track-initialize-functions nil
! "*List of functions to call for each new EMMS track.
! This can be used to initialize tracks with various info."
:group 'emms
:type 'hook)
(defcustom emms-player-started-hook nil
! "*Hook run when an EMMS player starts playing."
:group 'emms
:type 'hook
:options '(emms-show))
(defcustom emms-player-stopped-hook nil
! "*Hook run when an EMMS player is stopped by the user.
See `emms-player-finished-hook'."
:group 'emms
:type 'hook)
(defcustom emms-player-finished-hook '(emms-next-noerror)
! "*Hook run when an EMMS player finishes playing a track.
Please pay attention to the differences between
! `emms-player-finished-hook' and `emms-player-stopped-hook'.
! The former is called only when the player is stopped interactively;
! the latter, only when the player actually finishes playing a track."
:group 'emms
:type 'hook
:options '(emms-next-noerror))
(defvar emms-player-playing-p nil
! "The currently playing EMMS player, or nil.")
(defvar emms-playlist []
! "The current EMMS playlist: a vector of tracks.")
(defvar emms-playlist-current nil
! "The zero-based playlist index of the current EMMS track.
! If there is no playlist, this will be set to nil.")
(defcustom emms-sort-on-file-add nil
! "*If non-nil, sort tracks before adding them to the EMMS playlist."
:group 'emms
:type 'boolean)
+
;;; User Interface
+
(defun emms-start ()
! "Start playing the current track in the EMMS playlist."
(interactive)
(unless emms-player-playing-p
(emms-player-start (emms-playlist-current-track))))
(defun emms-stop ()
! "Stop any current EMMS playback."
(interactive)
(when emms-player-playing-p
(emms-player-stop)))
(defun emms-next ()
! "Start playing the next track in the EMMS playlist.
! This might behave funny if called from `emms-player-finished-hook',
! so use `emms-next-noerror' in that case."
(interactive)
(when emms-player-playing-p
(emms-stop))
***************
*** 190,198 ****
(error "No next track in playlist")))
(defun emms-next-noerror ()
! "Play the next track in the playlist, but don't signal an error when
! we're at the end. This should be called when no player is playing.
! This is a suitable function to put in `emms-player-finished-hook'."
(interactive)
(when emms-player-playing-p
(error "A track is already being played"))
--- 198,208 ----
(error "No next track in playlist")))
(defun emms-next-noerror ()
! "Start playing the next track in the EMMS playlist.
! Unlike `emms-next', this function doesn't signal an error when called
! at the end of the playlist.
! This function should only be called when no player is playing.
! This is a good function to put in `emms-player-finished-hook'."
(interactive)
(when emms-player-playing-p
(error "A track is already being played"))
***************
*** 202,211 ****
(setq emms-playlist-current 0)
(emms-start))
(t
! (message "No next track in playlist."))))
(defun emms-previous ()
! "Play the previous track in the playlist."
(interactive)
(when emms-player-playing-p
(emms-stop))
--- 212,221 ----
(setq emms-playlist-current 0)
(emms-start))
(t
! (message "No next track in playlist"))))
(defun emms-previous ()
! "Start playing the previous track in the EMMS playlist."
(interactive)
(when emms-player-playing-p
(emms-stop))
***************
*** 215,221 ****
;;;###autoload
(defun emms-play-all ()
! "Play all sources in `emms-source-list'."
(interactive)
(let ((new (emms-play-all-except
emms-play-all-except
--- 225,232 ----
;;;###autoload
(defun emms-play-all ()
! "Play all sources in `emms-source-list'.
! Except that `emms-play-all-except' can be used as a filter."
(interactive)
(let ((new (emms-play-all-except
emms-play-all-except
***************
*** 233,240 ****
(emms-start)))
(defun emms-play-all-except (funclist tracklist)
! "Delete all elements in TRACKLIST for which any element of FUNCLIST
! returns non-nil."
(let ((tracks nil)
(funcs nil))
(while tracklist
--- 244,252 ----
(emms-start)))
(defun emms-play-all-except (funclist tracklist)
! "Filter the elements in TRACKLIST according to FUNCLIST.
! The result will be a newly-created list containing all the elements of
! TRACKLIST, except those for which some element of FUNCLIST returns non-nil."
(let ((tracks nil)
(funcs nil))
(while tracklist
***************
*** 250,258 ****
(reverse tracks)))
(defun emms-show (&optional insertp)
! "Show the current playlist track in the minibuffer, or insert it if
! INSERTP is non-nil. This uses `emms-show-format' to format the current
! track."
(interactive "P")
(let ((string (format emms-show-format (emms-playlist-current))))
(if insertp
--- 262,270 ----
(reverse tracks)))
(defun emms-show (&optional insertp)
! "Describe the current EMMS track in the minibuffer.
! If INSERTP is non-nil, insert the description into the current buffer instead.
! This function uses `emms-show-format' to format the current track."
(interactive "P")
(let ((string (format emms-show-format (emms-playlist-current))))
(if insertp
***************
*** 260,271 ****
(message "%s" string))))
(defun emms-shuffle ()
! "Shuffle the playlist."
(interactive)
(emms-playlist-shuffle))
(defun emms-sort ()
! "Sort the playlist."
(interactive)
(emms-playlist-sort))
--- 272,283 ----
(message "%s" string))))
(defun emms-shuffle ()
! "Shuffle the EMMS playlist."
(interactive)
(emms-playlist-shuffle))
(defun emms-sort ()
! "Sort the EMMS playlist."
(interactive)
(emms-playlist-sort))
***************
*** 278,293 ****
(append (emms-playlist-shuffle-vector (vconcat list)) nil))
(defun emms-sort-track-name-less-p (a b)
! "Return non-nil if the track name of a is before b."
(string< (emms-track-name a)
(emms-track-name b)))
! ;;; A Track
! ;; This is a simple datatype to store track information. A track
! ;; consists of a type (a symbol) and a name (a string).
(defun emms-track (type name)
! "Create a track with type TYPE and name NAME."
(let ((track (emms-dictionary '*track*)))
(emms-track-set track 'type type)
(emms-track-set track 'name name)
--- 290,308 ----
(append (emms-playlist-shuffle-vector (vconcat list)) nil))
(defun emms-sort-track-name-less-p (a b)
! "Return non-nil if the track name of A sorts before B."
(string< (emms-track-name a)
(emms-track-name b)))
!
! ;;; Tracks
!
! ;; This is a simple datatype to store track information.
! ;; Each track consists of a type (a symbol) and a name (a string).
! ;; In addition, each track has an associated dictionary of information.
(defun emms-track (type name)
! "Create an EMMS track with type TYPE and name NAME."
(let ((track (emms-dictionary '*track*)))
(emms-track-set track 'type type)
(emms-track-set track 'name name)
***************
*** 302,310 ****
"Return the name of TRACK."
(emms-track-get track 'name))
! (defun emms-track-get (track name &optional inexistent)
! "Return the value of NAME for TRACK. If there is no value, return
! INEXISTENT (or nil if not given)."
(emms-dictionary-get track name inexistent))
(defun emms-track-set (track name value)
--- 317,325 ----
"Return the name of TRACK."
(emms-track-get track 'name))
! (defun emms-track-get (track name &optional default)
! "Return the value of NAME for TRACK.
! If there is no value, return DEFAULT (or nil, if not given)."
(emms-dictionary-get track name inexistent))
(defun emms-track-set (track name value)
***************
*** 312,340 ****
(emms-dictionary-set track name value))
(defun emms-track-description (track)
! "A simple function to give a user-readable description of a track.
! If it's a file track, it's just the filename.
! Else it's the type and the name with a colon in between."
(if (eq 'file (emms-track-type track))
(emms-track-name track)
(concat (symbol-name (emms-track-type track))
":"
(emms-track-name track))))
;;; The Playlist
! ;; This is a simple vector storing the current playlist. If at all
! ;; possible, don't access the vector directly but use the functions
! ;; provided here. If you can't avoid accessing the vector directly, be
! ;; careful to call the right hooks.
(defun emms-playlist-current ()
! "Return a description of the currently playing track.
! This uses `emms-track-description-function'."
(funcall emms-track-description-function
(emms-playlist-current-track)))
(defun emms-playlist-current-track ()
! "Return the currently playing track."
(when emms-playlist-current
(emms-playlist-get-track emms-playlist-current)))
--- 327,357 ----
(emms-dictionary-set track name value))
(defun emms-track-description (track)
! "Simple function to give a user-readable description of a track.
! If it's a file track, just return the file name.
! Otherwise, return the type and the name with a colon in between."
(if (eq 'file (emms-track-type track))
(emms-track-name track)
(concat (symbol-name (emms-track-type track))
":"
(emms-track-name track))))
+
;;; The Playlist
!
! ;; This is a simple vector storing the current playlist. You should avoid
! ;; accessing the vector directly, and use the functions provided here instead.
! ;; If you can't avoid accessing the vector directly, be careful to call the
! ;; right hooks at the right times.
(defun emms-playlist-current ()
! "Return a description of the currently playing EMMS track.
! This function uses `emms-track-description-function'."
(funcall emms-track-description-function
(emms-playlist-current-track)))
(defun emms-playlist-current-track ()
! "Return the currently playing EMMS track."
(when emms-playlist-current
(emms-playlist-get-track emms-playlist-current)))
***************
*** 343,360 ****
This uses `emms-track-description-function'."
(funcall emms-track-description-function track))
! (defun emms-playlist-get (number)
! "Return a description of the NUMBERth entry of the current playlist.
This uses `emms-track-description-function'"
(funcall emms-track-description-function
! (emms-playlist-get-track number)))
! (defun emms-playlist-get-track (number)
! "Return the NUMBERth track of the current playlist."
(aref emms-playlist number))
(defun emms-playlist-set-playlist (new)
! "Set the playlist to NEW.
This runs `emms-playlist-changed-hook'."
(setq emms-playlist new)
(cond
--- 360,377 ----
This uses `emms-track-description-function'."
(funcall emms-track-description-function track))
! (defun emms-playlist-get (n)
! "Return a description of the Nth entry of the current EMMS playlist.
This uses `emms-track-description-function'"
(funcall emms-track-description-function
! (emms-playlist-get-track n)))
! (defun emms-playlist-get-track (n)
! "Return the Nth track of the current EMMS playlist."
(aref emms-playlist number))
(defun emms-playlist-set-playlist (new)
! "Set the current EMMS playlist to NEW.
This runs `emms-playlist-changed-hook'."
(setq emms-playlist new)
(cond
***************
*** 367,389 ****
(run-hooks 'emms-playlist-changed-hook))
(defun emms-playlist-get-playlist ()
! "Return the current playlist."
emms-playlist)
! (defun emms-playlist-set-current (new)
! "Set the current track in the playlist to NEW (a number).
This runs `emms-playlist-current-changed-hook'."
! (setq emms-playlist-current new)
(run-hooks 'emms-playlist-current-changed-hook))
(defun emms-playlist-get-current ()
! "Return the number of the current track, or nil if the playlist is
! empty."
emms-playlist-current)
(defun emms-playlist-next ()
! "Advance the current track to the next entry in the playlist and
! return non-nil. Return nil if there is no next track."
(let ((cur (emms-playlist-get-current)))
(when (and cur
(< cur (- (length (emms-playlist-get-playlist)) 1)))
--- 384,407 ----
(run-hooks 'emms-playlist-changed-hook))
(defun emms-playlist-get-playlist ()
! "Return the current EMMS playlist.
! Avoid changing the structure returned by this function."
emms-playlist)
! (defun emms-playlist-set-current (n)
! "Set the current track in the EMMS playlist to N (a number).
This runs `emms-playlist-current-changed-hook'."
! (setq emms-playlist-current n)
(run-hooks 'emms-playlist-current-changed-hook))
(defun emms-playlist-get-current ()
! "Return the index number of the current EMMS track.
! If the playlist is empty, returns nil."
emms-playlist-current)
(defun emms-playlist-next ()
! "Advance to the next entry in the EMMS playlist.
! Return nil if there was no next track, or non-nil otherwise."
(let ((cur (emms-playlist-get-current)))
(when (and cur
(< cur (- (length (emms-playlist-get-playlist)) 1)))
***************
*** 391,400 ****
t)))
(defun emms-playlist-previous ()
! "Set the current track to the previous entry in the playlist and
! return non-nil. Return nil if there is no previous track."
(let ((cur (emms-playlist-get-current)))
! (when (and cur
(> cur 0))
(emms-playlist-set-current (- cur 1))
t)))
--- 409,418 ----
t)))
(defun emms-playlist-previous ()
! "Back up to the previous entry in the EMMS playlist.
! Return nil if there was no previous track, or non-nil otherwise."
(let ((cur (emms-playlist-get-current)))
! (when (and cur
(> cur 0))
(emms-playlist-set-current (- cur 1))
t)))
***************
*** 411,423 ****
(substring emms-playlist idx)))))
(defun emms-playlist-remove (idx)
! "Remove track at IDX from playlist."
(emms-playlist-set-playlist
(vconcat (substring emms-playlist 0 idx)
(substring emms-playlist (1+ idx)))))
(defun emms-playlist-search-vector (track vector)
! "Returns the index of the track TRACK in VECTOR."
(catch 'loop
(let ((i 0))
(while (< i (length vector))
--- 429,442 ----
(substring emms-playlist idx)))))
(defun emms-playlist-remove (idx)
! "Remove track at IDX from the EMMS playlist."
(emms-playlist-set-playlist
(vconcat (substring emms-playlist 0 idx)
(substring emms-playlist (1+ idx)))))
(defun emms-playlist-search-vector (track vector)
! "Return the index of TRACK in VECTOR, or nil if not found.
! Comparison is done with `eq'."
(catch 'loop
(let ((i 0))
(while (< i (length vector))
***************
*** 427,435 ****
(setq i (1+ i)))))))
(defun emms-playlist-shuffle ()
! "Shuffle the current playlist.
! This retains the current track at the front if anything is
! playling."
(if (not emms-player-playing-p)
(emms-playlist-set-playlist
(emms-playlist-shuffle-vector
--- 446,454 ----
(setq i (1+ i)))))))
(defun emms-playlist-shuffle ()
! "Shuffle the current EMMS playlist.
! If a track is currently being played, it will end up at the front
! of the playlist after shuffling."
(if (not emms-player-playing-p)
(emms-playlist-set-playlist
(emms-playlist-shuffle-vector
***************
*** 445,453 ****
(emms-playlist-set-current 0))))
(defun emms-playlist-sort ()
! "Sort the current playlist according to `emms-sort-lessp-function'.
! When a song is playing at the moment, retain it as the current
! song, changing the current index as appropriate."
(if (not emms-player-playing-p)
(emms-playlist-set-playlist
(emms-playlist-sort-vector
--- 464,473 ----
(emms-playlist-set-current 0))))
(defun emms-playlist-sort ()
! "Sort the current EMMS playlist.
! Comparison is done with `emms-sort-lessp-function'.
! If a song is currently being played, it will remain the current track
! after sorting, though its index may change as appropriate."
(if (not emms-player-playing-p)
(emms-playlist-set-playlist
(emms-playlist-sort-vector
***************
*** 475,494 ****
(vconcat (sort (append vector nil)
emms-sort-lessp-function)))
;;; Sources
! ;; A source is a source for tracks. It's just a function that returns
! ;; a list. The define-emms-source macro also defines emms-play-SOURCE
! ;; and emms-add-SOURCE. The former will replace the current playlist,
! ;; the latter add to the end.
(defmacro define-emms-source (name arglist &rest body)
! "Define a new source named NAME. This will define the function
! emms-source-NAME and commands emms-play-NAME and emms-add-NAME. The
! source function will return a list to be played, while the play and
! add commands will be interactive (if you specify an interactive form
! in the BODY) to be used by the user, both calling the source function
! with the appropriate arguments. See emms-source-file.el for some
! examples."
(let ((source-name (intern (format "emms-source-%s" name)))
(source-play (intern (format "emms-play-%s" name)))
(source-add (intern (format "emms-add-%s" name)))
--- 495,516 ----
(vconcat (sort (append vector nil)
emms-sort-lessp-function)))
+
;;; Sources
!
! ;; A source is just a function that returns a list of tracks.
! ;; The define-emms-source macro also defines functions emms-play-SOURCE
! ;; and emms-add-SOURCE. The former will replace the current playlist,
! ;; while the latter will add to the end.
(defmacro define-emms-source (name arglist &rest body)
! "Define a new EMMS source called NAME.
! This macro defines three functions: `emms-source-NAME', `emms-play-NAME'
! and `emms-add-NAME'. BODY should evaluate do a list of tracks to be played,
! which is exactly what `emms-source-NAME' will return.
! The other two functions will be simple wrappers around `emms-source-NAME';
! any `interactive' form that you specify in BODY will end up in these.
! See emms-source-file.el for some examples."
(let ((source-name (intern (format "emms-source-%s" name)))
(source-play (intern (format "emms-play-%s" name)))
(source-add (intern (format "emms-add-%s" name)))
***************
*** 517,523 ****
(emms-source-add (,source-name ,@call-args))))))
(defun emms-source-play (lis)
! "Play the tracks in LIS."
(let ((new
(if emms-sort-on-file-add
(emms-playlist-sort-vector (vconcat lis))
--- 539,545 ----
(emms-source-add (,source-name ,@call-args))))))
(defun emms-source-play (lis)
! "Play the tracks in LIS, after first clearing the EMMS playlist."
(let ((new
(if emms-sort-on-file-add
(emms-playlist-sort-vector (vconcat lis))
***************
*** 530,558 ****
(emms-start)))
(defun emms-source-add (lis)
! "Add the tracks in LIS to the playlist."
(emms-playlist-add lis))
;;; Players
! ;; A player is a data structure created by `emms-player'. See the
! ;; docstring of that function for more information.
(defvar emms-player-stopped-p nil
! "This is non-nil only when the currently playing player has
! been stopped forcibly by the user.")
(defun emms-player (start stop playablep)
! "Create a new player with the start function being START, the stop
! function being STOP, and a function that returns non-nil for a track
! that this player can play being PLAYABLEP.
!
! When trying to play a track, emms walks `emms-player-list' and for
! each player, it calls the PLAYABLEP function. If that returns non-nil,
! this player is used to play this track. Emms then calls the START
! function with this track as a parameter. The STOP function is called
! when the user tells emms to stop playing. Once the player has finished
! playing, it should call `emms-player-stopped' to tell emms about
! this."
(let ((p (emms-dictionary '*player*)))
(emms-player-set p 'start start)
(emms-player-set p 'stop stop)
--- 552,584 ----
(emms-start)))
(defun emms-source-add (lis)
! "Add the tracks in LIS to the end of the EMMS playlist."
(emms-playlist-add lis))
+
;;; Players
!
! ;; A player is a data structure created by `emms-player'.
! ;; See the docstring of that function for more information.
(defvar emms-player-stopped-p nil
! "Non-nil if the last EMMS player was stopped by the user.")
(defun emms-player (start stop playablep)
! "Create a new EMMS player.
! The start function will be START, and the stop function STOP.
! PLAYABLEP should return non-nil for tracks that this player can play.
!
! When trying to play a track, EMMS walks `emms-player-list'.
! For each player,it calls the PLAYABLEP function.
! The player corresponding to the first PLAYABLEP function that returns
! non-nil is used to play the track.
! To actually play the track, EMMS calls the START function,
! passing the chosen track as a parameter.
!
! If the user tells EMMS to stop playing, the STOP function is called.
! Once the player has finished playing, it should call `emms-player-stopped'
! to let EMMS know."
(let ((p (emms-dictionary '*player*)))
(emms-player-set p 'start start)
(emms-player-set p 'stop stop)
***************
*** 574,581 ****
(emms-dictionary-set p name value)))
(defun emms-player-for (track)
! "Return the player that feels responsible for TRACK, or nil if there
! is none."
(let ((lis emms-player-list))
(while (and lis
(not (funcall (emms-player-get (car lis) 'playablep)
--- 600,608 ----
(emms-dictionary-set p name value)))
(defun emms-player-for (track)
! "Return an EMMS player capable of playing TRACK.
! This will be the first player whose PLAYABLEP function returns non-nil,
! or nil if no such player exists."
(let ((lis emms-player-list))
(while (and lis
(not (funcall (emms-player-get (car lis) 'playablep)
***************
*** 598,620 ****
(run-hooks 'emms-player-started-hook)))))
(defun emms-player-stop ()
! "Stop the currently playing player."
(when emms-player-playing-p
(let ((emms-player-stopped-p t))
(funcall (emms-player-get emms-player-playing-p 'stop)))
(setq emms-player-playing-p nil)))
(defun emms-player-stopped ()
! "Declare that the current player has finished playing.
! This should only be called by a player."
(setq emms-player-playing-p nil)
(if emms-player-stopped-p
(run-hooks 'emms-player-stopped-hook)
(run-hooks 'emms-player-finished-hook)))
;;; Dictionaries
! ;; A simple helper data structure, a dictionary. This is used by both
! ;; players and tracks.
(defun emms-dictionary (name)
"Create a new dictionary of type NAME."
--- 625,649 ----
(run-hooks 'emms-player-started-hook)))))
(defun emms-player-stop ()
! "Stop the current EMMS player."
(when emms-player-playing-p
(let ((emms-player-stopped-p t))
(funcall (emms-player-get emms-player-playing-p 'stop)))
(setq emms-player-playing-p nil)))
(defun emms-player-stopped ()
! "Declare that the current EMMS player is finished.
! This should only be done by the current player itself."
(setq emms-player-playing-p nil)
(if emms-player-stopped-p
(run-hooks 'emms-player-stopped-hook)
(run-hooks 'emms-player-finished-hook)))
+
;;; Dictionaries
!
! ;; This is a simple helper data structure, used by both players
! ;; and tracks.
(defun emms-dictionary (name)
"Create a new dictionary of type NAME."
--
Daniel Brockman <address@hidden>
- [emms-help] Doc fixes to emms.el,
Daniel Brockman <=