Skip to content
Browse files

Documentation

Signed-off-by: Damien Cassou <damien.cassou@gmail.com>
  • Loading branch information...
1 parent 97a18b0 commit d21bac9cae938b75b1666f8894465983c8ef2832 @DamienCassou DamienCassou committed Jun 30, 2012
Showing with 52 additions and 29 deletions.
  1. +52 −29 rswitcher.el
View
81 rswitcher.el
@@ -54,17 +54,21 @@ and manipulate SWITCHER."
(defun rswitcher--last-pos (switcher)
"Return the index of SWITCHER's most-recent element.
-This function returns nil in all cases except after a
+A value of 0 means the first element of SWITCHER's elements. This
+function returns nil in all cases except after a
`rswitcher-switch-partial' (and the function
`rswitcher--reset-last-pos' will make this function return nil
-again). See `rswitcher--most-recent-pos' and `rswitcher--most-recent' for
-higher-level functions. Change the value returned by this
-function by using `rswitcher--reset-last-pos',
-`rswitcher--increment-last-pos', and `rswitcher--set-last-pos'."
+again). See `rswitcher--most-recent-pos' and
+`rswitcher--most-recent' for higher-level functions. Change the
+value returned by this function by using
+`rswitcher--reset-last-pos', `rswitcher--increment-last-pos', and
+`rswitcher--set-last-pos'."
(cdr switcher))
(defun rswitcher--set-last-pos (switcher last-pos)
- "Set the last pos field of SWITCHER to be LAST-POS."
+ "Set the last pos field of SWITCHER to be LAST-POS.
+
+A value of 0 means the first element of SWITCHER's elements."
(setcdr switcher last-pos))
(defun rswitcher--increment-last-pos (switcher)
@@ -91,26 +95,48 @@ See `rswitcher--elements'."
(defun rswitcher--most-recent-pos (switcher)
"Return the index of the most recent element.
The most recent element is always the first of SWITCHER's
-elements except after a call to `rswitcher-switch-partial' in
-which case the most recent element is pointed to by the last pos
-field of SWITCHER."
+elements (in which case the function returns 0) except after a
+call to `rswitcher-switch-partial' in which case the most recent
+element is pointed to by the last pos field of SWITCHER."
(or (rswitcher--last-pos switcher) 0))
(defun rswitcher-most-recent (switcher)
+ "Return the most recently accessed element in SWITCHER."
(elt (rswitcher--elements switcher) (rswitcher--most-recent-pos switcher)))
(defun rswitcher--push (switcher elt)
+ "Update SWITCHER's elements by adding ELT in front."
(setcar switcher (cons elt (car switcher))))
+(defun rswitcher-make-most-recent-elt-the-first (switcher)
+ "Move most recent element to the beginning of SWITCHER's elements."
+ (unless (zerop (rswitcher--most-recent-pos switcher))
+ (rswitcher--push
+ switcher
+ (rswitcher--delete switcher (rswitcher--most-recent-pos switcher)))))
+
+(defun rswitcher-add (switcher elt)
+ "Reorganize SWITCHER with most-recent element on front and push ELT."
+ (rswitcher-make-most-recent-elt-the-first switcher)
+ (rswitcher--push switcher elt)
+ (rswitcher--reset-last-pos switcher))
+
(defun rswitcher--pop (switcher)
- (prog1
- (caar switcher)
- (setcar switcher (cdar switcher))))
+ "Remove and return the first element of SWITCHER's elements."
+ (let ((elements (rswitcher--elements switcher)))
+ (prog1
+ (car elements)
+ (setcar switcher (cdr elements)))))
(defun rswitcher-memq (switcher elt)
+ "Check if SWITCHER's elements include ELT. Comparison done with `eq'."
(memq elt (rswitcher--elements switcher)))
(defun rswitcher--delete (switcher pos)
+ "Delete and return the element in SWITCHER at position POS.
+
+This function only accepts valid values for POS between 0 and the
+number of SWITCHER's elements minus 1."
(prog1
;; return the deleted element
(elt (rswitcher--elements switcher) pos)
@@ -124,43 +150,40 @@ field of SWITCHER."
(rswitcher--reset-last-pos switcher))))
(defun rswitcher-delete-most-recent (switcher)
+ "Remove the most recent element from SWITCHER."
(rswitcher--delete switcher (rswitcher--most-recent-pos switcher)))
-(defun rswitcher-make-most-recent-elt-the-first (switcher)
- ;; put most-recent element to the beginning of the list
- (unless (zerop (rswitcher--most-recent-pos switcher))
- (rswitcher--push
- switcher
- (rswitcher--delete switcher (rswitcher--most-recent-pos switcher)))))
-
-(defun rswitcher-add (switcher elt)
- (rswitcher-make-most-recent-elt-the-first switcher)
- (rswitcher--push switcher elt)
- (rswitcher--reset-last-pos switcher))
-
(defun rswitcher--swap-first-two-elts (switcher)
- (let ((most-recent (rswitcher--pop switcher))
+ "Reorganize SWITCHER by swapping first and second elements."
+ (let ((first (rswitcher--pop switcher))
(new (rswitcher--pop switcher)))
- (rswitcher--push switcher most-recent)
+ (rswitcher--push switcher first)
(rswitcher--push switcher new)))
(defun rswitcher-switch-full (switcher)
+ "Select the next most recent element in SWITCHER.
+This function is similar to pressing and releasing ALT+TAB in
+standard window managers. Repeatedly calling this function will
+always select the two most recent elements alternatively."
(when (>= (rswitcher-length switcher) 2)
(rswitcher-make-most-recent-elt-the-first switcher)
(rswitcher--swap-first-two-elts switcher)
(rswitcher--reset-last-pos switcher)))
(defun rswitcher-switch-partial (switcher)
+ "Continue switching after 1 full switch and many partial switches.
+This function is similar to pressing TAB after pressing ALT+TAB.
+Repeatedly calling this function will alternatively select all
+elements of SWITCHER, most recent elements first."
(when (>= (rswitcher-length switcher) 2)
(if (rswitcher--last-pos switcher)
(rswitcher--increment-last-pos switcher)
- ;; Reverse swap done in previous execution of rswitcher-switch-full
+ ;; Reverse swap done in previous execution of
+ ;; `rswitcher-switch-full'
(rswitcher--swap-first-two-elts switcher)
(rswitcher--set-last-pos switcher
(if (> (rswitcher-length switcher) 2) 2 0)))))
(provide 'rswitcher)
-(provide 'rswitcher)
-
;;; rswitcher.el ends here

0 comments on commit d21bac9

Please sign in to comment.
Something went wrong with that request. Please try again.