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 {
- Requires: ${:@require} + Package requires: ${:@require}
} ] Index: library/lib/doc-tools.tcl =================================================================== diff -u -r3df933477f01d26d32220be5a1c87bfc0c5b7685 -r39306d4d36096f20dba3262638e2a87f04e90111 --- library/lib/doc-tools.tcl (.../doc-tools.tcl) (revision 3df933477f01d26d32220be5a1c87bfc0c5b7685) +++ library/lib/doc-tools.tcl (.../doc-tools.tcl) (revision 39306d4d36096f20dba3262638e2a87f04e90111) @@ -1756,7 +1756,7 @@ :method listing {{-inline true} script} { #return [expr {$inline?"$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