Index: TODO =================================================================== diff -u -r3df933477f01d26d32220be5a1c87bfc0c5b7685 -r39306d4d36096f20dba3262638e2a87f04e90111 --- TODO (.../TODO) (revision 3df933477f01d26d32220be5a1c87bfc0c5b7685) +++ TODO (.../TODO) (revision 39306d4d36096f20dba3262638e2a87f04e90111) @@ -2175,8 +2175,41 @@ - extended regression test TODO: +- doc: + NextScriptingLanguage/index.html: + * heading "Glossary" missing. + It ist not clear, what the list of items is, when one sees index.html + + * A short introductory text, what the "package" + is whould be more well suited for the index page, + moving glossary (index) to the left column. + ..... Better to use "package_nx.html" as index.html + + * glossary entries in nsf.nxd should be sorted (in the source) + ...... Maybe, a single glossary.nxd file? + + * the non-documented entitied should not show up in the menu + + (::nsf::parametersfromslots) + ::nx::current + (::nx::infoOptions) + (::nx::isSlotContainer( + ::nx::next + ::nx::self + (::nx::slotObj) + + => provide a different flag for the generation of the documentation + (-develop, .... or -final) to show/hide it. + + * This package contains 12 classes.... 3 objects .... + Why are all these marked with "mismatch"? + + + - nsf::proc + * check, if there are parameter types that should not be applicable + for nsf::proc * scripted-method like implementation (like ProcMethodDispatch, not urgent) * toplevel (object less) introspection * memleak testing Index: doc/next-migration.txt =================================================================== diff -u -r3df933477f01d26d32220be5a1c87bfc0c5b7685 -r39306d4d36096f20dba3262638e2a87f04e90111 --- doc/next-migration.txt (.../next-migration.txt) (revision 3df933477f01d26d32220be5a1c87bfc0c5b7685) +++ doc/next-migration.txt (.../next-migration.txt) (revision 39306d4d36096f20dba3262638e2a87f04e90111) @@ -19,9 +19,16 @@ 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. The overall goal is to -improve the maintainability and stability of large projects, where -many developers are involved. +several hundert 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 +to ease the learning of the language by novices (by using a more +mainstream terminology, higher orthogonality of the methods, less +predefined methods), to improve maintainability (remove sources of +common errors) and to encourage developer to write better structured +programs (to provide interfaces) especially for large projects, where +many developers are involved. The Next Scripting Language is based on the Next Scripting Framework which was developed based on the notion of language oriented Index: generic/nsf.tcl =================================================================== diff -u -r821c01bd241c51be4fa0931d423d8f8658606ee1 -r39306d4d36096f20dba3262638e2a87f04e90111 --- generic/nsf.tcl (.../nsf.tcl) (revision 821c01bd241c51be4fa0931d423d8f8658606ee1) +++ generic/nsf.tcl (.../nsf.tcl) (revision 39306d4d36096f20dba3262638e2a87f04e90111) @@ -130,7 +130,7 @@ } } return /tmp - } + } namespace export tmpdir Index: library/lib/doc-assets/package.html.tmpl =================================================================== diff -u -rb067e586fadae95916358904fd8392d073c7c87c -r39306d4d36096f20dba3262638e2a87f04e90111 --- library/lib/doc-assets/package.html.tmpl (.../package.html.tmpl) (revision b067e586fadae95916358904fd8392d073c7c87c) +++ library/lib/doc-assets/package.html.tmpl (.../package.html.tmpl) (revision 39306d4d36096f20dba3262638e2a87f04e90111) @@ -10,7 +10,7 @@ [:?var :@require {
$script
":"$script"}] - return [expr {$inline?"
$script
":[nx::pp render $script]}]
+ return [expr {$inline?"$script
":[nx::pp render [string trimright $script " \r\n"]]}]
}
:method link {tag names} {
Index: library/nx/nx.nxd
===================================================================
diff -u -r0f9252f548c879e1271816332e50ade960d8b148 -r39306d4d36096f20dba3262638e2a87f04e90111
--- library/nx/nx.nxd (.../nx.nxd) (revision 0f9252f548c879e1271816332e50ade960d8b148)
+++ library/nx/nx.nxd (.../nx.nxd) (revision 39306d4d36096f20dba3262638e2a87f04e90111)
@@ -2,19 +2,104 @@
# @package nx
#
-# The <<@glossary nx>> is a compact and expressive object-oriented
-# language extension for <<@Gls tcl>>. The object system model is
-# highly influenced by <<@glossary clos>> and its off-springs (e.g.,
-# <<@glossary flavors>>). This package provides the basic object
-# system for <<@glossary nx>>. It defines the basic language entities
-# <<@class ::nx::Object>> and <<@class ::nx::Class>>, as well as
-# essential language primitives (in particular, <<@command
-# ::nx::next>> and <<@command ::nx::current>>).
+# The <<@glossary nx>> is an object oriented scripting language based
+# on the Next Scripting Framework (TODO: passende Referenz <<@package
+# nsf>>).
+# 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
+# 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
+# to ease the learning of the language by novices (by using a more
+# mainstream terminology, higher orthogonality of the methods, less
+# predefined methods), to improve maintainability (remove sources of
+# common errors) and to encourage developer to write better structured
+# programs (to provide interfaces) especially for large projects, where
+# many developers are involved.
#
+# NX is implemented as an object-oriented language extension for
+# <<@Gls tcl>>. The object system model is highly influenced by
+# <<@glossary clos>>, where classes are certain kind of objects and
+# objects might have their own properties (variables and methods) not
+# induced by the classes. The object system of NX is fully dynamic,
+# all object-class (e.g. instance-of relationship) and class-class
+# relationships (e.g. superclass relationship) can change at any time
+# at runtime. This way, object can change classes at runtime, or
+# objects might obtain different properties, etc.
+#
+# The language and object system of NX is implemeted by the package
+# nx. It defines the basic language entities <<@class ::nx::Object>>
+# and <<@class ::nx::Class>>, as well as essential language primitives
+# (in particular, <<@command ::nx::next>> and <<@command
+# ::nx::current>>).
+#
# @require nsf
# @version 1.0.0a
# @namespace ::nx
+
+#
+# @glossary metaclass
+#
+# A meta-class is a certain kind of <<@gls class>> that manages
+# classes. The instances of meta classes are classes.
+#
+# @pretty_name Meta Class
+# @pretty_plural Meta Classes
+
+
+#
+# @glossary class
+#
+# A class is a certain kind of <<@gls object>> that is responsible for
+# the life-cycle management of other objects (creation,
+# initialization, destruction) and which serves as a method
+# respository for abjects (typically along a class hierarchy). In the
+# object systems of XOTcl and NX, where objects might have their own
+# methods, the class objects might have as well methods applicable
+# only to the class object. We refer to these methods as class-object
+# specific methods, sometimes these methods are called "static methods".
+#
+# @pretty_name Class
+# @pretty_plural Classes
+
+
+#
+# @glossary baseclass
+#
+# A base class is the most general class (common root class) of an
+# object system. All objects of an object system are direct or
+# indirect instances of the base class.
+#
+# @pretty_name Base Class
+# @pretty_plural Base Classes
+
+#
+# @glossary basemetaclass
+#
+# A base meta class is the most general meta class of an object
+# system. All classes are direct or indirect instances of the base
+# meta class.
+#
+# @pretty_name Base Meta Class
+# @pretty_plural Base Meta Classes
+
+
+
+#
+# @glossary object
+#
+# An object is the basic entity of an object system. Every object is
+# the instance of a <<@gls class>> and might contain variables (called
+# instance variables). In the object systems of XOTcl and NX, objects
+# might have as well their own methods (called object specific
+# methods).
+#
+# @pretty_name Object
+# @pretty_plural Objects
+
+
# @class Object
#
# Programs written in the <<@glossary nx>> are constructed out of
@@ -24,13 +109,17 @@
# @class Class
#
-# A <<@gls class>> defines a family of object implementations and
-# <<@glspl objtype>>, sharing a common set of <<@glspl attribute>>
-# attributes (see <<@class ::nx::Attribute>>) and methods. Classes are
-# organised according to their similarities and differences in
-# classification hierarchies. This object represents the root <<@gls
-# metaclass>> in the <<@glossary nx>> object system.
+# ::nx::Class is the <<@gls basemetaclass>> of the <<@glossary nx>>
+# object system. All application classes are created as (direct or
+# indirect) instances of this class using e.g. the '''create''' method
+# of this class:
#
+# '''
+# ::nx::Class create Person {
+# \# ....
+# }
+# '''
+#
# @superclass ::nx::doc::entities::class::nx::Object
# @class.method {Class alloc}
@@ -790,11 +879,11 @@
# @glossary nx
#
-# The Next Scripting Language (Nx) is one of the languages hosted by
+# The Next Scripting Language (NX) is one of the languages hosted by
# and implemented on top of the Next Scripting Framework (NSF).
#
# @pretty_name Next Scripting Language
-# @acronym Nx
+# @acronym NX
# @glossary objtype
#
@@ -807,14 +896,6 @@
# @pretty_plural Object-types
-# @glossary metaclass
-#
-# A meta-class defines a minimal set of shared state structure and
-# behaviour for a family of classes.
-#
-# @pretty_name Meta-class
-# @pretty_plural Meta-classes
-
# @glossary attribute
#
# An attribute describes a structural feature of a class or an
@@ -897,3 +978,4 @@
# @pretty_name object initialisation script
# @pretty_plural object initialisation scripts
+
Index: nsf.nxd
===================================================================
diff -u -r0f9252f548c879e1271816332e50ade960d8b148 -r39306d4d36096f20dba3262638e2a87f04e90111
--- nsf.nxd (.../nsf.nxd) (revision 0f9252f548c879e1271816332e50ade960d8b148)
+++ nsf.nxd (.../nsf.nxd) (revision 39306d4d36096f20dba3262638e2a87f04e90111)
@@ -2,94 +2,143 @@
# @package nsf
#
-# The package provides a basic set of commands to perform
-# language-oriented programming based on the Next Scripting Framework
-# and to develop applications which are meant to operate across
-# different NSF object systems.
+# The package provides a basic set of primitives (Tcl commands) to
+# support language-oriented programming based on the Next Scripting
+# Framework. These primitives are used to define one or multiple
+# object systems within a single system. The NSF primitives are
+# primarily meant for the designer of an object system. Application
+# developers should use the functionality provided by the object
+# systems they are using (eg. XOTcl or NX).
#
# @require Tcl
# @version 1.0.0a
# @namespace ::nsf
-# @glossary alias
+
#
-# An alias is a placeholder for a command, its target, which is made
-# available as a proper method of the alias-owning object.
+# @glossary metaclass
#
-# @pretty_name Alias
-# @pretty_plural Aliases
+# A meta-class is a certain kind of <<@gls class>> that manages
+# classes. The instances of meta classes are classes.
+#
+# @pretty_name Meta Class
+# @pretty_plural Meta Classes
+
+#
# @glossary class
#
-# A class represents a family of object sharing a minimal common
-# structure and behaviour.
+# A class is a certain kind of <<@gls object>> that is responsible for
+# the life-cycle management of other objects (creation,
+# initialization, destruction) and which serves as a method
+# respository for abjects (typically along a class hierarchy). In the
+# object systems of XOTcl and NX, where objects might have their own
+# methods, the class objects might have as well methods applicable
+# only to the class object. We refer to these methods as class-object
+# specific methods, sometimes these methods are called "static methods".
#
# @pretty_name Class
# @pretty_plural Classes
+#
+# @glossary object
+#
+# An object is the basic entity of an object system. Every object is
+# the instance of a <<@gls class>> and might contain variables (called
+# instance variables). In the object systems of XOTcl and NX, objects
+# might have as well their own methods (called object specific
+# methods).
+#
+# @pretty_name Object
+# @pretty_plural Objects
+
+
+# @glossary alias
+#
+# An alias is an alternate name for some artefact. In NSF, the term
+# "alias" is an abbreviation for a "method alias", which allows to
+# reuse some command or method unter a certain name. This way, one can
+# e.g. reuse Tcl commands like "set" or "unset" without invocation
+# overhead as methods for object and classes.
+#
+# @pretty_name Alias
+# @pretty_plural Aliases
+
# @glossary method_handle
#
-# A method handle is a fully qualified, directly executable reference
-# to scripted procs and methods, as well as C-implemented commands and
-# methods. An handle is a unique identifier for a given '''interp'''.
+# A method handle is a fully qualified reference to a method. Since
+# methods with identical names can be defined on object and classes,
+# method names are subject to resolving. In contrary to method names,
+# method handles provide unique identifier to methods.
#
# @pretty_name Method handle
# @pretty_plural Method handles
-# @glossary cframe
+# @glossary callframe
#
-# NSF provides adds a set of callframe types, e.g., to carry
-# object-specific callstack information, to realise variable- and
-# command-resolution schemes etc. The callframe types are realised by
-# piggybacking standard Tcl callframe structures. The following
-# callframe types can be found: ...
+# A call frame (sometimes called activation record) is an entry on the
+# execution stack, keeping information about the invoked functions and
+# methods. NSF uses the extension mechansims of Tcl to provide its
+# own types of callframes, which are different for scripted and C
+# implemented methods.
#
# @pretty_name Callframe
# @pretty_plural Callframes
-# @glossary assert
+# @glossary assertion
#
-# Following a Design-by-Contract approach, you may define different
-# kinds of assertions on object, classes, and methods. For objects and
-# classes, you can express object and class invariants. For methods,
-# pre- and postconditions allow to express obligations on and benefits
-# at a method's call site.
+# An assertion is an assumption that the developer assumes to hold (to
+# be true). Following a Design-by-Contract approach, a developer may
+# define different kinds of assertions on object, classes, and
+# methods. NSF assertions support object and class invariants and
+# method asstions (pre- and post-conditions).
#
# @pretty_name Assertion
# @pretty_plural Assertions
# @glossary forwarder
#
-# A forwarder is a method-level delegation mechanism to realise a
-# variety of programming techniques (e.g., signature adapters, method
-# decorators). The forward-owning object (or class) exposes the
-# forwarder as a method (e.g., in its signature interface and through
-# method-level introspection). Delegation targets are not limited to
-# other methods, arbitrary <<@acr tcl>> command statements can be
-# used. Forwarders come with a filtering protocol which allows to
-# manipulate the argument vector processed by the forwarder.
+# A forwarder (shorthand for a "forwarder method") is a delegation
+# mechanism to realize a variety of programming techniques. A
+# forwarder is a C implemented method that redirects an invocation
+# with a potentially different argument list to some implementation
+# (delegation target). Delegation targets might be methods of the same
+# or different objects, but these might be as well arbitrary Tcl
+# commands. Like <<@glspl alias>>, method forwarders are a
+# means of reuse. On contrary to aliases method forwarders allow the
+# modification of the argument vector, but involve more calling
+# overhead. Method forwarder do not extend the expressability of the
+# language, since everything performed by a forwarder could be
+# implemented as well in a scripted method. However, a forwarder is
+# more efficient and expresses the intention of the developer more
+# clearly.
#
# @pretty_name Forwarder
# @pretty_plural Forwarders
-# @glossary mixincls
+# @glossary mixin_class
#
-# A mixin is realised by an otherwise ordinary class which is put in a
-# dedicated mixin relation to another object or class. Hence, we refer
-# to such classes as mixin-classes. If the mixing target is another
-# mixin-class, we refer to the source mixin-class as a transitive
-# mixin-class.
+# A mixin class is a class that provides its method set to objects and
+# classes outside of the intrinsic class hierarchy (the class
+# hierarchy defined by the is-instance-of and superclass
+# relationship). A mixin class registered on an object is called a
+# per-object mixin, a mixin class registed on a class is called an
+# per-class mixin. Technically, a mixin class is realized by an
+# ordinary class which is registered via a dedicated mixin relation.
#
-# @pretty_name Mixin-class
-# @pretty_plural Mixin-classes
+# @pretty_name Mixin class
+# @pretty_plural Mixin classes
# @glossary filter
#
-# An object filter implementes the idea of a composition filters in NSF.
+# A filter is a method called before and after every method
+# invocation. Filters can be registered on the object level
+# (per-object filters) and on the class level (per-class filters).
#
# @pretty_name Filter
# @pretty_plural Filters
+# xxxx-bis-hierher
# @command alias
#
@@ -110,7 +159,7 @@
# in the method signature interface. The
# alias method name and the target name
# so can differ from each other.
-# @parameter -frame Denotes the type of <<@gls cframe>> to
+# @parameter -frame Denotes the type of <<@gls callframe>> to
# be stacked upon invoking the alias
# method. Permissible options are:
# '''method''', '''object''',
@@ -224,7 +273,7 @@
# object variables through dedicated setter methods provides several
# benefits: They facilitate accessing object states from client
# objects and render operations on object variables interceptable
-# by <<@glspl filter>> and <<@glspl mixincls>>.
+# by <<@glspl filter>> and <<@glspl mixin_class>>.
#
# @parameter object The owner object or class of
# the setter method
@@ -244,7 +293,7 @@
# two barebone objects as a starting point to define the basic class
# and object interfaces for your object system. In addition, you may
# map system hooks required by the NSF runtime to methods specific to
-# your object system. For instance, the Nx object system is defined as follows:
+# your object system. For instance, the NX object system is defined as follows:
# '''
# ::nsf::createobjectsystem ::nx::Object ::nx::Class {
# -class.alloc alloc
@@ -294,7 +343,7 @@
# analyzer).
#
# @parameter object Indicates the name of the receiving object
-# @parameter -frame Denotes the type of <<@gls cframe>> to
+# @parameter -frame Denotes the type of <<@gls callframe>> to
# be stacked upon invoking the alias
# method. Permissible options are:
# '''method''', '''object''',
@@ -829,7 +878,7 @@
# '''class''': Describes an '''instance-of''' relationship between an
# object (instance) and another object (its class).
#
-# '''object-mixin''': Declares a list of <<@glspl mixincls>> as the
+# '''object-mixin''': Declares a list of <<@glspl mixin_class>> as the
# mixins of a given object.
#
# '''object-filter''': Declares a method as a <<@gls filter>> method
@@ -845,7 +894,7 @@
# '''superclass''': Establishes a generalisation/specialisation
# relation between two classes.
#
-# '''class-mixin''': Declares a list of <<@glspl mixincls>> as the
+# '''class-mixin''': Declares a list of <<@glspl mixin_class>> as the
# mixins of a given class, with the method interceptors becoming
# active on all instances of this class.
#
@@ -930,7 +979,7 @@
# @command mixin
#
# A helper command to set and maintain mixin relations between an
-# object and a set of of <<@gls mixincls>>. It is a convenience
+# object and a set of of <<@gls mixin_class>>. It is a convenience
# wrapper around <<@command relation>>.
#
# @parameter object The target object to refine