GNU bug report logs - #31660
26.1.50; EIEIO manual's Quick Start example makes Emacs unusable

Previous Next

Package: emacs;

Reported by: Gemini Lasswell <gazally <at> runbox.com>

Date: Wed, 30 May 2018 19:02:01 UTC

Severity: minor

Tags: confirmed, fixed

Merged with 32595

Found in version 26.1.50

Fixed in version 26.2

Done: Noam Postavsky <npostavs <at> gmail.com>

Bug is archived. No further changes may be made.

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 31660 in the body.
You can then email your comments to 31660 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

View this report as an mbox folder, status mbox, maintainer mbox


Report forwarded to bug-gnu-emacs <at> gnu.org:
bug#31660; Package emacs. (Wed, 30 May 2018 19:02:02 GMT) Full text and rfc822 format available.

Acknowledgement sent to Gemini Lasswell <gazally <at> runbox.com>:
New bug report received and forwarded. Copy sent to bug-gnu-emacs <at> gnu.org. (Wed, 30 May 2018 19:02:02 GMT) Full text and rfc822 format available.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Gemini Lasswell <gazally <at> runbox.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 26.1.50; EIEIO manual's Quick Start example makes Emacs unusable
Date: Wed, 30 May 2018 12:00:49 -0700
The first example in the EIEIO manual defines a class called 'record'.
Evaluating this example changes the function definition of 'record',
which makes many Emacs commands produce errors, including find-file,
ielm, and report-emacs-bug.

To reproduce, with emacs -Q:

