Names

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 GNU Elpa, so every Emacs user running at least 24.1 has access to it.

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 Why a namespace package? for a description on why this is necessary, and see 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 Travis-CI machine. See the “tests” subdirectory for our test suite, and see .

Usage

The 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 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.

(require 'names-dev)

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 great essay on the subject, and you might want to read 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.

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 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.