Index: doc/next-tutorial/next-tutorial.html =================================================================== diff -u -N -rd725e5e4cfc9f89d78e781e6ce27900e199ba8c5 -rd8b8fec1b9c4b2ab7c1cc36c156649109ca0807a --- doc/next-tutorial/next-tutorial.html (.../next-tutorial.html) (revision d725e5e4cfc9f89d78e781e6ce27900e199ba8c5) +++ doc/next-tutorial/next-tutorial.html (.../next-tutorial.html) (revision d8b8fec1b9c4b2ab7c1cc36c156649109ca0807a) @@ -735,8 +735,8 @@
nx::Class create Stack { - # - # Stack of Things - # + # + # Stack of Things + # :variable things {} :public method push {thing} { - set :things [linsert ${:things} 0 $thing] - return $thing + set :things [linsert ${:things} 0 $thing] + return $thing } :public method pop {} { - set top [lindex ${:things} 0] - set :things [lrange ${:things} 1 end] - return $top + set top [lindex ${:things} 0] + set :things [lrange ${:things} 1 end] + return $top } }
Typically, classes are defined in NX via nx::Class create
, followed
@@ -970,14 +970,14 @@
16
17
18
-
#!/usr/bin/env tclsh
+
#!/usr/bin/env tclsh package require nx nx::Class create Stack { - # - # Stack of Things - # + # + # Stack of Things + # .... } @@ -1071,14 +1071,14 @@ :object variable things {} :public object method push {thing} { - set :things [linsert ${:things} 0 $thing] - return $thing + set :things [linsert ${:things} 0 $thing] + return $thing } :public object method pop {} { - set top [lindex ${:things} 0] - set :things [lrange ${:things} 1 end] - return $top + set top [lindex ${:things} 0] + set :things [lrange ${:things} 1 end] + return $top } }
The example in Listing 5 defines the @@ -1184,14 +1184,14 @@ 24
nx::Class create Safety { - # - # Implement stack safety by defining an additional - # instance variable named "count" that keeps track of - # the number of stacked elements. The methods of - # this class have the same names and argument lists - # as the methods of Stack; these methods "shadow" - # the methods of class Stack. - # + # + # Implement stack safety by defining an additional + # instance variable named "count" that keeps track of + # the number of stacked elements. The methods of + # this class have the same names and argument lists + # as the methods of Stack; these methods "shadow" + # the methods of class Stack. + # :variable count 0 @@ -1201,7 +1201,7 @@ } :public method pop {} { - if {${:count} == 0} then { error "Stack empty!" } + if {${:count} == 0} then { error "Stack empty!" } incr :count -1 next } @@ -1325,10 +1325,10 @@ 5 6 7 -
# -# Create a safe stack class by using Stack and mixin -# Safety -# +
# +# Create a safe stack class by using Stack and mixin +# Safety +# nx::Class create SafeStack -superclass Stack -mixin Safety SafeStack create s3
Stack create s4 { - # - # Create a stack with a object-specific method - # to check the type of entries - # + # + # Create a stack with a object-specific method + # to check the type of entries + # :public object method push {thing:integer} { next @@ -1432,9 +1432,9 @@ 10
nx::Class create IntegerStack -superclass Stack { - # - # Create a Stack accepting only integers - # + # + # Create a Stack accepting only integers + # :public method push {thing:integer} { next @@ -1506,14 +1506,14 @@ :variable things {} :public method push {thing} { - set :things [linsert ${:things} 0 $thing] - return $thing + set :things [linsert ${:things} 0 $thing] + return $thing } :public method pop {} { - set top [lindex ${:things} 0] - set :things [lrange ${:things} 1 end] - return $top + set top [lindex ${:things} 0] + set :things [lrange ${:things} 1 end] + return $top } } @@ -1605,11 +1605,11 @@
nx::Class create Foo { :method foo args {...} - # "a" is a method scoped variable + # "a" is a method scoped variable set a 1 - # "b" is an Instance variable + # "b" is an Instance variable set :b 2 - # "c" is a global variable/namespaced variable + # "c" is a global variable/namespaced variable set ::c 3 } }
# -# Define a class Person with properties "name" -# and "birthday" -# +
# +# Define a class Person with properties "name" +# and "birthday" +# nx::Class create Person { :property name:required :property birthday } -# -# Define a class Student as specialization of Person -# with additional properties -# +# +# Define a class Student as specialization of Person +# with additional properties +# nx::Class create Student -superclass Person { :property matnr:required :property {oncampus:boolean true} } -# -# Create instances using configure parameters -# for the initialization -# +# +# Create instances using configure parameters +# for the initialization +# Person create p1 -name Bob Student create s1 -name Susan -matnr 4711 -# Access property value via accessor method +# Access property value via accessor method puts "The name of s1 is [s1 cget -name]"
By defining name
and birthday
as properties of Person
, NX makes
these configurable. When we create an instance of Person
named
@@ -1789,19 +1789,19 @@
15
nx::Class create Base { :variable x 1 - # ... + # ... } nx::Class create Derived -superclass Base { :variable y 2 - # ... + # ... } -# Create instance of the class Derived +# Create instance of the class Derived Derived create d1 -# Object d1 has instance variables -# x == 1 and y == 2
Note that the variable definitions are inherited in the same way as
properties. The example in Listing 19 shows a
class Derived
that inherits from Base
. When an instance d1
is
@@ -1840,23 +1840,23 @@
18
19
nx::Class create Base2 { - # ... + # ... :method init {} { set :x 1 - # .... + # .... } } nx::Class create Derived2 -superclass Base2 { - # ... + # ... :method init {} { set :y 2 next - # .... + # .... } } -# Create instance of the class Derived2 +# Create instance of the class Derived2 Derived2 create d2
In many other object oriented languages, the instance variables are
initialized solely by the constructor (similar to class Derived2
in
@@ -1918,19 +1918,19 @@
12
13
14
-
# Define a class
+
# Define a class nx::Class create Dog { - # Define a scripted method for the class + # Define a scripted method for the class :public method bark {} { puts "[self] Bark, bark, bark." } } -# Create an instance of the class +# Create an instance of the class Dog create fido -# The following line prints "::fido Bark, bark, bark." +# The following line prints "::fido Bark, bark, bark." fido bark
In the example above we create a class Dog
with a scripted method
named bark
. The method body defines the code, which is executed when
@@ -2015,20 +2015,20 @@
:public method wag {} {return Joy}
}
-# Create an instance of the class
+# Create an instance of the class
Dog create fido
-# Use the accessor "length" as a getter, to obtain the value
-# of a property. The following call returns the length of the
-# tail of fido
+# Use the accessor "length" as a getter, to obtain the value
+# of a property. The following call returns the length of the
+# tail of fido
fido::tail length get
-# Use the accessor "length" as a setter, to alter the value
-# of a property. The following call changes the length of
-# the tail of fido
+# Use the accessor "length" as a setter, to alter the value
+# of a property. The following call changes the length of
+# the tail of fido
fido::tail length set 10
-# Proving an invalid values will raise an error
+# Proving an invalid values will raise an error
fido::tail length set "Hello"
Listing 22 shows an extended example, where every dog
has a tail. The object tail
is created as a subobject of the dog in
@@ -2082,11 +2082,11 @@
:public method wag {} {return Joy}
}
-# Create an instance of the class
+# Create an instance of the class
Dog create fido
-# The invocation of "fido wag" is delegated to "fido::tail wag".
-# Therefore, the following method returns "Joy".
+# The invocation of "fido wag" is delegated to "fido::tail wag".
+# Therefore, the following method returns "Joy".
fido wag
Listing 23 again extends the example by adding a
forwarder named wag
to the object (e.g. fido
). The forwarder
@@ -2149,15 +2149,15 @@
nx::Class create Dog { :public method bark {} { puts "[self] Bark, bark, bark." } - # Define a public alias for the method "bark" + # Define a public alias for the method "bark" :public alias warn [:info method handle bark] - # ... + # ... } -# Create an instance of the class +# Create an instance of the class Dog create fido -# The following line prints "::fido Bark, bark, bark." +# The following line prints "::fido Bark, bark, bark." fido warn
Listing 24 extends the last example by defining an
alias for the method bark
. The example only shows the bare
@@ -2230,25 +2230,25 @@
22
nx::Class create Foo { - # Define a public method + # Define a public method :public method foo {} { - # .... + # .... return [:helper] } - # Define a protected method + # Define a protected method :method helper {} { return 1 } } -# Create an instance of the class: +# Create an instance of the class: Foo create f1 -# The invocation of the public method "foo" returns 1 +# The invocation of the public method "foo" returns 1 f1 foo -# The invocation of the protected method "helper" raises an error: +# The invocation of the protected method "helper" raises an error: f1 helper
The example above uses :protected method helper …
. We could have
used here as well :method helper …
, since the default method
@@ -2284,19 +2284,19 @@
13
14
nx::Class create Base { - :private method helper {a b} {expr {$a + $b}} - :public method foo {a b} {: -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} {: -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 } -s1 foo 3 4 ;# returns 7 -s1 bar 3 4 ;# returns 12 -s1 helper 3 4 ;# raises error: unable to dispatch method helper
The base class implements a public method foo
using the helper
method named helper
. The derived class implements a as well a public
method bar
, which is also using a helper method named helper
. When
@@ -2360,31 +2360,31 @@
23
24
25
-
# -# Define a class C with a property "x" and a public accessor -# +
# +# Define a class C with a property "x" and a public accessor +# nx::Class create C { :property -accessor public {x c} } -# -# Define a subclass D with a private property "x" -# and a method bar, which is capable of accessing -# the private property. -# +# +# 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 { :property -accessor private {x d} - :public method bar {p} {return [: -local $p get]} + :public method bar {p} {return [: -local $p get]} } -# -# The private and public (or protected) properties -# define internally separate variable that do not -# conflict. -# +# +# The private and public (or protected) properties +# define internally separate variable that do not +# conflict. +# D create d1 -puts [d1 x get] ;# 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
@@ -2430,8 +2430,8 @@
:create c1
}
-# Method "foo" is defined on class "C"
-# and applicable to the instances of "C"
+# Method "foo" is defined on class "C"
+# and applicable to the instances of "C"
c1 foo
There are many programming languages that only allow these types of methods. However, NX also allows methods to be defined on objects.
nx::Class create C { - # - # Define a class method "bar" and an instance - # method "foo" - # + # + # Define a class method "bar" and an instance + # method "foo" + # :public object method bar {} {return 2} :public method foo {} {return 1} - # - # Create an instance of the current class - # + # + # Create an instance of the current class + # :create c1 } -# Method "bar" is a class method of class "C" -# therefore applicable on the class object "C" +# Method "bar" is a class method of class "C" +# therefore applicable on the class object "C" C bar -# Method "foo" is an instance method of "C" -# therefore applicable on instance "c1" +# Method "foo" is an instance method of "C" +# therefore applicable on instance "c1" c1 foo -# When trying to invoke the class method on the -# instance, an error will be raised. +# When trying to invoke the class method on the +# instance, an error will be raised. c1 bar
In some other object oriented programming languages, class methods are called "static methods".
nx::Class create C { - # Define an ensemble method "string" with sub-methods - # "length", "tolower" and "info" + # Define an ensemble method "string" with sub-methods + # "length", "tolower" and "info" :public method "string length" {x} {....} :public method "string tolower" {x} {...} :public method "string info" {x} {...} - #... + #... :create c1 } -# Invoke the ensemble method +# Invoke the ensemble method c1 string length "hello world"
Consider the example in
Listing 32. When the method
foo
is invoked on object d1
, the object method has the highest
@@ -2775,23 +2775,23 @@
:public method foo {} { return "M2 foo: [next]"}
}
-#
-# "d1" is created based on the definitions of the last example
-#
-# Add the methods from "M1" as per-object mixin to "d1"
+#
+# "d1" is created based on the definitions of the last example
+#
+# Add the methods from "M1" as per-object mixin to "d1"
d1 object mixins add M1
-#
-# Add the methods from "M2" as per-class mixin to class "C"
+#
+# Add the methods from "M2" as per-class mixin to class "C"
C mixins add M2
-# Invoke the method foo
+# Invoke the method foo
d1 foo
-# result: "M1 foo: M2 foo: d1 foo: D foo: C foo: "
+# result: "M1 foo: M2 foo: d1 foo: D foo: C foo: "
-# Query the precedence order from NX via introspection
+# Query the precedence order from NX via introspection
d1 info precedence
-# result: "::M1 ::M2 ::D ::C ::nx::Object"
The example in Listing 33 is
an extension of the previous example. We define here two additional
classes M1
and M2
which are used as per-object and per-class
@@ -2827,21 +2827,21 @@
14
15
16
-
# -# "d1" is created based on the definitions of the last two examples, -# the mixins "M1" and "M2" are registered. -# -# Define a public object method "bar", which calls the method -# "foo" which various invocation options: -# +
# +# "d1" is created based on the definitions of the last two examples, +# the mixins "M1" and "M2" are registered. +# +# Define a public object method "bar", which calls the method +# "foo" which various invocation options: +# d1 public object method bar {} { puts [:foo] puts [: -local foo] puts [: -intrinsic foo] puts [: -system foo] } -# Invoke the method "bar" +# 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 receiver, which defaults to the
@@ -2973,37 +2973,37 @@
36
nx::Object create o1 { - # - # Method foo has positional parameters: - # + # + # Method foo has positional parameters: + # :public object method foo {x y} { puts "x=$x y=$y" } - # - # Method bar has non-positional parameters: - # + # + # Method bar has non-positional parameters: + # :public object method bar {-x -y} { puts "x=$x y=$y" } - # - # Method baz has non-positional and - # positional parameters: - # + # + # Method baz has non-positional and + # positional parameters: + # :public object method baz {-x -y a} { puts "x? [info exists x] y? [info exists y] a=$a" } } -# invoke foo (positional parameters) +# invoke foo (positional parameters) o1 foo 1 2 -# invoke bar (non-positional parameters) +# invoke bar (non-positional parameters) o1 bar -y 3 -x 1 o1 bar -x 1 -y 3 -# invoke baz (positional and non-positional parameters) +# invoke baz (positional and non-positional parameters) o1 baz -x 1 100 o1 baz 200 o1 baz -- -y
nx::Object create o2 { - # - # Method foo has one required and one optional - # positional parameter: - # + # + # Method foo has one required and one optional + # positional parameter: + # :public object method foo {x:required y:optional} { puts "x=$x y? [info exists y]" } - # - # Method bar has one required and one optional - # non-positional parameter: - # + # + # Method bar has one required and one optional + # non-positional parameter: + # :public object method bar {-x:required -y:optional} { puts "x=$x y? [info exists y]" } } -# invoke foo (one optional positional parameter is missing) +# invoke foo (one optional positional parameter is missing) o2 foo 1
The example in Listing 36 defined method foo
with one required and one optional positional parameter. For this
@@ -3153,22 +3153,22 @@
20
nx::Object create o3 { - # - # Positional parameter with default value: - # + # + # Positional parameter with default value: + # :public object method foo {{x 1} {y 2}} { puts "x=$x y=$y" } - # - # Non-positional parameter with default value: - # + # + # Non-positional parameter with default value: + # :public object method bar {{-x 10} {-y 20}} { puts "x=$x y=$y" } } -# use default values +# use default values o3 foo o3 bar
In order to define a default value for a parameter, the parameter @@ -3243,23 +3243,23 @@ 20
nx::Object create o4 { - # - # Positional parameter with value constraints: - # + # + # Positional parameter with value constraints: + # :public object method foo {x:integer o:object,optional} { puts "x=$x o? [info exists o]" } - # - # Non-positional parameter with value constraints: - # + # + # Non-positional parameter with value constraints: + # :public object method bar {{-x:integer 10} {-verbose:boolean false}} { puts "x=$x verbose=$verbose" } } -# The following invocation raises an exception, since the -# value "a" for parameter "x" is not an integer +# The following invocation raises an exception, since the +# value "a" for parameter "x" is not an integer o4 foo a
Value contraints are specified as parameter options in the parameter
specifications. The parameter specification x:integer
defines x
as
@@ -3310,33 +3310,33 @@
26
27
28
-
# -# Create classes for Person and Project -# +
# +# Create classes for Person and Project +# nx::Class create Person nx::Class create Project nx::Object create o5 { - # - # Parameterized value constraints - # + # + # Parameterized value constraints + # :public object method work { -person:object,type=Person -project:object,type=Project } { - # ... + # ... } } -# -# Create a Person and a Project instance -# +# +# Create a Person and a Project instance +# Person create gustaf Project create nx -# -# Use method with value constraints -# +# +# Use method with value constraints +# o5 work -person gustaf -project nx
The native checkers object
, class
, metaclass
and baseclass
can
be further specialized with the parameter option type
to restrict
@@ -3414,47 +3414,47 @@
41
42
43
-
# -# Value checker named "groupsize" -# +
# +# Value checker named "groupsize" +# ::nx::Slot method type=groupsize {name value} { - if {$value < 1 || $value > 6} { + if {$value < 1 || $value > 6} { error "Value '$value' of parameter $name is not between 1 and 6" } } -# -# Value checker named "choice" with extra argument -# +# +# Value checker named "choice" with extra argument +# ::nx::Slot method type=choice {name value arg} { - if {$value ni [split $arg |]} { + if {$value ni [split $arg |]} { error "Value '$value' of parameter $name not in permissible values $arg" } } -# -# Create an application class D -# using the new value checkers -# +# +# Create an application class D +# using the new value checkers +# nx::Class create D { :public method foo {a:groupsize} { - # ... + # ... } :public method bar {a:choice,arg=red|yellow|green b:choice,arg=good|bad} { - # ... + # ... } } D create d1 -# testing "groupsize"; -# the second call (with value 10) will raise an exception: +# testing "groupsize"; +# the second call (with value 10) will raise an exception: d1 foo 2 d1 foo 10 -# testing "choice" -# the second call (with value pink for parameter a) -# will raise an exception: +# testing "choice" +# the second call (with value pink for parameter a) +# will raise an exception: d1 bar green good d1 bar pink bad
In order to define a checker groupsize
a method of the name
@@ -3542,26 +3542,26 @@
26
nx::Object create o6 { - # - # Positional parameter with an possibly empty - # single value - # + # + # Positional parameter with an possibly empty + # single value + # :public object method foo {x:integer,0..1} { puts "x=$x" } - # - # Positional parameter with an possibly empty - # list of values value - # + # + # Positional parameter with an possibly empty + # list of values value + # :public object method bar {x:integer,0..n} { puts "x=$x" } - # - # Positional parameter with a non-empty - # list of values - # + # + # Positional parameter with a non-empty + # list of values + # :public object method baz {x:integer,1..n} { puts "x=$x" } @@ -3681,32 +3681,32 @@ 25 26 27 -
# -# Define a class Person with properties "name" -# and "birthday" -# +
# +# Define a class Person with properties "name" +# and "birthday" +# nx::Class create Person { :property name:required :property birthday } -# -# Define a class Student as specialization of Person -# with and additional property -# +# +# Define a class Student as specialization of Person +# with and additional property +# nx::Class create Student -superclass Person { :property matnr:required :property {oncampus:boolean true} } -# -# Create instances using configure parameters -# for the initialization -# +# +# Create instances using configure parameters +# for the initialization +# Person create p1 -name Bob Student create s1 -name Susan -matnr 4711 -# Access property value via "cget" method +# Access property value via "cget" method puts "The name of s1 is [s1 cget -name]"
The class Person
has two properties name
and birthday
, where the
property name
is required, the property birthday
is not. The
@@ -3978,10 +3978,10 @@
}
}
-# Invoke an unknown method for object o:
+# Invoke an unknown method for object o:
o foo 1 2 3
-# Output will be: "Unknown method 'foo' called"
Without any provision of an unknown method handler, an error will be raised, when an unknown method is called.
::nx::Class public object method __unknown {name} { - # A very simple unknown handler, showing just how - # the mechanism works. + # A very simple unknown handler, showing just how + # the mechanism works. puts "***** __unknown called with <$name>" - ::nx::Class create $name + ::nx::Class create $name } -# Register an unknown handler as a method of ::nx::Class +# Register an unknown handler as a method of ::nx::Class ::nsf::object::unknown::add nx {::nx::Class __unknown} ::nx::Object create o { - # The class M is unknown at this point + # The class M is unknown at this point :object mixins add M - # The line above has triggered the unknown class handler, - # class M is now defined + # The line above has triggered the unknown class handler, + # class M is now defined puts [:info object mixins] - # The output will be: - # ***** __unknown called with <::M> - # ::M + # The output will be: + # ***** __unknown called with <::M> + # ::M }
The Next Scripting Framework allows to add, query, delete and list unknown handlers.
# Interface for unknown handlers: -# nsf::object::unknown::add /key/ /handler/ -# nsf::object::unknown::get /key/ -# nsf::object::unknown::delete /key/ -# nsf::object::unknown::keys
# Interface for unknown handlers: +# nsf::object::unknown::add /key/ /handler/ +# nsf::object::unknown::get /key/ +# nsf::object::unknown::delete /key/ +# nsf::object::unknown::keys
@@ -4155,8 +4155,8 @@