Index: doc/Announce2.0 =================================================================== diff -u -N -r8ec912177de5c542eb22a9a135d3624322ae20c9 -r04d83e1651aa2c2062e4423e9e08a3a01de9e7cc --- doc/Announce2.0 (.../Announce2.0) (revision 8ec912177de5c542eb22a9a135d3624322ae20c9) +++ doc/Announce2.0 (.../Announce2.0) (revision 04d83e1651aa2c2062e4423e9e08a3a01de9e7cc) @@ -11,110 +11,123 @@ happened in NX and, therefore, on the NSF scripting level, without the need to modify the NSF C layer. The implementation of XOTcl 2 has changed very little. The Next Scripting Framework was tested with Tcl -8.5.14 and Tcl 8.6.2 on Linux, Mac OS X, and in windows enviroments -(MinGW, VC11). +8.5.17 and Tcl 8.6.2 on Linux, Mac OS X, and in Windows enviroments +(MinGW, VC12). -Below are the most notable differences in NX 2.0 final relative to +Below are the most notable differences in NSF/NX 2.0 final relative to 2.0b5: -a) Pluralism reform: - Use a pluralword, whenever potentially multiple elements - are provided or returned. This rule applies now consitently - on all nx methods. Here are examples from the introspection - interface: +a) Pluralism reform: + Use plural names for structural features of objects and classes, + whenever potentially multiple elements are provided or + returned. This rule applies now consistently throughout NX. Here are + examples from the introspection interface: + /cls/ info superclasses /cls/ info subclasses /cls/ info mixins /obj/ info object mixins /cls/ info filters /obj/ info object filters - use plural forms for configure options + Similarly, there the plural is used for configure options, e.g.: nx:create create Foo -superclasses {C D} - but abbreviations are allowed as well + Note that abbreviations are allowed as well: nx:create create Foo -superclass {C D} b) Dispatch by arity is gone in NX. - XOTcl and earlier versions of NX supported - for relation slots a dispatch-by-arity mechanism + XOTcl and earlier versions of NX supported a dispatch-by-arity + mechanism for relation slots: - o mixin # arity 1: get value - o mixin M1 # arity 2: set value - o mixin add M1 # arity 3: use arg 2 for slot methods + o mixin; # arity 1: get value + o mixin M1; # arity 2: set value + o mixin add M1; # arity 3: use arg 2 for slot methods - The problem with this approach is that it is not easy to - provide good error messages, and one might be surprised, - if e.g. "o mixin add" is used (without a class to be added). - In the final release, we removed the entailed complexity - by using alway the last form, supporting by default the - slot methods + The problem with this approach is that it is not straight forward + to provide meaningful error messages. In addition, one might be + irritated about the result of e.g. "o mixin add" (leaving out a + class to be added). In the final release, we removed the entailed + complexity by relying on a fixed arity of 3 (last form above) for + the default slot methods: add, clear, delete, get, guard, set -c) Support for querying computed parameters of methods. - Earlier versions of of nx had several methods to - query the parameters for configuring objects of - different classes. The configure parameters are - determined by the inheritance in the class hierarchy. - and are relevant as well during object creation - (e.g methods "create" or "new"). +c) Support for querying computed parameters of methods. - Now these parameter can be queried using the standard - parameter introspction interface for e.g. "new", "create", - or "configure", such as in: + Earlier versions of NX had several methods to query the parameters + for configuring objects of different classes. The configure + parameters are determined by the inheritance order in the class + hierarchy and are relevant during object creation (e.g. + methods "create" or "new"). + + Now, these configure parameter can be queried using the standard + parameter introspection interface for e.g. "new", "create", or + "configure", such as in: nx::Object info lookup parameters create - which returns the parameters which can be given - in a "nx::Object create ..." invocation. Furthermore, - these computed parameters are as well returned in error - messages. + The above command call returns the parameters which can be provided + to an "nx::Object create ..." invocation. Furthermore, these + computed parameters are returned in error messages. -d) Support abbreviations of nonpositional arguments - (for plain methods, nsf::proc, or "... configure..."). - To avoid surprises, especially for computed argument - lists, the minimal number of provided characters is set - to 4. +d) Support abbreviations of non-positional parameter names (for plain + methods, nsf::proc, or "... configure..."). + + To avoid surprises, especially for computed argument lists, the + minimal number of optional trailing characters is set to 4. -e) MongoDB interface: - The interface was extended in various ways an is now - based on mongo-c-driver 1.0.2 and was tested with - MongoDB 2.6.5. The driver can be used nicely with - e.g. Naviserver by using the c-driver supported - connection pool. +e) Updated MongoDB interface: + + The interface was extended in various ways and is now based on + mongo-c-driver 1.0.2 and was tested with MongoDB 2.6.5. The driver + can be used nicely with e.g. Naviserver by using the c-driver + supported connection pool. -f) Language reference manual +f) API changes: -nx::Object info lookup parameters create - /cls/ mixins ... - /obj/ object mixins ... - /cls/ filters ... - /obj/ object filters ... + nx::Object info lookup parameters create + /cls/ mixins ... + /obj/ object mixins ... + /cls/ filters ... + /obj/ object filters ... - simplified info methods for interceptors - /cls/ info mixin classes -> /cls/ info mixins - /cls/ info filter methods -> /cls/ info filters - /obj/ info object mixin classes -> /obj/ info object mixins + Simplified info methods for interceptors: - dropped - /cls/ info mixin guard - /obj/ info object mixin guard - /cls/ info filter guard - /obj/ info object filter guard - -> use use "-guard option insteads + /cls/ info mixin classes -> /cls/ info mixins + /cls/ info filter methods -> /cls/ info filters + /obj/ info object mixin classes -> /obj/ info object mixins - added - /cls/ mixins classes - /cls/ filters methods - /obj/ object filters methods - /obj/ object mixins classes + Dropped methods: + /cls/ info mixin guard + /obj/ info object mixin guard + /cls/ info filter guard + /obj/ info object filter guard + + Instead, use the "-guards" option of "... info ?object? mixins|filters ...". + Added methods: + + /cls/ mixins classes + /cls/ filters methods + /obj/ object filters methods + /obj/ object mixins classes + +g) Added API documentation: + + Using tcllib's doctools markup and dtplite, we now provide manpages + for: + nx::Object + nx::Class + nx::current + nx::next + nx::configure + a) NX 2.0b3 used the following conventions to define methods for instances, object-specific methods and class-object specific methods: