merge 8.7

6 files changed, 351 insertions, 155 deletions

diff --git a/doc/Method.3 b/doc/Method.3
index 225da00..9e636a1 100644
--- a/doc/Method.3
+++ b/doc/Method.3
@@ -9,18 +9,18 @@
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
-Tcl_ClassSetConstructor, Tcl_ClassSetDestructor, Tcl_MethodDeclarerClass, Tcl_MethodDeclarerObject, Tcl_MethodIsPublic, Tcl_MethodIsType, Tcl_MethodName, Tcl_NewInstanceMethod, Tcl_NewMethod, Tcl_ObjectContextInvokeNext, Tcl_ObjectContextIsFiltering, Tcl_ObjectContextMethod, Tcl_ObjectContextObject, Tcl_ObjectContextSkippedArgs \- manipulate methods and method-call contexts
+Tcl_ClassSetConstructor, Tcl_ClassSetDestructor, Tcl_MethodDeclarerClass, Tcl_MethodDeclarerObject, Tcl_MethodIsPublic, Tcl_MethodIsPrivate, Tcl_MethodIsType, Tcl_MethodName, Tcl_NewInstanceMethod, Tcl_NewMethod, Tcl_ObjectContextInvokeNext, Tcl_ObjectContextIsFiltering, Tcl_ObjectContextMethod, Tcl_ObjectContextObject, Tcl_ObjectContextSkippedArgs \- manipulate methods and method-call contexts
 .SH SYNOPSIS
 .nf
 \fB#include <tclOO.h>\fR
 .sp
 Tcl_Method
-\fBTcl_NewMethod\fR(\fIinterp, class, nameObj, isPublic,
-              methodTypePtr, clientData\fR)
+\fBTcl_NewMethod\fR(\fIinterp, class, nameObj, flags, methodTypePtr,
+              clientData\fR)
 .sp
 Tcl_Method
-\fBTcl_NewInstanceMethod\fR(\fIinterp, object, nameObj, isPublic,
-                      methodTypePtr, clientData\fR)
+\fBTcl_NewInstanceMethod\fR(\fIinterp, object, nameObj, flags, methodTypePtr,
+                      clientData\fR)
 .sp
 \fBTcl_ClassSetConstructor\fR(\fIinterp, class, method\fR)
 .sp
@@ -35,8 +35,13 @@ Tcl_Object
 Tcl_Obj *
 \fBTcl_MethodName\fR(\fImethod\fR)
 .sp
+.VS TIP500
 int
 \fBTcl_MethodIsPublic\fR(\fImethod\fR)
+.VE TIP500
+.sp
+int
+\fBTcl_MethodIsPrivate\fR(\fImethod\fR)
 .sp
 int
 \fBTcl_MethodIsType\fR(\fImethod, methodTypePtr, clientDataPtr\fR)
@@ -66,10 +71,15 @@ The class to create the method in.
 .AP Tcl_Obj *nameObj in
 The name of the method to create. Should not be NULL unless creating
 constructors or destructors.
-.AP int isPublic in
-A flag saying what the visibility of the method is. The only supported public
-values of this flag are 0 for a non-exported method, and 1 for an exported
-method.
+.AP int flags in
+A flag saying (currently) what the visibility of the method is. The supported
+public values of this flag are \fBTCL_OO_METHOD_PUBLIC\fR (which is fixed at 1
+for backward compatibility) for an exported method,
+\fBTCL_OO_METHOD_UNEXPORTED\fR (which is fixed at 0 for backward
+compatibility) for a non-exported method,
+.VS TIP500
+and \fBTCL_OO_METHOD_PRIVATE\fR for a private method.
+.VE TIP500
 .AP Tcl_MethodType *methodTypePtr in
 A description of the type of the method to create, or the type of method to
 compare against.
@@ -105,8 +115,12 @@ Given a method, the entity that declared it can be found using
 attached to (or NULL if the method is not attached to any class) and
 \fBTcl_MethodDeclarerObject\fR which returns the object that the method is
 attached to (or NULL if the method is not attached to an object). The name of
-the method can be retrieved with \fBTcl_MethodName\fR and whether the method
-is exported is retrieved with \fBTcl_MethodIsPublic\fR. The type of the method
+the method can be retrieved with \fBTcl_MethodName\fR, whether the method
+is exported is retrieved with \fBTcl_MethodIsPublic\fR,
+.VS TIP500
+and whether the method is private is retrieved with \fBTcl_MethodIsPrivate\fR.
+.VE TIP500
+The type of the method
 can also be introspected upon to a limited degree; the function
 \fBTcl_MethodIsType\fR returns whether a method is of a particular type,
 assigning the per-method \fIclientData\fR to the variable pointed to by
@@ -117,8 +131,12 @@ Methods are created by \fBTcl_NewMethod\fR and \fBTcl_NewInstanceMethod\fR,
 which
 create a method attached to a class or an object respectively. In both cases,
 the \fInameObj\fR argument gives the name of the method to create, the
-\fIisPublic\fR argument states whether the method should be exported
-initially, the \fImethodTypePtr\fR argument describes the implementation of
+\fIflags\fR argument states whether the method should be exported
+initially
+.VS TIP500
+or be marked as a private method,
+.VE TIP500
+the \fImethodTypePtr\fR argument describes the implementation of
 the method (see the \fBMETHOD TYPES\fR section below) and the \fIclientData\fR
 argument gives some implementation-specific data that is passed on to the
 implementation of the method when it is called.
