diff options
Diffstat (limited to 'llama.el')
| -rw-r--r-- | llama.el | 111 |
1 files changed, 55 insertions, 56 deletions
@@ -25,29 +25,31 @@ ;;; Commentary: -;; This package implements the macro `##', which provides compact -;; syntax for short `lambda', without actually being new syntax, -;; which would be difficult to get merged into Emacs. Past attempts -;; to add syntax were met with determined pushback and the use of a -;; macro was suggested as an alternative. - -;; The `##' macro, whose signature is (## FN &rest BODY), expands -;; to a `lambda' expression, which wraps around these arguments. - -;; This `lambda' expression calls the function FN with arguments -;; BODY and returns its value. Its own arguments are derived from -;; symbols found in ARGS. - -;; Each symbol from `%1' through `%9', which appears in BODY, -;; specifies a mandatory argument. Each symbol from `&1' through -;; `&9', which appears in BODY, specifies an optional argument. -;; All arguments following an optional argument have to be optional -;; as well, thus their names have to begin with `&'. Symbol `&*' -;; specifies extra (`&rest') arguments. - -;; The shorter symbol `%' can be used instead of `%1', but using both -;; in the same expression is not allowed. Likewise `&' can be used -;; instead of `&1'. +;; This package implements a macro named `##', which provides a compact way +;; to write short `lambda' expressions. + +;; The signature of the macro is (## FN &rest BODY) and it expands to a +;; `lambda' expression, which calls the function FN with the arguments BODY +;; and returns the value of that. The arguments of the `lambda' expression +;; are derived from symbols found in BODY. + +;; Each symbol from `%1' through `%9', which appears in an unquoted part +;; of BODY, specifies a mandatory argument. Each symbol from `&1' through +;; `&9', which appears in an unquoted part of BODY, specifies an optional +;; argument. The symbol `&*' specifies extra (`&rest') arguments. + +;; The shorter symbol `%' can be used instead of `%1', but using both in +;; the same expression is not allowed. Likewise `&' can be used instead +;; of `&1'. These shorthands are not recognized in function position. + +;; To support binding forms that use a vector as VARLIST (such as `-let' +;; from the `dash' package), argument symbols are also detected inside of +;; vectors. + +;; The space between `##' and FN can be omitted because `##' is read-syntax +;; for the symbol whose name is the empty string. If you prefer you can +;; place a space there anyway, and if you prefer to not use this somewhat +;; magical symbol at all, you can instead use the alternative name `llama'. ;; Instead of: ;; @@ -63,8 +65,8 @@ ;; (lambda (%1 &optional _&2 &3 &rest &*) ;; (foo %1 (bar &3) &*)) -;; Unused trailing arguments and mandatory unused arguments at the -;; border between mandatory and optional arguments are also supported: +;; Unused trailing arguments and mandatory unused arguments at the border +;; between mandatory and optional arguments are also supported: ;; ;; (##list %1 _%3 &5 _&6) ;; @@ -73,13 +75,9 @@ ;; (lambda (%1 _%2 _%3 &optional _&4 &5 _&6) ;; (list %1 &5)) ;; -;; Note how `_%3' and `_&6' are removed from the body, because their -;; names begin with an underscore. Also note that `_&4' is optional, -;; unlike the explicitly specified `_%3'. - -;; The name `##' was chosen because that allows (optionally) -;; omitting the whitespace between it and the following symbol. -;; It also looks similar to #'function. +;; Note how `_%3' and `_&6' are removed from the body, because their names +;; begin with an underscore. Also note that `_&4' is optional, unlike the +;; explicitly specified `_%3'. ;;; Code: @@ -87,20 +85,28 @@ (defmacro llama (fn &rest body) "Expand to a `lambda' expression that wraps around FN and BODY. -This `lambda' expression calls the function FN with arguments -BODY and returns its value. Its own arguments are derived from -symbols found in BODY. +This macro provides a compact way to write short `lambda' expressions. +It expands to a `lambda' expression, which calls the function FN with +arguments BODY and returns its value. The arguments of the `lambda' +expression are derived from symbols found in BODY. + +Each symbol from `%1' through `%9', which appears in an unquoted part +of BODY, specifies a mandatory argument. Each symbol from `&1' through +`&9', which appears in an unquoted part of BODY, specifies an optional +argument. The symbol `&*' specifies extra (`&rest') arguments. -Each symbol from `%1' through `%9', which appears in BODY, -specifies a mandatory argument. Each symbol from `&1' through -`&9', which appears in BODY, specifies an optional argument. -All arguments following an optional argument have to be optional -as well, thus their names have to begin with `&'. Symbol `&*' -specifies extra (`&rest') arguments. +The shorter symbol `%' can be used instead of `%1', but using both in +the same expression is not allowed. Likewise `&' can be used instead +of `&1'. These shorthands are not recognized in function position. -The shorter symbol `%' can be used instead of `%1', but using both -in the same expression is not allowed. Likewise `&' can be used -instead of `&1'. +To support binding forms that use a vector as VARLIST (such as `-let' +from the `dash' package), argument symbols are also detected inside of +vectors. + +The space between `##' and FN can be omitted because `##' is read-syntax +for the symbol whose name is the empty string. If you prefer you can +place a space there anyway, and if you prefer to not use this somewhat +magical symbol at all, you can instead use the alternative name `llama'. Instead of: @@ -116,8 +122,8 @@ which expands to: (lambda (%1 &optional _&2 &3 &rest &*) (foo %1 (bar &3) &*)) -Unused trailing arguments and mandatory unused arguments at the -border between mandatory and optional arguments are also supported: +Unused trailing arguments and mandatory unused arguments at the border +between mandatory and optional arguments are also supported: (##list %1 _%3 &5 _&6) @@ -126,16 +132,9 @@ becomes: (lambda (%1 _%2 _%3 &optional _&4 &5 _&6) (list %1 &5)) -Note how `_%3' and `_&6' are removed from the body, because their -names begin with an underscore. Also note that `_&4' is optional, -unlike the explicitly specified `_%3'. - -The name `##' was chosen because that allows (optionally) omitting -the whitespace between it and the following symbol. If you dislike -this trickery, you can alternatively use this macro under the name -`llama'. (It is also available under the name `\\#\\#', but the sole -purpose of that is to allow using \"M-x describe-function RET ## RET\" -to view this docstring.)" +Note how `_%3' and `_&6' are removed from the body, because their names +begin with an underscore. Also note that `_&4' is optional, unlike the +explicitly specified `_%3'." (cond ((symbolp fn)) ((and (eq (car-safe fn) backquote-backquote-symbol) (not body)) |