bug#73505: EIEIO manual out of date, doesn't reflect current functionality

bug#73505: EIEIO manual out of date, doesn't reflect current functionality

[zyd via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Hi,

The info manual for EIEIO seems to be out of date, specifically the introduction
section:

    (info "(eieio) Introduction")

Therein it's stated that EIEIO lacks support for both eql specializers and
`:around' methods


> EQL specialization
>    EIEIO does not support it.
> 
> ‘:around’ method tag
>      This CLOS method tag is non-functional.


But this isn't true at all, EIEIO has both of these features fully functional in
fact. 

-------------------------------------------------------------------------------

(cl-defgeneric inform-chat (msg preamble))

(cl-defmethod inform-chat (msg (preamble (eql :night)))
  (message "Good night chat, %s" msg))

(cl-defmethod inform-chat (msg (preamble (eql :morning)))
  (message "Good morning chat, %s" msg))

(inform-chat "that's all she wrote. What more do you want from me?" :night)
;; => "Good night chat, that's all she wrote. What more do you want from me?"

(inform-chat "many mornings such as this one, today is different! Today is the day I tell you all my hot takes." :morning)
;; => "Good morning chat, many mornings such as this one, but today is the day I
;; tell you all my hot takes."

(cl-defmethod inform-chat :around (msg (preamble (eql :morning)))
  (setq msg (concat "even though there are " msg " Now I know, I know... you're sick of them but I must. I'm compelled, even!"))
  (cl-call-next-method msg preamble))

(inform-chat "many mornings such as this one, today is different! Today is the day I tell you all my hot takes." :morning)
;; => "Good morning chat, even though there are many mornings such as this one,
;; today is different! Today is the day I tell you all my hot takes. Now I know,
;; I know... you're sick of them but I must. I'm compelled, even!"

-------------------------------------------------------------------------------

So I wonder, how much of the rest of the manual is out of date like this? Is it
not to be trusted as a source of factual information about the current state of
CLOS in elisp?

Emacs version: 30.0.60 (commit 1154d8aafe2f4702b8fc775835f830fd00cfbaaf)

-zyd

bug#73505: EIEIO manual out of date, doesn't reflect current functionality

[Eli Zaretskii]

> Date: Thu, 26 Sep 2024 22:45:27 +0000
> From:  zyd via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
> 
> The info manual for EIEIO seems to be out of date, specifically the introduction
> section:
> 
>     (info "(eieio) Introduction")
> 
> Therein it's stated that EIEIO lacks support for both eql specializers and
> `:around' methods
> 
> 
> > EQL specialization
> >    EIEIO does not support it.
> > 
> > ‘:around’ method tag
> >      This CLOS method tag is non-functional.
> 
> 
> But this isn't true at all, EIEIO has both of these features fully functional in
> fact. 
> 
> -------------------------------------------------------------------------------
> 
> (cl-defgeneric inform-chat (msg preamble))
> 
> (cl-defmethod inform-chat (msg (preamble (eql :night)))
>   (message "Good night chat, %s" msg))
> 
> (cl-defmethod inform-chat (msg (preamble (eql :morning)))
>   (message "Good morning chat, %s" msg))
> 
> (inform-chat "that's all she wrote. What more do you want from me?" :night)
> ;; => "Good night chat, that's all she wrote. What more do you want from me?"
> 
> (inform-chat "many mornings such as this one, today is different! Today is the day I tell you all my hot takes." :morning)
> ;; => "Good morning chat, many mornings such as this one, but today is the day I
> ;; tell you all my hot takes."
> 
> (cl-defmethod inform-chat :around (msg (preamble (eql :morning)))
>   (setq msg (concat "even though there are " msg " Now I know, I know... you're sick of them but I must. I'm compelled, even!"))
>   (cl-call-next-method msg preamble))
> 
> (inform-chat "many mornings such as this one, today is different! Today is the day I tell you all my hot takes." :morning)
> ;; => "Good morning chat, even though there are many mornings such as this one,
> ;; today is different! Today is the day I tell you all my hot takes. Now I know,
> ;; I know... you're sick of them but I must. I'm compelled, even!"
> 
> -------------------------------------------------------------------------------
> 
> So I wonder, how much of the rest of the manual is out of date like this? Is it
> not to be trusted as a source of factual information about the current state of
> CLOS in elisp?

You are using above cl-defgeneric and cl-defmethod, which are not part
of EIEIO.  So I think the EIEIO manual is not mistaken in what it
says.  But maybe I'm missing something.  Adding Stefan who might have
comments.

bug#73505: EIEIO manual out of date, doesn't reflect current functionality

[zyd via Bug reports for GNU Emacs, the Swiss army knife of text editors]

On Friday, September 27th, 2024 at 12:59 AM, Eli Zaretskii <eliz@gnu.org> wrote:
> You are using above cl-defgeneric and cl-defmethod, which are not part of
> EIEIO. So I think the EIEIO manual is not mistaken in what it says. But maybe
> I'm missing something. Adding Stefan who might have comments.

The EIEIO manual states that it provides method functionality for Emacs
Lisp. The manual has whole sections devoted to both cl-defmethod and
cl-defgeneric and refers to them as part of its corpus. It has documentation for
both.

    (info "(eieio) Generics")
    (info "(eieio) Methods")

And as far as I can tell there is no eieio-specific defmethod or defgeneric
macros that aren't cl-defmethod and cl-defgeneric. So I really doubt that I'm in
error here.

bug#73505: EIEIO manual out of date, doesn't reflect current functionality

[Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors]

> But this isn't true at all, EIEIO has both of these features fully
> functional in fact.

It's both true and false:

- EIEIO "has" none of those things because the defmethod stuff is now
  provided by something else than EIEIO.  EIEIO only provides `defclass`
  and associated functions (e.g. `slot-value`).

- But yes, the text is out of date because you can now use these
  features (with EIEIO objects, with defstruct objects, with
  oclosure objects, ...).

> The EIEIO manual states that it provides method functionality for
> Emacs Lisp.  The manual has whole sections devoted to both
> cl-defmethod and cl-defgeneric and refers to them as part of its
> corpus.  It has documentation for both.
>
>     (info "(eieio) Generics")
>     (info "(eieio) Methods")

This structure is a left-over from when generics were provided by EIEIO.
We should clarify.

> And as far as I can tell there is no eieio-specific defmethod or
> defgeneric macros that aren't cl-defmethod and cl-defgeneric.
> So I really doubt that I'm in error here.

Actually, `eieio-compat` still provides the old `defmethod` and
`defgeneric` (without `cl-`)


        Stefan

bug#73505: EIEIO manual out of date, doesn't reflect current functionality

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: zyd <zyd-p@proton.me>,  73505@debbugs.gnu.org
> Date: Fri, 27 Sep 2024 08:48:07 -0400
> 
> > But this isn't true at all, EIEIO has both of these features fully
> > functional in fact.
> 
> It's both true and false:
> 
> - EIEIO "has" none of those things because the defmethod stuff is now
>   provided by something else than EIEIO.  EIEIO only provides `defclass`
>   and associated functions (e.g. `slot-value`).
> 
> - But yes, the text is out of date because you can now use these
>   features (with EIEIO objects, with defstruct objects, with
>   oclosure objects, ...).
> 
> > The EIEIO manual states that it provides method functionality for
> > Emacs Lisp.  The manual has whole sections devoted to both
> > cl-defmethod and cl-defgeneric and refers to them as part of its
> > corpus.  It has documentation for both.
> >
> >     (info "(eieio) Generics")
> >     (info "(eieio) Methods")
> 
> This structure is a left-over from when generics were provided by EIEIO.
> We should clarify.

Thanks, please suggest how to clarify.

bug#73505: EIEIO manual out of date, doesn't reflect current functionality

[Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors]

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

> This structure is a left-over from when generics were provided by EIEIO.
> We should clarify.

I propose the patch below.


        Stefan

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: eieio.patch --]
[-- Type: text/x-diff, Size: 7363 bytes --]