diff --git a/doc/define.n b/doc/define.n
index c836c2f..b489e5f 100644
--- a/doc/define.n
+++ b/doc/define.n
@@ -82,17 +82,14 @@ by a superclass; subclass exports override superclass visibility, and may in
 turn be overridden by instances.
 .TP
 \fBfilter\fR ?\fI\-slotOperation\fR? ?\fImethodName ...\fR?
-.VS
+.
 This slot (see \fBSLOTTED DEFINITIONS\fR below)
-.VE
 sets or updates the list of method names that are used to guard whether
 method call to instances of the class may be called and what the method's
 results are. Each \fImethodName\fR names a single filtering method (which may
 be exposed or not exposed); it is not an error for a non-existent method to be
 named since they may be defined by subclasses.
-.VS
 By default, this slot works by appending.
-.VE
 .TP
 \fBforward\fI name cmdName \fR?\fIarg ...\fR?
 .
@@ -105,6 +102,13 @@ fully-qualified, the command will be searched for in each object's namespace,
 using the instances' namespace's path, or by looking in the global namespace.
 The method will be exported if \fIname\fR starts with a lower-case letter, and
 non-exported otherwise.
+.RS
+.PP
+.VS TIP500
+If in a private definition context (see the \fBprivate\fR definition command,
+below), this command creates private forwarded methods.
+.VE TIP500
+.RE
 .TP
 \fBmethod\fI name argList bodyScript\fR
 .
@@ -117,17 +121,40 @@ be a namespace that is unique to the current object. The method will be
 exported if \fIname\fR starts with a lower-case letter, and non-exported
 otherwise; this behavior can be overridden via \fBexport\fR and
 \fBunexport\fR.
+.RS
+.PP
+.VS TIP500
+If in a private definition context (see the \fBprivate\fR definition command,
+below), this command creates private procedure-like methods.
+.VE TIP500
+.RE
 .TP
 \fBmixin\fR ?\fI\-slotOperation\fR? ?\fIclassName ...\fR?
-.VS
+.
 This slot (see \fBSLOTTED DEFINITIONS\fR below)
-.VE
 sets or updates the list of additional classes that are to be mixed into
 all the instances of the class being defined. Each \fIclassName\fR argument
 names a single class that is to be mixed in.
-.VS
 By default, this slot works by replacement.
-.VE
+.TP
+\fBprivate \fIcmd arg...\fR
+.TP
+\fBprivate \fIscript\fR
+.
+.VS TIP500
+This evaluates the \fIscript\fR (or the list of command and arguments given by
+\fIcmd\fR and \fIarg\fRs) in a context where the definitions made on the
+current class will be private definitions.
+.RS
+.PP
+The following class definition commands are affected by \fBprivate\fR:
+\fBforward\fR, \fBmethod\fR, \fBself\fR, and \fBvariable\fR. Nesting
+\fBprivate\fR inside \fBprivate\fR has no cumulative effect; the innermost
+definition context is just a private definition context. All other definition
+commands have no difference in behavior when used in a private definition
+context.
+.RE
+.VE TIP500
 .TP
 \fBrenamemethod\fI fromName toName\fR
 .
@@ -159,21 +186,23 @@ operates identically to
 If no arguments at all are used, this gives the name of the class currently
 being configured.
 .VE TIP470
+.VS TIP500
+If in a private definition context (see the \fBprivate\fR definition command,
+below), the definitions on the class object will also be made in a private
+definition context.
+.VE TIP500
 .RE
 .TP
 \fBsuperclass\fR ?\fI\-slotOperation\fR? ?\fIclassName ...\fR?
-.VS
+.
 This slot (see \fBSLOTTED DEFINITIONS\fR below)
-.VE
 allows the alteration of the superclasses of the class being defined.
 Each \fIclassName\fR argument names one class that is to be a superclass of
 the defined class. Note that objects must not be changed from being classes to
 being non-classes or vice-versa, that an empty parent class is equivalent to
 \fBoo::object\fR, and that the parent classes of \fBoo::object\fR and
 \fBoo::class\fR may not be modified.
-.VS
 By default, this slot works by replacement.
-.VE
 .TP
 \fBunexport\fI name \fR?\fIname ...\fR?
 .
@@ -185,18 +214,31 @@ actually defined by a superclass; subclass unexports override superclass
 visibility, and may be overridden by instance unexports.
 .TP
 \fBvariable\fR ?\fI\-slotOperation\fR? ?\fIname ...\fR?
-.VS
+.
 This slot (see \fBSLOTTED DEFINITIONS\fR below) arranges for each of the named
 variables to be automatically made
 available in the methods, constructor and destructor declared by the class
 being defined. Each variable name must not have any namespace
 separators and must not look like an array access. All variables will be
-actually present in the instance object on which the method is executed. Note
+actually present in the namespace of the instance object on which the method
+is executed. Note
 that the variable lists declared by a superclass or subclass are completely
 disjoint, as are variable lists declared by instances; the list of variable
 names is just for methods (and constructors and destructors) declared by this
 class. By default, this slot works by appending.
