Index: TODO =================================================================== diff -u -r57c47e5fff431976511c200231567024bea09ff4 -r05f429e6986a7ed8c8d36cad30609f457ec93281 --- TODO (.../TODO) (revision 57c47e5fff431976511c200231567024bea09ff4) +++ TODO (.../TODO) (revision 05f429e6986a7ed8c8d36cad30609f457ec93281) @@ -854,6 +854,13 @@ * distributed packages in namespace ::nx::* * names of subpackages next::* + * should we stay with ::nx::: as namespace prefix? + The following looks inconsistent: + + package require next + package require next::test + namespace import ::nx::* + - documentation - documentationssytem - langref (xotcl 2.0 + next-scripting) Fisheye: Tag 05f429e6986a7ed8c8d36cad30609f457ec93281 refers to a dead (removed) revision in file `doc/migration1-2.html'. Fisheye: No comparison available. Pass `N' to diff? Index: doc/next-migration.html =================================================================== diff -u --- doc/next-migration.html (revision 0) +++ doc/next-migration.html (revision 05f429e6986a7ed8c8d36cad30609f457ec93281) @@ -0,0 +1,914 @@ + + + +Migration Guide from XOTcl to the Next Scripting Language + + + + +

Introduction

+ +... general text, maybe partly from slides/paper .... + + +TODO: Maybe we should not refer to ::nx::core here and import instead +the "needed" commands into ::nx namespace. + +

Using XOTcl 2.0 and the Next Scripting Language in the Next +Scripting Framework

+ +

In general, the Next Scripting Framework supports multiple object +systems concurrently. Effectively, every object system has different +base classes for creating objects and classes. Therefore, these object +systems can have different different interfaces and names of builtin +methods. Currently, the Next Scripting Framework supports primarily +XOTcl 2.0 (highly compatible with XOTcl 1.*) and the Next Scripting +Language (XOTcl provides about twice as many predefined builtin +methods compared to the Next Scripting Language).

+ +

A single Tcl interpreter can host both, XOTcl and the Next +Scripting Language at the same time. This makes migration +from XOTcl to Next easier. The following example script shows to use +in a single script XOTcl and Next: +

+ +

+   namespace eval mypackage {
+
+      package require XOTcl 2.0
+
+      # Import XOTcl into the current namespace
+      namespace import -force ::xotcl::*
+
+      # Define a class using XOTcl
+      Class C1
+      C1 instproc foo {} {puts "hello world"}
+
+      # Import Next into the current namespace
+      namespace import -force ::nx::*
+
+      # Define a class using Next
+      Class create C2 {
+         :method foo {} {puts "hello world"}
+      }
+   }
+

+ +

"Switching" between XOTcl and Next effectively means the load some +packages (if needed) and to import either the base classes +(Object and Class) of XOTcl or Next +into the current namespace.

+ +

XOTcl Idioms in the Next Scripting Language

+ +

Defining Objects and Classes

+ + + + + + + + + + + + + + + + + + +

XOTcl	Next Scripting Language
`Class ClassName`	`Class create ClassName`
`Object ObjectName`	`Object create ObjectName`
`::xotcl::Class ClassName`	`::nx::Class create ClassName`
`::xotcl::Object ObjectName`	`::nx::Object create ObjectName`

+ +

Defining Methods

+ +

Scripted Methods Defined in the Init-block of a Class/Object or with +Separate Calls

+ + + + + + + + + + + +

XOTcl	Next Scripting Language
`Class C + C instproc foo args {...} + C proc bar args {...} +`	+ # Define method and object method # in the init-block of a class + `Class create C { + :method foo args {...} + :object method bar args {...} + }` + # Define method and object method with separate calls + `Class create C + C method foo args {...} + C object method bar args {...} +`
`Object o + o set x 1 + o proc foo args {...} +`	+ # Define object method and set instance variable + # in the init-block of an object + `Object create o { + set :x 1 + :method foo args {...} + }` + # Define object method and set instance variable + # with separate commands + `Object create o + o eval {set :x 1} + o method foo args {...} +`

+ +

Define Different Kinds of Methods

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