diff --git a/doc/misc/eieio.texi b/doc/misc/eieio.texi
index 02cb51e6fdd..5eba594006a 100644
--- a/doc/misc/eieio.texi
+++ b/doc/misc/eieio.texi
@@ -232,12 +232,6 @@ Introduction
 should return instances of the metaclass, behave differently in
 @eieio{} in that they return symbols or plain structures instead.
 
-@item EQL specialization
-EIEIO does not support it.
-
-@item @code{:around} method tag
-This CLOS method tag is non-functional.
-
 @item :default-initargs in @code{defclass}
 Each slot can have an @code{:initform} tag, so this is not really necessary.
 
@@ -810,158 +804,19 @@ Accessing Slots
 @node Writing Methods
 @chapter Writing Methods
 
-Writing a method in @eieio{} is similar to writing a function.  The
-differences are that there are some extra options and there can be
+Writing a method in @eieio{} is similar to writing a function.
+The differences are that there are some extra options and there can be
 multiple definitions under the same function symbol.
 
-Where a method defines an implementation for a particular data type, a
-@dfn{generic method} accepts any argument, but contains no code.  It
-is used to provide the dispatching to the defined methods.  A generic
-method has no body, and is merely a symbol upon which methods are
-attached.  It also provides the base documentation for what methods
-with that name do.
-
-@menu
-* Generics::
-* Methods::
-* Static Methods::
-@end menu
-
-@node Generics
-@section Generics
-
-Each @eieio{} method has one corresponding generic.  This generic
-provides a function binding and the base documentation for the method
-symbol (@pxref{Symbol Components,,,elisp,GNU Emacs Lisp Reference
-Manual}).
-
-@defmac cl-defgeneric method arglist [doc-string]
-This macro turns the (unquoted) symbol @var{method} into a function.
-@var{arglist} is the default list of arguments to use (not implemented
-yet).  @var{doc-string} is the documentation used for this symbol.
-
-A generic function acts as a placeholder for methods.  There is no
-need to call @code{cl-defgeneric} yourself, as @code{cl-defmethod} will call
-it if necessary.  Currently the argument list is unused.
-
-@code{cl-defgeneric} signals an error if you attempt to turn an existing
-Emacs Lisp function into a generic function.
-
-You can also create a generic method with @code{cl-defmethod}
-(@pxref{Methods}).  When a method is created and there is no generic
-method in place with that name, then a new generic will be created,
-and the new method will use it.
-@end defmac
-
-@node Methods
-@section Methods
-
-A method is a function that is executed if the arguments passed
-to it matches the method's specializers.  Different @eieio{} classes may
-share the same method names.
-
-Methods are created with the @code{cl-defmethod} macro, which is similar
-to @code{defun}.
-
-@defmac cl-defmethod method [:before | :around | :after ] arglist [doc-string] forms
-
-@var{method} is the name of the function to create.
-
-@code{:before}, @code{:around}, and @code{:after} specify execution order
-(i.e., when this form is called).  If none of these symbols are present, the
-method is said to be a @emph{primary}.
-
-@var{arglist} is the list of arguments to this method.  The mandatory arguments
-in this list may have a type specializer (see the example below) which means
-that the method will only apply when those arguments match the given type
-specializer.  An argument with no type specializer means that the method
-applies regardless of its value.
-
-@var{doc-string} is the documentation attached to the implementation.
-All method doc-strings are incorporated into the generic method's
-function documentation.
-
-@var{forms} is the body of the function.
-
-@end defmac
-
-@noindent
-In the following example, we create a method @code{mymethod} for the
-@code{classname} class:
-
-@example
-(cl-defmethod mymethod ((obj classname) secondarg)
-  "Doc string" )
-@end example
-
-@noindent
-This method only executes if the @var{obj} argument passed to it is an
-@eieio{} object of class @code{classname}.
-
-A method with no type specializer is a @dfn{default method}.  If a given
-class has no implementation, then the default method is called when
-that method is used on a given object of that class.
-
-Only one method per combination of specializers and qualifiers (@code{:before},
-@code{:around}, or @code{:after}) is kept.  If two @code{cl-defmethod}s appear
-with the same specializers and the same qualifiers, then the second
-implementation replaces the first.
-
-When a method is called on an object, but there is no method specified
-for that object, but there is a method specified for object's parent
-class, the parent class's method is called.  If there is a method
-defined for both, only the child's method is called.  A child method
-may call a parent's method using @code{cl-call-next-method}, described
-below.
-
-If multiple methods and default methods are defined for the same
-method and class, they are executed in this order:
-
-@enumerate
-@item :around methods
-The most specific @code{:around} method is called first, which may invoke the
-less specific ones via @code{cl-call-next-method}.  If it doesn't invoke
-@code{cl-call-next-method}, then no other methods will be executed.  When there
-are no more @code{:around} methods to call, falls through to run the other
-(non-@code{:around}) methods.
-@item :before methods
-Called in sequence from most specific to least specific.
-@item primary methods
-The most specific method is called, which may invoke the less specific
-ones via @code{cl-call-next-method}.
-@item :after methods
-Called in sequence from least specific to most specific.
-@end enumerate
-
-If no methods exist, Emacs signals a @code{cl-no-applicable-method} error.
-@xref{Signals}.  If methods exist but none of them are primary, Emacs
-signals a @code{cl-no-primary-method} error.  @xref{Signals}.
-
-@defun cl-call-next-method &rest replacement-args
-@anchor{cl-call-next-method}
-
-This function calls the superclass method from a subclass method.
-This is the ``next method'' specified in the current method list.
-
-If @var{replacement-args} is non-@code{nil}, then use them instead of the
-arguments originally provided to the method.
-
-Can only be used from within the lexical body of a primary or around method.
-@end defun
-
-@defun cl-next-method-p
-@anchor{cl-next-method-p}
-Non-@code{nil} if there is a next method.
-
-Can only be used from within the lexical body of a primary or around method.
-@end defun
-
-@node Static Methods
-@section Static Methods
+You do it using Emacs Lisp's built-in support for CLOS-style generic
+functions via the @code{cl-defgeneric} and @code{cl-defmethod} macros
+(@pxref{Generic Functions,,,elisp,GNU Emacs Lisp Reference Manual}).
 
-Static methods do not depend on an object instance, but instead
-operate on a class.  You can create a static method by using
-the @code{subclass} specializer with @code{cl-defmethod}:
+EIEIO provides one extension to @code{cl-defmethod} to allow mathods to
+dispatch on a class argument: so-called ``static'' methods do not depend
+on an object instance, but instead operate on a class.  You can create
+a static method by using the @code{subclass} specializer with
+@code{cl-defmethod}:
 
 @example
 (cl-defmethod make-instance ((class (subclass mychild)) &rest args)

bug#73505: EIEIO manual out of date, doesn't reflect current functionality

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: zyd <zyd-p@proton.me>,  73505@debbugs.gnu.org
> Date: Fri, 27 Sep 2024 09:15:06 -0400
> 
> > This structure is a left-over from when generics were provided by EIEIO.
> > We should clarify.
> 
> I propose the patch below.

Thanks, this LGTM.

bug#73505: EIEIO manual out of date, doesn't reflect current functionality

[Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors]

>> I propose the patch below.
> Thanks, this LGTM.

Pushed to `emacs-30`, thanks.


        Stefan