Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/Malabarba/names

A Namespace implementation for Emacs-Lisp
https://github.com/Malabarba/names

Last synced: 2 months ago
JSON representation

A Namespace implementation for Emacs-Lisp

Awesome Lists containing this project

README 

        
#+OPTIONS: toc:nil num:nil



* Names [[https://travis-ci.org/Malabarba/names?branch%3Dmaster][https://secure.travis-ci.org/Malabarba/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 through [[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



The *Names* package aims to provide an implementation of

namespaces in Emacs with four guiding principles:



- Practical :: Actually useful and easy to grasp.

- 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

of previous packages attempting similar things.



**** Version Compatibility

Currently, *Names* is being supported on the entire Emacs 24 family

(24.1--24.4). Any new changes or pull requests are tested on a

[[https://travis-ci.org/Bruce-Connor/names][Travis-CI machine]]. See the /“tests”/ subdirectory for our test suite,

and see .



** Usage

The [[https://github.com/Bruce-Connor/emacs-lisp-namespaces/blob/master/UsageExample.org][UsageExample]] file clearly displays and explains how to use *Names*

in your package. There are few simple measures to take. Go have a look

if you’re interested, I promise it’s worth it!



If you want deeper descriptions of use-cases, see [[https://github.com/Bruce-Connor/emacs-lisp-namespaces/blob/master/TheNittyGritty.org][TheNittyGritty.org]].



** Developer Tools

*Names* offers a series of tools to make package writing more

convenient inside a namespace. These developer facilities are on this

separate file, so the file isn't loaded on the user's computer when

your package calls =(require 'names)=.



To access them add the following line to your init file.

#+begin_src emacs-lisp

(require 'names-dev)

#+end_src



*** Edebug and eval-defun support



First and foremost, the =edebug-eval-defun= command (bound to =C-u

C-M-x=) is an essential tool for any package developer. *Names*

wouldn't be a very useful utility if it prevented you from using this

asset.



Therefore, it provides the =names-eval-defun= command, which is

identical to =edebug-eval-defun= except it also works inside

namespaces. It will automatically be added to your

=emacs-lisp-mode-map=.



*** Font-locking

Font-lock for =define-namespace= and =:autoload=.



*** Expansion and comparison functions

=names-compare-forms= and =names-print= offer information when

something just doesn't seem to make sense.



** Nomenclature



The name of this package is *Names*, always with a capital “N”.

Despite the word being plural, refer to it in the singular (e.g.,

“Names is an amazing achievement”). If possible consider giving it a

slight emphasis, such as: /Names/.

When there's a risk of confusion or ambiguity, be it due to context or

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]], 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

packages, but it quickly leads to code that's repetitive and annoying

to write. Below is an example from =package.el=, the word "/package/"

is repeated 7 times in a 10-line function.



*Names* doesn't change this overall approach. It adheres to Emacs

standards and is completely invisible to the end-user. *Names* simply

gives /you/ (the developer) a convenient way of writing code that

adheres to this standard.



[[file:package-example.png]]

/Example usage of Names to namespace an emacs-lisp function./



- At runtime, the right-hand-side will create the same definitions as the left-hand-side.

- At compilation, it will create the exact same compiled file (with no left-over reference to =names.el= functions).



*** Tested On:

Below are the packages on which I've tested *Names*. If you're

interested, try using it on one of your packages and [[https://github.com/Bruce-Connor/names/issues][let me know how

it goes]].

**** elnode

- *Number of ert tests passed:* Same as before namespacing (62).

- *Reduction in code size:* Approx. 2000 characters.

**** s.el

- *Number of ert tests passed:* All.

- *Reduction in code size:* Approx. 1000 characters (8%).

1000 characters is a lot when you consider /s.el/ has the second

shortest namespace possible, =s-=.

**** dash.el

- *Number of ert tests passed:* Same as before namespacing (104).

**** latex-extra

- *Number of ert tests passed:* ALL.