Check-in [7ff5dde719]

mechanism does not need to be totally proof against prying (and introspection
mechanisms are desirable) as TclOO deliberately does not provide security
mechanisms; such mechanisms are the purpose of Tcl's interpreters. All that is
desired is a way of ensuring that code does not inadvertently trample other
code, allowing a superclass to evolve its implementation without needing to
take into account every detail of its subclasses.

# Private Declarations: Syntax and Immediate Semantics

This TIP introduces a new definition command, **private**, that is present
when doing both **oo::define** and **oo::objdefine**. Much as with the
**self** definition command (or the **oo::define** and **oo::objdefine**
commands themselves), it takes either single arguments or a list of arguments
(that it then builds a script of by turning them into a list) and evaluates
the result in a special context. The special context is the same as the outer
definition context, except that some definition commands instead create
_private definitions_ in that context.

The following commands are private-definition aware:

  * **forward** — the forwarded method it creates is a _private method_.
  * **method** — the procedure-like method it creates is a _private method_.
  * **self** (in **oo::class**) — the definitions on the class instance inside
    will be _private definitions_ (if the concept applies).
  * **variable** — the variable resolution rules created or manipulated (as
    this is a slot) will be for _private variables_.

If provided with no arguments, the **private** definition command will return
whether it was invoked from a context that should create private definitions.
Otherwise it returns the result of evaluating its script.

The meaning of a private method and a private variable is defined below.

# Detailed Proposal: Methods

For methods, as they actually exist in storage that is totally controlled by
TclOO (and which is not addressable other than via TclOO-created commands or
introspectors) the main complexity is working out what lookups are possible in
a particular case while ensuring that method lookups are fast. Determining
what the context class (or instance) is easy enough, as that's present pretty
much directly in the `Tcl_ObjectContext`, but rapidly determining whether the
object that is invoked is able to be seen in that way is the non-trivial part.
(As with most things in TclOO, appropriate caching is the key to accelerating
this sort of thing with a reasonable memory overhead.)

A key objective is that if one invokes `$otherobj ClassPrivateMethod` from
inside a method that is part of the class *but a different instance* or
possibly even a *different subclass* of that class, then that method will be
found. That makes this a useful mechanism that is not provided by the TclOO
system in Tcl 8.6.

## Method Invoke Semantics

When a method is invoked, a public (or unexported, if via the **my** command)
method is usually preferred. However, if the class of the object on which the
method is called is also the class that defined the currently executing method
(specifically, is the creator of the method that defines the current stack
frame at the point of the call), bearing in mind that the determination of
this also respects the inheritance and mixin hierarchies, then private methods
on that context class will also be found. Similarly, if the currently
executing method was defined by an object and that object is the object to
which the method invoke is directed, private methods on that object are also
found (the author expects these to be a rarely used feature). Searches for
private methods precede the equivalent public and unexported methods in the
method resolution order, but share a common naming space (i.e., they're stored
in the same hash tables) so that there are no ambiguities.


Since every method has at most one declaring class or object (and not both
simultaneously) there is at most one private method that can be on any call
chain. External calls (e.g., from the top level of Tcl, from a **namespace
eval**, from a procedure) will never have a private method on thir call
chains.

Once the call chain is created, the execution is handled as prior to this TIP;
the implementation of the first element on the call chain is executed,
whatever that is, and that can dispatch to later items on the call chain using
**next** and **nextto**.

A private method on a class (or object) may not have the same name as another
method on that class; all methods of a class (or object) are part of a single
space of names. When resolving a method call of a subclass of the class that
has the private method, even if the method names match, the private method
does not participate in the call chain; only an exact match from exactly the
right context counts.

In particular:

    oo::class create Top {
        method Foo {} {
            puts "This is Top::Foo for [self]"
        }
    }
    oo::class create Super {
        superclass Top
        private method Foo {} {
            puts "This is Super::Foo for [self]"
        }
        method bar {other} {
            puts "This is Super::bar for [self]"
            my Foo
            [self] Foo
            $other Foo
        }
    }
    oo::class create Sub {
        superclass Super
        method Foo {} {
            puts "This is Sub::Foo for [self]"
            next
        }
        private method bar {other} {
            error "This should be unreachable"
        }
        method grill {} {
            puts "This is Sub::grill for [self]"
            my Foo
        }
    }
    Sub create obj1
    Sub create obj2
    obj1 bar obj2
    obj1 grill

is expected to print out:

    This is Super::bar for ::obj1
    This is Super::Foo for ::obj1

    This is Super::Foo for ::obj1
    This is Super::Foo for ::obj2
    This is Sub::grill for ::obj1
    This is Sub::Foo for ::obj1
    This is Top::Foo for ::obj1

Note that the calls via **my**, **self** and through the public handle of
another object all pick up the private method from _Super_,
and the call to **next** from _Sub_ does not pick up the method on _Super_ but
instead goes straight to _Top_.




## Creation and Introspection

Private methods are created calling **oo::define** (and **oo::objdefine**, and
via the constructor of **oo::class**) like this:

    oo::define TheClass {
        private method foo {...} {
            ...
        }
        private forward bar  SomeOtherCommand
    }









At the C API level, private methods can be directly created by setting the
*flags* parameter (called *isPublic* in older versions of the API) of
`Tcl_NewMethod` and `Tcl_NewInstanceMethod` to the constant
`TCL_OO_METHOD_PRIVATE`. This lets custom types of methods be declared private
by their C code directly.

Introspection is done via appropriate options to **info class methods** and
**info object methods**. In particular, they are never returned when the
**-all** option is given, are found when **-private** option is given (unless
the **-all** option is _also_ given), and can be found when the new option
**-scope** is given, depending on what scope is chosen from the options below:

returns the creation ID of any existing object. It also applies to classes.
Again, note that creation IDs are _always_ system-allocated and are _never_
guaranteed to be unique between interpreters, either in multiple processes or
in the same thread or process; they are only ever locally unique.

# Implementation

See the [`tip-500` branch](https://core.tcl.tk/tcl/timeline?r=tip-500).

# Copyright

This document has been placed in the public domain.