Emacs Lisp: w32-shell-execute Example and Inline Documentation Bug

Perm url with updates: http://xahlee.org/emacs/w32-shell-execute.html

Emacs Lisp: w32-shell-execute Example and Inline Documentation Bug

Xah Lee, 2011-05-05

In emacs GNU Emacs 23.2.1, built for Windows, there's a documentation bug for the emacs lisp function “w32-shell-execute”. When you call “describe-function” on “w32-shell-execute”, you get this:

w32-shell-execute is a built-in function in `C source code'.

[Missing arglist.  Please make a bug report.]

Not documented.

This is fixed in emacs 23.3, the inline doc for “w32-shell-execute” is the followning:

w32-shell-execute is a built-in function in `C source code'. 

(w32-shell-execute OPERATION DOCUMENT &optional PARAMETERS SHOW-FLAG) 

Get Windows to perform OPERATION on DOCUMENT. 
This is a wrapper around the ShellExecute system function, which 
invokes the application registered to handle OPERATION for DOCUMENT. 

OPERATION is either nil or a string that names a supported operation. 
What operations can be used depends on the particular DOCUMENT and its 
handler application, but typically it is one of the following common 
operations: 

 "open"    - open DOCUMENT, which could be a file, a directory, or an 
               executable program.  If it is an application, that 
               application is launched in the current buffer's default 
               directory.  Otherwise, the application associated with 
               DOCUMENT is launched in the buffer's default directory. 

 "print"   - print DOCUMENT, which must be a file 

 "explore" - start the Windows Explorer on DOCUMENT 

 "edit"    - launch an editor and open DOCUMENT for editing; which 
               editor is launched depends on the association for the 
               specified DOCUMENT 

 "find"    - initiate search starting from DOCUMENT which must specify 
               a directory 

 nil       - invoke the default OPERATION, or "open" if default is 
               not defined or unavailable 

DOCUMENT is typically the name of a document file or a URL, but can 
also be a program executable to run, or a directory to open in the 
Windows Explorer. 

If DOCUMENT is a program executable, the optional third arg PARAMETERS 
can be a string containing command line parameters that will be passed 
to the program; otherwise, PARAMETERS should be nil or unspecified. 

Optional fourth argument SHOW-FLAG can be used to control how the 
application will be displayed when it is invoked.  If SHOW-FLAG is nil 
or unspecified, the application is displayed normally, otherwise it is 
an integer representing a ShowWindow flag: 

  0 - start hidden 
  1 - start normally 
  3 - start maximized 
  6 - start minimized 

(Thanks to Jason Rumney for telling me about this fix, and for his donations and support.)

Examples of Using “w32-shell-execute”

Here's some other useful examples of command that makes a shell call.

(defun open-in-desktop ()
  "Open the current file in desktop.
Works in Microsoft Windows, Mac OS X, Linux."
  (interactive)
  (cond
   ((string-equal system-type "windows-nt")
    (w32-shell-execute "explore" (replace-regexp-in-string "/" "\\" default-directory t t)))
   ((string-equal system-type "darwin") (shell-command "open ."))
   ((string-equal system-type "gnu/linux") (shell-command "xdg-open ."))
   ) )

For another example of using “w32-shell-execute”, see: Emacs Lisp: browse-url Function to View URL in a Web Browser.

Here's a example of similar purpose to “w32-shell-execute” but using “shell-command” for Mac OS X.

(defun open-with-textwrangler ()
  "Open the current file in Mac's TextWrangler."
  (interactive)
      (if (eq major-mode 'dired-mode)
          (shell-command "open .")
        (shell-command
         (concat "open -a /Applications/TextWrangler.app " "\"" (buffer-file-name) "\""))))

Popular posts from this blog

11 Years of Writing About Emacs

does md5 creates more randomness?

Google Code shutting down, future of ErgoEmacs