branch: externals/setup
commit 1925ed20c5855bfdd642e5f38efbe0dcc03311de
Author: Philip K <phil...@posteo.net>
Commit: Philip K <phil...@posteo.net>
Mention defsetup macro in tips section
---
README.md | 62 +++++++++++++++++++++++++++++++++++++++++++++++++-------------
1 file changed, 49 insertions(+), 13 deletions(-)
diff --git a/README.md b/README.md
index 93ae38d..8d1aa63 100644
--- a/README.md
+++ b/README.md
@@ -63,20 +63,56 @@ The `setup` macro is autoloaded, and can be used directly.
The code
generated by `setup` does not depend on `setup.el`, meaning that your
initialization file can be byte-compiled more efficiently.
-Tip
----
-
-The first element of a `setup` body can but does not have to be a
-name. That can be exploited to use `setup` in your own macros. I have
-this macro in my personal configuration, when I'm only interested in
-modifying user options:
+Tips
+----
-~~~elisp
-(defmacro setc (&rest args)
- "Customize user options using ARGS like `setq'."
- (declare (debug setq))
- `(setup (:option ,@args)))
-~~~
+1. The first element of a `setup` body can but does not have to be a
+ name. That can be exploited to use `setup` in your own macros. I have
+ this macro in my personal configuration, when I'm only interested in
+ modifying user options:
+
+ ~~~elisp
+ (defmacro setc (&rest args)
+ "Customize user options using ARGS like `setq'."
+ (declare (debug setq))
+ `(setup (:option ,@args)))
+ ~~~
+
+2. If you wish to define you own macros, use `setup-define`. In case the
+ syntax is too cumbersome, you can use a macro like this:
+
+ ~~~elisp
+ (defmacro defsetup (name signature &rest body)
+ "Shorthand for `setup-define'.
+ NAME is the name of the local macro. SIGNATURE is used as the
+ argument list for FN. If BODY starts with a string, use this as
+ the value for :documentation. Any following keywords are passed
+ as OPTS to `setup-define'."
+ (declare (debug defun))
+ (let (opts)
+ (when (stringp (car body))
+ (setq opts (nconc (list :documentation (pop body))
+ opts)))
+ (while (keywordp (car body))
+ (let* ((prop (pop body))
+ (val `',(pop body)))
+ (setq opts (nconc (list prop val) opts))))
+ `(setup-define ,name
+ (cl-function (lambda ,signature ,@body))
+ ,@opts)))
+ ~~~
+
+ To declare local macros more like `defun` or `defmacro`. Here is how
+ the definition for `:package` could be rewritten:
+
+ ~~~elisp
+ (defsetup :package (package)
+ "Install PACKAGE if it hasn't been installed yet."
+ :repeatable t
+ :shorthand #'cadr
+ `(unless (package-installed-p ',package)
+ (package-install ',package)))
+ ~~~
Bugs
----