-.VE
+.RS
+.PP
+.VS TIP500
+If in a private definition context (see the \fBprivate\fR definition command,
+below), this slot manipulates the list of private variable bindings for this
+class. In a private variable binding, the name of the variable within the
+instance object is different to the name given in the definition; the name
+used in the definition is the name that you use to access the variable within
+the methods of this class, and the name of the variable in the instance
+namespace has a unique prefix that makes accidental use from other classes
+extremely unlikely.
+.VE TIP500
+.RE
 .SS "CONFIGURING OBJECTS"
 .PP
 The following commands are supported in the \fIdefScript\fR for
@@ -223,18 +265,15 @@ being defined. Note that the methods themselves may be actually defined by a
 class or superclass; object exports override class visibility.
 .TP
 \fBfilter\fR ?\fI\-slotOperation\fR? ?\fImethodName ...\fR?
-.VS
+.
 This slot (see \fBSLOTTED DEFINITIONS\fR below)
-.VE
 sets or updates the list of method names that are used to guard whether a
 method call to the object may be called and what the method's results are.
 Each \fImethodName\fR names a single filtering method (which may be exposed or
 not exposed); it is not an error for a non-existent method to be named. Note
 that the actual list of filters also depends on the filters set upon any
 classes that the object is an instance of.
-.VS
 By default, this slot works by appending.
-.VE
 .TP
 \fBforward\fI name cmdName \fR?\fIarg ...\fR?
 .
@@ -244,6 +283,13 @@ additional arguments, \fIarg\fR etc., added before those arguments specified
 by the caller of the method. Forwarded methods should be deleted using the
 \fBmethod\fR subcommand. The method will be exported if \fIname\fR starts with
 a lower-case letter, and non-exported otherwise.
+.RS
+.PP
+.VS TIP500
+If in a private definition context (see the \fBprivate\fR definition command,
+below), this command creates private forwarded methods.
+.VE TIP500
+.RE
 .TP
 \fBmethod\fI name argList bodyScript\fR
 .
@@ -254,17 +300,38 @@ method will be \fIbodyScript\fR. When the body of the method is evaluated, the
 current namespace of the method will be a namespace that is unique to the
 object. The method will be exported if \fIname\fR starts with a lower-case
 letter, and non-exported otherwise.
+.RS
+.PP
+.VS TIP500
+If in a private definition context (see the \fBprivate\fR definition command,
+below), this command creates private procedure-like methods.
+.VE TIP500
+.RE
 .TP
 \fBmixin\fR ?\fI\-slotOperation\fR? ?\fIclassName ...\fR?
-.VS
+.
 This slot (see \fBSLOTTED DEFINITIONS\fR below)
-.VE
 sets or updates a per-object list of additional classes that are to be
 mixed into the object. Each argument, \fIclassName\fR, names a single class
 that is to be mixed in.
-.VS
 By default, this slot works by replacement.
-.VE
+.TP
+\fBprivate \fIcmd arg...\fR
+.TP
+\fBprivate \fIscript\fR
+.VS TIP500
+This evaluates the \fIscript\fR (or the list of command and arguments given by
+\fIcmd\fR and \fIarg\fRs) in a context where the definitions made on the
+current object will be private definitions.
+.RS
+.PP
+The following class definition commands are affected by \fBprivate\fR:
+\fBforward\fR, \fBmethod\fR, and \fBvariable\fR. Nesting \fBprivate\fR inside
+\fBprivate\fR has no cumulative effect; the innermost definition context is
+just a private definition context. All other definition commands have no
+difference in behavior when used in a private definition context.
+.RE
+.VE TIP500
 .TP
 \fBrenamemethod\fI fromName toName\fR
 .
@@ -275,7 +342,6 @@ that the object is an instance of. Does not change the export status of the
 method; if it was exported before, it will be afterwards.
 .TP
 \fBself \fR
-.
 .VS TIP470
 This gives the name of the object currently being configured.
 .VE TIP470
@@ -289,15 +355,42 @@ object being defined. Note that the methods themselves may be actually defined
 by a class; instance unexports override class visibility.
 .TP
 \fBvariable\fR ?\fI\-slotOperation\fR? ?\fIname ...\fR?
-.VS
+.
 This slot (see \fBSLOTTED DEFINITIONS\fR below) arranges for each of the named
 variables to be automatically made available in the methods declared by the
 object being defined.  Each variable name must not have any namespace
 separators and must not look like an array access. All variables will be
-actually present in the object on which the method is executed. Note that the
+actually present in the namespace of the object on which the method is
+executed. Note that the
 variable lists declared by the classes and mixins of which the object is an
 instance are completely disjoint; the list of variable names is just for
 methods declared by this object. By default, this slot works by appending.
+.RS
+.PP
+.VS TIP500
+If in a private definition context (see the \fBprivate\fR definition command,
+below), this slot manipulates the list of private variable bindings for this
+object.  In a private variable binding, the name of the variable within the
+instance object is different to the name given in the definition; the name
+used in the definition is the name that you use to access the variable within
+the methods of this instance object, and the name of the variable in the
+instance namespace has a unique prefix that makes accidental use from
+superclass methods extremely unlikely.
+.VE TIP500
+.RE
+.SH "PRIVATE METHODS"
+.VS TIP500
+When a class or instance has a private method, that private method can only be
+invoked from within methods of that class or instance. Other callers of the
+object's methods \fIcannot\fR invoke private methods, it is as if the private
+methods do not exist. However, a private method of a class \fIcan\fR be
+invoked from the class's methods when those methods are being used on another
+instance object; this means that a class can use them to coordinate behaviour
+between several instances of itself without interfering with how other
+classes (especially either subclasses or superclasses) interact. Private
+methods precede all mixed in classes in the method call order (as reported by
+\fBself call\fR).
+.VE TIP500
 .SH "SLOTTED DEFINITIONS"
 Some of the configurable definitions of a class or object are \fIslotted
 definitions\fR. This means that the configuration is implemented by a slot
