[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[elpa] externals/setup 1925ed2 06/10: Mention defsetup macro in tips sec
From: |
Stefan Monnier |
Subject: |
[elpa] externals/setup 1925ed2 06/10: Mention defsetup macro in tips section |
Date: |
Wed, 12 May 2021 18:45:55 -0400 (EDT) |
branch: externals/setup
commit 1925ed20c5855bfdd642e5f38efbe0dcc03311de
Author: Philip K <philipk@posteo.net>
Commit: Philip K <philipk@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
----
- [elpa] externals/setup updated (86b968f -> f15c902), Stefan Monnier, 2021/05/12
- [elpa] externals/setup fe21e39 02/10: Mention GPL3 instead of CC0 as license in README, Stefan Monnier, 2021/05/12
- [elpa] externals/setup c144c5f 03/10: Mention that setup operating using local macros, Stefan Monnier, 2021/05/12
- [elpa] externals/setup 646ed6f 01/10: Check if PATH exists for :load-from, Stefan Monnier, 2021/05/12
- [elpa] externals/setup 36e2602 04/10: Remove :name mention in setup-define, Stefan Monnier, 2021/05/12
- [elpa] externals/setup 1925ed2 06/10: Mention defsetup macro in tips section,
Stefan Monnier <=
- [elpa] externals/setup f86d9f4 07/10: Add support for xref jump-to-definition for local macros, Stefan Monnier, 2021/05/12
- [elpa] externals/setup f15c902 10/10: Allow xref to find setup-defines outside of setup.el, Stefan Monnier, 2021/05/12
- [elpa] externals/setup ce1e0e3 08/10: Prevent overriding all elisp xref requests, Stefan Monnier, 2021/05/12
- [elpa] externals/setup 6da3894 09/10: Elaborate on comments, Stefan Monnier, 2021/05/12
- [elpa] externals/setup 4137cd0 05/10: Give an example of setup-based macros, Stefan Monnier, 2021/05/12