Index: TODO =================================================================== diff -u -r79287f596cc2c14ecd2b788d217699e2baeb050d -rf62c1f601dda43d69c8b159e81b57d4271cd3175 --- TODO (.../TODO) (revision 79287f596cc2c14ecd2b788d217699e2baeb050d) +++ TODO (.../TODO) (revision f62c1f601dda43d69c8b159e81b57d4271cd3175) @@ -873,8 +873,18 @@ - added @properties and has_property to the documentation classes. Current primary purpose: define, which methods are internally-called -- added interanlly-called to the method object template +- added internally-called to the method object template +- added redefine-protected to the object template +- added methodtype to object template +- some documentation updates +- some indentation/spacing improvements on xotcl.c +- let ".... info method .... METHOD" return values, + when METHOD contains namespace prefix. This can be + used to obtain the parmeter definitions from nx::core +- get forward definition from the original command + + TODO: - nameing * .c-code: @@ -924,23 +934,39 @@ * org. tutorial (bzw teile davon) ala book or wiki (features als kategorien|tags|sections|directories) -Ein paar punkte im folgenden könnten obsolet sein: +Ein paar Punkte im folgenden könnten obsolet sein: TODO "Kleinigkeiten" - decide on syntax in documentation (info method parameter | info method parametersyntax | mixture) +- decide on paths for documentation of next and xotcl 2, with + version numbers; what should be included in distro, what on web-site +- decide on syntax subcomponent. Candiates are + * Object.method + * Object->method + * Object#method - systematic way of specifying results of methods - systematic way of reporting results in documentation - reduce indenting for code examples in documentation (high indentation makes readability worse). + i use usually jsut 2, 4 are ok as well; we should decide. - make quality checks (missing documentation, ...) optional (maybe?) - handle object methods as well in quality checks - why does one have to specify @superclass rather than determining the superclass via introspection? +- handle line-breaking in long @definitions (e.g. @param; e.g. via indented next line) - danger, tcl-commands in comments (see :method get_unqualified_name) + expecially for code commented out.... + - kann man "[:? {[$attr eval {info exists :default}]}" durch "[:?var :@param ..." ausdrücken? oder vielleicht besser die variablen mit leerstring initialisieren + infrastrukt anpassen? +- listing von methoden im left-bar, ähnlich http://developer.yahoo.com/yui/docs/YAHOO.util.Connect.html +- "Objects" im left-bar irreführend, sollten eher "Classes" sein. Allerdings sollten + auch objekte dukumentierbar sein +- doc-tools: was machen die argumenten von :? (bspw. ops?); ich nehme an, das ist work in progress. + sinnvoll wäre: [:?var obj varname body], da viele (die meisten) operationen auf anderen objeken ausgeführt werden + - die Dokumentation der objekt- und Klassenmethoden muss aus gentclapi weg und in predefined.tcl und xotcl2.tcl hineinwandern. Es werden nicht alle möglichen methoden in next und/oder xotcl2 registiert, ein paar namen sind Index: generic/gentclAPI.decls =================================================================== diff -u -r79287f596cc2c14ecd2b788d217699e2baeb050d -rf62c1f601dda43d69c8b159e81b57d4271cd3175 --- generic/gentclAPI.decls (.../gentclAPI.decls) (revision 79287f596cc2c14ecd2b788d217699e2baeb050d) +++ generic/gentclAPI.decls (.../gentclAPI.decls) (revision f62c1f601dda43d69c8b159e81b57d4271cd3175) @@ -319,8 +319,10 @@ # @method ::nx::Object#cleanup # -# TODO: this is a method not needed in Next, for backward compatibility -# available in XOTcl 2.0 +# TODO: this is a method not used in the Next Scripting Langauge. This +# mehtod is just called via recreate, so everything necessary can be +# performed there as well. However, it is available for backward +# compatibility available in XOTcl 2.0 # # Resets an object or class to its initial state, as after object # allocation (see {{@method ::nx::Class class alloc}}). This method @@ -358,31 +360,34 @@ # @method ::nx::Object#destroy # -# The method lays out the default object destruction process. By -# calling {{{destroy}}} on an object, you request its destruction: +# The standard destructor for an object. The method {{@method ::nx::Object class destroy}} +# triggers the physical destruction of the object. The method {{{destroy}}} can be refined +# by subclasses or mixin classes to add additional (class specific) destruction behavior. +# Note that in most cases, the class specific {{{destroy}}} methods should call +# {{@command ::nx::next}} to trigger physical destruction. # {{{ -# Object create anObject -# anObject destroy +# nx::Class create Foo { +# :method destroy {} { +# puts "destroying [self]" +# next +# } +# } +# Foo create f1 +# f1 destroy # }}} -# Upon calling {{{destroy}}} on a given object, {{{destroy}}} +# Technical details: The method {{@method ::nx::Object class destroy}} # delegates the actual destruction to {{@method ::nx::Class class dealloc}} -# which clears the memory object storage. +# which clears the memory object storage. Essentially, the behaviour could be +# scripted as: # {{{ -# [anObject destroy] .-----------------. .----------------. -# .......>|Object->destroy()|.....>|Class->dealloc()| -# `-----------------' `----------------' -# }}} -# Essentially, the behaviour could be scripted as: -# {{{ # Object method destroy {} { # [:info class] dealloc [self] # } # }}} # Note, however, that {{{destroy}}} is protected against # application-level redefinition. You must refine it in a subclass -# or mixin class. By doing so, {{{destroy}}} may be used to hook -# into the destruction process (e.g., to realise -# application-specific cleanup tasks). +# or mixin class. +# objectMethod destroy XOTclODestroyMethod { } Index: generic/predefined.h =================================================================== diff -u -r8aaec98df564488dc8540cd078d6a32dd55a08f7 -rf62c1f601dda43d69c8b159e81b57d4271cd3175 --- generic/predefined.h (.../predefined.h) (revision 8aaec98df564488dc8540cd078d6a32dd55a08f7) +++ generic/predefined.h (.../predefined.h) (revision f62c1f601dda43d69c8b159e81b57d4271cd3175) @@ -27,7 +27,7 @@ "foreach cmd [info command ::nx::core::cmd::Class::*] {\n" "set cmdName [namespace tail $cmd]\n" "::nx::core::alias Class $cmdName $cmd}\n" -"foreach cmd [list __next cleanup noinit residualargs uplevel upvar] {\n" +"foreach cmd [list __next cleanup noinit residualargs uplevel upvar] {\n" "::nx::core::methodproperty Object $cmd protected 1}\n" "foreach cmd [list recreate] {\n" "::nx::core::methodproperty Class $cmd protected 1}\n" Index: generic/xotcl.c =================================================================== diff -u -r8aaec98df564488dc8540cd078d6a32dd55a08f7 -rf62c1f601dda43d69c8b159e81b57d4271cd3175 --- generic/xotcl.c (.../xotcl.c) (revision 8aaec98df564488dc8540cd078d6a32dd55a08f7) +++ generic/xotcl.c (.../xotcl.c) (revision f62c1f601dda43d69c8b159e81b57d4271cd3175) @@ -663,7 +663,7 @@ if (!nsPtr) nsPtr = Tcl_GetCurrentNamespace(interp); /* fprintf(stderr, " (resolved %p, %s) ", nsPtr, nsPtr ? nsPtr->fullName:NULL);*/ - objPtr = Tcl_NewStringObj(nsPtr->fullName,-1); + objPtr = Tcl_NewStringObj(nsPtr->fullName, -1); len = Tcl_GetCharLength(objPtr); objString = ObjStr(objPtr); if (len == 2 && objString[0] == ':' && objString[1] == ':') { @@ -5950,18 +5950,18 @@ /* check if an absolute method name was provided */ if (*methodName == ':') { cmd = Tcl_GetCommandFromObj(interp, methodObj); - if (cmd) { - CONST char *mn = Tcl_GetCommandName(interp, cmd); - if (isClassName(methodName)) { - CONST char *className = NSCutXOTclClasses(methodName); - Tcl_DString ds, *dsPtr = &ds; - DSTRING_INIT(dsPtr); - Tcl_DStringAppend(dsPtr, className, strlen(className)-strlen(mn)-2); - cl = (XOTclClass *)XOTclpGetObject(interp, Tcl_DStringValue(dsPtr)); - DSTRING_FREE(dsPtr); - } - } - } + if (cmd) { + CONST char *mn = Tcl_GetCommandName(interp, cmd); + if (isClassName(methodName)) { + CONST char *className = NSCutXOTclClasses(methodName); + Tcl_DString ds, *dsPtr = &ds; + DSTRING_INIT(dsPtr); + Tcl_DStringAppend(dsPtr, className, strlen(className)-strlen(mn)-2); + cl = (XOTclClass *)XOTclpGetObject(interp, Tcl_DStringValue(dsPtr)); + DSTRING_FREE(dsPtr); + } + } + } /* if no filter/mixin is found => do ordinary method lookup */ if (cmd == NULL) { @@ -6758,9 +6758,9 @@ for (pPtr = parsedParam.paramDefs->paramsPtr; pPtr->name; pPtr++) { if (*pPtr->name == '-') { - Tcl_ListObjAppendElement(interp, argList, Tcl_NewStringObj(pPtr->name+1,-1)); + Tcl_ListObjAppendElement(interp, argList, Tcl_NewStringObj(pPtr->name+1, -1)); } else { - Tcl_ListObjAppendElement(interp, argList, Tcl_NewStringObj(pPtr->name,-1)); + Tcl_ListObjAppendElement(interp, argList, Tcl_NewStringObj(pPtr->name, -1)); } } ov[2] = argList; @@ -8890,7 +8890,7 @@ && insertRequired) { /* no match, but insert of flag is required */ /*fprintf(stderr, "no match, but insert of %s required\n", firstElementString);*/ - *out = Tcl_NewStringObj(firstElementString,-1); + *out = Tcl_NewStringObj(firstElementString, -1); *outputincr = 1; goto add_to_freelist; } else { @@ -8917,7 +8917,7 @@ } *out = listElements[nrArgs]; } else if (c == '%') { - Tcl_Obj *newarg = Tcl_NewStringObj(forwardArgString,-1); + Tcl_Obj *newarg = Tcl_NewStringObj(forwardArgString, -1); *out = newarg; goto add_to_freelist; } else { @@ -8934,7 +8934,7 @@ if (p == forwardArgString) *out = forwardArgObj; else { - Tcl_Obj *newarg = Tcl_NewStringObj(forwardArgString,-1); + Tcl_Obj *newarg = Tcl_NewStringObj(forwardArgString, -1); *out = newarg; goto add_to_freelist; } @@ -9916,15 +9916,15 @@ static void AppendForwardDefinition(Tcl_Interp *interp, Tcl_Obj *listObj, ForwardCmdClientData *tcd) { if (tcd->prefix) { - Tcl_ListObjAppendElement(interp, listObj, Tcl_NewStringObj("-methodprefix",-1)); + Tcl_ListObjAppendElement(interp, listObj, Tcl_NewStringObj("-methodprefix", -1)); Tcl_ListObjAppendElement(interp, listObj, tcd->prefix); } if (tcd->subcommands) { - Tcl_ListObjAppendElement(interp, listObj, Tcl_NewStringObj("-default",-1)); + Tcl_ListObjAppendElement(interp, listObj, Tcl_NewStringObj("-default", -1)); Tcl_ListObjAppendElement(interp, listObj, tcd->subcommands); } if (tcd->objscope) { - Tcl_ListObjAppendElement(interp, listObj, Tcl_NewStringObj("-objscope",-1)); + Tcl_ListObjAppendElement(interp, listObj, Tcl_NewStringObj("-objscope", -1)); } Tcl_ListObjAppendElement(interp, listObj, tcd->cmdName); if (tcd->args) { @@ -9943,16 +9943,16 @@ int withObjscope, int withPer_object) { Tcl_ListObjAppendElement(interp, listObj, object->cmdName); if (withPer_object) { - Tcl_ListObjAppendElement(interp, listObj, Tcl_NewStringObj("object",6)); + Tcl_ListObjAppendElement(interp, listObj, Tcl_NewStringObj("object", 6)); } - Tcl_ListObjAppendElement(interp, listObj, Tcl_NewStringObj(registerCmdName,-1)); + Tcl_ListObjAppendElement(interp, listObj, Tcl_NewStringObj(registerCmdName, -1)); if (withObjscope) { - Tcl_ListObjAppendElement(interp, listObj, Tcl_NewStringObj("-objscope",9)); + Tcl_ListObjAppendElement(interp, listObj, Tcl_NewStringObj("-objscope", 9)); } if (Tcl_Command_flags(cmd) & XOTCL_CMD_NONLEAF_METHOD) { - Tcl_ListObjAppendElement(interp, listObj, Tcl_NewStringObj("-nonleaf",8)); + Tcl_ListObjAppendElement(interp, listObj, Tcl_NewStringObj("-nonleaf", 8)); } - Tcl_ListObjAppendElement(interp, listObj, Tcl_NewStringObj(methodName,-1)); + Tcl_ListObjAppendElement(interp, listObj, Tcl_NewStringObj(methodName, -1)); } static int @@ -10045,7 +10045,7 @@ switch (subcmd) { case InfomethodsubcmdTypeIdx: - Tcl_SetObjResult(interp, Tcl_NewStringObj("scripted",-1)); + Tcl_SetObjResult(interp, Tcl_NewStringObj("scripted", -1)); break; case InfomethodsubcmdBodyIdx: @@ -10476,7 +10476,7 @@ Tcl_DString ds, *dsPtr = &ds; Tcl_SetVar2Ex(interp, XOTclGlobalStrings[XOTE_ALIAS_ARRAY], AliasIndex(dsPtr, cmdName, methodName, withPer_object), - Tcl_NewStringObj(cmd,-1), + Tcl_NewStringObj(cmd, -1), TCL_GLOBAL_ONLY); /*fprintf(stderr, "aliasAdd ::nx::core::alias(%s) '%s' returned %p\n", AliasIndex(dsPtr, cmdName, methodName, withPer_object), cmd, 1);*/ @@ -11450,8 +11450,8 @@ /* * construct full cmd names */ - newFullCmdName = Tcl_NewStringObj(toNsPtr->fullName,-1); - oldFullCmdName = Tcl_NewStringObj(fromNsPtr->fullName,-1); + newFullCmdName = Tcl_NewStringObj(toNsPtr->fullName, -1); + oldFullCmdName = Tcl_NewStringObj(fromNsPtr->fullName, -1); INCR_REF_COUNT(newFullCmdName); INCR_REF_COUNT(oldFullCmdName); Tcl_AppendStringsToObj(newFullCmdName, "::", name, (char *) NULL); @@ -13694,9 +13694,15 @@ static int XOTclObjInfoMethodMethod(Tcl_Interp *interp, XOTclObject *object, int subcmd, CONST char *methodName) { Tcl_Namespace *nsPtr = object->nsPtr; - return ListMethod(interp, object, - methodName, nsPtr ? FindMethod(nsPtr, methodName) : NULL, - subcmd, 1); + Tcl_Command cmd; + + if (*methodName == ':') { + Tcl_Obj *methodObj = Tcl_NewStringObj(methodName, -1); + cmd = Tcl_GetCommandFromObj(interp, methodObj); + } else { + cmd = nsPtr ? FindMethod(nsPtr, methodName) : NULL; + } + return ListMethod(interp, object, methodName, cmd, subcmd, 1); } /* @@ -13942,9 +13948,15 @@ static int XOTclClassInfoMethodMethod(Tcl_Interp *interp, XOTclClass *class, int subcmd, CONST char *methodName) { Tcl_Namespace *nsPtr = class->nsPtr; - return ListMethod(interp, &class->object, - methodName, nsPtr ? FindMethod(nsPtr, methodName) : NULL, - subcmd, 0); + Tcl_Command cmd; + + if (*methodName == ':') { + Tcl_Obj *methodObj = Tcl_NewStringObj(methodName, -1); + cmd = Tcl_GetCommandFromObj(interp, methodObj); + } else { + cmd = nsPtr ? FindMethod(nsPtr, methodName) : NULL; + } + return ListMethod(interp, &class->object, methodName, cmd, subcmd, 0); } /* @@ -14627,7 +14639,7 @@ XOTclGlobalObjs = NEW_ARRAY(Tcl_Obj*, nr_elements(XOTclGlobalStrings)); for (i = 0; i < nr_elements(XOTclGlobalStrings); i++) { - XOTclGlobalObjs[i] = Tcl_NewStringObj(XOTclGlobalStrings[i],-1); + XOTclGlobalObjs[i] = Tcl_NewStringObj(XOTclGlobalStrings[i], -1); INCR_REF_COUNT(XOTclGlobalObjs[i]); } Index: library/lib/doc-assets/object.html.tmpl =================================================================== diff -u -r79287f596cc2c14ecd2b788d217699e2baeb050d -rf62c1f601dda43d69c8b159e81b57d4271cd3175 --- library/lib/doc-assets/object.html.tmpl (.../object.html.tmpl) (revision 79287f596cc2c14ecd2b788d217699e2baeb050d) +++ library/lib/doc-assets/object.html.tmpl (.../object.html.tmpl) (revision f62c1f601dda43d69c8b159e81b57d4271cd3175) @@ -104,10 +104,13 @@ [$method parameters] [:? {[$method has_property interally-called]} { -
Internally called method, can be redefined.
+
Internally called method, can be redefined. }] - -
+ [:? {[[:name] info methods [$method name]] ne "" && + [::nx::core::methodproperty [:name] [$method name] redefine-protected]} { +
Method is redefine-protected + }] +
[$method text]
@@ -148,9 +151,13 @@ Deprecated [$method @deprecated]
}] + + [:? {[[:name] info methods [$method name]] ne ""} { +
Method type: [[:name] info method type [$method name]] + }] - +
@@ -188,7 +195,7 @@ }] [:?var :@method { - Undocumented: [:undocumented] + Undocumented Methods: [:undocumented] }] Index: library/lib/doc-tools.tcl =================================================================== diff -u -r79287f596cc2c14ecd2b788d217699e2baeb050d -rf62c1f601dda43d69c8b159e81b57d4271cd3175 --- library/lib/doc-tools.tcl (.../doc-tools.tcl) (revision 79287f596cc2c14ecd2b788d217699e2baeb050d) +++ library/lib/doc-tools.tcl (.../doc-tools.tcl) (revision f62c1f601dda43d69c8b159e81b57d4271cd3175) @@ -357,7 +357,7 @@ :method has_property {prop} { if {![info exists :@properties]} {return 0} - expr {$prop in ${:@properties}} + expr {$prop in ${:@properties}} } # @method _doc @@ -629,23 +629,51 @@ } } if {1} { + # documentaion quality check: is documentation in sync with implementation? # TODO: make me conditional, MARKUP should be in templates set object [${:partof} name] if {[::nx::core::objectproperty $object object]} { if {[$object info methods ${:name}] ne ""} { + set actualParams "" if {[$object info method type ${:name}] eq "forward"} { + set cmd "" + foreach w [lrange [$object info method definition ${:name}] 2 end] { + if {[string match ::* $w]} { + set cmd $w + break + } + } + if {$cmd ne "" && [string match ::nx::core::* $cmd]} { + # TODO: we assume here, the cmd is a primitive + # command and we intend only to handle cases from + # predefined or xotcl2. Make sure this is working + # reasonable for other cases, such as forwards to + # other objects, as well + if {![catch {set actualParams [::nx::Object info method parameter $cmd]}]} { + # drop usual object + set actualParams [lrange $actualParams 1 end] + # drop per object ; TODO: always? + if {[lindex $actualParams 0] eq "-per-object"} { + set actualParams [lrange $actualParams 1 end] + set syntax [lrange [::nx::Object info method parametersyntax $cmd] 2 end] + } else { + set syntax [lrange [::nx::Object info method parametersyntax $cmd] 1 end] + } + } + } set comment "Defined as a forwarder, can't check" - set handle ::nx::core::signature($object-class-${:name}) - if {[info exists $handle]} {append comment
[set $handle]} + #set handle ::nx::core::signature($object-class-${:name}) + #if {[info exists $handle]} {append comment
[set $handle]} } else { set actualParams [$object info method parameter ${:name}] - if {$actualParams eq $params} { - set comment "Perfect match" - } else { - set comment "actual parameter: $actualParams" - } - append comment "
Syntax: obj ${:name} [$object info method parametersyntax ${:name}]" + set syntax [$object info method parametersyntax ${:name}] } + if {$actualParams eq $params} { + set comment "Perfect match" + } else { + set comment "actual parameter: $actualParams" + } + append comment "
Syntax: obj ${:name} $syntax" } else { set comment "Method '${:name}' not defined on $object" } @@ -774,17 +802,16 @@ "\[info exists $varname\]" {*}$args] } :method ? { - {-ops {? -}} + {-ops {? -}} expr - then + then next:optional args } { if {[info exists next] && $next ni $ops} { return -code error "Invalid control operator '$next', we expect one of $ops" } - set condition [list expr $expr] - if {[uplevel 1 $condition]} { + if {[uplevel 1 [list expr $expr]]} { return [uplevel 1 [list subst $then]] } elseif {[info exists next]} { if {$next eq "-"} {