@@ -305,20 +398,17 @@ object, that is an instance of the class \fBoo::Slot\fR, which manages a list
 of values (class names, variable names, etc.) that comprises the contents of
 the slot. The class defines three operations (as methods) that may be done on
 the slot:
-.VE
 .TP
 \fIslot\fR \fB\-append\fR ?\fImember ...\fR?
-.VS
+.
 This appends the given \fImember\fR elements to the slot definition.
-.VE
 .TP
 \fIslot\fR \fB\-clear\fR
-.VS
+.
 This sets the slot definition to the empty list.
-.VE
 .TP
 \fIslot\fR \fB\-set\fR ?\fImember ...\fR?
-.VS
+.
 This replaces the slot definition with the given \fImember\fR elements.
 .PP
 A consequence of this is that any use of a slot's default operation where the
@@ -331,17 +421,15 @@ which is forwarded to the default operation of the slot (thus, for the class
 slot, this is forwarded to
 .QW "\fBmy \-append\fR" ),
 and these methods which provide the implementation interface:
-.VE
 .TP
 \fIslot\fR \fBGet\fR
-.VS
+.
 Returns a list that is the current contents of the slot. This method must
 always be called from a stack frame created by a call to \fBoo::define\fR or
 \fBoo::objdefine\fR.
-.VE
 .TP
 \fIslot\fR \fBSet \fIelementList\fR
-.VS
+.
 Sets the contents of the slot to the list \fIelementList\fR and returns the
 empty string. This method must always be called from a stack frame created by
 a call to \fBoo::define\fR or \fBoo::objdefine\fR.
@@ -352,7 +440,6 @@ an unknown method handler to tie all these pieces together, and they hide
 their \fBdestroy\fR method so that it is not invoked inadvertently. It is
 \fIrecommended\fR that any user changes to the slot mechanism be restricted to
 defining new operations whose names start with a hyphen.
-.VE
 .SH EXAMPLES
 This example demonstrates how to use both forms of the \fBoo::define\fR and
 \fBoo::objdefine\fR commands (they work in the same way), as well as
diff --git a/doc/info.n b/doc/info.n
index c3a62c9..02470af 100644
--- a/doc/info.n
+++ b/doc/info.n
@@ -35,10 +35,9 @@ Returns the body of procedure \fIprocname\fR.  \fIProcname\fR must be
 the name of a Tcl command procedure.
 .TP
 \fBinfo class\fI subcommand class\fR ?\fIarg ...\fR
-.VS 8.6
+.
 Returns information about the class, \fIclass\fR. The \fIsubcommand\fRs are
 described in \fBCLASS INTROSPECTION\fR below.
-.VE 8.6
 .TP
 \fBinfo cmdcount\fR
 .
@@ -78,11 +77,10 @@ command is not complete, the script can delay evaluating it until additional
 lines have been typed to complete the command.
 .TP
 \fBinfo coroutine\fR
-.VS 8.6
+.
 Returns the name of the currently executing \fBcoroutine\fR, or the empty
 string if either no coroutine is currently executing, or the current coroutine
 has been deleted (but has not yet returned or yielded since deletion).
-.VE 8.6
 .TP
 \fBinfo default \fIprocname arg varname\fR
 .
@@ -93,7 +91,7 @@ Otherwise it returns \fB1\fR and places the default value of \fIarg\fR
 into variable \fIvarname\fR.
 .TP
 \fBinfo errorstack \fR?\fIinterp\fR?
-.VS 8.6
+.
 Returns, in a form that is programmatically easy to parse, the function names
 and arguments at each level from the call stack of the last error in the given
 \fIinterp\fR, or in the current one if not specified.
@@ -118,7 +116,6 @@ options dictionary returned by 3-argument \fBcatch\fR; \fBinfo errorstack\fR
 is a convenient way of retrieving it for uncaught errors at top-level in an
 interactive \fBtclsh\fR.
 .RE
-.VE 8.6
 .TP
 \fBinfo exists \fIvarName\fR
 .
@@ -329,10 +326,9 @@ was invoked.  If Tcl was unable to identify the file, then an empty
 string is returned.
 .TP
 \fBinfo object\fI subcommand object\fR ?\fIarg ...\fR
-.VS 8.6
+.
 Returns information about the object, \fIobject\fR. The \fIsubcommand\fRs are
 described in \fBOBJECT INTROSPECTION\fR below.
-.VE 8.6
 .TP
 \fBinfo patchlevel\fR
 .
@@ -399,20 +395,22 @@ Note that a currently-visible variable may not yet
 if it has not
 been set (e.g. a variable declared but not set by \fBvariable\fR).
 .SS "CLASS INTROSPECTION"
-.VS 8.6
 .PP
 The following \fIsubcommand\fR values are supported by \fBinfo class\fR:
-.VE 8.6
 .TP
 \fBinfo class call\fI class method\fR
