Index: TODO =================================================================== diff -u -r187fbd20a453ae9d73e9b48f88b8d6a8c79685c2 -rf41ae7e802868efee95b5d5682edfdbbe9ba2f64 --- TODO (.../TODO) (revision 187fbd20a453ae9d73e9b48f88b8d6a8c79685c2) +++ TODO (.../TODO) (revision f41ae7e802868efee95b5d5682edfdbbe9ba2f64) @@ -3606,20 +3606,17 @@ in objectParameterSlots - doc: - * integrate ::nx::doc::make with Makefile.in + * integrated ::nx::doc::make with Makefile.in (provide shell calls and, targets and dependencies) - - * provide a different flag for the generation of the documentation + * provided a different flag for the generation of the documentation (-develop, .... or -final) to show/hide it. - SS: By "it", you refer to the glossary? - - * separate entries for methods and hooks (can't be called if not defined)? + * separated entries for methods and hooks (can't be called if not defined)? hooks: * recreate should only be called internally, similarly "init" etc. * __unknown unknown is a hook for Object but a method for Class -- strange refcounting bug in 8.6b2 bug-is-86.tcl +- fixed strange refcounting bug in 8.6b2 bug-is-86.tcl where 2 refcounted items are not freed (value:class, issued from nx.tcl around line 120). Compile with DEBUG86B2 for more info @@ -3638,6 +3635,17 @@ } ================================================= +- nsf.c: cleanup on DEBUG86B2 + +- nx.tcl: + * do not namespace import my into ::nx + * replace usages of "my" by colon invocations + +- doc: + * extended method resolution section + * documented invocation flags for colon + + TODO: - warnings for "numeric" names for args and nonpos-args? - special handling of values looking like nonpos-flags, Index: doc/next-migration.html =================================================================== diff -u -r686684910e44fac172d7bcd8440aa23e44c7df5b -rf41ae7e802868efee95b5d5682edfdbbe9ba2f64 --- doc/next-migration.html (.../next-migration.html) (revision 686684910e44fac172d7bcd8440aa23e44c7df5b) +++ doc/next-migration.html (.../next-migration.html) (revision f41ae7e802868efee95b5d5682edfdbbe9ba2f64) @@ -1768,7 +1768,7 @@ the default protection for properties. The defaults can be overwritten also e.g. on a class level.

NX provides means for method hiding via the method modifier -private. Hidden methods can be invoked only via +my -local
+private. Hidden methods can be invoked only via the -local flag, which means: "call the specified method defined in the same class/object as the currently executing method".

@@ -1812,13 +1812,13 @@ 
# Hiding of methods via "private"
 #
 nx::Class create Base {
-  :private method baz {a b} { expr {$a + $b} }
-  :public method foo {a b} { my -local baz $a $b }
+  :private method baz {a b} {expr {$a + $b}}
+  :public method foo {a b} {: -local baz $a $b}
 }
 
 nx::Class create Sub -superclass Base {
-  :public method bar {a b} { my -local baz $a $b }
-  :private method baz {a b} { expr {$a * $b} }
+  :public method bar {a b} {: -local baz $a $b}
+  :private method baz {a b} {expr {$a * $b}}
 
   :create s1
 }
@@ -6856,7 +6856,7 @@
 
 
Index: doc/next-migration.txt
===================================================================
diff -u -r686684910e44fac172d7bcd8440aa23e44c7df5b -rf41ae7e802868efee95b5d5682edfdbbe9ba2f64
--- doc/next-migration.txt	(.../next-migration.txt)	(revision 686684910e44fac172d7bcd8440aa23e44c7df5b)
+++ doc/next-migration.txt	(.../next-migration.txt)	(revision f41ae7e802868efee95b5d5682edfdbbe9ba2f64)
@@ -660,7 +660,7 @@
 also e.g. on a class level.
 
 NX provides means for method hiding via the method modifier
-+private+. Hidden methods can be invoked only via +my -local +
++private+. Hidden methods can be invoked only via the +-local+ flag,
 which means: "call the specified method defined in the same
 class/object as the currently executing method". 
 
@@ -677,13 +677,13 @@
 # Hiding of methods via "private"
 #
 nx::Class create Base {
-  :private method baz {a b} { expr {$a + $b} }
-  :public method foo {a b} { my -local baz $a $b }
+  :private method baz {a b} {expr {$a + $b}}	
+  :public method foo {a b} {: -local baz $a $b}
 }
     
 nx::Class create Sub -superclass Base {
-  :public method bar {a b} { my -local baz $a $b }
-  :private method baz {a b} { expr {$a * $b} }
+  :public method bar {a b} {: -local baz $a $b}
+  :private method baz {a b} {expr {$a * $b}}
 
   :create s1
 }
Index: doc/next-tutorial.html
===================================================================
diff -u -r61a1c5c9e11a0277be442d98572bae6a3162cf1f -rf41ae7e802868efee95b5d5682edfdbbe9ba2f64
--- doc/next-tutorial.html	(.../next-tutorial.html)	(revision 61a1c5c9e11a0277be442d98572bae6a3162cf1f)
+++ doc/next-tutorial.html	(.../next-tutorial.html)	(revision f41ae7e802868efee95b5d5682edfdbbe9ba2f64)
@@ -1892,7 +1892,7 @@
 forwarders and aliases.
-

An accessor is a (in most cases) C-implemented method to access +

An accessor method is a (in most cases) C-implemented method to access instance variables of an object. A call to an accessor with no arguments uses the accessor as a getter, obtaining the value of the associated variable. A call to an accessor with an argument uses it as a setter, @@ -2024,7 +2024,7 @@ fido::tail.

