Index: doc/next-migration.txt =================================================================== diff -u -N -r78c12b94b4cdcd5edb70a546b7bbb7c0a4724668 -r18b6516228b6bdc151f98734b6a3027bb1eff6fb --- doc/next-migration.txt (.../next-migration.txt) (revision 78c12b94b4cdcd5edb70a546b7bbb7c0a4724668) +++ doc/next-migration.txt (.../next-migration.txt) (revision 18b6516228b6bdc151f98734b6a3027bb1eff6fb) @@ -19,7 +19,7 @@ The Next Scripting Language (NX) is a successor of XOTcl 1 and is based on 10 years of experience with XOTcl in projects containing -several hundert thousand lines of code. While XOTcl was the first +several hundred thousand lines of code. While XOTcl was the first language designed to provide language support for design patterns, the focus of the Next Scripting Framework and NX are on combining this with Language Oriented Programming. In many respects, NX was designed @@ -49,7 +49,7 @@ orthogonal environment, which is better suited for large projects, trying to reduce maintenance costs. -We expect that many user will find it attractive to upgrade +We expect that many users will find it attractive to upgrade from XOTcl 1 to XOTcl 2, and some other users will upgrade to NX. This document focuses mainly on the differences between XOTcl 1 and NX, but addresses as well potential incompatibilities between XOTcl 1 @@ -170,7 +170,7 @@ processed in Tcl). . *Significantly Improved Test Suite:* The regression test suite of - Next Scripting Scripting framework contain now more than + Next Scripting framework contain now more than 5.000 tests, and order of magnitude more than in XOTcl 1.6 . *Much Smaller Interface:* The Next Scripting Language has a much @@ -203,7 +203,7 @@ NX supports a block syntax, where the methods are defined during the creation of the class. The XOTcl syntax is slightly more redundant, -since every definition of a method is a single toplevel command +since every definition of a method is a single top-level command starting with the class name (also NX supports the style used in XOTcl). In NX, all methods are per default protected (XOTcl does not support protection). In NX methods are defined in the definition of @@ -296,13 +296,13 @@ package require XOTcl 2.0 - # Define a class with a public method foo using XOTcl + # Define a class with a public method "foo" using XOTcl xotcl::Class C1 C1 instproc foo {} {puts "hello world"} package require nx - # Define a class with a public method foo using NX + # Define a class with a public method "foo" using NX nx::Class create C2 { :public method foo {} {puts "hello world"} } @@ -393,7 +393,7 @@ The following examples show the definition of a class and its methods in the init-block of a class (NX only), and the definition of methods -via separate top level calls (XOTcl and NX). +via separate top-level calls (XOTcl and NX). [options="header",cols="asciidoc,asciidoc",frame="none",valign="middle"] |====================== @@ -403,7 +403,7 @@ ---------------- # Define instance method 'foo' and object # method 'bar' for a Class 'C' with separate -# toplevel commands +# top-level commands Class C C instproc foo args {...} @@ -731,7 +731,7 @@ The Next Scripting Framework defines Tcl resolvers for method and variable names to implement object specific behavior. Within the -bodies of scripted methods these resolver treat variable and function +bodies of scripted methods these resolvers 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 @@ -1014,7 +1014,7 @@ Since the term "parameter" is underspecified, NX uses a more differentiated terminology. NX distinguishes between configurable -instance variables (also called _properties_) and non configurable +instance variables (also called _properties_) and non-configurable instance variables (called _variables_), which might have as well e.g. default values. The values of configurable properties can be queried at run time via +cget+, and their values can be altered via @@ -1032,7 +1032,8 @@ every +parameter+ defined as well automatically a same-named accessor method, leading to potential name conflicts with other method names. -In the examples below we show the definition of configurable a non-configurable instance variables using +variable+ and +property+ +In the examples below we show the definition of non-configurable +instance variables using +variable+ and +property+ respectively. [options="header",cols="asciidoc,asciidoc",frame="none",valign="middle"] @@ -1197,7 +1198,7 @@ # value of instance variable "b" f1 configure -b 100 -# Return the (non substituted) value of +# Return the (non-substituted) value of # parameter "c", and the substituted value # of parameter "d" f1 cget -c @@ -1566,7 +1567,7 @@ 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 -were limited and allowed only value constraints for non positional +were limited and allowed only value constraints for non-positional arguments. NX and XOTcl 2 provide value constraints for all kind of method parameters. @@ -2019,7 +2020,7 @@ ==== List callable methods -In order to obtain for an object the set of artefacts defined in the +In order to obtain the set of artefacts for an object defined in the class hierarchy, NX uses +info lookup+. One can either lookup methods (via +info lookup methods+) or slots (via +info lookup slots+). The plural term refers to a potential set of return values. @@ -2138,7 +2139,7 @@ methods. In NX, this list of +info+ subcommands is much shorter and more -orthogonal. For example +info method definition+ can be used to obtain +orthogonal. For example, +info method definition+ can be used to obtain with a single command the full definition of a _scripted method_, and furthermore, it works as well the same way to obtain e.g. the definition of a _forwarder_ or an _alias_. Index: doc/next-tutorial/next-tutorial.txt =================================================================== diff -u -N -rd25e6ec76196ecb6bf5cdba9fec72bced9062537 -r18b6516228b6bdc151f98734b6a3027bb1eff6fb --- doc/next-tutorial/next-tutorial.txt (.../next-tutorial.txt) (revision d25e6ec76196ecb6bf5cdba9fec72bced9062537) +++ doc/next-tutorial/next-tutorial.txt (.../next-tutorial.txt) (revision 18b6516228b6bdc151f98734b6a3027bb1eff6fb) @@ -107,7 +107,7 @@ In our first example, we define a class named +Stack+ with the methods +push+ and +pop+. When an instance of the stack is created (e.g. a concrete stack +s1+) the stack will contain an instance variable named -+things+, initialized with the an empty list. ++things+, initialized with an empty list. [[xmp-class-stack]] .Listing {counter:figure-number}: Class Stack @@ -168,7 +168,7 @@ a new list is returned, where the new element is inserted at the first position (index 0) in the list +things+. The result of the +linsert+ function is assigned again to the instance variable +things+, which is -updated this way. Finally the method +push+ returns the pushed thing +updated this way. Finally, the method +push+ returns the pushed thing using the +return+ statement. The method +pop+ returns the most recently stacked element and removes @@ -318,7 +318,7 @@ the methods of the class are updated, all instances of the class will immediately get the modified behavior. However, this does not mean that the reuse for the methods of +stack+ is not possible. NX allows for -example to copy objects (similar to prototype based languages) or to +example to copy objects (similar to prototype-based languages) or to reuse methods via e.g. aliases (more about this later). Note that we use capitalized names for classes and lowercase names for @@ -433,7 +433,7 @@ +s1+ and +s2+ in which order the involved classes are processed. This order is called the +precedence order+ and is obtained via +info precedence+. We see that the mixin class +Safety+ is only in use for -+s2+, and takes there precedence over +Stack+. The common root class ++s2+, and takes precedence over +Stack+. The common root class +nx::Object+ is for both +s1+ and +s2+ the base class. [[img-per-object-mixin]] @@ -901,7 +901,7 @@ named +bark+. The method body defines the code, which is executed when the method is invoked. In this example, the method +bar+ prints out a line on the terminal starting with the object name (this is determined -by the built in command +self+) followed by "Bark, bark, bark.". This +by the built-in command +self+) followed by "Bark, bark, bark.". This method is defined on a class and applicable to instances of the class (here the instance +fido+). @@ -964,7 +964,7 @@ # the tail of fido fido::tail length set 10 -# Proving an invalid values will raise an error +# Show that an invalid value raises an error fido::tail length set "Hello" -------------------------------------------------- @@ -1162,7 +1162,7 @@ an instance +s1+ is created from the derived class, the method +foo+ is invoked which uses in turn the private method of the base class. Therefore, the invocation +s1 foo 3 4+ returns its sum. If -the +local+ flag had not beed used in helper, +s1+ would +the +local+ flag had not been used in helper, +s1+ would 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. @@ -1338,11 +1338,11 @@ } # Method "bar" is a class method of class "C" -# therefore applicable on the class object "C" +# therefore, applicable on the class object "C" C bar # Method "foo" is an instance method of "C" -# therefore applicable on instance "c1" +# therefore, applicable on instance "c1" c1 foo # When trying to invoke the class method on the @@ -1363,7 +1363,7 @@ An *ensemble method* is a form of a hierarchical method consisting of a container method and sub-methods. The first argument of the container method is interpreted as a selector (the sub-method). Every -sub-method can be an container method as well. +sub-method can be a container method as well. ========================================= Ensemble methods provide a means to group related commands together, @@ -1550,7 +1550,7 @@ from basic - typically predefined - classes of the object system. This can be useful, when script overloads system methods, but still want to call the shadowed methods from the base classes. In our case, we have -no definitions of +foo+ on the base clases, therefore, an error message +no definitions of +foo+ on the base sclasses, therefore, an error message is returned. The output of <> is: @@ -1661,7 +1661,7 @@ parameter. A more tricky case is in line 36, where we want to pass +-y+ as a value to the positional parameter +a+. The case is more tricky since syntactically the argument parser might consider +-y+ as -the name of one of the non-positional parameter. Therefore, we use +--+ +the name of one of the non-positional parameters. Therefore, we use +--+ (double dash) to indicate the end of the block of the non-positional parameters and therefore the value of +-y+ is passed to +a+. @@ -1758,17 +1758,17 @@ -------------------------------------------------- In order to define a default value for a parameter, the parameter -specification must be of the form of a 2 element list, where the +specification must be of the form of a 2-element list, where the second argument is the default value. See for an example in <>. ==== Value Constraints NX provides value constraints for all kind of parameters. By -specifying value constraints a developer can restrict the permissible +specifying value constraints, a developer can restrict the permissible values for a parameter and document the expected values in the source code. Value checking in NX is conditional, it can be turned on or off -in general or on a per-usage level (more about this later). The same +in general, or on a per-usage level (more about this later). The same mechanisms can be used not only for input value checking, but as well for return value checking (we will address this point as well later). @@ -2059,7 +2059,7 @@ nx::Class create ::D nx::Class create ::C { # - # By default all substitutions (command, variable, control + # By default, all substitutions (command, variable, control # characters) are active, when "substdefault" is used: # :property {d:object,type=::D,substdefault {[::D new]}} @@ -2308,7 +2308,7 @@ ==== Slot Classes and Slot Objects In one of the previous sections, we defined scripted (application -defined) checker methods on a class named +nx::Slot+. In general NX +defined) checker methods on a class named +nx::Slot+. In general, NX offers the possibility to define value checkers not only for all usages of parameters but as well differently for method parameters or configure parameters Index: generic/predefined_part1.tcl =================================================================== diff -u -N -r1c256d871fdda3b5f51923b072129b9c589f567e -r18b6516228b6bdc151f98734b6a3027bb1eff6fb --- generic/predefined_part1.tcl (.../predefined_part1.tcl) (revision 1c256d871fdda3b5f51923b072129b9c589f567e) +++ generic/predefined_part1.tcl (.../predefined_part1.tcl) (revision 18b6516228b6bdc151f98734b6a3027bb1eff6fb) @@ -4,11 +4,11 @@ # the Next Scripting Framework. This file will be transformed by # mk_predefined.tcl into "predefined.h", which in included in nsf.c. # -# Copyright (C) 2009-2017 Gustaf Neumann +# Copyright (C) 2009-2021 Gustaf Neumann # Copyright (C) 2010 Stefan Sobernig # # The predefined code has to be split into 2 parts due to a string -# literal limitaton in ISO C99, that requires compilers to support +# literal limitation in ISO C99, that requires compilers to support # only strings up to 4095 bytes. # # This is part 1. Index: generic/predefined_part2.tcl =================================================================== diff -u -N -r1c256d871fdda3b5f51923b072129b9c589f567e -r18b6516228b6bdc151f98734b6a3027bb1eff6fb --- generic/predefined_part2.tcl (.../predefined_part2.tcl) (revision 1c256d871fdda3b5f51923b072129b9c589f567e) +++ generic/predefined_part2.tcl (.../predefined_part2.tcl) (revision 18b6516228b6bdc151f98734b6a3027bb1eff6fb) @@ -4,11 +4,11 @@ # the Next Scripting Framework. This file will be transformed by # mk_predefined.tcl into "predefined.h", which in included in nsf.c. # -# Copyright (C) 2009-2017 Gustaf Neumann +# Copyright (C) 2009-2021 Gustaf Neumann # Copyright (C) 2010 Stefan Sobernig # # The predefined code has to be split into 2 parts due to a string -# literal limitaton in ISO C99, that requires compilers to support +# literal limitation in ISO C99, that requires compilers to support # only strings up to 4095 bytes. # # This is part 2.