XOTcl	Next Scripting Language
+ # Methods for defining methods: # + # proc + # instproc + # forward + # instforward + # parametercmd + # instparametercmd + +	+ # Methods for defining methods: # + # method + # forward + # setter + # alias + # attribute + +
+ `Class C + C instproc foo args {...} + C proc bar args {...} + Object o + o proc baz args {...} + +`	+ # Define scripted methods + `Class create C { + :method foo args {...} + :object method bar args {...} + } + Object create o { + :method baz args {...} + } +`
+ `Class C + C instforward f1 ... + C forward f2 ... + Object o + o forward f3 ... + +`	+ # Define forwarder + `Class create C { + :forward f1 ... + :object forward f2 ... + } + Object create o { + :forward f3 ... + } +`
+ `Class C + C instparametercmd p1 + C parametercmd p2 + Object o + o parametercmd p3 + +`	+ # Define setter and getter methods + `Class create C { + :setter p1 ?value_constraint? + :object setter p2 ?value_constraint? + } + Object create o { + :setter p3 ?value_constraint? + } +`
+ # Method "alias" not available +	+ # Define method aliases # (to scripted or non-scripted methods) + `Class create C { + :alias a1 ... + :object alias a2 ... + } + Object create o { + :alias a3 ... + } +`
+ # Parameters only available at class level + `Class C \ -parameter { + x + {y 1} + } +` +	+ # Define object attributes # (parameters for initializing objects) + `Class create C { + :attribute x + :attribute {y 1} + :object attribute oa1 + } + Object create o { + :attribute oa2 + } +`

+ +

Method Modifiers and Method Protection

+ + + + + + + + + +

XOTcl Next Scripting Language

# Method modifiers
+ #
+ # "object",
+ # "public", and
+ # "protected"
+ #
+ # are not available.

+ + # Method modifiers orthogonal over all kinds of methods
+ #
+ # Method-definition-methods:
+ # method, forward, setter, alias, attribute +

+ Class create C { + :method-definiton-method ... + :public method-definiton-method ... + :protected method-definiton-method ... + :object method-definiton-method ... + :protected object method-definiton-method ... + :public object method-definiton-method ... + } +

XOTcl	Next Scripting Language
# Method modifiers + # + # "object", + # "public", and + # "protected" + # + # are not available. +	+ # Method modifiers orthogonal over all kinds of methods + # + # Method-definition-methods: + # method, forward, setter, alias, attribute + + `Class create C { + :method-definiton-method ... + :public method-definiton-method ... + :protected method-definiton-method ... + :object method-definiton-method ... + :protected object method-definiton-method ... + :public object method-definiton-method ... + } +`

+ +

Resolvers

+ +The Next Scripting Framework defines Tcl resolvers for method and +variable names to refer to object specific behavior. Withing method +bodies these resolver treat variable and function names starting with +a colon ":" specially. In short, a colon-prefixed variable name refers +to an instance variable, and a colon-prefixed function name refers to +a method. The sub-sections below provide detailed examples. + +

Note that the Next resolvers are used in the XOTcl 2.* environment +as well. + +

Invoking Methods

+ + + + + + +

XOTcl	Next Scripting Language
`Class C + C instproc foo args {...} + C instproc bar args { + my foo 1 2 3 ;# invoke own method + o baz ;# invoke other objects method + } + Object o + o proc baz {} {...} +`	`Class create C { + :method foo args {...} + :method bar args { + :foo 1 2 3 ;# invoke own method + o baz ;# invoke other objects method + } + } + Object create o { + :method baz {} {...} + } +`

+ + +

Accessing Own Instance Variables from Method Bodies

+ + + + + + + + + + + + + + + + + + + + + + + +

XOTcl	Next Scripting Language
`Class C + C instproc foo args { + # method scoped variable a + set a 1 + # instance variable b + my instvar b + set b 2 + # global variable/namespaced variable c + set ::c 3 + } +`	`Class create C { + :method foo args {...} + # method scoped variable a + set a 1 + # instance variable b + set :b 2 + # global variable/namespaced variable c + set ::c 3 + } + } +`
`my set varname value`	+ # set own instance variable to a value via + resolver # (prefered and fastest way) + `set :newVar value` +
`my instvar newVar + set newVar value +`	+ # set own instance variable via variable import + `::nx::var import [self] varname + set varname value +`
+ `set newVar [my set otherVar]`	+ # read own instance variable + `set newVar [set :otherVar]` + `set newVar ${:otherVar}` +
`my exists varname`	+ # Test existence of own instance variable + `info :varname` + + `::nx::var exists [self] varname` +

+ +

Accessing Instance Variables of other Objects

