The function naming convention used by Emacs.

The function naming convention used by Emacs.

[Hongyi Zhao]

As far as function names are concerned, are there some established
conventions used by Emacs? For example, I noticed that there are so
many functions in Emacs named by the suffix `-p', say,
`file-exists-p', `ht-equal-p', and so on. But I still can't figure out
the meaning of this suffix. Any tips will be appreciated.

Best, HZ
-- 
Assoc. Prof. Hongyi Zhao <hongyi.zhao@gmail.com>
Theory and Simulation of Materials
Hebei Vocational University of Technology and Engineering
No. 473, Quannan West Street, Xindu District, Xingtai, Hebei province

Re: The function naming convention used by Emacs.

[2QdxY4RzWzUUiLuE]

On 2021-09-26 at 19:05:36 +0800,
Hongyi Zhao <hongyi.zhao@gmail.com> wrote:

> As far as function names are concerned, are there some established
> conventions used by Emacs? For example, I noticed that there are so
> many functions in Emacs named by the suffix `-p', say,
> `file-exists-p', `ht-equal-p', and so on. But I still can't figure out
> the meaning of this suffix. Any tips will be appreciated.

The -p suffix is short for "predicate"; so file-exists-p is true if and
only if the argument names and existing file.  I learned of that
convention from Common Lisp; I don't know the entire history.

Re: The function naming convention used by Emacs.

[Emanuel Berg via Users list for the GNU Emacs text editor]

2QdxY4RzWzUUiLuE wrote:

>> As far as function names are concerned, are there some
>> established conventions used by Emacs? For example,
>> I noticed that there are so many functions in Emacs named
>> by the suffix `-p', say, `file-exists-p', `ht-equal-p', and
>> so on. But I still can't figure out the meaning of this
>> suffix. Any tips will be appreciated.
>
> The -p suffix is short for "predicate"; so file-exists-p is
> true if and only if the argument names and existing file.
> I learned of that convention from Common Lisp; I don't know
> the entire history.

Me neither :)

But it is from Predicate Logic which is an extension of
Propositional Logic ...

-- 
underground experts united
https://dataswamp.org/~incal

Re: The function naming convention used by Emacs.

[Hongyi Zhao]

On Sun, Sep 26, 2021 at 7:27 PM <2QdxY4RzWzUUiLuE@potatochowder.com> wrote:
[...]
> The -p suffix is short for "predicate"; so file-exists-p is true if and
> only if the argument names and existing file.  I learned of that
> convention from Common Lisp; I don't know the entire history.

Thank you for sharing your knowledge with me.

HZ

Re: The function naming convention used by Emacs.

[Emanuel Berg via Users list for the GNU Emacs text editor]

Hongyi Zhao wrote:

> As far as function names are concerned, are there some
> established conventions used by Emacs? For example,
> I noticed that there are so many functions in Emacs named by
> the suffix `-p', say, `file-exists-p', `ht-equal-p', and so
> on. But I still can't figure out the meaning of this suffix.
> Any tips will be appreciated.

It stands for "predicate", such a function returns t or nil.

there is also the "f" suffix for "function", e.g. `cl-incf'
and `cl-decf' ... and a couple of other conventions I can't
remember right now.

Speaking of CL, the convention for *global-variables* is not
encouraged in Elisp.

Other than that do this