-

A forwarder is a +

A forwarder method is a C-implemented method to redirect an invocation for a certain method to either a method of other object or to some other method of the same object. Forwarding an invocation of a method to some other @@ -2042,8 +2042,9 @@

3.2.3. Method-Aliases

-

A method alias is a means to register an existing method, a Tcl proc or -command under as a method with a certain name on a class or object.

+

An alias method is a means to register an existing method, or a +Tcl proc or a Tcl command as a method with the provided +name on a class or object.

In some way, the method alias is a restricted form of a forwarder, but it does not support delegation to different objects and argument @@ -2111,7 +2112,7 @@ called from every context. A protected method can only be invoked from the same object. A private method can be only invoked from methods defined on the same entity (e.g. defined on the same class) -via my -local.

+via the invocation with the local flag (i.e. ": -local").

All kind of methods protection are applicable for all kind of methods, either scripted or C-implemented.

@@ -2213,13 +2214,13 @@ 13 14 
nx::Class create Base {
-  :private method helper {a b} { expr {$a + $b} }
-  :public method foo {a b} { my -local helper $a $b }
+  :private method helper {a b} {expr {$a + $b}}
+  :public method foo     {a b} {: -local helper $a $b}
 }
 
 nx::Class create Sub -superclass Base {
-  :public method bar {a b} { my -local helper $a $b }
-  :private method helper {a b} { expr {$a * $b} }
+  :public method bar     {a b} {: -local helper $a $b}
+  :private method helper {a b} {expr {$a * $b}}
   :create s1
 }
 
@@ -2232,12 +2233,12 @@
 we create an instance s1 from the derived class, we can call the
 method foo which uses in turn the private method of the base
 class. Therefore, foo called with the arguments 3 and 4 returns its
-sum. If we would not have used my -local for invoking the helper,
+sum. If we would not have used the local flag for invoking the helper,
 s1 would have tried to call the helper of Sub, which would be
 incorrect. For all other purposes, the private methods are "invisible"
 in all situations, e.g. when mixins are used, or within the
 next-path, etc.
-

By using my -local for the invocation it is possible to call just the +

By using the local flag for the invocation it is possible to call just the local definition of the method. If we would call the method as usual, the resolution order would be the same as usual, starting with filters, mixins, per-object methods and the full intrinsic class @@ -2506,7 +2507,7 @@ of the object. The method can be defined multiple times on the search path, so some of these method definitions might be shadowed by the more specific definitions.

-
Listing 31: Method Resolution

+
Listing 31: Method Resolution with Intrinsic Classes

+
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+
nx::Class create M1 {
+  :public method foo {} { return "M1 foo: [next]"}
+}
+nx::Class create M2 {
+  :public method foo {} { return "M2 foo: [next]"}
+}
+
+#
+# "d1" is created based on the definitons of the last example
+#
+# Add the methods from "M1" as per-object mixin to "d1"
+d1 mixin M1
+
+#
+# Add the methods from "M2" as per-class mixin to class "C"
+C mixin M2
+
+# Invoke the method foo
+d1 foo
+# result: "M1 foo: M2 foo: d1 foo: D foo: C foo: "
+
+# Query the precedence order from NX via introspection
+d1 info precedence
+# result: "::M1 ::M2 ::D ::C ::nx::Object"
+

an extension of the previous example. We define here two additional +classes M1 and M2 which are used as per-object and per-class +mixins. Both classes define the method foo, these methods shadow +the definitins of the intrinsic class hierarchy. Therefore an +invocation of foo on object d1 causes first an invocation of +method in the the per-object mixin.

+
Listing 33: Method Invocation Flags

+
+
+
  1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+
#
+# "d1" is created based on the definitons of the last two examples,
+# the mixins "M1" and "M2" are registered.
+#
+# Define a public per-object method "bar", which calls the method
+# "foo" which variaous invocation options:
+#
+d1 public method bar {} {
+   puts [:foo]
+   puts [: -local foo]
+   puts [: -intrinsic foo]
+   puts [: -system foo]
+}
+
+# Invoke the method "bar"
+d1 bar
+

In the first line of the body of method bar, the method foo is +called as usual with an implicit reciever, which defaults to the +current object (therefore, the call is equivalent to d1 foo). The +next three calls show how to provide flags that influence the method +resolution. The flags can be provided between the colon and the method +name. These flags are used rather seldomly but can be helpful in some +situations.

+

The invocation flag -local means that the method has to be resolved +from the same place, where the current method is defined. Since the +current method is defined as a per-object method, foo is resolved as +a per-object method. The effect is that the mixin definitions are +ignored. The invocation flag -local was already introduced int the +setction about method protection, where it was used to call private +methods.

+

The invocation flag -intrinsic means that the method has to be resolved +from the intrinsic definitions, meaning simply without mixins. The +effect is here the same as with the invocation flag -local.

+

The invocation flag -system means that the method has to be resolved +from basic - typically predefined - classes of the object system. This +can be useful, when script overloads system methods, but still want to +call the shadowed methods from the base classes. In our case, we have +no definitions of foo on the base clases, therefore an error message +is returned.

+

+
+
+
   M1 foo: M2 foo: d1 foo: D foo: C foo:
+   d1 foo: D foo: C foo:
+   d1 foo: D foo: C foo:
+   ::d1: unable to dispatch method 'foo'
+

3.7. Parameters

@@ -2611,7 +2763,7 @@ determined by its position. When we call a method with non-positional parameters, their meaning is determined via a name passed with the argument during invocation.

-
Listing 32: Positional and Non-Positional Method Parameters

+
Listing 34: Positional and Non-Positional Method Parameters