How to choose Emacs Lisp package namespace prefix

1. background

Since Emacs Lisp doesn’t provide namespaces yet, Emacs Lisp packages use prefixes as substitute for namespaces. For example, the cl-lib library uses cl as its common prefix for all of its function names (and variable names), the rx library uses rx, the smartparens package uses sp, the rainbow-delimiters package uses rainbow-delimiters, the macrostep package uses macrostep.

This post is part of Living with Emacs Lisp.

2. how to choose namespace prefix for your package

There is no official guideline on how you should choose your package’s namespace prefix, but it seems to me that it is established that you should choose a prefix that is the same as the package name or one of its possible abbreviations.

2.1. packages that use short prefix

Examples:

  • rx and s from packages of same name
  • cl from cl-lib
  • sp from smartparens

If you choose a short prefix, it’s more likely to clash with other prefixes used by others than if it were a long prefix. If you are considering xy as your package prefix, you can search for xy in some package archives to see if there is any package with name xy. Even if there is no package of that name, it is still possible that some package might be using xy as its namespace prefix. If you take some leap of faith, and decide to use xy as prefix for your package, now you at least know that you can have XY as your package name as well.

Some time after you release your XY package, somebody tells you there is a package called XanaduYall which has been a popular package for a long time and it uses xy prefix too. What then? No problem, you can simply rename your package to XY2 and change its code to use xy2 as its namespace prefix. If some other package depend on your old package, you can continue to provide two packages: XY and XY2.

2.2. long prefix with hyphens

Examples:

  • rainbow-delimiters from package of same name

If you choose oh-dear as your namespace prefix, even if no other package uses oh-dear as its namespace prefix, there may still be some package that uses oh as its namespace prefix, and that can conflict with your package.

2.3. long prefix without hyphens

Examples:

  • flyspell from package of same name

If you choose ohdear as your namespace prefix and your package name, you can refer to your package as OhDear in literatures. Its lisp file name should still better be ohdear.el and not OhDear.el

2.4. etc

It’s best if the namespace prefix and the package name are the same.

One might think that choosing a long prefix is bad for readability and makes typing difficult, but you can use the following command to make long prefixes display as shorter prefixes of your choice.

(defface my-prefix
  '((t (:foreground "grey50")))
  "Face for simplified prefixes.")
(defun my-simplify-prefix (prefix rep)
  "Replace PREFIX with REP visually on this buffer.

PREFIX is simply displayed as REP, but not actually replaced with REP."
  (interactive "sVisually replace this long prefix: \nsWith this short prefix: ")
  (font-lock-add-keywords
   nil `((
          ;; ;; not sure why these don't work
          ;; ,(rx-to-string `(group word-boundary ,prefix word-boundary))
          ;; ,(rx-to-string `(: word-boundary ,prefix word-boundary))
          ;; ,(rx-to-string `(: ,prefix))

          ,(rx-to-string `(group ,prefix))

          (0 (progn (put-text-property (match-beginning 0) (match-end 0)
                                       'display ,rep)
                    'my-prefix)))))
  (font-lock-fontify-buffer))

Example usage: when you are reading rainbow-delimiters.el, you may execute M-x my-simplify-prefix RET rainbow-delimiters RET rd RET

For easier typing of long prefixes, Abbrev or similar packages might be of help.

This entry was posted in Emacs and tagged , , . Bookmark the permalink.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s