code.delx.au - gnu-emacs-elpa/blob - packages/names/Readme.org

   1 #+OPTIONS: toc:nil num:nil
   2
   3 * Names [[https://travis-ci.org/Bruce-Connor/names?branch=master][https://secure.travis-ci.org/Bruce-Connor/names.png?branch=master]]
   4
   5 *Names* is designed as a practical, complete, robust, and debuggable
   6 tool which writes your namespaces for you.
   7
   8 It is part of Emacs and is available trough [[https://elpa.gnu.org/packages/names.html][GNU Elpa]], so every
   9 Emacs user running at least 24.1 has access to it.
  10
  11 [[file:package-example.png]]\\
  12 /Example usage of Names to namespace an emacs-lisp function./
  13 *** A Namespace implementation for Emacs-Lisp
  14
  15 The *Names* package aims to provide an implementation of
  16 namespaces in Emacs with four guiding principles:
  17
  18 - Practical :: Actually useful and easy to grasp.
  19 - Complete :: Support any macro, function, or special-form available in
  20               emacs-lisp, /even/ the ones defined by you or a third
  21               party.
  22 - Robust :: No-surprises, well-tested, and with clearly stated
  23             limitations.
  24 - Debuggable :: Support *edebug* and =eval-defun=, and any other
  25                 package developing tools.
  26
  27 See [[https://github.com/Bruce-Connor/spaces#why-a-namespace-package][Why a namespace package?]] for a description on why this is
  28 necessary, and see [[https://github.com/Bruce-Connor/emacs-lisp-namespaces/blob/master/Other-Packages.org][Other-Packages.org]] for a description and comparison
  29 of previous packages attempting similar things.
  30
  31 **** Version Compatibility
  32 Currently, *Names* is being supported on the entire Emacs 24 family
  33 (24.1--24.4). Any new changes or pull requests are tested on a
  34 [[https://travis-ci.org/Bruce-Connor/names][Travis-CI machine]]. See the /“tests”/ subdirectory for our test suite,
  35 and see .
  36
  37 ** Usage
  38 The [[https://github.com/Bruce-Connor/emacs-lisp-namespaces/blob/master/UsageExample.org][UsageExample]] file clearly displays and explains how to use *Names*
  39 in your package. There are few simple measures to take. Go have a look
  40 if you’re interested, I promise it’s worth it!
  41
  42 If you want deeper descriptions of use-cases, see [[https://github.com/Bruce-Connor/emacs-lisp-namespaces/blob/master/TheNittyGritty.org][TheNittyGritty.org]].
  43
  44 ** Developer Tools
  45 *Names* offers a series of tools to make package writing more
  46 convenient inside a namespace. These developer facilities are on this
  47 separate file, so the file isn't loaded on the user's computer when
  48 your package calls =(require 'names)=.
  49
  50 To access them add the following line to your init file.
  51 #+begin_src emacs-lisp
  52 (require 'names-dev)
  53 #+end_src
  54
  55 *** Edebug and eval-defun support
  56
  57 First and foremost, the =edebug-eval-defun= command (bound to =C-u
  58 C-M-x=) is an essential tool for any package developer. *Names*
  59 wouldn't be a very useful utility if it prevented you from using this
  60 asset.
  61
  62 Therefore, it provides the =names-eval-defun= command, which is
  63 identical to =edebug-eval-defun= except it also works inside
  64 namespaces. It will automatically be added to your
  65 =emacs-lisp-mode-map=.
  66
  67 *** Font-locking
  68 Font-lock for =define-namespace= and =:autoload=.
  69
  70 *** Expansion and comparison functions
  71 =names-compare-forms= and =names-print= offer information when
  72 something just doesn't seem to make sense.
  73
  74 ** Nomenclature
  75
  76 The name of this package is *Names*, always with a capital “N”.
  77 Despite the word being plural, refer to it in the singular (e.g.,
  78 “Names is an amazing achievement”). If possible consider giving it a
  79 slight emphasis, such as: /Names/.
  80 When there's a risk of confusion or ambiguity, be it due to context or
  81 lack of knowledge by the reader, =names.el= is also acceptable.
  82
  83 ** Why a namespace package?
  84 Plain and simple: Emacs doesn't have namespaces, and it needs them.
  85
  86 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
  87 read [[https://lists.gnu.org/archive/html/emacs-devel/2014-12/msg00772.html][an opposing opinion]] as well. Note that *Names* is very different
  88 from the solution he proposes, but it does solve the problem he had
  89 with other alternatives which left the debugger unusable.
  90
  91 Emacs takes the approach of prefixing every symbol name with the name
  92 of the package. This successfully avoids name clashes between
  93 packages, but it quickly leads to code that's repetitive and annoying
  94 to write. Below is an example from =package.el=, the word "/package/"
  95 is repeated 7 times in a 10-line function.
  96
  97 *Names* doesn't change this overall approach. It adheres to Emacs
  98 standards and is completely invisible to the end-user. *Names* simply
  99 gives /you/ (the developer) a convenient way of writing code that
 100 adheres to this standard.
 101
 102 [[file:package-example.png]]
 103 /Example usage of Names to namespace an emacs-lisp function./
 104
 105 - At runtime, the right-hand-side will create the same definitions as the left-hand-side.
 106 - At compilation, it will create the exact same compiled file (with no left-over reference to =names.el= functions).
 107
 108 *** Tested On:
 109 Below are the packages on which I've tested *Names*. If you're
 110 interested, try using it on one of your packages and [[https://github.com/Bruce-Connor/names/issues][let me know how
 111 it goes]].
 112 **** elnode
 113 - *Number of ert tests passed:* Same as before namespacing (62).
 114 - *Reduction in code size:* Approx. 2000 characters.
 115 **** s.el
 116 - *Number of ert tests passed:* All.
 117 - *Reduction in code size:* Approx. 1000 characters (8%).
 118 1000 characters is a lot when you consider /s.el/ has the second
 119 shortest namespace possible, =s-=.
 120 **** dash.el
 121 - *Number of ert tests passed:* Same as before namespacing (104).
 122 **** latex-extra
 123 - *Number of ert tests passed:* ALL.
 124 **** aggressive-indent
 125 No actual tests defined, but this package actually uses /Names/ for
 126 real! And it's alive and well.