[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[elpa] externals/names 5c3d4f1 08/44: Merge branch 'elpa' into dev
From: |
Stefan Monnier |
Subject: |
[elpa] externals/names 5c3d4f1 08/44: Merge branch 'elpa' into dev |
Date: |
Sat, 27 Mar 2021 14:40:09 -0400 (EDT) |
branch: externals/names
commit 5c3d4f1d2202963d0fb1cc0afe6d620037c103ae
Merge: 7a6692a 68bcf86
Author: Artur Malabarba <bruce.connor.am@gmail.com>
Commit: Artur Malabarba <bruce.connor.am@gmail.com>
Merge branch 'elpa' into dev
---
Readme.org | 28 +++++++++++++++-------------
UsageExample.org | 36 ++++++++++++------------------------
names-dev.el | 19 ++++++++++---------
names.el | 44 ++++++++++++++++++++++++++++++++++++++------
4 files changed, 75 insertions(+), 52 deletions(-)
diff --git a/Readme.org b/Readme.org
index 2de1b31..ef55b04 100644
--- a/Readme.org
+++ b/Readme.org
@@ -1,10 +1,13 @@
#+OPTIONS: toc:nil num:nil
-* Names [[https://secure.travis-ci.org/Bruce-Connor/names.png?branch=master]]
+* Names
[[https://travis-ci.org/Bruce-Connor/names?branch=master][https://secure.travis-ci.org/Bruce-Connor/names.png?branch=master]]
*Names* is designed as a practical, complete, robust, and debuggable
tool which writes your namespaces for you.
+It is part of Emacs and is available trough
[[https://elpa.gnu.org/packages/names.html][GNU Elpa]], so every
+Emacs user running at least 24.1 has access to it.
+
[[file:package-example.png]]\\
/Example usage of Names to namespace an emacs-lisp function./
*** A Namespace implementation for Emacs-Lisp
@@ -13,14 +16,13 @@ The *Names* package aims to provide an implementation of
namespaces in Emacs with four guiding principles:
- Practical :: Actually useful and easy to grasp.
-- Completeness :: Support any macro/function/special-form available in
- emacs-lisp, even the ones defined by you or a third
- party.
-- Robustness :: No-surprises, well-tested, and with clearly stated
- limitations. Yes, as complete as we aim to be,
- there will be limitations.
-- Debuggable :: Support *edebug* and =eval-defun=, as well as any
- other essential tools for package developers.
+- Complete :: Support any macro, function, or special-form available in
+ emacs-lisp, /even/ the ones defined by you or a third
+ party.
+- Robust :: No-surprises, well-tested, and with clearly stated
+ limitations.
+- Debuggable :: Support *edebug* and =eval-defun=, and any other
+ package developing tools.
See [[https://github.com/Bruce-Connor/spaces#why-a-namespace-package][Why a
namespace package?]] for a description on why this is
necessary, and see
[[https://github.com/Bruce-Connor/emacs-lisp-namespaces/blob/master/Other-Packages.org][Other-Packages.org]]
for a description and comparison
@@ -81,10 +83,10 @@ lack of knowledge by the reader, =names.el= is also
acceptable.
** Why a namespace package?
Plain and simple: Emacs doesn't have namespaces, and it needs them.
-Nic Ferrier has a
[[http://nic.ferrier.me.uk/blog/2013_06/adding-namespaces-to-elisp][great essay
on the subject]]. Note that
-*Names* is very different from the solution he proposes, but it does
-solve the problem he had with other alternatives which left the
-debugger unusable.
+Nic Ferrier has a
[[http://nic.ferrier.me.uk/blog/2013_06/adding-namespaces-to-elisp][great essay
on the subject]], and you might want to
+read
[[https://lists.gnu.org/archive/html/emacs-devel/2014-12/msg00772.html][an
opposing opinion]] as well. Note that *Names* is very different
+from the solution he proposes, but it does solve the problem he had
+with other alternatives which left the debugger unusable.
Emacs takes the approach of prefixing every symbol name with the name
of the package. This successfully avoids name clashes between
diff --git a/UsageExample.org b/UsageExample.org
index 9c0ceb4..b27160e 100644
--- a/UsageExample.org
+++ b/UsageExample.org
@@ -7,22 +7,14 @@ The important items are already listed in the Readme:
#+BEGIN_SRC emacs-lisp
-;;; example-package.el --- Just an example
+;;; example.el --- Just an example
;;; You have to add this requirement!!
-;; Package-Requires: ((names "0.5"))
-
-;;; Commentary:
-
-;; Bla Bla Bla Bla Bla Bla Bla Bla Bla Bla Bla Bla Bla Bla Bla Bla Bla
-;; Bla Bla Bla Bla
+;; Package-Requires: ((names "0.5") (emacs "24"))
;;; Code:
-;;; Require us. After compilation there will be NO leftover reference
-;;; to the names package.
-
-(eval-when-compile (require 'names))
+;; `define-namespace' is autoloaded, so there's no need to require `names'.
;;;###autoload
(define-namespace example-
@@ -33,8 +25,8 @@ The important items are already listed in the Readme:
"Evaluate BODY, don't evaluate NAME."
(declare (debug (sexp body-form))
(indent defun))
- ;; `example-has-courage' here is inside a quoted
- ;; form, so it needs to be written explicitly.
+ ;; `example-has-courage' is inside a quoted form, so it needs to be
+ ;; written explicitly.
`(let ((example-has-courage ',name))
,@body))
@@ -48,15 +40,13 @@ The important items are already listed in the Readme:
(defun -fight-internal ()
"Called by `example-fight'"
(when has-courage
- ;; `has-courage' here is will be expanded to
- ;; `example-has-courage'.
+ ;; `has-courage' here is will be expanded to `example-has-courage'.
(let ((has-courage nil))
- ;; Victory!
- )))
+ (message "Victory!"))))
)
-(provide 'example-package)
-;;; example-package.el ends here
+(provide 'example)
+;;; example.el ends here
#+END_SRC
@@ -86,16 +76,14 @@ To see this expansion yourself.
"Called by `example-fight'"
(when example-has-courage
(let ((has-courage nil))
- ;; Victory!
- )))
+ (message "Victory!"))))
#+END_SRC
* Usage Instructions
-The
-follow these steps:
+Follow these steps:
-1. Remember to list =names= as a dependency, and =require= it.
+1. Remember to list =names= as a dependency.
2. Wrap all code that's to be namespaced inside a =(define-namespace NAME
...)= macro.
3. Pleasantly remove all that redundant repetition from you code!
4. When quoting function names, use =#' = instead of = ' =.
diff --git a/names-dev.el b/names-dev.el
index 5457f72..0133604 100644
--- a/names-dev.el
+++ b/names-dev.el
@@ -118,12 +118,7 @@ If KILL is non-nil, kill the temp buffer afterwards."
command))
(entire-namespace
(save-excursion
- (when (progn
- (end-of-defun)
- (beginning-of-defun)
- (ignore-errors
- (backward-up-list)
- (names--looking-at-namespace)))
+ (when (names--top-of-namespace)
(cdr (read (current-buffer))))))
b keylist spec name expanded-form)
@@ -156,6 +151,14 @@ If KILL is non-nil, kill the temp buffer afterwards."
(when (and ,kill (buffer-live-p b))
(kill-buffer b))))))
+(defun names--top-of-namespace ()
+ ""
+ (progn
+ (beginning-of-defun)
+ (ignore-errors
+ (backward-up-list)
+ (names--looking-at-namespace))))
+
(defun names-eval-defun (edebug-it)
"Identical to `eval-defun', except it works for forms inside namespaces.
Argument EDEBUG-IT is the same as `eval-defun', causes the form
@@ -208,9 +211,7 @@ Argument EVAL-LAST-SEXP-ARG-INTERNAL is the same as
`eval-print-last-sexp'."
(defalias 'find-function-read 'names--find-function-read)
(defun names--find-function-read (&optional type)
- "Identical to `eval-print-last-sexp', except it works for forms inside
namespaces.
-Argument EVAL-LAST-SEXP-ARG-INTERNAL is the same as `eval-print-last-sexp'."
- (interactive "P")
+ "Identical to `find-function-read', except it works inside namespaces."
(let ((buf (current-buffer)))
(names--wrapped-in-namespace
(names--find-function-read-original type) nil t
diff --git a/names.el b/names.el
index b019231..56713ce 100644
--- a/names.el
+++ b/names.el
@@ -185,7 +185,7 @@ Used to define a constant and a command.")
(defconst names--keyword-list
'((:group
1 (lambda (x)
- (if (symbolp x)
+ (if (or (symbolp x) (listp x))
(setq names--group-parent x)
(names--warn
"Argument given to :group is not a symbol: %s" x)))
@@ -194,6 +194,10 @@ The name of the group is the package name (see :package
keyword).
This keyword should be given one argument, the name of the PARENT
group as an unquoted symbol.
+Alternatively, the argument can be a list, in which case it is a
+list of arguments to be passed to `defgroup' (essentially, a full
+group definition without the leading `defgroup').
+
If this keyword is provided, besides including a defgroup, Names
will also include a :group keyword in every `defcustom' (and
similar forms) that don't already contain one.")
@@ -546,10 +550,12 @@ Decide package name based on several factors. In order:
(defun names--generate-defgroup ()
"Return a `defgroup' form for the current namespace."
- (list 'defgroup (names--package-name) nil
- (format "Customization group for %s." (names--package-name))
- :prefix (symbol-name names--name)
- :group `',names--group-parent))
+ (if (listp names--group-parent)
+ (cons 'defgroup names--group-parent)
+ (list 'defgroup (names--package-name) nil
+ (format "Customization group for %s." (names--package-name))
+ :prefix (symbol-name names--name)
+ :group `',names--group-parent)))
(defun names--generate-version ()
"Return a `defun' and a `defconst' forms declaring the package version.
@@ -563,6 +569,8 @@ Also adds `version' to `names--fbound' and `names--bound'."
(list 'defun (names--prepend 'version) nil
(format "Version of the %s package." (names--package-name))
'(interactive)
+ `(message
+ ,(format "%s version: %s" (names--package-name) names--version))
names--version)))
(defun names--add-macro-to-environment (form)
@@ -584,6 +592,30 @@ Also adds `version' to `names--fbound' and `names--bound'."
(cdr-safe def))
byte-compile-macro-environment))))))))
+;;;###autoload
+(defadvice find-function-search-for-symbol
+ (around names-around-find-function-search-for-symbol-advice
+ (symbol type library) activate)
+ "Make sure `find-function-search-for-symbol' understands namespaces."
+ ad-do-it
+ (ignore-errors
+ (unless (cdr ad-return-value)
+ (with-current-buffer (car ad-return-value)
+ (search-forward-regexp "^(define-namespace\\_>")
+ (skip-chars-forward "\r\n[:blank:]")
+ (let* ((names--regexp
+ (concat "\\`" (regexp-quote
+ (symbol-name (read (current-buffer))))))
+ (short-symbol
+ ;; We manually implement `names--remove-namespace'
+ ;; because it might not be loaded.
+ (let ((name (symbol-name symbol)))
+ (when (string-match names--regexp name)
+ (intern (replace-match "" nil nil name))))))
+ (when short-symbol
+ (ad-set-arg 0 short-symbol)
+ ad-do-it))))))
+
(defun names--extract-autoloads (body)
"Return a list of the forms in BODY preceded by :autoload."
(let (acons)
@@ -666,7 +698,7 @@ are namespaced become un-namespaced."
(delq nil (mapcar 'names--remove-namespace (apply 'append lists))))
(defun names--remove-namespace (symbol)
- "Return SYMBOL with namespace removed, or nil if S wasn't namespaced."
+ "Return SYMBOL with namespace removed, or nil if it wasn't namespaced."
(names--remove-regexp symbol names--regexp))
(defun names--remove-protection (symbol)
- [elpa] externals/names adeb39a 01/44: Add gitignore, (continued)
- [elpa] externals/names adeb39a 01/44: Add gitignore, Stefan Monnier, 2021/03/27
- [elpa] externals/names f050730 10/44: Merge branch 'master' into dev, Stefan Monnier, 2021/03/27
- [elpa] externals/names d1f33bd 20/44: Merge branch 'dev', Stefan Monnier, 2021/03/27
- [elpa] externals/names c07e0f6 22/44: Merge branch 'dev', Stefan Monnier, 2021/03/27
- [elpa] externals/names abe24c3 23/44: Merge branch 'elpa' into dev, Stefan Monnier, 2021/03/27
- [elpa] externals/names 5f100ac 25/44: Merge branch 'elpa' into dev, Stefan Monnier, 2021/03/27
- [elpa] externals/names c8a6a0f 02/44: Add tests, Stefan Monnier, 2021/03/27
- [elpa] externals/names 741bf08 09/44: Fix tests, Stefan Monnier, 2021/03/27
- [elpa] externals/names 8a009ac 07/44: Merge branch 'elpa', Stefan Monnier, 2021/03/27
- [elpa] externals/names 9ca77b7 18/44: Add test for :functionlike-macros, Stefan Monnier, 2021/03/27
- [elpa] externals/names 5c3d4f1 08/44: Merge branch 'elpa' into dev,
Stefan Monnier <=
- [elpa] externals/names a6865f9 28/44: Merge branch 'dev', Stefan Monnier, 2021/03/27
- [elpa] externals/names 2b24400 33/44: Merge branch 'elpa' into dev, Stefan Monnier, 2021/03/27
- [elpa] externals/names 34339b6 36/44: Merge pull request #25 from yurrriq/patch-1, Stefan Monnier, 2021/03/27
- [elpa] externals/names 65b577b 40/44: Merge pull request #28 from tarsius/master, Stefan Monnier, 2021/03/27
- [elpa] externals/names 65cb3f7 34/44: Merge branch 'dev', Stefan Monnier, 2021/03/27
- [elpa] externals/names 7a6692a 04/44: Merge branch 'elpa' into dev, Stefan Monnier, 2021/03/27
- [elpa] externals/names 2a5b21c 05/44: Merge branch 'elpa', Stefan Monnier, 2021/03/27
- [elpa] externals/names ca0f397 15/44: Travis badge, Stefan Monnier, 2021/03/27
- [elpa] externals/names 1587d24 29/44: Stop testing 23.4, Stefan Monnier, 2021/03/27
- [elpa] externals/names 097dc46 30/44: Update usage example, Stefan Monnier, 2021/03/27