1 ;;; eshell.el --- the Emacs command shell
3 ;; Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004,
4 ;; 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
6 ;; Author: John Wiegley <johnw@gnu.org>
10 ;; This file is part of GNU Emacs.
12 ;; GNU Emacs is free software: you can redistribute it and/or modify
13 ;; it under the terms of the GNU General Public License as published by
14 ;; the Free Software Foundation, either version 3 of the License, or
15 ;; (at your option) any later version.
17 ;; GNU Emacs is distributed in the hope that it will be useful,
18 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
19 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20 ;; GNU General Public License for more details.
22 ;; You should have received a copy of the GNU General Public License
23 ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
27 ;;;_* What does Eshell offer you?
29 ;; Despite the sheer fact that running an Emacs shell can be fun, here
30 ;; are a few of the unique features offered by Eshell:
32 ;; @ Integration with the Emacs Lisp programming environment
34 ;; @ A high degree of configurability
36 ;; @ The ability to have the same shell on every system Emacs has been
37 ;; ported to. Since Eshell imposes no external requirements, and
38 ;; relies upon only the Lisp functions exposed by Emacs, it is quite
39 ;; operating system independent. Several of the common UNIX
40 ;; commands, such as ls, mv, rm, ln, etc., have been implemented in
41 ;; Lisp in order to provide a more consistent work environment.
43 ;; For those who might be using an older version of Eshell, version
44 ;; 2.1 represents an entirely new, module-based architecture. It
45 ;; supports most of the features offered by modern shells. Here is a
46 ;; brief list of some of its more visible features:
48 ;; @ Command argument completion (tcsh, zsh)
49 ;; @ Input history management (bash)
50 ;; @ Intelligent output scrolling
51 ;; @ Pseudo-devices (such as "/dev/clip" for copying to the clipboard)
52 ;; @ Extended globbing (zsh)
53 ;; @ Argument and globbing predication (zsh)
54 ;; @ I/O redirection to buffers, files, symbols, processes, etc.
55 ;; @ Many niceties otherwise seen only in 4DOS
56 ;; @ Alias functions, both Lisp and Eshell-syntax
57 ;; @ Piping, sequenced commands, background jobs, etc...
61 ;; To start using Eshell, simply type `M-x eshell'.
65 ;; A shell is a layer which metaphorically surrounds the kernel, or
66 ;; heart of an operating system. This kernel can be seen as an engine
67 ;; of pure functionality, waiting to serve, while the user programs
68 ;; take advantage of that functionality to accomplish their purpose.
70 ;; The shell's role is to make that functionality accessible to the
71 ;; user in an unformed state. Very roughly, it associates kernel
72 ;; functionality with textual commands, allowing the user to interact
73 ;; with the operating system via linguistic constructs. Process
74 ;; invocation is perhaps the most significant form this takes, using
75 ;; the kernel's `fork' and `exec' functions.
77 ;; Other programs also interact with the functionality of the kernel,
78 ;; but these user applications typically offer a specific range of
79 ;; functionality, and thus are not classed as "shells" proper.
80 ;; (What they lose in quiddity, they gain in rigidity).
82 ;; Emacs is also a user application, but it does make the
83 ;; functionality of the kernel accessible through an interpreted
84 ;; language -- namely, Lisp. For that reason, there is little
85 ;; preventing Emacs from serving the same role as a modern shell. It
86 ;; too can manipulate the kernel in an unpredetermined way to cause
87 ;; system changes. All it's missing is the shell-ish linguistic
90 ;; Enter Eshell. Eshell translates "shell-like" syntax into Lisp
91 ;; in order to exercise the kernel in the same manner as typical
92 ;; system shells. There is a fundamental difference here, however,
93 ;; although it may seem subtle at first...
95 ;; Shells like csh and Bourne shell were written several decades ago,
96 ;; in different times, under more restrictive circumstances. This
97 ;; confined perspective shows itself in the paradigm used by nearly
98 ;; all command-line shells since. They are linear in conception, byte
99 ;; stream-based, sequential, and confined to movement within a single
102 ;; Emacs, on the other hand, is more than just a limited translator
103 ;; that can invoke subprocesses and redirect file handles. It also
104 ;; manages character buffers, windowing frames, network connections,
105 ;; registers, bookmarks, processes, etc. In other words, it's a very
106 ;; multi-dimensional environment, within which eshell emulates a highly
107 ;; linear methodology.
109 ;; Taking a moment, let's look at how this could affect the future of
110 ;; a shell allowed to develop in such a wider field of play:
112 ;; @ There is no reason why directory movement should be linear, and
113 ;; confined to a single file-system. Emacs, through w3 and ange-ftp,
114 ;; has access to the entire Web. Why not allow a user to cd to
115 ;; multiple directories simultaneously, for example? It might make
116 ;; some tasks easier, such as diff'ing files separated by very long
119 ;; @ Data sources are available from anywhere Emacs can derive
120 ;; information from: not just from files or the output of other
123 ;; @ Multiple shell invocations all share the same environment -- even
124 ;; the same process list! It would be possible to have "process
125 ;; views", so that one buffer is watching standard output, another
126 ;; standard error, and another the result of standard output grep'd
127 ;; through a regular expression...
129 ;; @ It is not necessary to "leave" the shell, losing all input and
130 ;; output history, environment variables, directory stack, etc.
131 ;; Emacs could save the contents of your eshell environment, and
132 ;; restore all of it (or at least as much as possible) each time you
133 ;; restart. This could occur automatically, without requiring
134 ;; complex initialization scripts.
136 ;; @ Typos occur all of the time; many of them are repeats of common
137 ;; errors, such as 'dri' for `dir'. Since executing non-existent
138 ;; programs is rarely the intention of the user, eshell could prompt
139 ;; for the replacement string, and then record that in a database of
140 ;; known misspellings. (Note: The typo at the beginning of this
141 ;; paragraph wasn't discovered until two months after I wrote the
142 ;; text; it was not intentional).
144 ;; @ Emacs' register and bookmarking facilities can be used for
145 ;; remembering where you've been, and what you've seen -- to varying
146 ;; levels of persistence. They could perhaps even be tied to
147 ;; specific "moments" during eshell execution, which would include
148 ;; the environment at that time, as well as other variables.
149 ;; Although this would require functionality orthogonal to Emacs'
150 ;; own bookmarking facilities, the interface used could be made to
151 ;; operate very similarly.
153 ;; This presents a brief idea of what the fuller dimensionality of an
154 ;; Emacs shell could offer. It's not just the language of a shell
155 ;; that determines how it's used, but also the Weltanschauung
156 ;; underlying its design -- and which is felt behind even the smallest
157 ;; feature. I would hope the freedom provided by using Emacs as a
158 ;; parent environment will invite rich ideas from others. It
159 ;; certainly feels as though all I've done so far is to tie down the
160 ;; horse, so to speak, so that he will run at a man's pace.
164 ;; The author of Eshell has been a long-time user of the following
165 ;; shells, all of which contributed to Eshell's design:
174 ;;;_* Speeding up load time
176 ;; If you find that Eshell loads too slowly, there is something you
177 ;; can do to speed it up.
179 ;; Create a file, named /tmp/elc, containing this filelist:
209 ;; The order is very important. Remove from the filelist any features
210 ;; you don't use. These all begin with "em-". If you don't use
211 ;; Eshell's key rebinding module, you can remove "em-rebind.elc" from
212 ;; the filelist. The modules you are currently using are listed in
213 ;; `eshell-modules-list'.
215 ;; Now, concatenating all of the above mentioned .elc files, in that
216 ;; order, to another file. Here is how to do this on UNIX:
218 ;; cat `cat /tmp/elc` > tmp.elc ; mv tmp.elc eshell.elc
220 ;; Now your eshell.elc file contains all of the .elc files that make
221 ;; up Eshell, in the right load order. When you next load Eshell, it
222 ;; will only have to read in this one file, which will greatly speed
232 "Eshell is a command shell implemented entirely in Emacs Lisp. It
233 invokes no external processes beyond those requested by the user. It
234 is intended to be a functional replacement for command shells such as
235 bash, zsh, rc, 4dos; since Emacs itself is capable of handling most of
236 the tasks accomplished by such tools."
237 :tag
"The Emacs shell"
238 :link
'(info-link "(eshell)Top")
240 :group
'applications
)
242 ;; This is hack to force make-autoload to put the whole definition
243 ;; into the autoload file (see esh-module.el).
244 (defalias 'eshell-defgroup
'defgroup
)
248 ;; The following user options modify the behavior of Eshell overall.
249 (defvar eshell-buffer-name
)
251 (defsubst eshell-add-to-window-buffer-names
()
252 "Add `eshell-buffer-name' to `same-window-buffer-names'."
253 (add-to-list 'same-window-buffer-names eshell-buffer-name
))
255 (defsubst eshell-remove-from-window-buffer-names
()
256 "Remove `eshell-buffer-name' from `same-window-buffer-names'."
257 (setq same-window-buffer-names
258 (delete eshell-buffer-name same-window-buffer-names
)))
260 (defcustom eshell-load-hook nil
261 "A hook run once Eshell has been loaded."
265 (defcustom eshell-unload-hook
266 '(eshell-remove-from-window-buffer-names
267 eshell-unload-all-modules
)
268 "A hook run when Eshell is unloaded from memory."
272 (defcustom eshell-buffer-name
"*eshell*"
273 "The basename used for Eshell buffers."
274 :set
(lambda (symbol value
)
275 ;; remove the old value of `eshell-buffer-name', if present
276 (if (boundp 'eshell-buffer-name
)
277 (eshell-remove-from-window-buffer-names))
280 (eshell-add-to-window-buffer-names)
285 (eshell-deftest mode same-window-buffer-names
286 "`eshell-buffer-name' is a member of `same-window-buffer-names'"
287 (member eshell-buffer-name same-window-buffer-names
))
289 (defcustom eshell-directory-name
(convert-standard-filename "~/.eshell/")
290 "The directory where Eshell control files should be kept."
294 (eshell-deftest mode eshell-directory-exists
295 "`eshell-directory-name' exists and is writable"
296 (file-writable-p eshell-directory-name
))
298 (eshell-deftest mode eshell-directory-modes
299 "`eshell-directory-name' has correct access protections"
300 (or (eshell-under-windows-p)
301 (= (file-modes eshell-directory-name
)
302 eshell-private-directory-modes
)))
306 ;; There are only three commands used to invoke Eshell. The first two
307 ;; are intended for interactive use, while the third is meant for
308 ;; programmers. They are:
311 (defun eshell (&optional arg
)
312 "Create an interactive Eshell buffer.
313 The buffer used for Eshell sessions is determined by the value of
314 `eshell-buffer-name'. If there is already an Eshell session active in
315 that buffer, Emacs will simply switch to it. Otherwise, a new session
316 will begin. A numeric prefix arg (as in `C-u 42 M-x eshell RET')
317 switches to the session with that number, creating it if necessary. A
318 nonnumeric prefix arg means to create a new session. Returns the
319 buffer selected (or created)."
321 (assert eshell-buffer-name
)
322 (let ((buf (cond ((numberp arg
)
323 (get-buffer-create (format "%s<%d>"
327 (generate-new-buffer eshell-buffer-name
))
329 (get-buffer-create eshell-buffer-name
)))))
330 ;; Simply calling `pop-to-buffer' will not mimic the way that
331 ;; shell-mode buffers appear, since they always reuse the same
332 ;; window that that command was invoked from. To achieve this,
333 ;; it's necessary to add `eshell-buffer-name' to the variable
334 ;; `same-window-buffer-names', which is done when Eshell is loaded
335 (assert (and buf
(buffer-live-p buf
)))
337 (unless (eq major-mode
'eshell-mode
)
341 (defun eshell-return-exits-minibuffer ()
342 (define-key eshell-mode-map
[(control ?g
)] 'abort-recursive-edit
)
343 (define-key eshell-mode-map
[return] 'exit-minibuffer)
344 (define-key eshell-mode-map [(control ?m)] 'exit-minibuffer)
345 (define-key eshell-mode-map [(control ?j)] 'exit-minibuffer)
346 (define-key eshell-mode-map [(meta return)] 'exit-minibuffer)
347 (define-key eshell-mode-map [(meta control ?m)] 'exit-minibuffer))
349 (defvar eshell-non-interactive-p nil
350 "A variable which is non-nil when Eshell is not running interactively.
351 Modules should use this variable so that they don't clutter
352 non-interactive sessions, such as when using `eshell-command'.")
355 (defun eshell-command (&optional command arg)
356 "Execute the Eshell command string COMMAND.
357 With prefix ARG, insert output into the current buffer at point."
361 (setq arg current-prefix-arg))
363 (let ((eshell-non-interactive-p t))
364 (add-hook 'minibuffer-setup-hook 'eshell-mode)
365 (add-hook 'minibuffer-exit-hook 'eshell-add-command-to-history)
366 (add-hook 'eshell-mode-hook 'eshell-return-exits-minibuffer)
368 (setq command (read-from-minibuffer "Emacs shell command: "))))
369 (remove-hook 'eshell-mode-hook 'eshell-return-exits-minibuffer)
370 (remove-hook 'minibuffer-exit-hook 'eshell-add-command-to-history)
371 (remove-hook 'minibuffer-setup-hook 'eshell-mode))
373 (error "No command specified!"))
374 ;; redirection into the current buffer is achieved by adding an
375 ;; output redirection to the end of the command, of the form
376 ;; 'COMMAND >>> #<buffer BUFFER>'. This will not interfere with
377 ;; other redirections, since multiple redirections merely cause the
378 ;; output to be copied to multiple target locations
382 (format " >>> #<buffer %s>"
383 (buffer-name (current-buffer))))))
385 (let ((buf (set-buffer (generate-new-buffer " *eshell cmd*")))
386 (eshell-non-interactive-p t))
388 (let* ((proc (eshell-eval-command
389 (list 'eshell-commands
390 (eshell-parse-command command))))
392 (bufname (if (and proc (listp proc))
393 "*EShell Async Command Output*"
395 "*EShell Command Output*")))
396 (if (buffer-live-p (get-buffer bufname))
397 (kill-buffer bufname))
398 (rename-buffer bufname)
399 ;; things get a little coarse here, since the desire is to
400 ;; make the output as attractive as possible, with no
401 ;; extraneous newlines
403 (if (eshell-interactive-process)
404 (eshell-wait-for-process (eshell-interactive-process)))
405 (assert (not (eshell-interactive-process)))
406 (goto-char (point-max))
407 (while (and (bolp) (not (bobp)))
408 (delete-backward-char 1)))
409 (assert (and buf (buffer-live-p buf)))
411 (let ((len (if (not intr) 2
412 (count-lines (point-min) (point-max)))))
415 (message "(There was no command output)")
418 (message "%s" (buffer-string))
421 (save-selected-window
422 (select-window (display-buffer buf))
423 (goto-char (point-min))
424 ;; cause the output buffer to take up as little screen
425 ;; real-estate as possible, if temp buffer resizing is
427 (and intr temp-buffer-resize-mode
428 (resize-temp-buffer-window)))))))))))
431 (defun eshell-command-result (command &optional status-var)
432 "Execute the given Eshell COMMAND, and return the result.
433 The result might be any Lisp object.
434 If STATUS-VAR is a symbol, it will be set to the exit status of the
435 command. This is the only way to determine whether the value returned
436 corresponding to a successful execution."
437 ;; a null command produces a null, successful result
440 (if (and status-var (symbolp status-var))
443 (let ((eshell-non-interactive-p t))
445 (let ((result (eshell-do-eval
446 (list 'eshell-commands
447 (list 'eshell-command-to-value
448 (eshell-parse-command command))) t)))
449 (assert (eq (car result) 'quote))
450 (if (and status-var (symbolp status-var))
451 (set status-var eshell-last-command-status))
454 (eshell-deftest mode simple-command-result
455 "`eshell-command-result' works with a simple command."
456 (= (eshell-command-result "+ 1 2") 3))
460 ;; If you do encounter a bug, on any system, please report
461 ;; it -- in addition to any particular oddities in your configuration
462 ;; -- so that the problem may be corrected for the benefit of others.
465 (define-obsolete-function-alias 'eshell-report-bug 'report-emacs-bug "23.1")
469 (defun eshell-unload-all-modules ()
470 "Unload all modules that were loaded by Eshell, if possible.
471 If the user has require'd in any of the modules, or customized a
472 variable with a :require tag (such as `eshell-prefer-to-shell'), it
473 will be impossible to unload Eshell completely without restarting
475 ;; if the user set `eshell-prefer-to-shell' to t, but never loaded
476 ;; Eshell, then `eshell-subgroups' will be unbound
477 (when (fboundp 'eshell-subgroups)
478 (eshell-for module (eshell-subgroups 'eshell)
479 ;; this really only unloads as many modules as possible,
480 ;; since other `require' references (such as by customizing
481 ;; `eshell-prefer-to-shell' to a non-nil value) might make it
482 ;; impossible to unload Eshell completely
483 (if (featurep module)
485 (message "Unloading %s..." (symbol-name module))
486 (unload-feature module)
487 (message "Unloading %s...done" (symbol-name module)))))
488 (message "Unloading eshell...done")))
490 (run-hooks 'eshell-load-hook)
494 ;; arch-tag: 9d4d5214-0e4e-4e02-b349-39add640d63f
495 ;;; eshell.el ends here