-.VS
+.
 Returns a description of the method implementations that are used to provide a
 stereotypical instance of \fIclass\fR's implementation of \fImethod\fR
 (stereotypical instances being objects instantiated by a class without having
 any object-specific definitions added). This consists of a list of lists of
 four elements, where each sublist consists of a word that describes the
 general type of method implementation (being one of \fBmethod\fR for an
-ordinary method, \fBfilter\fR for an applied filter, and \fBunknown\fR for a
+ordinary method, \fBfilter\fR for an applied filter,
+.VS TIP500
+\fBprivate\fR for a private method,
+.VE TIP500
+and \fBunknown\fR for a
 method that is invoked as part of unknown method handling), a word giving the
 name of the particular method invoked (which is always the same as
 \fImethod\fR for the \fBmethod\fR type, and
@@ -423,122 +421,149 @@ implementation (see \fBinfo class methodtype\fR).
 .RS
 .PP
 Note that there is no inspection of whether the method implementations
-actually use \fBnext\fR to transfer control along the call chain.
+actually use \fBnext\fR to transfer control along the call chain,
+.VS TIP500
+and the call chains that this command files do not actually contain private
+methods.
+.VE TIP500
 .RE
-.VE 8.6
 .TP
 \fBinfo class constructor\fI class\fR
-.VS 8.6
+.
 This subcommand returns a description of the definition of the constructor of
 class \fIclass\fR. The definition is described as a two element list; the first
 element is the list of arguments to the constructor in a form suitable for
 passing to another call to \fBproc\fR or a method definition, and the second
 element is the body of the constructor. If no constructor is present, this
 returns the empty list.
-.VE 8.6
 .TP
 \fBinfo class definition\fI class method\fR
-.VS 8.6
+.
 This subcommand returns a description of the definition of the method named
 \fImethod\fR of class \fIclass\fR. The definition is described as a two element
 list; the first element is the list of arguments to the method in a form
 suitable for passing to another call to \fBproc\fR or a method definition, and
 the second element is the body of the method.
-.VE 8.6
 .TP
 \fBinfo class destructor\fI class\fR
-.VS 8.6
+.
 This subcommand returns the body of the destructor of class \fIclass\fR. If no
 destructor is present, this returns the empty string.
-.VE 8.6
 .TP
 \fBinfo class filters\fI class\fR
-.VS 8.6
+.
 This subcommand returns the list of filter methods set on the class.
-.VE 8.6
 .TP
 \fBinfo class forward\fI class method\fR
-.VS 8.6
+.
 This subcommand returns the argument list for the method forwarding called
 \fImethod\fR that is set on the class called \fIclass\fR.
-.VE 8.6
 .TP
 \fBinfo class instances\fI class\fR ?\fIpattern\fR?
-.VS 8.6
+.
 This subcommand returns a list of instances of class \fIclass\fR. If the
 optional \fIpattern\fR argument is present, it constrains the list of returned
 instances to those that match it according to the rules of \fBstring match\fR.
-.VE 8.6
 .TP
 \fBinfo class methods\fI class\fR ?\fIoptions...\fR?
-.VS 8.6
+.
 This subcommand returns a list of all public (i.e. exported) methods of the
 class called \fIclass\fR. Any of the following \fIoption\fRs may be
 specified, controlling exactly which method names are returned:
 .RS
-.VE 8.6
 .TP
 \fB\-all\fR
-.VS 8.6
-If the \fB\-all\fR flag is given, the list of methods will include those
+.
+If the \fB\-all\fR flag is given,
+.VS TIP500
+and the \fB\-scope\fR flag is not given,
+.VE TIP500
+the list of methods will include those
 methods defined not just by the class, but also by the class's superclasses
 and mixins.
-.VE 8.6
 .TP
 \fB\-private\fR
-.VS 8.6
-If the \fB\-private\fR flag is given, the list of methods will also include
-the private (i.e. non-exported) methods of the class (and superclasses and
+.
+If the \fB\-private\fR flag is given,
+.VS TIP500
+and the \fB\-scope\fR flag is not given,
+.VE TIP500
+the list of methods will also include
+the non-exported methods of the class (and superclasses and
 mixins, if \fB\-all\fR is also given).
+.VS TIP500
+Note that this naming is an unfortunate clash with true private methods; this
+option name is retained for backward compatibility.
+.VE TIP500
+.TP
+\fB\-scope\fI scope\fR
+.VS TIP500
+Returns a list of all methods on \fIclass\fR that have the given visibility
+\fIscope\fR.  When this option is supplied, both the \fB\-all\fR and
+\fB\-private\fR options are ignored. The valid values for \fIscope\fR are:
+.RS
+.IP \fBpublic\fR 3
+Only methods with \fIpublic\fR scope (i.e., callable from anywhere by any instance
+of this class) are to be returned.
+.IP \fBunexported\fR 3
+Only methods with \fIunexported\fR scope (i.e., only callable via \fBmy\fR) are to
+be returned.
+.IP \fBprivate\fR 3
+Only methods with \fIprivate\fR scope (i.e., only callable from within this class's
+methods) are to be returned.
+.RE
+.VE TIP500
 .RE
-.VE 8.6
 .TP
 \fBinfo class methodtype\fI class method\fR
-.VS 8.6
+.
 This subcommand returns a description of the type of implementation used for
 the method named \fImethod\fR of class \fIclass\fR. When the result is
 \fBmethod\fR, further information can be discovered with \fBinfo class
 definition\fR, and when the result is \fBforward\fR, further information can
 be discovered with \fBinfo class forward\fR.
-.VE 8.6
 .TP
 \fBinfo class mixins\fI class\fR
-.VS 8.6
+.
 This subcommand returns a list of all classes that have been mixed into the
 class named \fIclass\fR.
-.VE 8.6
 .TP
 \fBinfo class subclasses\fI class\fR ?\fIpattern\fR?
-.VS 8.6
+.
 This subcommand returns a list of direct subclasses of class \fIclass\fR. If
 the optional \fIpattern\fR argument is present, it constrains the list of
 returned classes to those that match it according to the rules of
 \fBstring match\fR.
-.VE 8.6
 .TP
 \fBinfo class superclasses\fI class\fR
-.VS 8.6
+.
 This subcommand returns a list of direct superclasses of class \fIclass\fR in
 inheritance precedence order.
-.VE 8.6
 .TP
-\fBinfo class variables\fI class\fR
-.VS 8.6
+\fBinfo class variables\fI class\fR ?\fB\-private\fR?
+.
 This subcommand returns a list of all variables that have been declared for
 the class named \fIclass\fR (i.e. that are automatically present in the
 class's methods, constructor and destructor).
+.VS TIP500
+If the \fB\-private\fR option is specified, this lists the private variables
+declared instead.
+.VE TIP500
 .SS "OBJECT INTROSPECTION"
 .PP
 The following \fIsubcommand\fR values are supported by \fBinfo object\fR:
-.VE 8.6
 .TP
 \fBinfo object call\fI object method\fR
-.VS 8.6
+.
 Returns a description of the method implementations that are used to provide
 \fIobject\fR's implementation of \fImethod\fR.  This consists of a list of
 lists of four elements, where each sublist consists of a word that describes
 the general type of method implementation (being one of \fBmethod\fR for an
-ordinary method, \fBfilter\fR for an applied filter, and \fBunknown\fR for a
+ordinary method, \fBfilter\fR for an applied filter,
+.VS TIP500
+\fBprivate\fR for a private method,
+.VE TIP500
+and \fBunknown\fR for a
 method that is invoked as part of unknown method handling), a word giving the
 name of the particular method invoked (which is always the same as
 \fImethod\fR for the \fBmethod\fR type, and
@@ -550,128 +575,160 @@ implementation (see \fBinfo object methodtype\fR).
 .RS
 .PP
 Note that there is no inspection of whether the method implementations
-actually use \fBnext\fR to transfer control along the call chain.
+actually use \fBnext\fR to transfer control along the call chain,
+.VS TIP500
+and the call chains that this command files do not actually contain private
+methods.
+.VE TIP500
 .RE
-.VE 8.6
 .TP
 \fBinfo object class\fI object\fR ?\fIclassName\fR?
-.VS 8.6
+.
 If \fIclassName\fR is unspecified, this subcommand returns class of the
 \fIobject\fR object. If \fIclassName\fR is present, this subcommand returns a
 boolean value indicating whether the \fIobject\fR is of that class.
-.VE 8.6
+.TP
+\fBinfo object creationid\fI object\fR
+.VS TIP500
+Returns the unique creation identifier for the \fIobject\fR object. This
+creation identifier is unique to the object (within a Tcl interpreter) and
+cannot be controlled at object creation time or altered afterwards.
+.RS
+.PP
+\fIImplementation note:\fR the creation identifier is used to generate unique
+identifiers associated with the object, especially for private variables.
+.RE
+.VE TIP500
 .TP
 \fBinfo object definition\fI object method\fR
-.VS 8.6
+.
 This subcommand returns a description of the definition of the method named
 \fImethod\fR of object \fIobject\fR. The definition is described as a two
 element list; the first element is the list of arguments to the method in a
 form suitable for passing to another call to \fBproc\fR or a method definition,
 and the second element is the body of the method.
-.VE 8.6
 .TP
 \fBinfo object filters\fI object\fR
-.VS 8.6
+.
 This subcommand returns the list of filter methods set on the object.
-.VE 8.6
 .TP
 \fBinfo object forward\fI object method\fR
-.VS 8.6
+.
 This subcommand returns the argument list for the method forwarding called
 \fImethod\fR that is set on the object called \fIobject\fR.
-.VE 8.6
 .TP
 \fBinfo object isa\fI category object\fR ?\fIarg\fR?
-.VS 8.6
+.
 This subcommand tests whether an object belongs to a particular category,
 returning a boolean value that indicates whether the \fIobject\fR argument
 meets the criteria for the category. The supported categories are:
-.VE 8.6
 .RS
 .TP
 \fBinfo object isa class\fI object\fR
-.VS 8.6
+.
 This returns whether \fIobject\fR is a class (i.e. an instance of
 \fBoo::class\fR or one of its subclasses).
-.VE 8.6
 .TP
 \fBinfo object isa metaclass\fI object\fR
-.VS 8.6
+.
 This returns whether \fIobject\fR is a class that can manufacture classes
 (i.e. is \fBoo::class\fR or a subclass of it).
-.VE 8.6
 .TP
 \fBinfo object isa mixin\fI object class\fR
-.VS 8.6
+.
 This returns whether \fIclass\fR is directly mixed into \fIobject\fR.
-.VE 8.6
 .TP
 \fBinfo object isa object\fI object\fR
-.VS 8.6
+.
 This returns whether \fIobject\fR really is an object.
-.VE 8.6
 .TP
 \fBinfo object isa typeof\fI object class\fR
-.VS 8.6
+.
 This returns whether \fIclass\fR is the type of \fIobject\fR (i.e. whether
 \fIobject\fR is an instance of \fIclass\fR or one of its subclasses, whether
 direct or indirect).
 .RE
-.VE 8.6
 .TP
 \fBinfo object methods\fI object\fR ?\fIoption...\fR?
-.VS 8.6
+.
 This subcommand returns a list of all public (i.e. exported) methods of the
 object called \fIobject\fR. Any of the following \fIoption\fRs may be
 specified, controlling exactly which method names are returned:
 .RS
-.VE 8.6
 .TP
 \fB\-all\fR
-.VS 8.6
-If the \fB\-all\fR flag is given, the list of methods will include those
+.
+If the \fB\-all\fR flag is given,
+.VS TIP500
+and the \fB\-scope\fR flag is not given,
+.VE TIP500
+the list of methods will include those
 methods defined not just by the object, but also by the object's class and
 mixins, plus the superclasses of those classes.
-.VE 8.6
 .TP
 \fB\-private\fR
-.VS 8.6
-If the \fB\-private\fR flag is given, the list of methods will also include
-the private (i.e. non-exported) methods of the object (and classes, if
+.
+If the \fB\-private\fR flag is given,
+.VS TIP500
+and the \fB\-scope\fR flag is not given,
+.VE TIP500
+the list of methods will also include
+the non-exported methods of the object (and classes, if
 \fB\-all\fR is also given).
+.VS TIP500
+Note that this naming is an unfortunate clash with true private methods; this
+option name is retained for backward compatibility.
+.VE TIP500
+.TP
+\fB\-scope\fI scope\fR
+.VS TIP500
+Returns a list of all methods on \fIobject\fR that have the given visibility
+\fIscope\fR.  When this option is supplied, both the \fB\-all\fR and
+\fB\-private\fR options are ignored. The valid values for \fIscope\fR are:
+.RS
+.IP \fBpublic\fR 3
+Only methods with \fIpublic\fR scope (i.e., callable from anywhere) are to be
+returned.
+.IP \fBunexported\fR 3
+Only methods with \fIunexported\fR scope (i.e., only callable via \fBmy\fR) are to
+be returned.
+.IP \fBprivate\fR 3
+Only methods with \fIprivate\fR scope (i.e., only callable from within this object's
+instance methods) are to be returned.
+.RE
+.VE TIP500
 .RE
-.VE 8.6
 .TP
 \fBinfo object methodtype\fI object method\fR
-.VS 8.6
+.
 This subcommand returns a description of the type of implementation used for
 the method named \fImethod\fR of object \fIobject\fR. When the result is
 \fBmethod\fR, further information can be discovered with \fBinfo object
 definition\fR, and when the result is \fBforward\fR, further information can
 be discovered with \fBinfo object forward\fR.
-.VE 8.6
 .TP
 \fBinfo object mixins\fI object\fR
-.VS 8.6
+.
 This subcommand returns a list of all classes that have been mixed into the
 object named \fIobject\fR.
-.VE 8.6
 .TP
 \fBinfo object namespace\fI object\fR
-.VS 8.6
+.
 This subcommand returns the name of the internal namespace of the object named
 \fIobject\fR.
-.VE 8.6
 .TP
-\fBinfo object variables\fI object\fR
-.VS 8.6
+\fBinfo object variables\fI object\fRR ?\fB\-private\fR?
+.
 This subcommand returns a list of all variables that have been declared for
 the object named \fIobject\fR (i.e. that are automatically present in the
 object's methods).
-.VE 8.6
+.VS TIP500
+If the \fB\-private\fR option is specified, this lists the private variables
+declared instead.
+.VE TIP500
 .TP
 \fBinfo object vars\fI object\fR ?\fIpattern\fR?
-.VS 8.6
+.
 This subcommand returns a list of all variables in the private namespace of
 the object named \fIobject\fR. If the optional \fIpattern\fR argument is
 given, it is a filter (in the syntax of a \fBstring match\fR glob pattern)
@@ -680,7 +737,6 @@ from the list returned by \fBinfo object variables\fR; that can include
 variables that are currently unset, whereas this can include variables that
 are not automatically included by any of \fIobject\fR's methods (or those of
 its class, superclasses or mixins).
-.VE 8.6
 .SH EXAMPLES
 .PP
 This command prints out a procedure suitable for saving in a Tcl
@@ -703,7 +759,6 @@ proc printProc {procName} {
 }
 .CE
 .SS "EXAMPLES WITH OBJECTS"
-.VS 8.6
 .PP
 Every object necessarily knows what its class is; this information is
 trivially extractable through introspection:
@@ -724,8 +779,10 @@ method and get how it is defined. This procedure illustrates how:
 proc getDef {obj method} {
     foreach inf [\fBinfo object call\fR $obj $method] {
         lassign $inf calltype name locus methodtype
+
         # Assume no forwards or filters, and hence no $calltype
         # or $methodtype checks...
+
         if {$locus eq "object"} {
             return [\fBinfo object definition\fR $obj $name]
         } else {
@@ -748,7 +805,9 @@ proc getDef {obj method} {
         # Assume no forwards
         return [\fBinfo object definition\fR $obj $method]
     }
+
     set cls [\fBinfo object class\fR $obj]
+
     while {$method ni [\fBinfo class methods\fR $cls]} {
         # Assume the simple case
         set cls [lindex [\fBinfo class superclass\fR $cls] 0]
@@ -756,22 +815,17 @@ proc getDef {obj method} {
             error "no definition for $method"
         }
     }
+
     # Assume no forwards
     return [\fBinfo class definition\fR $cls $method]
 }
 .CE
-.VE 8.6
 .SH "SEE ALSO"
-.VS 8.6
 global(n), oo::class(n), oo::define(n), oo::object(n), proc(n), self(n),
-.VE 8.6
 tcl_library(n), tcl_patchLevel(n), tcl_version(n)
 .SH KEYWORDS
 command, information, interpreter, introspection, level, namespace,
-.VS 8.6
-object,
-.VE 8.6
-procedure, variable
+object, procedure, variable
 '\" Local Variables:
 '\" mode: nroff
 '\" fill-column: 78
diff --git a/doc/my.n b/doc/my.n
index 2a9769b..26d861a 100644
--- a/doc/my.n
+++ b/doc/my.n
@@ -19,13 +19,18 @@ package require TclOO
 .BE
 .SH DESCRIPTION
 .PP
-The \fBmy\fR command is used to allow methods of objects to invoke any method
+The \fBmy\fR command is used to allow methods of objects to invoke methods
 of the object (or its class). In particular, the set of valid values for
 \fImethodName\fR is the set of all methods supported by an object and its
-superclasses, including those that are not exported. The object upon which the
-method is invoked is always the one that is the current context of the method
-(i.e. the object that is returned by \fBself object\fR) from which the
-\fBmy\fR command is invoked.
+superclasses, including those that are not exported
+.VS TIP500
+and private methods of the object or class when used within another method
+defined by that object or class.
+.VE TIP500
+The object upon which the method is invoked is the one that owns the namespace
+that the \fBmy\fR command is contained in initially (\fBNB:\fR the link
+remains if the command is renamed), which is the currently invoked object by
+default.
 .PP
 Each object has its own \fBmy\fR command, contained in its instance namespace.
 .SH EXAMPLES
@@ -40,16 +45,38 @@ oo::class create c {
         puts [incr counter]
     }
 }
+
 c create o
 o count              \fI\(-> prints "1"\fR
 o count              \fI\(-> prints "2"\fR
 o count              \fI\(-> prints "3"\fR
 .CE
+.PP
+This example shows how you can use \fBmy\fR to make callbacks to private
+methods from outside the object (from a \fBtrace\fR), using
+\fBnamespace code\fR to enter the correct context:
+.PP
+.CS
+oo::class create HasCallback {
+    method makeCallback {} {
+        return [namespace code {
+            \fBmy\fR Callback
+        }]
+    }
+
+    method Callback {args} {
+        puts "callback: $args"
+    }
+}
+
+set o [HasCallback new]
+trace add variable xyz write [$o makeCallback]
+set xyz "called"     \fI\(-> prints "callback: xyz {} write"\fR
+.CE
 .SH "SEE ALSO"
 next(n), oo::object(n), self(n)
 .SH KEYWORDS
 method, method visibility, object, private method, public method
-
 .\" Local variables:
 .\" mode: nroff
 .\" fill-column: 78
diff --git a/doc/next.n b/doc/next.n
index db846be..8ebaed2 100644
--- a/doc/next.n
+++ b/doc/next.n
@@ -112,6 +112,7 @@ oo::class create theSuperclass {
         puts "in the superclass, args = $args"
     }
 }
+
 oo::class create theSubclass {
     superclass theSuperclass
     method example {args} {
@@ -121,6 +122,7 @@ oo::class create theSubclass {
         puts "after chaining from subclass"
     }
 }
+
 theSubclass create obj
 oo::objdefine obj method example args {
     puts "per-object method, args = $args"
@@ -167,6 +169,7 @@ oo::class create cache {
         \fI# Compute value, insert into cache, and return it\fR
         return [set ValueCache($key) [\fBnext\fR {*}$args]]
     }
+
     method flushCache {} {
         my variable ValueCache
         unset ValueCache
@@ -178,10 +181,12 @@ oo::class create cache {
 oo::object create demo
 oo::objdefine demo {
     mixin cache
+
     method compute {a b c} {
         after 3000 \fI;# Simulate deep thought\fR
         return [expr {$a + $b * $c}]
     }
+
     method compute2 {a b c} {
         after 3000 \fI;# Simulate deep thought\fR
         return [expr {$a * $b + $c}]
diff --git a/doc/self.n b/doc/self.n
index 0ad5428..855d067 100644
--- a/doc/self.n
+++ b/doc/self.n
@@ -32,7 +32,12 @@ implement the current call chain. The first element is the same as would be
 reported by \fBinfo object\fR \fBcall\fR for the current method (except that this
 also reports useful values from within constructors and destructors, whose
 names are reported as \fB<constructor>\fR and \fB<destructor>\fR
-respectively), and the second element is an index into the first element's
+respectively,
+.VS TIP500
+and for private methods, which are described as being \fBprivate\fR instead of
+being a \fBmethod\fR),
+.VE TIP500
+and the second element is an index into the first element's
 list that indicates which actual implementation is currently executing (the
 first implementation to execute is always at index 0).
 .TP