[sawfish] Jump-or-exec cleanup.

[Christopher Bratusek <chrisb src gnome org>]

commit f97d16daed0a226bc67fef61fa701603e9759291
Author: Teika kazura <teika lavabit com>
Date:   Sat Jan 8 13:45:54 2011 +0900

    Jump-or-exec cleanup.
    
    * Wrote a thorough documentation.
    * Handling of arguments "prog" and "onfocused" is extended in lucid way.
      They can be a command-name or a lisp expression, too.
    * Code is cleaned.

 lisp/sawfish/wm/commands/jump-or-exec.jl |   76 +++++++++++++----------------
 man/sawfish.texi                         |   51 ++++++++++++++++++++
 2 files changed, 85 insertions(+), 42 deletions(-)
---
diff --git a/lisp/sawfish/wm/commands/jump-or-exec.jl b/lisp/sawfish/wm/commands/jump-or-exec.jl
index cb39e5c..0db1222 100644
--- a/lisp/sawfish/wm/commands/jump-or-exec.jl
+++ b/lisp/sawfish/wm/commands/jump-or-exec.jl
@@ -1,4 +1,4 @@
-;;; jump-or-exec.jl 1.0.0 -- flexible application shortcut keys
+;;; jump-or-exec.jl -- flexible application shortcut keys
 
 ;; Copyright (C) 2002 Damien Elmes <resolve repose cx>
 ;; Copyright (C) 2010 Christopher Roy Bratusek <zanghar freenet de>
@@ -22,22 +22,10 @@
 
 ;;; Description
 
-;; This function either focusses a given window, or starts
-;; the application instead.
+;; Provides key bindings to focus a given window, or starts the
+;; application if absent.
 ;;
