diff options
Diffstat (limited to 'lisp/eshell')
| -rw-r--r-- | lisp/eshell/esh-opt.el | 55 | ||||
| -rw-r--r-- | lisp/eshell/esh-util.el | 3 |
2 files changed, 49 insertions, 9 deletions
diff --git a/lisp/eshell/esh-opt.el b/lisp/eshell/esh-opt.el index d7162406879..a9e8f11c39a 100644 --- a/lisp/eshell/esh-opt.el +++ b/lisp/eshell/esh-opt.el @@ -35,13 +35,51 @@ Eshell commands implemented in Lisp." ;;; User Functions: -(defmacro eshell-eval-using-options (name macro-args - options &rest body-forms) +(defmacro eshell-eval-using-options (name macro-args options &rest body-forms) "Process NAME's MACRO-ARGS using a set of command line OPTIONS. -After doing so, settings will be stored in local symbols as declared -by OPTIONS; FORMS will then be evaluated -- assuming all was OK. +After doing so, stores settings in local symbols as declared by OPTIONS; +then evaluates BODY-FORMS -- assuming all was OK. -The syntax of OPTIONS is: +OPTIONS is a list, beginning with one or more elements of the form: +\(SHORT LONG VALUE SYMBOL HELP-STRING) +Each of these elements represents a particular command-line switch. + +SHORT is either nil, or a character that can be used as a switch -SHORT. +LONG is either nil, or a string that can be used as a switch --LONG. +At least one of SHORT and LONG must be non-nil. +VALUE is the value associated with the option. It can be either: + t - the option needs a value to be specified after the switch; + nil - the option is given the value t; + anything else - specifies the actual value for the option. +SYMBOL is either nil, or the name of the Lisp symbol that will be bound +to VALUE. A nil SYMBOL calls `eshell-show-usage', and so is appropriate +for a \"--help\" type option. +HELP-STRING is a documentation string for the option. + +Any remaining elements of OPTIONS are :KEYWORD arguments. Some take +arguments, some do not. The recognized :KEYWORDS are: + +:external STRING + STRING is an external command to run if there are unknown switches. + +:usage STRING + STRING is the initial part of the command's documentation string. + It appears before the options are listed. + +:post-usage STRING + STRING is an optional trailing part of the command's documentation string. + It appears after the options, but before the final part of the + documentation about the associated external command (if there is one). + +:show-usage + If present, then show the usage message if the command is called with no + arguments. + +:preserve-args + If present, do not pass MACRO-ARGS through `eshell-flatten-list' +and `eshell-stringify-list'. + +For example, OPTIONS might look like: '((?C nil nil multi-column \"multi-column display\") (nil \"help\" nil nil \"show this usage display\") @@ -52,8 +90,9 @@ The syntax of OPTIONS is: Sort entries alphabetically across.\") `eshell-eval-using-options' returns the value of the last form in -BODY-FORMS. If instead an external command is run, the tag -`eshell-external' will be thrown with the new process for its value. +BODY-FORMS. If instead an external command is run (because of +an unknown option), the tag `eshell-external' will be thrown with +the new process for its value. Lastly, any remaining arguments will be available in a locally interned variable `args' (created using a `let' form)." @@ -200,7 +239,7 @@ switch is unrecognized." (defun eshell-process-args (name args options) "Process the given ARGS using OPTIONS. -This assumes that symbols have been intern'd by `eshell-with-options'." +This assumes that symbols have been intern'd by `eshell-eval-using-options'." (let ((ai 0) arg) (while (< ai (length args)) (setq arg (nth ai args)) diff --git a/lisp/eshell/esh-util.el b/lisp/eshell/esh-util.el index dbe4f824deb..424d246a2b6 100644 --- a/lisp/eshell/esh-util.el +++ b/lisp/eshell/esh-util.el @@ -138,7 +138,8 @@ function `string-to-number'." (memq system-type '(ms-dos windows-nt))) (defmacro eshell-condition-case (tag form &rest handlers) - "Like `condition-case', but only if `eshell-pass-through-errors' is nil." + "If `eshell-handle-errors' is non-nil, this is `condition-case'. +Otherwise, evaluates FORM with no error handling." (if eshell-handle-errors `(condition-case ,tag ,form |