M-x info RET
Navigate to the Quick Start node in the EIEIO manual, and select
the (defclass record ...) example.
M-w
M-x ielm RET
(require 'eieio) RET
C-y RET

Result: *** IELM Error ***  Error during pretty-printing (bug in pp)

Definitely the name of the class in the examples in the manual should be
changed, so that the examples work.

Maybe it would also be a good idea for defclass to signal an error or
at least give a warning message if it is asked to define a class with
the same name as an existing function unless that function is from a
previous class definition.




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#31660; Package emacs. (Sun, 03 Jun 2018 00:24:02 GMT) Full text and rfc822 format available.

Message #8 received at 31660 <at> debbugs.gnu.org (full text, mbox):

From: Noam Postavsky <npostavs <at> gmail.com>
To: Gemini Lasswell <gazally <at> runbox.com>
Cc: 31660 <at> debbugs.gnu.org
Subject: Re: bug#31660: 26.1.50;
 EIEIO manual's Quick Start example makes Emacs unusable
Date: Sat, 02 Jun 2018 20:23:31 -0400
Gemini Lasswell <gazally <at> runbox.com> writes:

> Definitely the name of the class in the examples in the manual should be
> changed, so that the examples work.

Yeah.

> Maybe it would also be a good idea for defclass to signal an error or
> at least give a warning message if it is asked to define a class with
> the same name as an existing function unless that function is from a
> previous class definition.

A warning would be okay I think.  An error is too much: if you were
developing a library and decided to change a function into a class, then
you wouldn't be able to reload the new version without restarting Emacs.





Added tag(s) confirmed. Request was from Noam Postavsky <npostavs <at> gmail.com> to control <at> debbugs.gnu.org. (Sun, 03 Jun 2018 00:25:01 GMT) Full text and rfc822 format available.

Forcibly Merged 31660 32595. Request was from Glenn Morris <rgm <at> gnu.org> to control <at> debbugs.gnu.org. (Thu, 30 Aug 2018 20:28:02 GMT) Full text and rfc822 format available.

Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#31660; Package emacs. (Thu, 22 Nov 2018 22:03:02 GMT) Full text and rfc822 format available.

Message #15 received at 31660 <at> debbugs.gnu.org (full text, mbox):

From: Gemini Lasswell <gazally <at> runbox.com>
To: Noam Postavsky <npostavs <at> gmail.com>
Cc: 31660 <at> debbugs.gnu.org
Subject: Re: bug#31660: 26.1.50;
 EIEIO manual's Quick Start example makes Emacs unusable
Date: Thu, 22 Nov 2018 14:01:48 -0800
[Message part 1 (text/plain, inline)]
Noam Postavsky <npostavs <at> gmail.com> writes:

> Gemini Lasswell <gazally <at> runbox.com> writes:
>
>> Definitely the name of the class in the examples in the manual should be
>> changed, so that the examples work.
>
> Yeah.

Here's a patch to eieio.texi which makes the examples work, and adds a
suggestion to check for name conflicts to the description of 'defclass':

[0001-Address-name-conflicts-in-EIEIO-documentation-bug-31.patch (text/plain, inline)]
From 81fa42ad5ad73bb789ad3edc6e06c9d91edbc997 Mon Sep 17 00:00:00 2001
From: Gemini Lasswell <gazally <at> runbox.com>
Date: Thu, 22 Nov 2018 13:00:03 -0800
Subject: [PATCH] Address name conflicts in EIEIO documentation (bug#31660)

* doc/misc/eieio.texi (Quick Start): Rename the class used in the
example from 'record' to 'person'.
(Building Classes): Advise user to check for name conflicts before
naming a class.  Add a missing apostrophe.
(Making New Objects): Correct grammar.  Rename the class used in the
example from 'record' to 'my-class'.
---
 doc/misc/eieio.texi | 49 +++++++++++++++++++++++++--------------------
 1 file changed, 27 insertions(+), 22 deletions(-)

diff --git a/doc/misc/eieio.texi b/doc/misc/eieio.texi
index 689ff72b72..1ad1733762 100644
--- a/doc/misc/eieio.texi
+++ b/doc/misc/eieio.texi
@@ -88,11 +88,11 @@ Quick Start
 use @eieio{} to create classes, methods for those classes, and
 instances of classes.
 
-Here is a simple example of a class named @code{record}, containing
+Here is a simple example of a class named @code{person}, containing
 three slots named @code{name}, @code{birthday}, and @code{phone}:
 
 @example
-(defclass record () ; No superclasses
+(defclass person () ; No superclasses
   ((name :initarg :name
          :initform ""
          :type string
@@ -106,23 +106,23 @@ Quick Start
    (phone :initarg :phone
           :initform ""
           :documentation "Phone number."))
-  "A single record for tracking people I know.")
+  "A class for tracking people I know.")
 @end example
 
 Each class can have methods, which are defined like this:
 
 @example
-(cl-defmethod call-record ((rec record) &optional scriptname)
-  "Dial the phone for the record REC.
+(cl-defmethod call-person ((pers person) &optional scriptname)
+  "Dial the phone for the person PERS.
 Execute the program SCRIPTNAME to dial the phone."
-  (message "Dialing the phone for %s"  (oref rec name))
+  (message "Dialing the phone for %s"  (oref pers name))
   (shell-command (concat (or scriptname "dialphone.sh")
                          " "
-                         (oref rec phone))))
+                         (oref pers phone))))
 @end example
 
 @noindent
-In this example, the first argument to @code{call-record} is a list,
+In this example, the first argument to @code{call-person} is a list,
 of the form (@var{varname} @var{classname}).  @var{varname} is the
 name of the variable used for the first argument; @var{classname} is
 the name of the class that is expected as the first argument for this
@@ -130,17 +130,17 @@ Quick Start
 
 @eieio{} dispatches methods based on the type of the first argument.
 You can have multiple methods with the same name for different classes
-of object.  When the @code{call-record} method is called, the first
+of object.  When the @code{call-person} method is called, the first
 argument is examined to determine the class of that argument, and the
 method matching the input type is then executed.
 
 Once the behavior of a class is defined, you can create a new
-object of type @code{record}.  Objects are created by calling the
+object of type @code{person}.  Objects are created by calling the
 constructor.  The constructor is a function with the same name as your
 class which returns a new instance of that class.  Here is an example:
 
 @example
-(setq rec (record :name "Eric" :birthday "June" :phone "555-5555"))
+(setq pers (person :name "Eric" :birthday "June" :phone "555-5555"))
 @end example
 
 @noindent
@@ -157,19 +157,19 @@ Quick Start
 method defined for it.  In this example it would look like this:
 
 @example
-(call-record rec)
+(call-person pers)
 @end example
 
 @noindent
 or
 
 @example
-(call-record rec "my-call-script")
+(call-person pers "my-call-script")
 @end example
 
 In these examples, @eieio{} automatically examines the class of
-@code{rec}, and ensures that the method defined above is called.  If
-@code{rec} is some other class lacking a @code{call-record} method, or
+@code{pers}, and ensures that the method defined above is called.  If
+@code{pers} is some other class lacking a @code{call-person} method, or
 some other data type, Emacs signals a @code{cl-no-applicable-method}
 error.  @ref{Signals}.
 
@@ -270,10 +270,15 @@ Building Classes
 the class as a symbol property of @var{class-name} (@pxref{Symbol
 Components,,,elisp,GNU Emacs Lisp Reference Manual}).
 
+When defining a class, @eieio{} overwrites any preexisting variable or
+function bindings for the symbol @var{class-name}, which may lead to
+undesired consequences.  Before naming a new class, you should check
+for name conflicts.
+
 The @var{class-name} symbol's variable documentation string is a
 modified version of the doc string found in @var{options-and-doc}.
 Each time a method is defined, the symbol's documentation string is
-updated to include the methods documentation as well.
+updated to include the method's documentation as well.
 
 The parent classes for @var{class-name} is @var{superclass-list}.
 Each element of @var{superclass-list} must be a class.  These classes
@@ -625,10 +630,10 @@ Class Options
 @node Making New Objects
 @chapter Making New Objects
 
-Suppose we have a simple class is defined, such as:
+Suppose we have defined a simple class, such as:
 
 @example
-(defclass record ()
+(defclass my-class ()
    ( ) "Doc String")
 @end example
 
@@ -636,10 +641,10 @@ Making New Objects
 It is now possible to create objects of that class type.
 
 Calling @code{defclass} has defined two new functions.  One is the
-constructor @var{record}, and the other is the predicate,
-@var{record}-p.
+constructor @var{my-class}, and the other is the predicate,
+@var{my-class}-p.
 
-@defun record object-name &rest slots
+@defun my-class object-name &rest slots
 
 This creates and returns a new object.  This object is not assigned to
 anything, and will be garbage collected if not saved.  This object
@@ -657,7 +662,7 @@ Making New Objects
 Example of creating an object from a class:
 
 @example
-(record :value 3 :reference nil)
+(my-class :value 3 :reference nil)
 @end example
 
 @end defun
-- 
2.18.1


Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#31660; Package emacs. (Tue, 09 Apr 2019 23:11:02 GMT) Full text and rfc822 format available.

Message #18 received at 31660 <at> debbugs.gnu.org (full text, mbox):

From: Noam Postavsky <npostavs <at> gmail.com>
To: Gemini Lasswell <gazally <at> runbox.com>
Cc: 31660 <at> debbugs.gnu.org
Subject: Re: bug#31660: 26.1.50;
 EIEIO manual's Quick Start example makes Emacs unusable
Date: Tue, 09 Apr 2019 19:10:21 -0400
tags 31660 fixed
close 31660 26.2
quit

Gemini Lasswell <gazally <at> runbox.com> writes:
>
> Here's a patch to eieio.texi which makes the examples work, and adds a
> suggestion to check for name conflicts to the description of 'defclass':
  
> +When defining a class, @eieio{} overwrites any preexisting variable or
> +function bindings for the symbol @var{class-name}, which may lead to
> +undesired consequences.  Before naming a new class, you should check
> +for name conflicts.

I added another sentence here about using package prefixes, and pushed
to emacs-26.

8d2f1df51a 2019-04-09T18:53:43-04:00 "Address name conflicts in EIEIO documentation (bug#31660)"




Added tag(s) fixed. Request was from Noam Postavsky <npostavs <at> gmail.com> to control <at> debbugs.gnu.org. (Tue, 09 Apr 2019 23:11:02 GMT) Full text and rfc822 format available.

bug marked as fixed in version 26.2, send any further explanations to 31660 <at> debbugs.gnu.org and Gemini Lasswell <gazally <at> runbox.com> Request was from Noam Postavsky <npostavs <at> gmail.com> to control <at> debbugs.gnu.org. (Tue, 09 Apr 2019 23:11:03 GMT) Full text and rfc822 format available.

bug archived. Request was from Debbugs Internal Request <help-debbugs <at> gnu.org> to internal_control <at> debbugs.gnu.org. (Wed, 08 May 2019 11:24:06 GMT) Full text and rfc822 format available.

This bug report was last modified 4 years and 327 days ago.

Previous Next


GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.