branch: elpa/pcmpl-args
commit 2ba03b3125ada8037585e545b88bd85b79da5c37
Author: Jonathan Waltman <jonathan.walt...@gmail.com>
Commit: Jonathan Waltman <jonathan.walt...@gmail.com>
Add README and more documentation
---
Makefile | 10 ++++
README | 92 +++++++++++++++++++++++++++++
pcmpl-args.el | 185 +++++++++++++++++++++++++++++++++++++++++-----------------
3 files changed, 232 insertions(+), 55 deletions(-)
diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000000..bc6fc0c836
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,10 @@
+
+.PHONY: clean
+
+README::
+ emacs --batch pcmpl-args.el -l pcmpl-args.el \
+ -f pcmpl-args--print-readme > README
+
+clean:
+ -rm README
+ -rm *.elc
diff --git a/README b/README
new file mode 100644
index 0000000000..113ea07422
--- /dev/null
+++ b/README
@@ -0,0 +1,92 @@
+pcmpl-args.el --- Enhanced shell command completion
+===================================================
+
+This package extends option and argument completion of shell
+commands read by Emacs. It is intended to make shell completion in
+Emacs comparable to the rather excellent completion provided by
+both Bash and Zsh.
+
+This package uses `pcomplete' to define completion handlers which
+are used whenever shell completion is performed. This includes
+when commands are read in the minibuffer via `shell-command' (M-!)
+or in `shell-mode'.
+
+Completion support is provided for many different commands
+including:
+
+ - GNU core utilities (ls, rm, mv, date, sort, cut, printf, ...)
+
+ - Built-in shell commands (if, test, time, ...)
+
+ - Various GNU/Linux commands (find, xargs, grep, man, tar, ...)
+
+ - Version control systems (bzr, git, hg, ...)
+
+
+Installation:
+
+To use this package, save `pcmpl-args.el' to your `load-path' and
+add the following to your `init.el':
+
+ (require 'pcmpl-args)
+
+Note: This package uses `lexical-binding' so it probably will not
+work with older versions of Emacs (prior to 24.1).
+
+Note: This package redefines the following functions:
+
+ `pcomplete/bzip2'
+ `pcomplete/chgrp'
+ `pcomplete/chown'
+ `pcomplete/gdb'
+ `pcomplete/gzip'
+ `pcomplete/make'
+ `pcomplete/rm'
+ `pcomplete/rmdir'
+ `pcomplete/tar'
+ `pcomplete/time'
+ `pcomplete/which'
+ `pcomplete/xargs'
+
+
+Defining new completion commands:
+
+This package contains a number of utilities for defining new
+pcomplete completion commands:
+
+`pcmpl-args-pcomplete'
+ Can be used to define completion for commands that have
+ complex option and argument parsing.
+
+`pcmpl-args-pcomplete-on-help'
+ Completion via parsing the output of `COMMAND --help'.
+
+`pcmpl-args-pcomplete-on-man'
+ Completion via parsing the output of `man COMMAND'.
+
+
+------------------------------------------------------------------------
+
+This file is not part of GNU Emacs.
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program. If not, see <http://www.gnu.org/licenses/>.
+
+------------------------------------------------------------------------
+
+Author: Jonathan Waltman <jonathan.walt...@gmail.com>
+URL: https://github.com/JonWaltman/pcmpl-args.el
+Keywords: abbrev completion convenience processes terminals unix
+Created: 25 Jul 2012
+Version: 0.1.1
+Compatibility: GNU Emacs: 24.x
diff --git a/pcmpl-args.el b/pcmpl-args.el
index 95a28b5db3..9ce3db659c 100644
--- a/pcmpl-args.el
+++ b/pcmpl-args.el
@@ -5,56 +5,90 @@
;; Author: Jonathan Waltman <jonathan.walt...@gmail.com>
;; URL: https://github.com/JonWaltman/pcmpl-args.el
;; Keywords: abbrev completion convenience processes terminals unix
-;; Version: 0.1
+;; Created: 25 Jul 2012
+;; Version: 0.1.1
+;; Compatibility: GNU Emacs: 24.x
;; This file is not part of GNU Emacs.
-
+;;
;; This program is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation, either version 3 of the License, or
;; (at your option) any later version.
-
+;;
;; This program is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
;; GNU General Public License for more details.
-
+;;
;; You should have received a copy of the GNU General Public License
;; along with this program. If not, see <http://www.gnu.org/licenses/>.
;;; Commentary:
;;
-;; This package provides option and argument completion for shell
-;; commands. It intends to make shell completion in Emacs comparable
-;; to the rather excellent completion provided by both Bash and Zsh.
+;; This package extends option and argument completion of shell
+;; commands read by Emacs. It is intended to make shell completion in
+;; Emacs comparable to the rather excellent completion provided by
+;; both Bash and Zsh.
+;;
+;; This package uses `pcomplete' to define completion handlers which
+;; are used whenever shell completion is performed. This includes
+;; when commands are read in the minibuffer via `shell-command' (M-!)
+;; or in `shell-mode'.
+;;
+;; Completion support is provided for many different commands
+;; including:
+;;
+;; - GNU core utilities (ls, rm, mv, date, sort, cut, printf, ...)
+;;
+;; - Built-in shell commands (if, test, time, ...)
+;;
+;; - Various GNU/Linux commands (find, xargs, grep, man, tar, ...)
+;;
+;; - Version control systems (bzr, git, hg, ...)
;;
-;; It uses `pcomplete' to define completion handlers which are used
-;; whenever shell command completion is performed. This includes when
-;; commands are read in the minibuffer via `shell-command' (M-!) or in
-;; `shell-mode'.
+
+;; Installation:
;;
-;; To use this package, save `pcmpl-args.el' to your `load-path' and add
-;; the following to your `init.el':
+;; To use this package, save `pcmpl-args.el' to your `load-path' and
+;; add the following to your `init.el':
;;
;; (require 'pcmpl-args)
;;
;; Note: This package uses `lexical-binding' so it probably will not
;; work with older versions of Emacs (prior to 24.1).
;;
-;; The following existing pcomplete functions will be redefined:
+;; Note: This package redefines the following functions:
+;;
+;; `pcomplete/bzip2'
+;; `pcomplete/chgrp'
+;; `pcomplete/chown'
+;; `pcomplete/gdb'
+;; `pcomplete/gzip'
+;; `pcomplete/make'
+;; `pcomplete/rm'
+;; `pcomplete/rmdir'
+;; `pcomplete/tar'
+;; `pcomplete/time'
+;; `pcomplete/which'
+;; `pcomplete/xargs'
+;;
+
+;; Defining new completion commands:
+;;
+;; This package contains a number of utilities for defining new
+;; pcomplete completion commands:
+;;
+;; `pcmpl-args-pcomplete'
+;; Can be used to define completion for commands that have
+;; complex option and argument parsing.
+;;
+;; `pcmpl-args-pcomplete-on-help'
+;; Completion via parsing the output of `COMMAND --help'.
+;;
+;; `pcmpl-args-pcomplete-on-man'
+;; Completion via parsing the output of `man COMMAND'.
;;
-;; `pcomplete/bzip2'
-;; `pcomplete/chgrp'
-;; `pcomplete/chown'
-;; `pcomplete/gdb'
-;; `pcomplete/gzip'
-;; `pcomplete/make'
-;; `pcomplete/rm'
-;; `pcomplete/rmdir'
-;; `pcomplete/tar'
-;; `pcomplete/time'
-;; `pcomplete/which'
-;; `pcomplete/xargs'
;;; Code:
@@ -233,8 +267,8 @@ SPECS should be a list of the form:
TYPE is a symbol and should be either `argument' or `option'.
If the TYPE is `argument' then NAME is either an integer
-specifying the nth positional argument or the symbol
-`*' which specifies any number of arguments.
+specifying the nth positional argument or the symbol `*' which
+specifies any number of arguments.
If the TYPE is `option' then NAME is a string or a list of
strings specifying the name, style, and possibly the
@@ -247,22 +281,23 @@ sub-arguments of the option. The following forms are
supported:
\"--option<ARG>\" - Option with one required argument.
\"--option=ARG\" - Option with one argument that is either
seperate or inline delimited by \"=\".
- \"--option[=ARG]\" - Option with one optional argument that is either
- seperate or inline delimited by \"=\".
+ \"--option[=ARG]\" - Option with one optional argument that
+ is either seperate or inline delimited
+ by \"=\".
These forms work for both long-named options (those beginning
with \"--\") and single-letter options.
-Multiple options can be specified in the same NAME by
-delimiting them with commas. For example:
+Multiple options can be specified in the same NAME by delimiting
+them with commas. For example:
- \"-o, --option\" - Two options that both have no arguments.
- \"-o, --option ARG\" - Two options that both have one argument.
- same as \"-o ARG, -option ARG\"
- \"-o, --option[=ARG]\" - Two options with one optional argument;
- same as \"-o[ARG], -option[=ARG]\"
- \"-o, --option=ARG\" - Two options with one argument;
- same as \"-o ARG, -option=ARG\"
+ \"-o, --option\" - Two options that both have no arguments.
+ \"-o, --option ARG\" - Two options that both have one argument.
+ same as \"-o ARG, -option ARG\"
+ \"-o, --option[=ARG]\" - Two options with one optional argument;
+ same as \"-o[ARG], -option[=ARG]\"
+ \"-o, --option=ARG\" - Two options with one argument;
+ same as \"-o ARG, -option=ARG\"
A description can also be specified in NAME by delimiting it with
multiple spaces or a tab character. For example:
@@ -286,32 +321,32 @@ the form:
will contain the string being completed.
`(:lambda FUNCTION)'
- FUNCTION is called when completion is performed and it should
- return a completion-table. The function is called with one
- argument, an alist of the options and arguments.
+ FUNCTION is called when completion is performed and it
+ should return a completion-table. The function is called
+ with one argument, an alist of the options and arguments.
`t'
- The symbol `t' means to use the completion-table
- returned by `pcmpl-args-guess-completions'.
+ The symbol `t' means to use the completion-table returned
+ by `pcmpl-args-guess-completions'.
`none'
The symbol `none' means that no completions can be
- generated and prevents the fallback behaviour of
- completing file names.
+ generated and prevents the fallback behaviour of completing
+ file names.
SUFFIX is optional and it specifies a string to insert after
completion is performed.
-PROPERTIES are optional and consists of keywords followed by
-a value. The following are recognized:
+PROPERTIES are optional and consists of keywords followed by a
+value. The following are recognized:
:help
String describing the option.
:excludes
List of option and argument names that will not be completed
- after this point. Also, the symbol `-' excludes options and `:'
- excludes positional arguments.
+ after this point. Also, the symbol `-' excludes options and
+ `:' excludes positional arguments.
:repeat
Non-nil value specifies that this option or argument can occur
@@ -324,7 +359,8 @@ a value. The following are recognized:
`seperate-or-inline' - arguments can be inline or not
:delim
- String specifying the delimiter used for options with inline arguments.
+ String specifying the delimiter used for options with inline
+ arguments.
:suffix
String to insert after completion is performed.
@@ -1587,12 +1623,14 @@ Function is called with one argument, the word to
complete.")
;;; Pcomplete completion functions
(defun pcmpl-args-pcomplete (argspecs)
- "Parse and complete `pcomplete-args' according to ARGSPECS.
+ "Complete the current pcomplete arguments according to ARGSPECS.
Does not return. Throws the tag `pcomplete-completions' with the
value of the completion-table found by calling
-`pcmpl-args-parse-arguments' with the current pcomplete arguments.
+`pcmpl-args-parse-arguments' with the current value of
+`pcomplete-args' and ARGSPECS.
-ARGSPECS should be value a created with `pcmpl-args-make-argspecs'."
+ARGSPECS should be value a created with
+`pcmpl-args-make-argspecs'."
(noreturn
(progn
(pcmpl-args-debug "\n \n================================")
@@ -1653,7 +1691,7 @@ ARGSPECS should be value a created with
`pcmpl-args-make-argspecs'."
(table table))))))))
(defun pcmpl-args-pcomplete-on-help ()
- "Perform pcomplete completion on the help output of the current command.
+ "Perform completion on the help output of the current command.
The current command is called with one option `--help' and its
output is processed via `pcmpl-args-parse-help-buffer'.
@@ -3515,6 +3553,43 @@ will print completions for `ls -'."
(pcmpl-args-cache-flush t)
nil)))
+(defun pcmpl-args--print-readme ()
+ "Print the commentary in a form suitable for a README file."
+ (save-excursion
+ (let (header meta copyright commentary)
+ (goto-char (point-min))
+ (setq header
+ (buffer-substring
+ (progn (re-search-forward ";+ ")
+ (point))
+ (progn (re-search-forward " +-\\*-")
+ (match-beginning 0))))
+ (forward-line 3)
+ (setq meta
+ (buffer-substring (point)
+ (progn (forward-paragraph)
+ (point)))
+ copyright
+ (buffer-substring (point)
+ (progn (re-search-forward "^;+ Commentary:")
+ (forward-line -1)
+ (point))))
+ (forward-line 3)
+ (setq commentary
+ (buffer-substring (point)
+ (progn (re-search-forward "^;+ Code:")
+ (forward-line -1)
+ (point))))
+ (princ (replace-regexp-in-string
+ "^;;;?\\( \\| *$\\)" ""
+ (concat header "\n"
+ (make-string (length header) ?=) "\n\n"
+ commentary "\n"
+ (make-string 72 ?-) "\n"
+ copyright "\n"
+ (make-string 72 ?-) "\n"
+ meta))))))
+
;; (ert-deftest pcmpl-args-test-make-argspecs ()
;; (let ((opts
;; '((("-o") ((option "-o")))
