Re: Predicate for true lists

[Eli Zaretskii <eliz@gnu.org>]

> From: "Basil L. Contovounesios" <contovob@tcd.ie>
> Date: Fri, 06 Jul 2018 01:31:26 +0300
> Cc: emacs-devel@gnu.org
> 
> I attach three patches (and a benchmark).  The first introduces the
> function proper-list-length as per your suggestion in
> https://lists.gnu.org/archive/html/emacs-devel/2018-06/msg00138.html
> (please check whether I have properly attributed you, as I am unfamiliar
> with the preferred way of doing this).
> 
> The second changes the Elisp manual to refer to "proper lists" instead
> of "true lists".
> 
> The third moves the definition of zerop in lisp/subr.el from under the
> 'List functions' heading to under the 'Basic Lisp functions' heading.
> 
> Finally, here are the updated (byte-compiled) benchmark results:
> 
>     ‘proper-list-length’
>       proper   (0.004452047000000001 0 0.0)
>       dotted   (0.005584044999999999 0 0.0)
>       circular (0.006193915          0 0.0)
>     ‘format-proper-list-p’
>       proper   (0.06397756299999999  0 0.0)
>       dotted   (0.063610087          0 0.0)
>       circular (0.09455345899999999  0 0.0)
>     ‘ert--proper-list-p’
>       proper   (0.29080201899999997  0 0.0)
>       dotted   (0.290801063          0 0.0)
>       circular (0.433813842          0 0.0)
> 
> WDYT?

Thanks, I have a few comments below.

> >From f42cb45f449dbb6c3d806398a128bc5914fdebab Mon Sep 17 00:00:00 2001
> From: "Basil L. Contovounesios" <contovob@tcd.ie>
> Date: Fri, 6 Jul 2018 00:41:11 +0300
> Subject: [PATCH 1/3] Add convenience function proper-list-length
> 
> * lisp/subr.el (proper-list-length): New function.
> Suggested by Paul Eggert <eggert@cs.ucla.edu> in
> https://lists.gnu.org/archive/html/emacs-devel/2018-06/msg00138.html.
> * doc/lispref/lists.texi (List Elements):
> * etc/NEWS: Mention it.

The "it" part here is ambiguous, because it's too far from the last
place where the function's name was mentioned.  Please state the name
of the function for better readability.

> * lisp/emacs-lisp/byte-opt.el (byte-optimize-if):
> * lisp/emacs-lisp/cl-macs.el (cl--make-usage-args):
> * lisp/org/ob-core.el (org-babel-insert-result): Use it.

Likewise.

> * lisp/emacs-lisp/ert.el (ert--proper-list-p): Remove.
> (ert--explain-equal-rec): Use proper-list-length instead.
> * lisp/format.el (format-proper-list-p): Remove.

Maybe consider mentioning that these are removed "because
SUCH-AND-SUCH replaces them in file FOO."

> +@defun proper-list-length object
> +This function returns the length of @var{object} if it is a proper
> +list, @code{nil} otherwise.  In addition to satisfying @code{listp}, a
> +proper list is neither circular nor dotted.

Proper list is defined elsewhere in the manual, so please add here a
cross-reference to that spot (I'd suggest doing that with @pxref in
parentheses at the end of the first sentence).

> +** New function 'proper-list-length'.
> +Given a proper list as argument, this function returns its length;
> +otherwise, it returns nil.  This function can thus be used as a
> +predicate for proper lists.

Do we really want this usage of the function as a predicate?  I find
this slightly unnatural, and also not future-proof enough, because you
rely on the checks 'length' does internally.  If the internals of
'length' change one day, this predicate usage will collapse like a
house of cards.  Would it make more sense to have a separate
predicate?

> +(defun proper-list-length (object)
> +  "Return OBJECT's length if it is a proper list, nil otherwise.
> +A proper list is neither circular nor dotted (i.e., its last cdr
> +is nil)."

But if we do want to use this as a predicate, then the doc string
should say so.

> * doc/lispref/lists.texi (Cons Cells, Building Lists):
> * doc/lispref/sequences.texi (Vector Functions): Do it.

Please put the full description in the log entry.  "Do it" refers to
what the header says, I presume, but I at least am used to ignoring
the headers and reading the entries, because they are generally more
informative (due to space constraints on the header).

> +@cindex proper list
>  @cindex true list
>    Also by convention, the @sc{cdr} of the last cons cell in a list is
>  @code{nil}.  We call such a @code{nil}-terminated structure a
> -@dfn{true list}.  In Emacs Lisp, the symbol @code{nil} is both a
> +@dfn{proper list}.  In Emacs Lisp, the symbol @code{nil} is both a

We still have "true list" in the index (and rightly so), so I think
the new text should say, perhaps in parens or in a footnote, that such
lists are also known as "true lists".  Imagine a reader who follows
the "true list" index entry and gets placed on this text -- they will
be confused to not see "true list" mentioned anywhere.  Besides, that
term is in wide usage elsewhere.

Thanks again for working on this.