3

In emacs the typical method of marking package namespaces is to choose a (preferably short) prefix applied to all symbols related to the package; In order to indicate that a function is considered "internal use only" and shouldn't be used directly outside of the package the most common convetions seem to be prefix--functionname and, or when a function requires a very simple subfunction e.g. prefix-functionname-1.

However, I also often need kind of "sub-packages", e.g. when a package consists of several public functions that I have split into non-overlapping subfunctions. Are there conventions whether to prefer

mypkg-list-all
mypkg-list-all--filter-list
mypkg-list-all--fontify-buffer 
mypkg-list-all-public-subfunction

or

mypkg--list-all-filter-list
mypkg--list-all-fontify-buffer
mypkg-list-all
mypkg-list-all-public-subfunction

?

Intuitively I find the first version better, since -- here also acts as kind of a "subpackage" delimiter and groups the most closely related functions together in the completion buffer. Sadly it causes the internal functions to be listed before the public functions of the same hierachy level, which makes me question that convention.

Are there any convetions on this or is it just "everyone as they want"?

Also, in many cases, particularily when the "fully qualified" name of a function becomes lengthy, the lack of distinction between word and package delimiter feels a bit problematic; personally I have found myself using naming conventions like

mypkg-view-mode
mypkg-view-mode:mouse-action
mypkg-view-mode:keyboard-action 

so I was wondering if there might be a better convention for subgroup delimiters than the single hyphen -.

1

2 Answers 2

4

Colon as a symbol separator is, generally, discouraged (it makes it harder to load emacs lisp into common lisp and will probably interfere with a future emacs lisp package system).

Double dash (hyphen) -- is used to indicate that the symbol is internal to the package.

Thus the currently accepted practice is package-external-symbol and package--internal-symbol.

The official Emacs Lisp Coding Conventions page does not talk about this issue in detail, just specifies:

You should choose a short word to distinguish your program from other Lisp programs. The names of all global variables, constants, and functions in your program should begin with that chosen prefix. Separate the prefix from the rest of the name with a hyphen, ‘-’. This practice helps avoid name conflicts, since all global variables in Emacs Lisp share the same name space, and all functions share another name space.

2
  • 1
    So no convention at all for structuring names within a namespace? I also noticed that org-mode, particularily org-babel introduces many symbols that contain colons; Mostly language-specific implementations of functions, e.g. org-babel-execute:C++.
    – kdb
    Sep 24, 2013 at 15:26
  • I don't myself ever loading Emacs Lisp into a Common Lisp environment. But I do want a namespace prefix to be an obvious namespace prefix. Readability counts, you know. Thus, colon is my namespace-separating character. If Emacs EVER gets proper namespaces (and I really don't see a chance in that, at least not in the non-distant future), I can rework whatever I need to. Apr 26, 2022 at 16:15
2

There's no accepted convention on this one. I personally tend to use "pkgname-sub--internal" rather than "pkgname--sub-internal", probably because I don't pay much attention to how functions/varables get sorted.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.