Index: TODO =================================================================== diff -u -r062dd3cb76774853a767854e29f60a3325c4bd94 -r26480a59b14cf250904da0cdc7d895f21b0ed5fd --- TODO (.../TODO) (revision 062dd3cb76774853a767854e29f60a3325c4bd94) +++ TODO (.../TODO) (revision 26480a59b14cf250904da0cdc7d895f21b0ed5fd) @@ -4007,6 +4007,7 @@ - added documentation for "/obj/ info name" to migration guide and .nxd file - adding more comments to examples in migration guide +- document private properties in tutorial and migration guide ======================================================================== TODO: Index: doc/next-migration.html =================================================================== diff -u -r062dd3cb76774853a767854e29f60a3325c4bd94 -r26480a59b14cf250904da0cdc7d895f21b0ed5fd --- doc/next-migration.html (.../next-migration.html) (revision 062dd3cb76774853a767854e29f60a3325c4bd94) +++ doc/next-migration.html (.../next-migration.html) (revision 26480a59b14cf250904da0cdc7d895f21b0ed5fd) @@ -849,7 +849,7 @@

  • NX provides means for method protection (method modifiers - public, protected and private). Therefore developers have + public, protected, and private). Therefore developers have to define explicitly public interfaces in order to use methods from other objects.

    @@ -2693,13 +2693,13 @@

  • register an accessor function (setter), for wich the usual - protection levels (public or protected) can be used. + protection levels (public, protected or private) can be used.

    • The method variable in NX is similar to property, but it creates -only slot objects in cases where needed, and it does not provide -object parameters or accessors.

    +only slot objects in cases where internally needed. variable it does +neither provide object parameters, or naccessors.

    We show first the definition of properties simliar to the functionality provided as well by XOTcl and show afterwards how to use value constraints, optional parameters, etc. in NX.

    @@ -2878,8 +2878,6 @@ -

    XOTcl 1 did not support value constraints for object parameters (just -for non-positional arguments).

    NX supports value constraints (value-checkers) for object and method parameters in an orthogonal manner. NX provides a predefined set of value checkers, which can be extended by the application developer. @@ -2934,11 +2932,13 @@ # # User defined value constraints are possible. # All parameter value checkers can be turned on -# and off. +# and off at runtime. # -# Define a boolean property and an integer -# property with a default firstly via "properties", -# then with multiple "property" statements. +# Define a required boolean property "a" +# and an integer property "b" with a default. +# The first definition uses "properties", +# the second definition uses multiple +# "property" statements. Class create Foo -properties { a:boolean @@ -6950,7 +6950,7 @@

    Index: doc/next-migration.txt =================================================================== diff -u -r062dd3cb76774853a767854e29f60a3325c4bd94 -r26480a59b14cf250904da0cdc7d895f21b0ed5fd --- doc/next-migration.txt (.../next-migration.txt) (revision 062dd3cb76774853a767854e29f60a3325c4bd94) +++ doc/next-migration.txt (.../next-migration.txt) (revision 26480a59b14cf250904da0cdc7d895f21b0ed5fd) @@ -102,7 +102,7 @@ under arbitrary names for arbitrary objects or classes. .. NX provides means for _method protection_ (method modifiers - +public+, +protected+ and +private+). Therefore developers have + +public+, +protected+, and +private+). Therefore developers have to define explicitly public interfaces in order to use methods from other objects. @@ -1164,11 +1164,11 @@ object (usable via a non-positional parameter during object creation), and . register an accessor function (setter), for wich the usual - protection levels (+public+ or +protected+) can be used. + protection levels (+public+, +protected+ or +private+) can be used. The method +variable+ in NX is similar to +property+, but it creates -only slot objects in cases where needed, and it does not provide -object parameters or accessors. +only slot objects in cases where internally needed. +variable+ it does +neither provide object parameters, or naccessors. We show first the definition of properties simliar to the functionality provided as well by XOTcl and show afterwards how to use @@ -1289,9 +1289,6 @@ ---------------- |====================== -XOTcl 1 did not support value constraints for object parameters (just -for non-positional arguments). - NX supports _value constraints_ (value-checkers) for object and method parameters in an orthogonal manner. NX provides a predefined set of value checkers, which can be extended by the application developer. @@ -1319,11 +1316,13 @@ # # User defined value constraints are possible. # All parameter value checkers can be turned on -# and off. +# and off at runtime. # -# Define a boolean property and an integer -# property with a default firstly via "properties", -# then with multiple "property" statements. +# Define a required boolean property "a" +# and an integer property "b" with a default. +# The first definition uses "properties", +# the second definition uses multiple +# "property" statements. Class create Foo -properties { a:boolean Index: doc/next-tutorial/next-tutorial.html =================================================================== diff -u -ra54313f558be3d0e7c909fa76cdee874f1880ef3 -r26480a59b14cf250904da0cdc7d895f21b0ed5fd --- doc/next-tutorial/next-tutorial.html (.../next-tutorial.html) (revision a54313f558be3d0e7c909fa76cdee874f1880ef3) +++ doc/next-tutorial/next-tutorial.html (.../next-tutorial.html) (revision 26480a59b14cf250904da0cdc7d895f21b0ed5fd) @@ -1623,7 +1623,7 @@

    A property is a definition of an attribute (an instance variable) -with accessors. The property definition might as well carry +with accessor methods. A property definition might carry value-constraints and a default value.

    @@ -2142,15 +2142,15 @@ The call-protection defines from which calling context methods might be called. The Next Scripting Framework supports as well redefinition protection for methods.

    -

    NX distinguished between public, protected and private methods, -where the default call-protection is "protected".

    +

    NX distinguishes between public, protected and private methods, +where the default call-protection is protected.

    A public method can be called from every context. A protected method can only be invoked from the same object. A private method can only be invoked from methods defined on the same entity (defined on the same class or on the same object) via the invocation -with the local flag (i.e. ": -local").

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

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

    @@ -2275,11 +2275,88 @@ 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 the local flag for the invocation it is possible to call +

    By using the -local flag at the call site it is possible to invoce only 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 -hierarchy.

    +without this flag, the resolution order would be the standard +resolution order, starting with filters, mixins, per-object methods +and the full intrinsic class hierarchy.

    +

    NX supports the modifier private for methods and properties. In all +cases private is an instrument to avoid unanticipated interactions +and means actually "accessible for methods defined on the same entity +(object or class)". The main usage for private is to improve +locality of the code e.g. for compositional operations.

    +

    In order to improve locality for properties, a private property +defines therfore internally a variable with a different name to avoid +unintended interactions. The variable should be accessed via the +private accessor, which can be invoved with the -local flag. In the +following example class D introduces a private property with the +same name as a property in the superclass.

    +
    Listing 27: Private Properties

    +
    +
    +
      1
+  2
+  3
+  4
+  5
+  6
+  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+
    #
+# Define a class C with a (public) property "x"
+#
+nx::Class create C {
+  :property {x c}
+}
+
+#
+# Define a subclass D with a private property "x"
+# and a method bar, which is capable of accessing
+# the private property.
+#
+nx::Class create D -superclass C {
+  :private property {x d}
+  :public method bar {p} {return [: -local $p]}
+}
+
+#
+# The private and public (or protected) properties
+# define internally separate variable that do not
+# conflict.
+#
+D create d1
+puts [d1 x]       ;# prints "c"
+puts [d1 bar x]   ;# prints "d"
    +

    Without the private definition of the property, the definition of +property x in class D would shadow the +definition of the property in the superclass C for its instances +(d1 x or set :x would return d instead of c).

    3.4. Applicability of Methods

    @@ -2296,7 +2373,7 @@

    In the following example method, foo is an instance method defined on class C.

    -
    Listing 27: Methods applicable for instances

    +
    Listing 28: Methods applicable for instances