Proposal to change naming format to allow package-prefix/function-name

Proposal to change naming format to allow package-prefix/function-name

[Zachary Kanfer]

[-- Attachment #1: Type: text/plain, Size: 3768 bytes --]

I'd like to propose a change to the recommended symbol name format.
Currently, Emacs recommends that public functions, macros, variables, etc,
are named package-prefix-thing-name (
https://www.gnu.org/software/emacs/manual/html_node/elisp/Coding-Conventions.html
).

> You should choose a short word to distinguish your program from other
Lisp programs. The names of all global symbols in your program, that is the
names of variables, constants, and functions, 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
space1. Use two hyphens to separate prefix and name if the symbol is not
meant to be used by other packages.

This works, but I find not as readable as could be. When looking at any
function with three or more words in its name, it's not obvious where the
package name stops, and the function name begins. For example, is the
function lsp-java-organize-imports part of the lsp package, and called
"java-organize-imports", or part of the lsp-java package, and called
"organize-imports"? Is there a package named lsp-java-organize? You don't
know from the function name.

==Proposal==

I'd like to suggest allowing the use of a slash character to separate the
package prefix from the rest of the function name. So, our example of
lsp-java-organize-imports would become lsp-java/organize-imports. Then,
it's obvious the package prefix is lsp-java.

This extends well to private funtions too, by repeating the slash
character. For example, cl--do-arglist could become cl//do-arglist. This
actually is a slight visual pun -- two slashes is a comment in C, Java,
Javascript, etc, and private functions are similarly intended to be
somewhat hidden from the user.

I don't wish to disallow the dash from separating the package prefix from
the rest of the name, only allow an alternative that I believe to be more
readable.

==Prior Art & Existing Uses==

Here are some examples that show this should be easily grokked:
1. Elsewhere in technology, a slash is used to indicate hierarchy --
Unix/Linux filesystems use the slash between a parent directory and the
directory or file inside it, as do URLs.
2. Clojure separates the namespace name from the function name with a
slash, as in clojure.core/refer.
3. Dates are often written with the slash separating the componenets of the
date, as in 12/27/2019.

Some Elisp functions that are part of Emacs already follow this format.
1. Many eshell functions already follow this format, for example eshell/ls,
eshell/exit, and eshell/define.
2. Pcomplete functions use this format, even some for more than one
hierarchical level, e.g. pcomplete/gzip,
pcomplete/erc-mode/complete-command, pcomplete/org-mode/block-option/src.
3. Org-plot has half a dozen functions, like org-plot/goto-nearest-table.

Some popular libaries have functions with this format:
1. Powerline, like pl/memoize and pl/default-mode-line.
2. Multiple-cursors uses this format for one hundred public functions.

This change, at least until we see how it is accepted, is only intended to
be a change to the coding conventions for new code. I don't expect to go
through and rename existing Emacs functions; I rather would like this to be
a way to write Emacs packages that doesn't go against the Emacs coding
conventions. I've searched the mailing list for related discussions, and
haven't found much, so if there has been some, please point it out to me.
I'm very interested in the reception here; I think this would improve
readability of names.

Thanks,

Zachary Kanfer

[-- Attachment #2: Type: text/html, Size: 4033 bytes --]

Re: Proposal to change naming format to allow package-prefix/function-name

[Juanma Barranquero]

[-- Attachment #1: Type: text/plain, Size: 940 bytes --]

On Mon, Dec 30, 2019 at 8:03 AM Zachary Kanfer <zkanfer@gmail.com> wrote:

> Some Elisp functions that are part of Emacs already follow this format.
> 1. Many eshell functions already follow this format, for example
eshell/ls, eshell/exit, and eshell/define.
> 2. Pcomplete functions use this format, even some for more than one
hierarchical level, e.g. pcomplete/gzip,
pcomplete/erc-mode/complete-command, pcomplete/org-mode/block-option/src.
> 3. Org-plot has half a dozen functions, like org-plot/goto-nearest-table.

I think this proposal is unlikely to gain traction. But if it were, in a
Lisp context colon (:) would make more sense IMHO, as it is used in Common
Lisp to separate the namespace ("package", in CL-speak) from the symbol
name. That would make easier to adapt to CL-style namespaces, if they were
implemented in Emacs some day (which I think won't ever happen, if previous
discussions on the subject are to be believed).

[-- Attachment #2: Type: text/html, Size: 1070 bytes --]

Re: Proposal to change naming format to allow package-prefix/function-name

[Elias Mårtenson]

[-- Attachment #1: Type: text/plain, Size: 987 bytes --]

On Mon, 30 Dec 2019, 20:05 Juanma Barranquero, <lekktu@gmail.com> wrote:

>
> I think this proposal is unlikely to gain traction. But if it were, in a
> Lisp context colon (:) would make more sense IMHO, as it is used in Common
> Lisp to separate the namespace ("package", in CL-speak) from the symbol
> name. That would make easier to adapt to CL-style namespaces, if they were
> implemented in Emacs some day (which I think won't ever happen, if previous
> discussions on the subject are to be believed).
>

I just want to voice my 100% agreement that the minus character should be
changed. Its double use is, as mentioned in the original post, incredibly
annoying to read. In my package, gnu-apl-mode, all symbols are prefixed
with gbu-apl- and it's full of these issues.

Whether the character is / or : or anything else, I could not care less.
All I want is a symbol that isn't much used for anything else.

The benefit of / is that a lot of third party packages already use it.

>

[-- Attachment #2: Type: text/html, Size: 1618 bytes --]

Re: Proposal to change naming format to allow package-prefix/function-name

[Zachary Kanfer]

[-- Attachment #1: Type: text/plain, Size: 1614 bytes --]

> But if it were, in a Lisp context colon (:) would make more sense IMHO,
as it is used in Common Lisp to separate the namespace ("package", in
CL-speak) from the symbol name.

Perhaps. My gut feeling is that package-prefix/function-name is more
readable than package-prefix:function-name, and also more obvious to new
users, but I think either would be better than the current dash separation.
I would think that any future implementation of namespaces would be able to
work with any character chosen here; it wouldn't be just a copy-and-paste
of CL code.

On Mon, Dec 30, 2019 at 7:04 AM Juanma Barranquero <lekktu@gmail.com> wrote:

>
> On Mon, Dec 30, 2019 at 8:03 AM Zachary Kanfer <zkanfer@gmail.com> wrote:
>
> > Some Elisp functions that are part of Emacs already follow this format.
> > 1. Many eshell functions already follow this format, for example
> eshell/ls, eshell/exit, and eshell/define.
> > 2. Pcomplete functions use this format, even some for more than one
> hierarchical level, e.g. pcomplete/gzip,
> pcomplete/erc-mode/complete-command, pcomplete/org-mode/block-option/src.
> > 3. Org-plot has half a dozen functions, like org-plot/goto-nearest-table.
>
> I think this proposal is unlikely to gain traction. But if it were, in a
> Lisp context colon (:) would make more sense IMHO, as it is used in Common
> Lisp to separate the namespace ("package", in CL-speak) from the symbol
> name. That would make easier to adapt to CL-style namespaces, if they were
> implemented in Emacs some day (which I think won't ever happen, if previous
> discussions on the subject are to be believed).
>
>
>

[-- Attachment #2: Type: text/html, Size: 2058 bytes --]

Re: Proposal to change naming format to allow package-prefix/function-name

[Adam Porter]

FWIW, as yet another Emacs package developer, I support Zachary's
proposal.  

As he said, it already exists as a de facto convention, even in some
canonical Emacs and Org code.  And users and new package developers are
doing it on their own, often being required to replace the slashes with
hyphens when submitting packages to MELPA, which strictly follows the
official guidelines.

Whatever the character used, as long as it's visually distinctive and
easy to type, I think it would be helpful to both users and developers
to allow it to be used to separate the package/feature name from the
rest of the symbol name.

Re: Proposal to change naming format to allow package-prefix/function-name

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

In Common Lisp, name spaces do not behave cleanly.  The reason is that
a symbol's name space has to be recognized when it is read, for the
sake of symbols compared with eq.  This is too early to make good choices.

To get clean behavior for name spaces, it is necessary to be able to
choose a symbol's name space based on the execution context when code
is run.  Some languages do that, and name spaces are simple and clear
in those languages.

Unless we can find a way to do this right in Lisp -- and I don't see
how that could be -- name spaces will offer no advantage over name
prefixes that are part of the name.

I have no strong opinions about using / or : in symbol names.

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: Proposal to change naming format to allow package-prefix/function-name

[Lars Ingebrigtsen]

Adam Porter <adam@alphapapa.net> writes:

> Whatever the character used, as long as it's visually distinctive and
> easy to type, I think it would be helpful to both users and developers
> to allow it to be used to separate the package/feature name from the
> rest of the symbol name.

I don't.  In Common Lisp, it's a functional thing, and it's easy to
remember that foo:bar-zot is a thing, but in Emacs Lisp, where it would
just be a character that's not sounded when you read the symbol, it's
just confounding.  In the past, when working on Emacs Lisp code bases
where somebody has been creative with non-letter characters, I always
find myself having to try all the variations to find the correct symbol,
because what my brain remembers is "foo bar zot", and not whatever is in
between those letters.

foo:bar-zot?  foo-bar:zot?  foo:bar/zot?

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: Proposal to change naming format to allow package-prefix/function-name

[Ihor Radchenko]

> ... I always find myself having to try all the variations to find the
> correct symbol, because what my brain remembers is "foo bar zot", and
> not whatever is in between those letters.

> foo:bar-zot?  foo-bar:zot?  foo:bar/zot?

I support this point. It will indeed be a problem for vanilla Emacs
completion users.

Let me propose an alternative solution.

The proposal is trying to solve the problem of distinguishing the
package name from function name.
Why not just highlight the feature name in the completion buffer?
Emacs knows which `provide` (if any) corresponds to every function anyway.

Best,
Ihor



Lars Ingebrigtsen <larsi@gnus.org> writes:

> Adam Porter <adam@alphapapa.net> writes:
>
>> Whatever the character used, as long as it's visually distinctive and
>> easy to type, I think it would be helpful to both users and developers
>> to allow it to be used to separate the package/feature name from the
>> rest of the symbol name.
>
> I don't.  In Common Lisp, it's a functional thing, and it's easy to
> remember that foo:bar-zot is a thing, but in Emacs Lisp, where it would
> just be a character that's not sounded when you read the symbol, it's
> just confounding.  In the past, when working on Emacs Lisp code bases
> where somebody has been creative with non-letter characters, I always
> find myself having to try all the variations to find the correct symbol,
> because what my brain remembers is "foo bar zot", and not whatever is in
> between those letters.
>
> foo:bar-zot?  foo-bar:zot?  foo:bar/zot?
>
> -- 
> (domestic pets only, the antidote for overdose, milk.)
>    bloggy blog: http://lars.ingebrigtsen.no
>

-- 
Ihor Radchenko,
PhD,
Center for Advancing Materials Performance from the Nanoscale (CAMP-nano)
State Key Laboratory for Mechanical Behavior of Materials, Xi'an Jiaotong University, Xi'an, China
Email: yantar92@gmail.com, ihor_radchenko@alumni.sutd.edu.sg

Re: Proposal to change naming format to allow package-prefix/function-name

[Clemens Radermacher]

On 31.12.19 11:14, Lars Ingebrigtsen wrote:
> Adam Porter <adam@alphapapa.net> writes:
> 
>> Whatever the character used, as long as it's visually distinctive and
>> easy to type, I think it would be helpful to both users and developers
>> to allow it to be used to separate the package/feature name from the
>> rest of the symbol name.
> 
> I don't.  In Common Lisp, it's a functional thing, and it's easy to
> remember that foo:bar-zot is a thing, but in Emacs Lisp, where it would
> just be a character that's not sounded when you read the symbol, it's
> just confounding.  In the past, when working on Emacs Lisp code bases
> where somebody has been creative with non-letter characters, I always
> find myself having to try all the variations to find the correct symbol,
> because what my brain remembers is "foo bar zot", and not whatever is in
> between those letters.
> 
> foo:bar-zot?  foo-bar:zot?  foo:bar/zot?
> 

Maybe using a char suffix would be better so it would better align with current conventions 
and make it easier to search/complete for users which expect those:

    package-name-/function-name
    package-name--/private-fun-name

Re: Proposal to change naming format to allow package-prefix/function-name

[Teemu Likonen]

[-- Attachment #1: Type: text/plain, Size: 693 bytes --]

Clemens Radermacher [2019-12-31T13:06:16+01] wrote:

> Maybe using a char suffix would be better so it would better align
> with current conventions and make it easier to search/complete for
> users which expect those:
>
>     package-name-/function-name
>     package-name--/private-fun-name

Not sure if this is a good idea but here is yet another possibility: use
a capital letter in package name words and small letter in others:

    Package-Name-command-name
    Package-Name--private-name

-- 
///  OpenPGP key: 4E1055DC84E9DFF613D78557719D69D324539450
//  https://keys.openpgp.org/search?q=tlikonen@iki.fi
/  https://keybase.io/tlikonen  https://github.com/tlikonen

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 694 bytes --]

Re: Proposal to change naming format to allow package-prefix/function-name

[Sam Steingold]

> * Richard Stallman <ezf@tah.bet> [2019-12-30 19:45:34 -0500]:
>
> In Common Lisp, name spaces do not behave cleanly.  The reason is that
> a symbol's name space has to be recognized when it is read, for the
> sake of symbols compared with eq.  This is too early to make good choices.

Could you please elaborate?

If you are referring to the need to wrap `require` in `eval-when`, then
CLISP dealt with it by handling `require` specially in compiler, so that

--8<---------------cut here---------------start------------->8---
(require 'foo)
(foo:define-foo ...)
--8<---------------cut here---------------end--------------->8---

works just fine.
https://clisp.sourceforge.io/impnotes/require.html

> To get clean behavior for name spaces, it is necessary to be able to
> choose a symbol's name space based on the execution context when code
> is run.  Some languages do that, and name spaces are simple and clear
> in those languages.

Again, could you please clarify what you mean here?

Thanks.

-- 
Sam Steingold (http://sds.podval.org/)
http://childpsy.net http://calmchildstories.com http://steingoldpsychology.com
https://camera.org https://jij.org http://islamexposedonline.com
I'm a Lisp variable -- bind me!