+ + + + + + + + + + + + + + + + + + +

XOTcl	Next Scripting Language
`obj set varname value`	+ # set instance variable of object obj to a value via + namespace # resolver (prefered way: define setter method on obj) + `obj eval [list set :varname value]`
`set newVar [obj set otherVar]`	+ # read instance variable of object obj via resolver + `set newVar [obj eval {set :otherVar}]` +
`obj instvar newVar + set newVar value` +	+ # read instance variable of object obj via import + `::nx::var import obj newVar + set newVar value`
`obj exists varname`	+ # Test existence of instance variable of + object obj + `obj eval {info exists :varname}` + + `::nx::var exists obj varname` +

+ + +

Object Parameters

Method Parameters

Introspection

+ +

List methods defined by objects

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

XOTcl	Next Scripting Language
`obj info commands ?pattern?`	`obj info methods ?pattern?`
`obj info parametercmd ?pattern?`	`obj info methods -methodtype setter ?pattern?`
`obj info procs ?pattern?`	`obj info methods -methodtype scripted ?pattern?`
n.a.	`obj info methods -methodtype alias ?pattern?`
n.a.	`obj info methods -methodtype forwarder ?pattern?`
n.a.	`obj info methods -methodtype object ?pattern?`
n.a.	`obj info methods -callprotection public\|protected ...`

List methods defined by classes

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

`cls info instcommands ?pattern?`	`cls info methods ?pattern?`
`cls info instparametercmd ?pattern?`	`cls info methods -methodtype setter ?pattern?`
`cls info instprocs ?pattern?`	`cls info methods -methodtype scripted ?pattern?`
n.a.	`cls info methods -methodtype alias ?pattern?`
n.a.	`cls info methods -methodtype forwarder ?pattern?`
n.a.	`cls info methods -methodtype object ?pattern?`
n.a.	`cls info methods -callprotection public\|protected ...`

+ +

List class object specific methods

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

`cls info commands ?pattern?`	`cls object info methods ?pattern?`
`cls info parametercmd ?pattern?`	`cls object info methods -methodtype setter ?pattern?`
`cls info procs ?pattern?`	`cls object info methods -methodtype scripted ?pattern?`
n.a.	`cls object info methods -methodtype alias ?pattern?`
n.a.	`cls object info methods -methodtype forwarder ?pattern?`
n.a.	`cls object info methods -methodtype object ?pattern?`
n.a.	`cls object info methods -callprotection public\|protected ...`

+ +

List callable methods

+ + + + + + + + + + +

XOTcl	Next Scripting Language
`obj info methods ?pattern?`	`obj info callable ?pattern?`
n.a.	`# list only application specific methods` + `obj info callable -application`

+ +

List object/class where some method is defined

+ + + + + + + +

XOTcl	Next Scripting Language
`obj procsearch methodName`	`obj info callable -which methodName`

+ +

List definition of scripted methods defined by classes

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

XOTcl	Next Scripting Language
`cls info instbody methodName`	`cls info method body methodName`
`cls info instargs methodName`	`cls info method args methodName`
`cls info instnonposargs methodName`	`cls info method parameter methodName`
`cls info instdefault methodName`	`cls info method parameter methodName`
`cls info instpre methodName`	`cls info method precondition methodName`
`cls info instpost methodName`	`cls info method postcondition methodName`
n.a.	`cls info method definition methodName`

+ +

List definition of scripted object specific methods

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

XOTcl	Next Scripting Language
`obj info body methodName`	`obj info method body methodName`
`obj info args methodName`	`obj info method args methodName`
`obj info nonposargs methodName`	`obj info method parameter methodName`
`obj info default methodName`	`obj info method parameter methodName`
`obj info pre methodName`	`obj info method precondition methodName`
`obj info post methodName`	`obj info method postcondition methodName`
n.a.	`obj info method definition methodName`

For definition of class object specific methods, use modifier + object as shown in examples above. +

+ +

List filter or mixins

+ + + + + + + + + + + + + + + + + + + + + + + + + + +

