aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--emms-mark.el53
-rw-r--r--emms-tag-editor.el126
2 files changed, 112 insertions, 67 deletions
diff --git a/emms-mark.el b/emms-mark.el
index 0eec5f3..5132b1d 100644
--- a/emms-mark.el
+++ b/emms-mark.el
@@ -1,10 +1,9 @@
;;; emms-mark.el --- mark track like dired
-;; Copyright (C) 2006, 2007 Ye Wenbin
+;; Copyright (C) 2006, 2007 Free Software Foundation, Inc.
;;
;; Author: Ye Wenbin <wenbinye@163.com>
;; Keywords:
-;; X-URL: not distributed yet
;; This program is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
@@ -46,7 +45,8 @@
"Return a description of the current track."
(assert (not (eq (default-value 'emms-track-description-function)
'emms-mark-track-description))
- nil "Should never set emms-track-selection-function to be emms-mark-track-description.")
+ nil (concat "Do not set `emms-track-selection-function' to be"
+ " emms-mark-track-description."))
(concat " " (funcall (default-value 'emms-track-description-function)
track)))
@@ -66,6 +66,9 @@
(?\040 . emms-playlist-track-face)))
(defun emms-mark-track (&optional arg)
+ "Mark the current track.
+If ARG is positive, also mark the next ARG-1 tracks as well.
+If ARG is negative, also mark the previous ARG-1 tracks."
(interactive "p")
(or arg (setq arg 1))
(let ((face (assoc-default emms-mark-char emms-mark-face-alist))
@@ -95,38 +98,47 @@
(1+ arg)))))))
(defun emms-mark-unmark-track (&optional arg)
+ "Unmark the current track.
+If ARG is positive, also unmark the next ARG-1 tracks as well.
+If ARG is negative, also unmark the previous ARG-1 tracks."
(interactive "p")
(let ((emms-mark-char ?\040))
(emms-mark-track arg)))
(defun emms-mark-forward (arg)
+ "Mark one or more tracks and move the point past the newly-marked tracks.
+See `emms-mark-track' for further details."
(interactive "p")
(emms-mark-track arg)
(forward-line arg))
(defun emms-mark-unmark-forward (arg)
+ "Unmark one or more tracks and move the point past the tracks.
+See `emms-mark-unmark-track' for further details."
(interactive "p")
(emms-mark-unmark-track arg)
(forward-line arg))
(defun emms-mark-all ()
+ "Mark all tracks in the current buffer."
(interactive)
(save-excursion
(goto-char (point-min))
(emms-mark-track (count-lines (point-min) (point-max)))))
(defun emms-mark-unmark-all ()
+ "Unmark all tracks in the current buffer."
(interactive)
(emms-mark-do-with-marked-track 'emms-mark-unmark-track))
(defun emms-mark-regexp (regexp arg)
- "Mark all tracks matching a regexp. A prefix argument means to
+ "Mark all tracks matching REGEXP. A prefix argument means to
unmark them instead."
(interactive
(list
(read-from-minibuffer (if current-prefix-arg
- "Mark track match: "
- "Unmark track match: "))
+ "Mark tracks matching: "
+ "Unmark tracks matching: "))
current-prefix-arg))
(let ((emms-mark-char (if arg ?\040 ?*)))
(save-excursion
@@ -136,6 +148,7 @@ unmark them instead."
(forward-line 1)))))
(defun emms-mark-toggle ()
+ "Toggle all marks in the current buffer."
(interactive)
(save-excursion
(goto-char (point-min))
@@ -147,7 +160,7 @@ unmark them instead."
(forward-line 1)))))
(defsubst emms-mark-has-markedp ()
- "Predicate whether the playlist has marked line"
+ "Return non-nil if the playlist has a marked line, nil otherwise."
(save-excursion
(goto-char (point-min))
(re-search-forward (format "^[%c]" emms-mark-char) nil t)))
@@ -156,13 +169,15 @@ unmark them instead."
;;{{{ functions to operate marked tracks
(defun emms-mark-do-with-marked-track (func &optional move)
- "Call FUNC on every marked line in current playlist. The FUNC take
-no argument, so if need the track in marked line, should use
-`emms-playlist-track-at' to get it. The FUNC can also modify the
-playlist buffer, such as delete the line. It is import for who want to
-use this function, this function didn't move forward. So if FUNC don't
-move forward, set the second parameter MOVE to non-nil. Otherwise, the
-function will never exit the loop."
+ "Call FUNC on every marked line in current playlist.
+The function specified by FUNC takes no argument, so if the track
+on the marked line is needed, use `emms-playlist-track-at' to get
+it.
+
+The function can also modify the playlist buffer, such as
+deleting the current line. If the function doesn't move forward,
+be sure to set the second parameter MOVE to non-nil. Otherwise
+the function will never exit the loop."
(let ((regexp (format "^[%c]" emms-mark-char))
(newfunc func))
(if move
@@ -175,8 +190,8 @@ function will never exit the loop."
(defun emms-mark-mapcar-marked-track (func &optional move)
"This function does the same thing as
-`emms-mark-do-with-marked-track', the only difference is this function
-collect the result of FUNC."
+`emms-mark-do-with-marked-track', the only difference being that
+this function collects the result of FUNC."
(let ((regexp (format "^[%c]" emms-mark-char))
result (newfunc func))
(if move
@@ -190,6 +205,7 @@ collect the result of FUNC."
(nreverse result))))
(defun emms-mark-delete-marked-tracks ()
+ "Delete all tracks that have been marked in the current buffer."
(interactive)
(emms-with-inhibit-read-only-t
(emms-mark-do-with-marked-track
@@ -197,6 +213,7 @@ collect the result of FUNC."
(progn (forward-line 1) (point)))))))
(defun emms-mark-kill-marked-tracks ()
+ "Kill all tracks that have been marked in the current buffer."
(interactive)
(let (tracks buffer-read-only)
(emms-mark-do-with-marked-track
@@ -208,6 +225,7 @@ collect the result of FUNC."
(kill-new tracks)))
(defun emms-mark-copy-marked-tracks ()
+ "Copy all tracks that have been marked in the current buffer."
(interactive)
(let (tracks)
(emms-mark-do-with-marked-track
@@ -230,7 +248,8 @@ collect the result of FUNC."
(define-key map "U" 'emms-mark-unmark-all)
(define-key map "t" 'emms-mark-toggle)
(define-key map "%m" 'emms-mark-regexp)
- map))
+ map)
+ "Keymap for `emms-mark-mode'.")
(defun emms-mark-mode ()
"An EMMS major mode that allows tracks to be marked like dired.
diff --git a/emms-tag-editor.el b/emms-tag-editor.el
index 0fc4149..865639b 100644
--- a/emms-tag-editor.el
+++ b/emms-tag-editor.el
@@ -1,10 +1,9 @@
;;; emms-tag-editor.el --- Edit track tags.
-;; Copyright (C) 2006, 2007 Ye Wenbin
+;; Copyright (C) 2006, 2007 Free Software Foundation, Inc.
;;
;; Author: Ye Wenbin <wenbinye@163.com>
;; Keywords:
-;; X-URL: not distributed yet
;; This program is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
@@ -22,8 +21,6 @@
;;; Commentary:
-;;
-
;; Put this file into your load-path and the following into your ~/.emacs:
;; (require 'emms-tag-editor)
@@ -47,14 +44,15 @@
(info-genre . "g")
(info-date . "d")
(info-note . "c"))
-"A list to setup format.")
+ "An alist to determine the format of various info tags.")
(defvar emms-tag-editor-edit-buffer "*EMMS-TAGS*"
- "Buffer name to edit tags")
+ "Name of the buffer used for editing tags.")
(defvar emms-tag-editor-log-buffer "*EMMS-LOG*"
- "Buffer name of tag edit log")
+ "Name of emms-tag-editor's log buffer.")
(defun emms-tag-editor-make-format (tags)
+ "Make a format string based on TAGS."
(concat "%m\n" (emms-propertize (format "%-16s = " "name")
'read-only t 'rear-nonsticky t
'face 'bold)
@@ -74,9 +72,10 @@
`(("mp3" . ,default)
("ogg" . ,(emms-tag-editor-make-format (remove 'info-year tags)))
("default" . ,default)))
- "Format to insert the track. The CAR part is the extension of the
-track name, and the CDR part is the format template. The format
-specification is like:
+ "Format to use when inserting the track.
+The CAR part is the extension of the track name, and the CDR part
+is the format template. The format specification is like:
+
m -- Track description
f -- Track name
a -- Track info-artist
@@ -87,22 +86,24 @@ specification is like:
g -- Track info-genre
c -- Track info-note
-You can add new specification in `emms-tag-editor-tags' and use
-`emms-tag-editor-make-format' to help create a new format.
+You can add new specifications in `emms-tag-editor-tags', and use
+`emms-tag-editor-make-format' to create a new format string.
-The CDR part also can be a function, which accept one parameter, the
-track, and should return a string to insert to `emms-tag-editor-edit-buffer'.
-")
+The CDR part also can be a function, which accepts one parameter,
+the track, and returns a string to insert in
+`emms-tag-editor-edit-buffer'.")
(defvar emms-tag-editor-get-format-function 'emms-tag-editor-get-format
- "Function to decide which format to use for format the track.")
+ "Determines which function to call to get the format string, which is
+used for inserting the track.")
(defvar emms-tag-editor-parse-function 'emms-tag-editor-default-parser
- "Function to parse tags in `emms-tag-editor-edit-buffer'. It should find
-all modified tags, and return all the tracks. The tracks which tag has
-been modified should set a property 'tag-modified to t, and if the
-track name have been change, the function should set a new property
-'newname instead set the 'name directly.
+ "Function to parse tags in `emms-tag-editor-edit-buffer'.
+It should find all modified tags, and return all the tracks. The
+tracks for which a tag has been modified should set a property
+'tag-modified to t. If the track name has been changed, the
+function should set a new property 'newname instead of setting
+the 'name directly.
See also `emms-tag-editor-default-parser'.")
@@ -116,17 +117,18 @@ See also `emms-tag-editor-default-parser'.")
(info-genre . "g")
(info-note . "c")))
("ogg" . emms-tag-editor-tag-ogg))
- "A List for change tag in files. If the extern program set tag by
-command line options one by one such as mp3info, the list should like:
+ "An alist used when committing changes to tags in files.
+If the external program sets tags by command line options
+one-by-one such as mp3info, then the list should like:
(EXTENSION PROGRAM COMMAND_LINE_OPTIONS)
-Otherwise, a function that accept a parameter, the track, should be
-given.
+Otherwise, a function that accepts a single parameter, the track,
+should be given.
-See also `emms-tag-editor-tag-file' and `emms-tag-editor-tag-ogg'.
-")
+See also `emms-tag-editor-tag-file' and `emms-tag-editor-tag-ogg'.")
(defun emms-tag-editor-tag-ogg (track)
+ "Commit changes to an OGG file according to TRACK."
(let (args val)
(mapc (lambda (tag)
(let ((info-tag (intern (concat "info-" tag))))
@@ -141,7 +143,8 @@ See also `emms-tag-editor-tag-file' and `emms-tag-editor-tag-ogg'.
(append args (list (emms-track-name track)))))))
(defun emms-tag-editor-tag-file (track program tags)
- "Change tag in FILE use PROGRAM. The TAGS is given in `emms-tag-editor-tagfile-functions'."
+ "Change TAGS in FILE, using PROGRAM.
+Valid tags are given by `emms-tag-editor-tagfile-functions'."
(let (args val)
(mapc (lambda (tag)
(setq val (emms-track-get track (car tag)))
@@ -153,6 +156,7 @@ See also `emms-tag-editor-tag-file' and `emms-tag-editor-tag-ogg'.
(nconc args (list filename)))))
(defun emms-tag-editor-get-format (track)
+ "Get the format string to use for committing changes to TRACK."
(let ((format
(assoc (file-name-extension (emms-track-name track))
emms-tag-editor-formats)))
@@ -161,6 +165,8 @@ See also `emms-tag-editor-tag-file' and `emms-tag-editor-tag-ogg'.
(cdr (assoc "default" emms-tag-editor-formats)))))
(defun emms-tag-editor-format-track (track)
+ "Return a string representing the info tags contained in TRACK.
+This string is suitable for inserting into the tags buffer."
(let ((format (funcall emms-tag-editor-get-format-function track)))
(if (functionp format)
(funcall format track)
@@ -178,6 +184,7 @@ See also `emms-tag-editor-tag-file' and `emms-tag-editor-tag-ogg'.
emms-tag-editor-tags)))))))
(defun emms-tag-editor-track-at (&optional pos)
+ "Return a copy of the track at POS. Defaults to point if POS is nil."
(let ((track (emms-playlist-track-at pos))
newtrack)
(when track
@@ -187,20 +194,24 @@ See also `emms-tag-editor-tag-file' and `emms-tag-editor-tag-ogg'.
newtrack)))
(defsubst emms-tag-editor-erase-buffer (&optional buf)
+ "Erase the buffer BUF, and ensure that it exists."
(let ((inhibit-read-only t))
(save-excursion
(set-buffer (get-buffer-create buf))
(erase-buffer))))
(defsubst emms-tag-editor-insert-track (track)
+ "Insert TRACK, if it is specified."
(and track
(insert (emms-tag-editor-format-track track))))
(defsubst emms-tag-editor-display-log-buffer-maybe ()
+ "Display the log buffer if it has any contents."
(if (> (buffer-size (get-buffer emms-tag-editor-log-buffer)) 0)
(display-buffer emms-tag-editor-log-buffer)))
(defun emms-tag-editor-insert-tracks (tracks)
+ "Insert TRACKS into the tag editor buffer."
(save-excursion
(emms-tag-editor-erase-buffer emms-tag-editor-log-buffer)
(emms-tag-editor-erase-buffer emms-tag-editor-edit-buffer)
@@ -212,12 +223,14 @@ See also `emms-tag-editor-tag-file' and `emms-tag-editor-tag-ogg'.
(emms-tag-editor-display-log-buffer-maybe)))
(defun emms-tag-editor-edit-track (track)
+ "Edit the track at point, or TRACK."
(interactive (list (emms-tag-editor-track-at)))
(if (null track)
(message "No track at point!")
(emms-tag-editor-insert-tracks (list track))))
(defun emms-tag-editor-edit-marked-tracks ()
+ "Edit all tracks marked in the current buffer."
(interactive)
(let ((tracks (emms-mark-mapcar-marked-track 'emms-tag-editor-track-at t)))
(if (null tracks)
@@ -225,7 +238,7 @@ See also `emms-tag-editor-tag-file' and `emms-tag-editor-tag-ogg'.
(emms-tag-editor-insert-tracks tracks))))
(defun emms-tag-editor-edit ()
- "Edit tags of track at point or marked tracks"
+ "Edit tags of either the track at point or all marked tracks."
(interactive)
(if (emms-mark-has-markedp)
(emms-tag-editor-edit-marked-tracks)
@@ -243,7 +256,8 @@ See also `emms-tag-editor-tag-file' and `emms-tag-editor-tag-ogg'.
(define-key map "\C-c\C-r" 'emms-tag-editor-set-all)
(define-key map "\C-c\C-a" 'emms-tag-editor-replace-in-tag)
(define-key map "\C-c\C-t" 'emms-tag-editor-transpose-tag)
- map))
+ map)
+ "Keymap for `emms-tag-editor-mode'.")
(define-key emms-playlist-mode-map "E" 'emms-tag-editor-edit)
(define-derived-mode emms-tag-editor-mode text-mode "Tag-Edit"
@@ -251,10 +265,12 @@ See also `emms-tag-editor-tag-file' and `emms-tag-editor-tag-ogg'.
\\{emms-tag-editor-mode-map}")
(defun emms-tag-editor-set-all (tag value)
- "Replace all track's TAG to VALUE. If turn transient-mark-mode on,
-you can apply the command to a selected region. If
-`transient-mark-mode' is on andthe mark is activate, the changes
-will only take on the tracks in the region."
+ "Set TAG to VALUE in all tracks.
+If transient-mark-mode is turned on, you can apply the command to
+a selected region.
+
+ If `transient-mark-mode' is on and the mark is active, the
+changes will only take effect on the tracks in the region."
(interactive
(list (completing-read "Set tag: "
emms-tag-editor-tags nil t)
@@ -270,10 +286,12 @@ will only take on the tracks in the region."
(insert value)))))
(defun emms-tag-editor-replace-in-tag (tag from to)
- "Query and replace text in selected TAG. For example, select
-tag info-title, then replace will only occur in title. If
-`transient-mark-mode' is on andthe mark is activate, the changes
-will only take on the tracks in the region."
+ "Query and replace text in selected TAG.
+For example, if the info-title tag is selected, then only perform
+replacement in title tags.
+
+If `transient-mark-mode' is on and the mark is active, the
+changes will only take effect on the tracks in the region."
(interactive
(cons (completing-read "Replace in tag: "
emms-tag-editor-tags nil t)
@@ -314,13 +332,13 @@ will only take on the tracks in the region."
(delete-overlay overlay))))
(defun emms-tag-editor-transpose-tag (tag1 tag2)
- "Transpose value of TAG1 and TAG2. If `transient-mark-mode' is
-on andthe mark is activate, the changes will only take on the
-tracks in the region."
+ "Transpose value of TAG1 and TAG2.
+If `transient-mark-mode' is on and the mark is active, the
+changes will only take effect on the tracks in the region."
(interactive
- (let* ((tag1 (intern (completing-read "Tag1: "
+ (let* ((tag1 (intern (completing-read "Tag 1: "
emms-tag-editor-tags nil t)))
- (tag2 (intern (completing-read "Tag2: "
+ (tag2 (intern (completing-read "Tag 2: "
(assq-delete-all tag1 (copy-sequence emms-tag-editor-tags))
nil t))))
(list tag1 tag2)))
@@ -341,12 +359,14 @@ tracks in the region."
(emms-tag-editor-insert-track track))))))
(defun emms-tag-editor-next-field (arg)
+ "Move to the next tag field."
(interactive "p")
(if (> arg 0)
(re-search-forward "\\s-*=[ \t]*" nil nil arg)
(emms-tag-editor-prev-field (- arg))))
(defun emms-tag-editor-prev-field (arg)
+ "Move to the previous tag field."
(interactive "p")
(if (< arg 0)
(emms-tag-editor-next-field (- arg))
@@ -355,6 +375,7 @@ tracks in the region."
(skip-chars-forward " \t=")))
(defun emms-tag-editor-prev-track ()
+ "Move to the previous track."
(interactive)
(let ((prev (previous-single-property-change (point)
'emms-track)))
@@ -369,6 +390,7 @@ tracks in the region."
(goto-char prev)))
(defun emms-tag-editor-next-track ()
+ "Move to the next track."
(interactive)
(let ((next (next-single-property-change (point)
'emms-track)))
@@ -382,15 +404,15 @@ tracks in the region."
(goto-char next)))
(defun emms-tag-editor-submit (arg)
- "Make modified tags take affect. With prefiex argument, bury tag
-edit buffer."
+ "Make modified tags take affect.
+With prefix argument, bury the tag edit buffer."
(interactive "P")
(let ((tracks (funcall emms-tag-editor-parse-function))
filename func exit old pos val need-sync)
(if (not (and tracks (y-or-n-p "Submit changes? ")))
- (message "Nothing have to do!")
+ (message "No tags were modified")
(emms-tag-editor-erase-buffer emms-tag-editor-log-buffer)
- (message "Wait while set tags...")
+ (message "Setting tags...")
(save-excursion
(dolist (track tracks)
(when (emms-track-get track 'tag-modified)
@@ -425,7 +447,9 @@ edit buffer."
(emms-tag-editor-tag-file track (cadr func) (nth 2 func))))
(if (zerop exit)
(emms-track-get track 'info-mtime (butlast (current-time)))
- (emms-tag-editor-log "Change tags of %s failed with exit value %d" filename exit)))
+ (emms-tag-editor-log
+ "Changing tags of %s failed with exit value %d"
+ filename exit)))
;; update track in playlist
(when (and (setq pos (emms-track-get track 'position))
(marker-position pos))
@@ -436,18 +460,20 @@ edit buffer."
(emms-track-set track 'tag-modified nil))))
(if (and (featurep 'emms-cache)
need-sync
- (y-or-n-p "You have change some track names, sync the cache? "))
+ (y-or-n-p "You have changed some track names; sync the cache? "))
(and (fboundp 'emms-cache-sync) ; silence byte-compiler
(emms-cache-sync)))
(unless (emms-tag-editor-display-log-buffer-maybe)
- (message "Set all mp3 tag done!"))))
+ (message "Setting tags...done"))))
(if arg (bury-buffer)))
(defun emms-tag-editor-submit-and-exit ()
+ "Submit changes to track information and exit the tag editor."
(interactive)
(emms-tag-editor-submit t))
(defun emms-tag-editor-default-parser ()
+ "Default function used to parse tags in `emms-tag-editor-edit-buffer'."
(let (next tracks track key val)
(goto-char (point-min))
(if (get-text-property (point) 'emms-track)