Index: doc/next-migration.html =================================================================== diff -u -r417e9e54ae7b0af1ee69c34525ad99c2beabedf8 -r74bae7e8ef9109fbcd95b77be8cf422ce330b59d --- doc/next-migration.html (.../next-migration.html) (revision 417e9e54ae7b0af1ee69c34525ad99c2beabedf8) +++ doc/next-migration.html (.../next-migration.html) (revision 74bae7e8ef9109fbcd95b77be8cf422ce330b59d) @@ -734,8 +734,8 @@

Migration Guide for the Next Scripting Language

Gustaf Neumann
<neumann@wu-wien.ac.at>
-version 2.1, -March 2011 +version 2.2, +May 2013
Table of Contents
@@ -905,7 +905,7 @@ arguments for methods, the Next Scripting Framework provides the same value checkers for positional and non-positional arguments of methods, as well as for positional and - non-positional object parameters (-parameter in + non-positional configure parameters (-parameter in XOTcl 1).

@@ -1523,10 +1523,9 @@ 
# Methods for defining methods:
 #
-#     method
-#     forward
 #     alias
-#     property
+#     forward
+#     method
 #
 # All these methods return method-handles.
@@ -1538,9 +1537,10 @@ to variables (called parametercmd and instparametercmd). The accessor functions are used normally internally when object-specific parameters are defined (see Section 3.4).

-

In NX forwarders are called forward. NX does not provide an own -method to define variable accessors, but uses the Next Scripting -Framework primitive nsf::method::setter for it.

+

In NX forwarders are called forward. NX does not provide an public +available method to define variable accessors like parametercmd in +XOTcl, but use interanlly the Next Scripting Framework primitive +nsf::method::setter when appropriate.

# are applicable for all kinds of # method defining methods: # -# method, forward, alias, property +# method, forward, alias # # The modifier "private" is available for # @@ -1790,10 +1790,8 @@ 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.

+call protection for scripted methods, forwarder and aliases. +The defaults can be overwritten also on a class level.

NX provides means for method hiding via the method modifier private. Hidden methods can be invoked only via the -local flag, which means: "call the specified method defined in the same @@ -1860,9 +1858,8 @@

-

2.2.4. Method and Property Deletion

-

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

+

2.2.4. Method Deletion

+

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

# XOTcl provides only method deletion with # the equivalent of Tcl's "proc foo {} {}" /cls/ instproc foo {} {} -/obj/proc foo {} {} - -# No support for property deletion +/obj/proc foo {} {}
# Define class "Foo" with instance
 # variables "x" and "y" initialized
-# on instance creation.
+# on instance creation. The initialization
+# has to be performed in the constructor.
 
 Class Foo
 Foo instproc init args {
@@ -2522,7 +2526,7 @@
 # to Tcl's "variable" command. During
 # instance creation, the variable
 # definitions are used for the
-# initialization of the object.
+# initialization of the variables of the object.
 
 Class create Foo {
   :variable x 1
@@ -2539,12 +2543,14 @@

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.

+constructor init, NX follows a more declarative approach. Often, +classes have superclasses, which often want to provide their own +instance variables and default values. The declarative approach from +NX solves this via inheritance, while an procedural approach via +assign statements in the constructor requires explicit constructor +calls, which are often error-prone. Certainly, when a user prefers to +assign initial values to instance variables via explicit assign +operations in constructors, this is as ell possible in NX.

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

@@ -2588,8 +2594,8 @@ 
 # Define a object variable "V" with value 100 and
-# an instance variable "x". "V" is just available
-# for the class object Foo, "x" is available in the
+# an instance variable "x". "V" is defined for the
+# class object Foo, "x" is defined in the
 # instances of the class. "object variable" works
 # similar to "object method".
 
@@ -2601,12 +2607,33 @@
-

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

+

In the next step, we define configurable instance variables which we +call properties in NX.

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.

+configurable variables with automically created accessors (methods for +reading and writing of the variables). In NX, the prefered way to +create configurable variables is to use the method property. The +method property in NX is similar to variable, but makes the +variables configurable, which means that

+
    +
  1. +

    +one can specify the property as a non-positional parameter upon + creation of the object, +

    +
    2. +
  2. +

    +one can query the value via the method cget, and +

    +
    3. +
  3. +

    +one can modify the value of the underlying variable via the method + configure. +

    +
    4. +
-
# Object parameter specified as a list
-# (short form); Parameter
+
# Parameters specified as a list
+# (short form); parameter
 # "a" has no default, "b" has default "1"
 
 Class Foo -parameter {a {b 1}}
@@ -2643,7 +2670,16 @@
 Foo f1 -a 0
 
 # Object f1 has instance variables
-# a == 0 and b == 1

+# a == 0 and b == 1
+
+# XOTcl registers automatically accessors
+# for the parameters. Use the accessor
+# "b" to output the value of variable "b"
+puts [f1 b]
+
+# Use the setter to alter value of
+# instance variable "b"
+f1 b 100
+# a == 0 and b == 1 + +# Use the method "cget" to query the value +# of a configuration parameter +puts [f1 cget -b] + +# Use the method "configure" to alter the +# value of instance variable "b" +f1 configure -b 100
-
# Object parameter specified as a list
-# (short form); "a" has no default,
-# "b" has default "1"
+
# Define property "a" and "b". The
+# property "a" has no default, "b" has
+# default value "1"
 
-Class create Foo -properties {a {b 1}}
+Class create Foo {
+  :property a
+  :property {b 1}
+}
 
 # Create instance of the class Foo
 Foo create f1 -a 0
 
 # Object f1 has instance variables
-# a == 0 and b == 1
-

Since every property defines a slot object, NX provides as well a -scripted initialization for every slot object. Therefore, NX uses -property to define a single property, similar in syntax to method -parameters (a braced pair to denote a variable with a default). The -method property can be used in NX on the class and on the object -level (in XOTcl: just on the class level). When an property is -created, NX does actually three things:

-
    -
  1. -

    -Create a slot object, which can be specified in more detail - using the init-block of the slot object -

    -
    2. -
  2. -

    -Create an object parameter definition for the initialization of the - object (usable via a non-positional parameter during object - creation), and -

    -
    3. -
  3. -

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

    -
    4. -
-

The method variable in NX is similar to property, but it creates -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.

+

In general, NX allows to create variables and properties with and +without accessor methods. The created accessor methods might be +public, protected or public. When the value none is provided +to -accessor, no accessor will be created. This is actually the +default in NX. In order to change the default behavior in NX, one can use +::nx::configure defaultAccessor none|public|protected|private.

-
# Object parameters specified via slots
-
-Class Foo -slots {
-   Attribute a
-   Attribute b -default 1
-}
-
-# 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
-
-# Use the setter to alter value of
-# instance variable "b"
-f1 b 100
-
-# Use the accessor to output
-# the value
-puts [f1 b]
+
# "parameter" creates always accessor
+# methods, accessor methods are
+# always public, no "cget" is available.
+# Use the accessor method to set the +# value of instance variable "a" +f1 a 100 + +
-
# Object parameters specified via the method
-# "property" (supports method modifiers and
-# scripted configuration; see below)
+
# Define property "a" and "b". The
+# property "a" has no default, "b" has
+# default value "1"
 
 Class create Foo {
-   :property a
-   :property {b 1}
+  :variable -accessor public a
+  :property -accessor public {b 1}
 }
 
-# Create instance of the class Foo and
-# provide a value for instance variable "a"
-Foo create f1 -a 0
+# Use the accessor method to query
+# the value of a configuration parameter
+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]
+
+

Similar to variable, properties can be defined in NX on the class +and on the object level.

+
+ +++ + + + + + + +
# XOTcl provides no means to define
+# configurable variables at the object
+# level
- - - -
XOTcl Next Scripting Language
-
# Parameters only available at
-# class level
-
# Define instance and object properties
+
# Define class with a property for the class object
+# named "cp". This is similar to "static variables"
+# in some other object-oriented programming
+# languages.
 
-Class create C {
-  :property x
-  :property {y 1}
-  :object property cp
+Class create Foo {
+  ...
+  :object property cp 101
 }
 
+# Define object property "op"
+
 Object create o {
-  :object property op
+  :object property op 102
 }
-
-
# Object parameter with configured slot,
-# defining an attribute specific type
-# checker
-
-Class Person -slots {
-  Attribute create sex -type "sex" {
-    my proc type=sex {name value} {
-      switch -glob $value {
-        m* {return m}
-        f* {return f}
-        default {
-          error "expected sex but got $value"
-        }
-      }
-    }
-  }
-}
-
-
# Object parameter with scripted
-# definition (init-block), defining a
-# property specific type checker
-
-Class create Person {
-  :property sex {
-    :type "sex"
-    :object method type=sex {name value} {
-      switch -glob $value {
-        m* {return m}
-        f* {return f}
-        default {
-          error "expected sex but got $value"
-        }
-      }
-    }
-  }
-}
@@ -2967,10 +2929,10 @@ -

In XOTcl all object parameters were optional. Required parameters have +

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

-

NX allows to define optional and required object parameters (as -well as method parameters). Therefore, object parameters can be used +

NX allows to define optional and required configure parameters (as +well as method parameters). Therefore, configure 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.

@@ -3114,12 +3076,236 @@
-

The Object parameters provided by a class for the initialization of -instances can be introspected via /cls/ info parameter (see -[info_parameter]).

+

For the implementation of variables and properties, NX uses slot +objects, which are an extension to the -slots already available in +XOTcl. While very for every property in NX, a slot object is created, +for performance reasons, not every variable has a slot associated.

+

When an property is created, NX does actually three things:

+
    +
  1. +

    +Create a slot object, which can be specified in more detail + using the init-block of the slot object +

    +
    2. +
  2. +

    +Create a parameter definition for the initialization of the + object (usable via a non-positional parameter during object + creation), and +

    +
    3. +
  3. +

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

    +
    4. +
+
+ +++ + + + + + + + + + + + +
XOTcl Next Scripting Language
+
+
# Define parameters via slots
+
+Class Foo -slots {
+   Attribute a
+   Attribute b -default 1
+}
+
+# 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
+
+
# Configurable 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 and
+# provide a value for instance variable "a"
+Foo create f1 -a 0
+
+# Object f1 has a == 0 and b == 1
+

Since the slots are objects, the slot objects can be configured and +parameterized like every other object in NX. Slot objects can be +provided with a scripted initialization as well. 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.

+
+ +++ + + + + + + + + + + + +
XOTcl Next Scripting Language
+
+
# Define parameter with an an
+# attribute-specific type checker
+
+Class Person -slots {
+  Attribute create sex -type "sex" {
+    my proc type=sex {name value} {
+      switch -glob $value {
+        m* {return m}
+        f* {return f}
+        default {
+          error "expected sex but got $value"
+        }
+      }
+    }
+  }
+}
+
+
# Configure parameter with scripted
+# definition (init-block), defining a
+# property specific type checker
+
+Class create Person {
+  :property sex {
+    :type "sex"
+    :object method type=sex {name value} {
+      switch -glob $value {
+        m* {return m}
+        f* {return f}
+        default {
+          error "expected sex but got $value"
+        }
+      }
+    }
+  }
+}
+
+

The configure parameters provided by a class for the initialization of +instances can be introspected via /cls/ info configure parameters +(see [info_configure_parameter]).

+
-

2.4.2. Method Parameters

+

2.4.2. Delete Variable Handlers

+
+ +++ + + + + + + + + + + + +
XOTcl Next Scripting Language
+
+
# No syntactic support for deleting
+# variable handlers
+
+
/cls/ delete property /name/
+/obj/ delete object property /name/
+
+
+
+

2.4.3. Method Parameters

Method parameters are used to specify the interface of a single method (what kind of values may be passed to a method, what default values are provided etc.). The method parameters specifications in XOTcl 1 @@ -3258,7 +3444,7 @@ } # In general, the same list of value - # constraints as for object parameter is + # constraints as for configure parameter is # available (see above). # # User defined value constraints are @@ -3271,7 +3457,7 @@

-

2.4.3. Return Value Checking

+

2.4.4. Return Value Checking

Return value checking is a functionality available in the Next Scripting Framework, that was not yet available in XOTcl 1. A return value checker assures that a method returns always a value satisfying @@ -4713,7 +4899,12 @@ object as usual.

-

2.6.8. List Slots and their definitions

+

2.6.8. List Configure Parameters

+

Obtain information, how newly created object can be configured. The +configuration of objects is performed in many languages over arguments +to the constructors. NX has - what we think - a superiour approach for +configuration via configure parameters. The configure parameter are +defined by NX application programs usually via property.

-
# Return list of slots objects defined on the
-# object or class
-#
-# -source might be all|application|baseclasses
-# -type is the class of the slot object
-# -closure includes slots of superclasses
+
# Return configure parameter(s), the parameters
+# provided by a class for its instances; these
+# parameters define, how objects of this
+# class can be configured. a pattern can
+# be used to filter the results.
 
-/obj/ info object slot objects ?-type ...? ?pattern?
-/cls/ info slot objects \
-   ?-type value? ?-closure? ?-source value? ?pattern?

-
-
- - - - - - +/obj/infolookupconfigure parameters ?pattern? + +# "info lookup configure syntax" returns syntax of +# a call to configure in the Tcl parameter syntax + +/obj/infolookupconfigure syntax + +# Obtain information from a parameter +# (as e.g. returned from "info configure +# parameters"). + +/obj/info parameter name /parameter/ +/obj/info parameter syntax /parameter/ + + +
-
-
# n.a.
-
-
# List definition of slots
+/cls/ info configure parameters ?pattern?
+
+# Return in the Tcl parameter syntax
 
-/obj/ info object slot definition \
-   ?-type value? ?pattern?
-/cls/ info slot definition \
-   ?-type value? ?-closure? ?-source value? ?pattern?
-
-
/cls/ info parameter
-
-
# "info properties" is a short form of "info slot definiton"
+/cls/ info configure syntax
+
+# "info lookup configure parameters" returns
+# parameters available for configuring the
+# current object  (might contain object
+# specific information)
 
-/cls/ info properties \
-   ?-type value? ?-closure? ?-source value? ?pattern?
+
+
+
+

2.6.9. List Variable Handlers

+
+ +++ - - + + + + +
# obtain parameter definitions defined
+# for a class
+/cls/ info parameter
+# "info lookup variables" returns handles +# of variables and properties applicable +# for the current object (might contain +# object specific information) + +/obj/infolookup variables /pattern/ + +# "info variable" lists details about a +# single property or variable. + +/obj/infovariable definition /handle/ +/obj/infovariable name /handle/ +/obj/infovariable parameter /handle/
-
-
# n.a.
-
-
# List names of slots
-
-/obj/ info object slot names \
-   ?-type value? ?pattern?
-/cls/ info slot names \
-   ?-type value? ?-closure? ?-source value? ?pattern?
XOTcl Next Scripting Language
-
# n.a.
-
# List reachable slot objects defined for obj
-# -source might be all|application|baseclasses
-# -type is the class of the slot object
+
# "info variables" returns handles of
+# properties and variables defined by this
+# class or object
 
-/obj/ info lookup slots \
-   ?-type ...? ?-source ... ?pattern?
+/cls/ info variables ?pattern?
+/obj/ info object variables ?pattern?
 
-# Returns list of slot objects
-

2.6.9. List Object parameters

+

2.6.10. List Slots

-
# Return parameter(s) provided by class for
-# its instances; defines, how objects of this
-# class can be configured. If name is provided
-# only the named object parameter is returned
-# otherwise the full list.
+
# Return list of slots objects defined on the
+# object or class
 #
-#
-# Return object parameters with leading dashes
-# for non-positional object parameters and
-# defaults
-/cls/ info parameter list ?name?
+# -source might be all|application|baseclasses
+# -type is the class of the slot object
+# -closure includes slots of superclasses
+
+/obj/ info object slots ?-type ...? ?pattern?
+/cls/ info slots \
+   ?-type value? ?-closure? ?-source value? ?pattern?
 
-# Return just the names of the parameters
-/cls/ info parameter names ?name?
+# List reachable slot objects defined for obj
+# -source might be all|application|baseclasses
+# -type is the class of the slot object
+# Returns list of slot objects.
+
+/obj/ info lookup slots \
+   ?-type ...? ?-source ... ?pattern?
 
-# Return the full parameter specs
-/cls/ info parameter definitions ?name?
-
-# Return in the Tcl parameter syntax
-/cls/ info parameter syntax ?name?

+# Obtain definition, name or parameter from
+# slot object
+
+/slotobj/ definition
+/slotobj/ name
+/slotobj/ parameter
-

2.6.10. List Filter or Mixins

+

2.6.11. List Filter or Mixins

In NX all introspection options for filters are grouped under info filter and all introspection options for mixins are under info mixin. Therefore, NX follows here the approach of using hierarchical @@ -5103,7 +5263,7 @@

-

2.6.11. List definition of methods defined by aliases, setters or forwarders

+

2.6.12. List definition of methods defined by aliases, setters or forwarders

As mentioned earlier, info method definition can be used on every kind of method. The same call can be used to obtain the definition of a scripted method, a method-alias, a forwarder or a setter method.

@@ -5153,7 +5313,7 @@
-

2.6.12. List Method-Handles

+

2.6.13. List Method-Handles

NX supports method-handles to provide means to obtain further information about a method or to change maybe some properties of a method. When a method is created, the method creating method returns @@ -5224,7 +5384,7 @@

-

2.6.13. List type of a method

+

2.6.14. List type of a method

The method info ?object? method type is new in NX to obtain the type of the specified method.

@@ -5298,7 +5458,7 @@
-

2.6.14. List the scope of mixin classes

+

2.6.15. List the scope of mixin classes

NX provides a richer set of introspection options to obtain information, where mixins classes are mixed into.

@@ -5418,7 +5578,7 @@
-

2.6.15. Check properties of object and classes

+

2.6.16. Check properties of object and classes

Similar as noted before, NX uses rather a hierarchical approach of naming using multiple layers of subcommands).

@@ -5629,7 +5789,7 @@
-

2.6.16. Call-stack Introspection

+

2.6.17. Call-stack Introspection

Call-stack introspection is very similar in NX and XOTcl. NX uses for subcommand the term current instead of self, since self has a strong connotation to the current object. The term proc is renamed @@ -6469,8 +6629,8 @@