Index: TODO =================================================================== diff -u -N -rac96e6ce975fe5864b64dee9d66bc701a31e113b -r89714df5a6af5799a4444805cf1f82b4b2b21af2 --- TODO (.../TODO) (revision ac96e6ce975fe5864b64dee9d66bc701a31e113b) +++ TODO (.../TODO) (revision 89714df5a6af5799a4444805cf1f82b4b2b21af2) @@ -3429,12 +3429,17 @@ - nsf.c: * added permissable value "private" to flag "-callprotection" for - "info lookup method" and "info methods". + "info lookup method" and "inbfo methods". * extended regression test +- doc: + * fixed naming of "attribute" in migration guide + * added "private" to migration guide + * some textual improvements in migration guide + TODO: - private: - * document private in migration guide tutorial + * document private in tutorial - nx: * maybe provide a replacement for -attributes, but without the magic variable. Index: doc/next-migration.html =================================================================== diff -u -N -raa41f220776456c37553c5daf8e0519d5b51f0b8 -r89714df5a6af5799a4444805cf1f82b4b2b21af2 --- doc/next-migration.html (.../next-migration.html) (revision aa41f220776456c37553c5daf8e0519d5b51f0b8) +++ doc/next-migration.html (.../next-migration.html) (revision 89714df5a6af5799a4444805cf1f82b4b2b21af2) @@ -824,9 +824,9 @@
  • NX provides means for method protection (method modifiers - public and protected). Therefore developers have to define - explicitly public interfaces in order to use methods from other - objects. + public, protected and private). Therefore developers have + to define explicitly public interfaces in order to use methods + from other objects.

  • @@ -999,29 +999,29 @@

    Total

    -

    43

    -

    123

    +

    44

    +

    124

    Methods for Objects

    -

    18

    +

    20

    51

    Methods for Classes

    -

    4

    -

    23

    +

    3

    +

    24

    Info-methods for Objects

    -

    14

    +

    15

    25

    Info-methods for Classes

    -

    7

    +

    6

    24

    @@ -1079,9 +1079,7 @@ # Stack of Things # - :method init {} { - set :things "" - } + :variable things "" :public method push {thing} { set :things [linsert ${:things} 0 $thing] @@ -1501,7 +1499,7 @@ # method # forward # alias -# attribute +# property # # All these methods return method-handles. @@ -1682,11 +1680,11 @@

    2.2.3. Method Modifiers and Method Protection

    -

    NX supports the three method modifiers class, public and -protected. All method modifiers can be written in front of every method -defining command. The method modifier class is used to denote -class-specific methods (see above). The concept of method -protection is new in NX.

    +

    NX supports four method modifiers class, public, protected and +private. All method modifiers can be written in front of every +method defining command. The method modifier class is used to denote +class-specific methods (see above). The concept of method protection +is new in NX.

    # Method modifiers # # "class", -# "public", and -# "protected" +# "public", +# "protected", and +# "private" # # are not available
    @@ -1734,39 +1733,108 @@
    # Method modifiers
     #
     #   "class",
    -#   "public", and
    +#   "public",
     #   "protected"
     #
     # are applicable for all kinds of method
     # defining methods:
     #
    -#    method, forward, alias, attribute
    -
    -Class create C {
    +#    method, forward, alias, property
    +#
    +# The modifier "private" is available for
    +#
    +#    method, forward, alias
    +#
    +Class create C {
       :/method-definiton-method/ ...
       :public /method-definiton-method/ ...
       :protected /method-definiton-method/ ...
    +  :private /method-definiton-method/ ...
       :class /method-definiton-method/ ...
    -  :protected class /method-definiton-method/ ...
       :public class /method-definiton-method/ ...
    +  :protected class /method-definiton-method/ ...
    +  :private class /method-definiton-method/ ...
     }

    XOTcl does not provide method protection. In NX, all methods are -defined per default as protected. These defaults can be changed by the +defined per default as protected. This default can be changed by the application developer in various ways. The command ::nx::configure defaultMethodCallProtection true|false can be used to set the default call protection for scripted methods, forwarder and aliases, while ::nx::configure defaultPropertyCallProtection true|false can set 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
    +which means: "call the specified method defined in the same +class/object as the currently executing method".

    +
    + +++ + + + + + + + + + + + +
    XOTcl Next Scripting Language
    +
    +
    # XOTcl provides no means for method hiding
    +
    +
    # 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 }
    +}
    +
    +nx::Class create Sub -superclass Base {
    +  :public method bar {a b} { my -local baz $a $b }
    +  :private method baz {a b} { expr {$a * $b} }
    +
    +  :create s1
    +}
    +
    +s1 foo 3 4  ;# returns 7
    +s1 bar 3 4  ;# returns 12
    +s1 baz 3 4  ;# unable to dispatch method 'baz'
    +
    -

    2.2.4. Method and Attribute Deletion

    +

    2.2.4. Method and Property Deletion

    NX provides an explicit delete method for the deletion of methods -and attributes.

    +and properties.

    /obj/proc foo {} {} /cls/ instproc foo {} {} -# No support for attribute deletion +# No support for property deletion @@ -2318,38 +2386,55 @@

    2.4. Parameters

    While XOTcl 1 had very limited forms of parameters, XOTcl 2 and NX -provide a generalized and highly orthogonal parameter handling with -various kinds of value constraints (also called value checker). We -divide the parameters into Object Parameters (parameters used for -initializing objects and classes, specified in XOTcl primarily via the -method parameter) and Method Parameters (parameters passed to -methods). The Next Scripting Framework provide a unified, -C-implemented infrastructure to handle both, object and method -parameters.

    -

    Furthermore, the Next Scripting Framework provides

    +provide a generalized and highly orthogonal parameter machinery +handling various kinds of value constraints (also called value +checkers). Parameters are used to specify,

    • -unified parameter checking (for object and method parameters) and +how objects and classes are initialized (we call these parameter types + Object Parameters), and

    • -return value checking +what values can be passed to methods (we call these Method + Parameters).

    -

    based on the same mechanisms.

    +

    Furthermore, parameters might be positional or non-positional, they +might be optional or required, they might have a defined multiplicity, +and value-types, they might be introspected, etc. The Next Scripting +Framework provide a unified, C-implemented infrastructure to handle +both, object and method parameters in the same way with a high degree +of orthogonality.

    +

    Object Parameters were specified in XOTcl 1 primarily via the method +parameter in a rather limited way, XOTcl 1 only supported +non-positional parameters in front of positional ones, there were no +value constraints for positional parameters, no distinction between +optional and required, or multiplicity.

    +

    Furthermore, the Next Scripting Framework provides optionally Return +Value Checking based on the same mechanism to check whether some +methods return always the values as specified.

    -

    2.4.1. Object Parameters

    -

    Object parameters are used for specifying, how objects should be -initialized (what parameters can be passed in for initialization, what -default values are provided, etc.). Object parameters are supported -in XOTcl primarily via the method parameter, which is used to define -multiple parameters via a list of parameter specifications. Since the -term "parameter" is underspecified, NX uses the term "attribute". To -define multiple attributes in a short form, NX provides the method -attributes.

    +

    2.4.1. Instance Variables and Object Parameters

    +

    Object parameters are used for specifying, how objects are +initialized (i.e. how instance variables are initialized, what +parameters can be passed in for initialization, what default values +are used, etc.). Object parameters are supported in XOTcl primarily +via the method parameter, which is used in XOTcl to define multiple +parameters via a list of parameter specifications. Since the term +"parameter" is underspecified, NX uses a more differentiated +terminology. NX distinguishes between instance variables with +accessors (also called properties) and instance variables without +accessors. To define a property, NX uses the method property, to +define an instance variable without accessor, it uses the method +variable. To define multiple properties in a short form (similar to +XOTcl’s parameter), NX provides the method properties.

    +

    In a first step, we show the initialization of instance variables +without accessors (using variable in NX), and then the definition of +instance variables with accessors (using property).

    # Set instance variable of object obj to a
     # value via resolver
    -# (preferred way: define attribute on obj)
    +# (preferred way: define property on obj)
     
     /obj/ eval [list set /:varName/ ?value?]
    +
    # Define that instances of the class have
    +# a instance variables "x" and "y" initialized
    +# with some values
    +
    +Class Foo
    +Foo instproc init args {
    +   instvar x y
    +   set x 1
    +   set y 2
    +}
    +
    +# Create instance of the class Foo
    +Foo f1
    +
    +# Object f1 has instance variables
    +# x == 1 and y == 2
    + + + +
    +
    +
    +# The method "variable" is similar in syntax
    +# to Tcl's "variable" command. During object
    +# creation, the definition are used for the
    +# initialization of the object.
    +
    +Class create Foo {
    +  :variable x 1
    +  :variable y 2
    +}
    +
    +# Create instance of the class Foo
    +Foo create f1
    +
    +# Object f1 has instance variables
    +# x == 1 and y == 2
    +
    +

    While XOTcl follows a procedural way to initialize variables via the +constructor init, NX follows a more declarative approach. Note, that +the variable definitions are inherited from superclasses, which is +straightforward in NX, while in XOTcl, the constructor has to call +explicitly the constructor of its superclasses.

    +

    It is certainly as well possible to use constructors in NX in the same +way as in XOTcl.

    +

    NX uses the same mechanism to define class variables or object +variables.

    +
    + +++ + + + + + + + + + + + +
    XOTcl Next Scripting Language
    +
    +
    # No syntactic support for creating
    +# class variables
    +
    +
    +# Define a class variable "V" with value 100 and
    +# an instance variable "x". "class variable" works
    +# similar to "class method".
    +
    +Class create Foo {
    +  :class variable V 100
    +  :variable x 1
    +}
    +
    +

    In the next step, we define properties, i.e. variables with accessors.

    +

    XOTcl uses the method parameter is a shortcut for creating multiple +properties. For every parameter definition, XOTcl creates as well a +slot object, keeping an extensible set of meta-data for every +parameter. Slot objects can be as well created in XOTcl directly via +the method slots. NX provides a similar method named properties.

    +
    + +++ + + + + + + + + +# Object f1 has instance variables +# a == 0 and b == 1 + +# Use the setter to alter instance variable "b" +f1 b 100 + +# Use the accessor to output the value +puts [f1 b] +# Object f1 has a == 0 and b == 1 + +# Use the setter to alter instance variable "b" +f1 b 100 + +# Use the accessor to output the value +puts [f1 b] @@ -2580,8 +2825,8 @@ .nx-variable {color: #AF663F; font-weight: normal; font-style: normal;}
    # Object parameter with scripted
    -# definition (init-block), defining an
    -# attribute specific type checker
    +# definition (init-block), defining a
    +# property specific type checker
     
     Class create Person {
       :property sex {
    @@ -2605,8 +2850,8 @@
     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.

    -

    In NX, the value checking is optional. This means that it is possible to +value checkers, which can be extended by the application developer. +In NX, the value checking is optional. This means that it is possible to develop e.g. which a large amount of value-checking and deploy the script with value checking turned off, if the script is highly performance sensitive.

    @@ -2659,11 +2904,11 @@ # All parameter value checkers can be turned on # and off. # -# Define a boolean attribute and an integer -# attribute with a default firstly via "attributes", -# then with multiple "attribute" statements. +# Define a boolean property and an integer +# property with a default firstly via "properties", +# then with multiple "property" statements. -Class create Foo -attributes { +Class create Foo -properties { a:boolean {b:integer 1} }
    @@ -2688,10 +2933,11 @@

    In XOTcl all object parameters were optional. Required parameters have to be passed to the constructor of the object.

    -

    NX allows to define optional and required object -attributes. Therefore, object parameters can be used as the single -mechanism to parameterize objects. The constructors do not require any -parameters.

    +

    NX allows to define optional and required object parameters (as +well as method parameters). Therefore, object parameters can be used +as the single mechanism to parameterize objects. It is in NX not +necessary (and per default not possible) to pass arguments to the +constructor.

    XOTcl Next Scripting Language
    +
    # Object parameter specified as a list (short form)
     # "a" has no default, "b" has default "1"
     
    @@ -2384,7 +2609,8 @@
     # Create instance of the class Foo
     Foo f1 -a 0
     
    -# Object f1 has a == 0 and b == 1
    -
    # Object parameter specified via slots
    +
    # Object parameters specified via slots
     
     Class Foo -slots {
        Attribute a
        Attribute b -default 1
     }
     
    -# Create instance of the class Foo
    +# Create instance of the class Foo and
    +# provide a value for instance variable "a"
     Foo f1 -a 0
     
     # Object f1 has a == 0 and b == 1
    -
    -
    # Object parameter specified via attribute
    -# methods (supports method modifiers and
    -# scripted configuration)
    +
    # Object parameters specified via the method
    +# "property" (supports method modifiers and
    +# scripted configuration; see below)
     
     Class create Foo {
        :property a
        :property {b 1}
     }
     
    -# Create instance of the class Foo
    +# Create instance of the class Foo and
    +# provide a value for instance variable "a"
     Foo create f1 -a 0
     
    -# Object f1 has a == 0 and b == 1
    @@ -2526,17 +2771,17 @@ .nx-placeholder {color: #AF663F; font-weight: normal; font-style: italic;} .nx-variable {color: #AF663F; font-weight: normal; font-style: normal;} -
    # Define object parameter at the class
    -# and object level
    +
    # Define a class property and an object
    +# property
     
     Class create C {
       :property x
       :property {y 1}
    -  :class attribute oa1
    +  :class property cp
     }
     
     Object create o {
    -  :property oa2
    +  :property op
     }
    # Required parameter:
    -# Define a required attribute "a" and a
    -# required boolean attribute "b"
    +# Define a required property "a" and a
    +# required boolean property "b"
     
    -Class create Foo -attributes {
    +Class create Foo -properties {
        a:required
        b:boolean,required
     }
    @@ -2802,12 +3048,15 @@ .nx-variable {color: #AF663F; font-weight: normal; font-style: normal;}
    # Parameter with multiplicity
    +#   ints is a list of integers, with default
    +#   objs is a non-empty list of objects
    +#   obj is a single object, maybe empty
     
    -Class create Foo -attributes {
    -  {ints:integer,0..n ""} ;# list of integers, with default
    -   objs:object,1..n       ;# non-empty list of objects
    -   obj:object,0..1        ;# single object, maybe empty
    -}
    +Classcreate Foo -properties { + {ints:integer,0..n ""} + objs:object,1..n + obj:object,0..1 +}
    -
    /obj|cls/ info [inst](commands|procs|parametercmd) ?pattern?
    +
    /obj|cls/ info \
    +   [inst](commands|procs|parametercmd) \
    +   ?pattern?
    +
    /obj|cls/ info \
    +   [inst](commands|procs|parametercmd) \
    +   ?pattern?
    -
    /obj|cls/ info [inst](commands|procs|parametercmd) ?pattern?