XOTcl	Next Scripting Language
`obj info filter ?-order? ?-guards? ?pattern?`	`obj info filter ?-order? ?-guards? ?pattern?`
`cls info filter ?-order? ?-guards? ?pattern?`	`cls object info filter ?-order? ?-guards? ?pattern?`
`cls info instfilter ?-order? ?-guards? ?pattern?`	`cls info filter ?-order? ?-guards? ?pattern?`
`obj info mixin ?-order? ?-guards? ?pattern?`	`obj info mixin ?-order? ?-guards? ?pattern?`
`cls info mixin ?-order? ?-guards? ?pattern?`	`cls object info mixin ?-order? ?-guards? ?pattern?`
`cls info instmixin ?-order? ?-guards? ?pattern?`	`cls info mixin ?-order? ?-guards? ?pattern?`

+ +

List definition of methods defined by aliases, setters or forwarders

+ + + + + + + + + + +

XOTcl	Next Scripting Language
n.a.	`obj info method definition methodName`
n.a.	`cls ?object? info method definition methodName`

+ +

List fully qualified name of method

+ + + + + + + + + + +

XOTcl	Next Scripting Language
n.a.	`obj info method name methodName`
n.a.	`cls ?object? info method name methodName`

+ +

List type of a method

+ + + + + + + + + + +

XOTcl	Next Scripting Language
n.a.	`obj info method type methodName`
n.a.	`cls ?object? info method type methodName`

+ +

List the scope of mixin classes

+ + + + + + + + + + + + + + +

XOTcl	Next Scripting Language
`cls info mixinof ?-closure? ?pattern?`	`cls info mixinof -scope object ?-closure? ?pattern?`
`cls info instmixinof ?-closure? ?pattern?`	`cls info mixinof -scope class ?-closure? ?pattern?`
n.a.	`cls info mixinof -scope all ?-closure? ?pattern?`

+ +

Check properties of object and classes

+ + + + + + + + + + + + + + + + + + + + + + + + + + + +

XOTcl	Next Scripting Language
`obj istype sometype`	+ TODO: ::nx::core::objectproperty and/or + ::nx::objectproperty and/or nx::is? + `::nx::core::objectproperty obj type sometype` + + `obj info is type sometype` +
`obj ismixin cls`	+ `::nx::core::objectproperty obj mixin cls` + + `obj info is mixin cls` +
`obj isclass ?cls?`	+ `::nx::core::objectproperty obj\|cls class` + + `obj info is class` +
`obj ismetaclass cls`	`::nx::core::objectproperty obj\|cls metaclass` + + `obj info is metaclass` +
n.a.	`::nx::core::objectproperty cls baseclass` + + `cls info is baseclass` +
`obj isobject obj2`	`::nx::core::objectproperty obj\|obj2 object` + + `obj info is object` +

+ +

Predefined Methods

Dispatch, Aliases, etc.

Assertions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

XOTcl	Next Scripting Language
`obj check checkoptions`	`::nx::core::assertion obj check checkptions`
`obj info check`	`::nx::core::assertion obj check`
`obj invar conditions`	`::nx::core::assertion obj object-invar conditions`
`obj info invar`	`::nx::core::assertion obj object-invar`
`cls instinvar conditions`	`::nx::core::assertion cls class-invar conditions`
`cls info instinvar`	`::nx::core::assertion cls class-invar`
`cls invar conditions`	`::nx::core::assertion cls object-invar conditions`
`cls info invar`	`::nx::core::assertion cls object-invar`

Method Protection

+ + +

Incompatibilities between Next Scripting/XOTcl 2.0 and XOTcl 1.*

+ +

Resolvers

The tesolvers of the Next Scripting Framework are used as well +within XOTcl 2.0. When names starting with single colons are used in +XOTcl 1.* scripts, conflicts will arise. +

+ +

Stronger Checking

+ +

The Next Scripting Framework performs stronger checking than XOTcl +1.*. For example, the requiredness of slots in XOTcl was just a +comment, while Next enforces it.

+ +

Different results

[self next] returns
+ instead of "proc" and "instproc" => "method"
+ instead of "parametercmd" and "instparametercmd" => "setter"
+ instead of "instforward" => "forward"
+ instead of "instcmd" => "cmd".
+ The modifier "object" is added when needed. +
[self filterreg] returns
+ instead of "instforward" => "forward"
+ The modifier "object" is added when needed. +

+ + + +

Exit Handlers

+The exit hander interface changed from a method of +::xotcl::Object into three Tcl procs in the ::nx::core +namespace. Next provides now: +

+   ::nx::core::setExitHandler script
+   ::nx::core::getExitHandler
+   ::nx::core::unsetExitHandler
+

+ + +

+ Last modified: Mon Aug 2 14:48:57 CEST 2010 + +