-;; Examples:
-;;
-;; => application gnome-run-dialog matched on it's WM_CLASS
-;; ( bind-keys global-keymap "W-F2"
-;;   `( jump-or-exec "Gnome-run-dialog" "gnome-run-dialog" #:match-class t ) )
-;;
-;; => application geany matched on it's WM_NAME
-;; ( bind-keys global-keymap "W-F10"
-;;   `( jump-or-exec "Geany" "geany" #:match-class nil ) )
-;;
-;; NOTE: `#:match-class nil' can be skipped, as it's nil by default
-;;
-;; In version 1.0.0 toggle-or-exec was merged into jump-or-exec. It's basically
+;; toggle-or-exec was merged into jump-or-exec. It's basically
 ;; the same, but it turns windows into drop-down-terminal like ones, that means
 ;; then you press the key while on the corresponding window, it will be hidden.
 ;; Optionally you may add a window-matcher, wich will also hide the window when
@@ -75,26 +63,30 @@
 	  sawfish.wm.util.display-window
 	  sawfish.wm.commands)
 
-  (define (jump-or-exec re prog #!key match-class onfocused)
-    "jump to a window matched by re, or start program otherwise."
-    (catch 'return
-      (let ((wind (if match-class
-                    (get-window-by-class-re re)
-                    (get-window-by-name-re re))))
-        (if (functionp onfocused) ; check if already focused
-            (let ((curwin (input-focus)))
-              (if curwin
-                  (if (or (string-match re (window-class curwin))
-			  (string-match re (window-name curwin)))
-		      (progn
-			;; shouldn't it be curwin
-                        (funcall onfocused wind)
-                        (throw 'return))))))
-        (if (windowp wind)
-            (display-window wind)
-          (if (functionp prog)
-                (funcall prog)
-              (system (concat prog "&")))))))
+  (define (jump-or-exec regex prog #!key match-class onfocused)
+    "Jump to a window, or when absent, start program."
+    (let ((wind (if match-class
+		    (get-window-by-class-re regex)
+		  (get-window-by-name-re regex)))
+	  (curwin (input-focus)))
+      (cond ((and onfocused
+		  curwin
+		  (if match-class
+		      (string-match regex (window-class curwin))
+		    (string-match regex (window-name curwin))))
+	     ;; Exec "onfocused"
+	     (cond ((commandp onfocused)
+		    (call-command onfocused))
+		   ((functionp onfocused)
+		    (funcall onfocused wind))
+		   (t (user-eval onfocused ))))
+	    ;; Jump to the window.
+	    ((windowp wind) (display-window wind))
+	    ;; Exec "prog"
+	    ((stringp prog) (system (concat prog "&")))
+	    ((functionp prog) (funcall prog))
+	    ((commandp prog) (call-command prog))
+	    (t (user-eval prog)))))
 
   (define-command 'jump-or-exec jump-or-exec #:class 'default)
 
@@ -102,15 +94,15 @@
     (let ((default-window-animator 'none))
       (iconify-window (input-focus))))
 
-  (define (toggle-or-exec re prog #!key match-class)
-    (if match-class
-        (jump-or-exec re prog #:match-class t #:onfocused jump-or-exec-leave)
-      (jump-or-exec re prog #:onfocused jump-or-exec-leave)))
+  (define (toggle-or-exec regex prog #!key match-class)
+    (jump-or-exec regex prog
+		  #:match-class match-class
+		  #:onfocused jump-or-exec-leave))
 
   (define (jump-or-exec-hook)
     (if (and (not (eq (current-event-window) 'root)) ;; may error on startup else
 	     (window-get (current-event-window) 'iconify-on-leave))
-      (let ((default-window-animator 'none)) ;; no animator
-	(iconify-window (current-event-window)))))
+	(let ((default-window-animator 'none)) ;; no animator
+	  (iconify-window (current-event-window)))))
 
   (add-hook 'leave-notify-hook jump-or-exec-hook))
diff --git a/man/sawfish.texi b/man/sawfish.texi
index 58fa14f..ab4856c 100644
--- a/man/sawfish.texi
+++ b/man/sawfish.texi
@@ -6803,6 +6803,57 @@ order of elements is not preserved.
 @chapter External Applications
 @cindex External applications
 
+In this chapter relation to external applications is described.
+See also @xref{Applications Menu}, which is a popup to execute applications.
+
+ menu
+* Application Invocation::
+* Common Applications::         terminal, browser, and so on.
+ end menu
+
+ node Application Invocation, Common Applications,, External Applications
+ section Application Invocation
+
+See also the function @code{system} which invokes a command from a shell.
+(@pxref{Shell Commands,,, librep, The Librep Manual})
+
+ defun jump-or-exec regex prog #!key match-class onfocused
+Jump to a window, or if it doesn't exist, start a program. Main use of
+this function is as a binding to keys. Defined in the
+module @code{sawfish.wm.commands.jump-or-exec}.
+
+Window is searched by matching the name with a regex @var{regex}, or
+if @var{match-class} is non-nil, by window's WM_CLASS. When no window
+matches, action specified by @var{prog} is taken.
+
+If @var{prog} is a string, then it should be a program name, and
+executed from a shell in the background. (I.e. Sawfish adds ''&''.)
+Otherwise, it should be one of a function, command name, or lisp
+expression. The function is called without any argument. The lisp
+expression will be evaluated in the @code{user} module.
+
+If the optional argument @var{onfocused} is non-nil, it defines the
+action when the window is already focused, in the same manner as
+ var{prog}, but the function will receive the focused windows as the
+argument. This can't be a string.
+
+ lisp
+;; Examples:
+
+;; Jump to a window named "Geany". When not found, invoke "geany" 
+;; from a shell.
+(bind-keys global-keymap "W-F10"
+  '(jump-or-exec "Geany" "geany"))
+
+;; Jump to a window with the class "Gnome-run-dialog".
+(bind-keys global-keymap "W-F2"
+  '(jump-or-exec "Gnome-run-dialog" "gnome-run-dialog" #:match-class t ))
+ end lisp
+
+ end defun
+
+ node Common Applications,, Application Invocation, External Applications
+ section Common Applications
 There're some functions and variables for invocation of external
 applications. They're defined in @code{sawfish.wm.commands.launcher}
 module.