(require 'checkdoc)

(setq checkdoc-permit-comma-termination-flag t)

(defun check-package-style ()
  (interactive)
  (let ((msg "Style check..."))
    (message msg)
    (checkdoc-current-buffer t) ; TAKE-NOTES
    (message "%sdone" msg) ))
(defalias 'check-style #'check-package-style)

and do byte-compile for more pointers ...

-- 
underground experts united
https://dataswamp.org/~incal

Re: The function naming convention used by Emacs.

[Hongyi Zhao]

On Sun, Sep 26, 2021 at 7:49 PM Emanuel Berg via Users list for the
GNU Emacs text editor <help-gnu-emacs@gnu.org> wrote:
>
> Hongyi Zhao wrote:
>
> > As far as function names are concerned, are there some
> > established conventions used by Emacs? For example,
> > I noticed that there are so many functions in Emacs named by
> > the suffix `-p', say, `file-exists-p', `ht-equal-p', and so
> > on. But I still can't figure out the meaning of this suffix.
> > Any tips will be appreciated.
>
> It stands for "predicate", such a function returns t or nil.
>
> there is also the "f" suffix for "function", e.g. `cl-incf'
> and `cl-decf' ... and a couple of other conventions I can't
> remember right now.
>
> Speaking of CL, the convention for *global-variables* is not
> encouraged in Elisp.
>
> Other than that do this
>
> (require 'checkdoc)
>
> (setq checkdoc-permit-comma-termination-flag t)
>
> (defun check-package-style ()
>   (interactive)
>   (let ((msg "Style check..."))
>     (message msg)
>     (checkdoc-current-buffer t) ; TAKE-NOTES
>     (message "%sdone" msg) ))
> (defalias 'check-style #'check-package-style)

Do you mean and suggest adding the above code snippets into the init file?

> and do byte-compile for more pointers ...

I now use the `--with-native-compilation' option to configure Emacs
for compilation. So, the thing you mentioned above should have been
done automatically by Emacs.

HZ

Re: The function naming convention used by Emacs.

[Emanuel Berg via Users list for the GNU Emacs text editor]

Hongyi Zhao wrote:

>> Other than that do this
>>
>> (require 'checkdoc)
>>
>> (setq checkdoc-permit-comma-termination-flag t)
>>
>> (defun check-package-style ()
>>   (interactive)
>>   (let ((msg "Style check..."))
>>     (message msg)
>>     (checkdoc-current-buffer t) ; TAKE-NOTES
>>     (message "%sdone" msg) ))
>> (defalias 'check-style #'check-package-style)
>
> Do you mean and suggest adding the above code snippets into
> the init file?

Yes, if you will. And use it on your code.

>> and do byte-compile for more pointers ...
>
> I now use the `--with-native-compilation' option to
> configure Emacs for compilation. So, the thing you mentioned
> above should have been done automatically by Emacs.

Byte-compile your code after you've written it. Do it again
when you change it. Byte-compiling makes it faster to load and
run, that's the reason to do it. But as a positive
side-effect, the byte-compiler will also output errors and
warnings - so it is a tool to improve you code as well.

Do a Makefile and shell alias to it to run it, so you can
byte-compile fast in terms of the mere interface, but also so
that files you didn't change and have already byte-compiled
will not be byte-compiled again.

-- 
underground experts united
https://dataswamp.org/~incal

RE: [External] : The function naming convention used by Emacs.

[Drew Adams]

> As far as function names are concerned, are there some established
> conventions used by Emacs? For example, I noticed that there are so
> many functions in Emacs named by the suffix `-p', say,
> `file-exists-p', `ht-equal-p', and so on. But I still can't figure
> out the meaning of this suffix. Any tips will be appreciated.

Ask Emacs!

In the Elisp manual, `i' followed by `convention'
(if you have substring completion turned on) shows
these index-entry candidates (the exact list might
depend on your Emacs version):

 buffer display conventions
 coding conventions in Emacs Lisp 
 comments, Lisp convention for
 conventions for writing major modes 
 conventions for writing minor modes
 documentation conventions 
 documentation strings, conventions and tips
 key binding, conventions for 
 major mode conventions
 minor mode conventions 
 programming conventions
 set-advertised-calling-convention 
 typographic conventions

Some of those point to the same nodes of the manual.

Choosing, say, `coding conventions in Emacs Lisp'
takes you to node `Coding Conventions', where you
find this:

   • If the purpose of a function is to tell you
     whether a certain condition is true or false,
     give the function a name that ends in ‘p’
     (which stands for “predicate”).  If the name
     is one word, add just ‘p’; if the name is
     multiple words, add ‘-p’.  Examples are
     ‘framep’ and ‘frame-live-p’.

https://www.gnu.org/software/emacs/manual/html_node/elisp/Coding-Conventions.html

Re: [External] : The function naming convention used by Emacs.

[Hongyi Zhao]

On Mon, Sep 27, 2021 at 1:04 AM Drew Adams <drew.adams@oracle.com> wrote:
>
> > As far as function names are concerned, are there some established
> > conventions used by Emacs? For example, I noticed that there are so
> > many functions in Emacs named by the suffix `-p', say,
> > `file-exists-p', `ht-equal-p', and so on. But I still can't figure
> > out the meaning of this suffix. Any tips will be appreciated.
>
> Ask Emacs!
>
> In the Elisp manual, `i' followed by `convention'
> (if you have substring completion turned on)

What's the exact vanilla Emacs keystrokes corresponding to the above operations?

> shows these index-entry candidates (the exact list might
> depend on your Emacs version):
>
>  buffer display conventions
>  coding conventions in Emacs Lisp
>  comments, Lisp convention for
>  conventions for writing major modes
>  conventions for writing minor modes
>  documentation conventions
>  documentation strings, conventions and tips
>  key binding, conventions for
>  major mode conventions
>  minor mode conventions
>  programming conventions
>  set-advertised-calling-convention
>  typographic conventions
>
> Some of those point to the same nodes of the manual.
>
> Choosing, say, `coding conventions in Emacs Lisp'
> takes you to node `Coding Conventions', where you
> find this:
>
>    • If the purpose of a function is to tell you
>      whether a certain condition is true or false,
>      give the function a name that ends in ‘p’
>      (which stands for “predicate”).  If the name
>      is one word, add just ‘p’; if the name is
>      multiple words, add ‘-p’.  Examples are
>      ‘framep’ and ‘frame-live-p’.
>
> https://www.gnu.org/software/emacs/manual/html_node/elisp/Coding-Conventions.html

Thank you for showing me this. With swiper [1], I use the following
command to access the above Elisp manual built-in Emacs:

C-h i RET elisp RET cod conv RET

[1] https://github.com/abo-abo/swiper

HZ

RE: [External] : The function naming convention used by Emacs.

[Drew Adams]

> > In the Elisp manual, `i' followed by `convention'
> > (if you have substring completion turned on)
> 
> What's the exact vanilla Emacs keystrokes
> corresponding to the above operations?

With vanilla Emacs, enable style `substring' for
user option `completion-styles', if you want to
be able to type just `convention' and see
substring matches (completions) for it.

In the Elisp manual, `i completion-styles RET'
tells you about this.

Then `i convention TAB' does what I described.

If you don't enable substring completion then
`i convention TAB' completes only to `conventions
for writing m', and `TAB' again shows you these
two candidates:

  conventions for writing major modes
  conventions for writing minor modes

Neither of those is relevant for your question.

But you can instead type `i coding c TAB' to
get candidate `coding conventions in Emacs Lisp'.

The problem with that is guessing/knowing more
about what index entries there might be.

This illustrates a general point: vanilla Emacs
completion is limited, out of the box.  But you
can customize it to help you better.  You'll
need to read about `completion-styles' to decide
just how you want to do that.

Personally, I use a completion library (Icicles)
that provides both (1) "prefix" completion
(speaking generally) such as what vanilla Emacs
provides - using `TAB', and (2) "apropos"
completion such as regexp (which includes
substring) matching - using `S-TAB'.  So I use
`i convention S-TAB' to see substring matches.

https://www.emacswiki.org/emacs/Icicles_-_Completion_Methods_and_Styles

[
 I use those names, "prefix" and "apropos", but
 they're a bit misleading.  In Icicles, "prefix"
 completion (`TAB') includes whatever vanilla
 Emacs `completion-styles' you configured (so it
 can include `substring', `flex', etc.).  And it
 includes `fuzzy' and `swank' completion.

 "Apropos" completion includes 2 kinds of "scatter" 
 completion (sometimes called "flex"), and 3 other
 kinds of "fuzzy" completion.  (And you can add
 other matching methods.)

 Having two keys for completion means you can
 use either kind anytime, and you can use them
 together when progressively narrowing.  Each
 has its own advantages.

 (You can also change the method used for either
 `TAB' or `S-TAB' anytime, during completion.)
]

> With swiper, I use the following command to
> access the above Elisp manual built-in Emacs:
> 
> C-h i RET elisp RET cod conv RET

Same with Icicles, and no doubt with other
libraries.

It's enough to type just `cod co'.  But again,
this means you have to guess that there's an
index entry that's something like `coding
conventions'.  Otherwise, how would you come up
with `cod co'?

It's not about how little you can type to match
just what you need.  It's about what you need
to guess, to get to what you need.

Guessing that there's some info (an answer)
about "conventions" is fairly natural, here.

Guessing there might be info for "coding" might
also be natural (or not).  With uncustomized
vanilla Emacs, if you try just `coding TAB'
you'll get about 20 candidates.  If you try just
`convention' you'll get the two candidates I
cited above (neither of which is relevant here).

You might guess "programming" instead of "coding".
And there is an index entry `programming
conventions'.  But that takes you to node
`Programming Tips', which doesn't help with your
quest.

1. My point was to _ask Emacs_, using its index.

(And you can of course also just go directly to
node `Index' and browse/search there, instead of
using `i'.)

2. A secondary point is that you can help yourself
by using a better matching style or system than
the default.

Re: The function naming convention used by Emacs.

[Pierpaolo Bernardi]

Il giorno 26 settembre 2021, alle ore 13:49, Emanuel Berg via Users list for the GNU Emacs text editor <help-gnu-emacs@gnu.org> ha scritto:

>there is also the "f" suffix for "function", e.g. `cl-incf'
>and `cl-decf' ... 

The "f" in these cases stands for "field".

Re: The function naming convention used by Emacs.

[Emanuel Berg via Users list for the GNU Emacs text editor]

Pierpaolo Bernardi wrote:

>> there is also the "f" suffix for "function", e.g. `cl-incf'
>> and `cl-decf' ...
>
> The "f" in these cases stands for "field".

That so, OK, thanks.

-- 
underground experts united
https://dataswamp.org/~incal