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

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