Index: TODO =================================================================== diff -u -r809d5cfca32225ba624c87a2e09f9a265a84cb2d -ref17499c6911ca6b6712384f6793acc1d7cb856e --- TODO (.../TODO) (revision 809d5cfca32225ba624c87a2e09f9a265a84cb2d) +++ TODO (.../TODO) (revision ef17499c6911ca6b6712384f6793acc1d7cb856e) @@ -4984,6 +4984,14 @@ ======================================================================== TODO: + +- forwarder: should %proc be renamed to %method or (for XOTcl2 compat) + %method be accepted as alternative name (more NX'ish)? + +- Revisit nsf::*::assertion interface? Why does nsf::method::assertion + allow for setting invariants. One would rather expect a + ::nsf::object|class::assertion or the like? + - test cases switch now to global dir. maybe due to new tcl.m4. See e.g.: notice: Running test cases: /usr/local/ns/lib/nsf2.0b6/lib/nx-test.tcl Index: doc/Object.man =================================================================== diff -u -rdb01a10696125a444bc827592087f56491900c2d -ref17499c6911ca6b6712384f6793acc1d7cb856e --- doc/Object.man (.../Object.man) (revision db01a10696125a444bc827592087f56491900c2d) +++ doc/Object.man (.../Object.man) (revision ef17499c6911ca6b6712384f6793acc1d7cb856e) @@ -339,6 +339,14 @@ [list_end] +[cmd_def forward] + +[list_begin definitions] + +[include forward.man.inc] + +[list_end] + [cmd_def info] [list_begin definitions] @@ -527,9 +535,6 @@ [call [arg obj] [method {object filter}] ...] [para] Description of [method {object filter}] ... -[call [arg obj] [method {object forward}] ...] -[para] Description of [method {object forward}] ... - [call [arg obj] [method {object method}] ...] [para] Description of [method {object method}] ... Index: doc/alias.man.inc =================================================================== diff -u -r430801481ec743e9b44376bc82f1568ac165cdf7 -ref17499c6911ca6b6712384f6793acc1d7cb856e --- doc/alias.man.inc (.../alias.man.inc) (revision 430801481ec743e9b44376bc82f1568ac165cdf7) +++ doc/alias.man.inc (.../alias.man.inc) (revision ef17499c6911ca6b6712384f6793acc1d7cb856e) @@ -12,11 +12,11 @@ [cmd proc]), the argument should be a fully qualified Tcl command name. If aliasing a subcommand (e.g., [cmd "array exists"]) of a Tcl namespace ensemble (e.g., [cmd array]), [arg cmdName] must hold the fully qualified subcommand name (and not the ensemble name of the subcommand). - -[para] As for a regular [method "[vset SCOPE] method"], [option "-returns"] allows -for setting a [term "value checker"] on the values -returned by the [term "alias method"]. [para] +As for a regular [method "[vset SCOPE] method"], [option "-returns"] +allows for setting a [term "value checker"] on the values returned by +the aliased command [arg cmdName]. +[para] When creating an [term "alias method"] for a [emph C-implemented] Tcl command (i.e., command defined using the Tcl/NX C-API), [opt [option -frame]] sets the scope @@ -25,4 +25,4 @@ context of the called object, i.e., the object upon which the [term "alias method"] is invoked, as if they were object variables. There is no need for using the colon-prefix notation for identifying object variables. If the -value is [const method], then the aliased command will be executed as a regular method call. The command is aware of its called-object context; i.e., it can resolve [cmd ::nx::self]. In addition, the [term "alias method"] has access to the method-call context (e.g., [cmd nx::next]). If [option "-frame"] is omitted, and by default, the variable references will resolve in the context of the caller of the [term "alias method"]. \ No newline at end of file +value is [const method], then the aliased command will be executed as a regular method call. The command is aware of its called-object context; i.e., it can resolve [cmd ::nx::self]. In addition, the [term "alias method"] has access to the method-call context (e.g., [cmd nx::next]). If [option "-frame"] is omitted, and by default, the variable references will resolve in the context of the caller of the [term "alias method"]. Index: doc/forward.man.inc =================================================================== diff -u --- doc/forward.man.inc (revision 0) +++ doc/forward.man.inc (revision ef17499c6911ca6b6712384f6793acc1d7cb856e) @@ -0,0 +1,94 @@ +[comment {-*- tcl -*- manpage fragment for forward method, shared by nx::Object and nx::Class}] + +[keywords "value checker"] +[keywords "forward method"] + +[call [arg [vset CMD]] [opt "public | protected | private"] [const [vset SCOPE]] [method forward] [arg methodName] [opt [option "-default [arg value]"]] [opt [option "-methodprefix [arg prefixName]"]] [opt [option "-objframe"]] [opt [option "-onerror [arg cmdName]"]] [opt [option "-returns [arg valueChecker]"]] [opt [option "-verbose"]] [arg arg] [opt "[arg arg] ..."]] + +Define a [term "forward method"] for the given [vset SCOPE]. The +resulting method registers a predefined, but changeable list of +forwarder arguments under the (forwarder) name [arg methodName]. Upon +calling the [term "forward method"], the forwarder arguments are +evaluated as a Tcl command call. That is, the first argument [arg arg] +is interpreted as a Tcl command (e.g., a Tcl [cmd proc] or an object) +and the remainder of the forwarder arguments as arguments passed into +this command. The actual method arguments to the invocation of the +[term "forward method"] itself are appended to the list of forwarder +arguments. + +[para] + +As for a regular [method "[vset SCOPE] method"], [option "-returns"] allows +for setting a [term "value checker"] on the values returned by the +resulting Tcl command call. When setting the [term "switch"] [option "-objframe"], the +resulting Tcl command is evaluated in the context of the object +receiving the [term "forward method"] call. [option "-onerror"] sets a +Tcl command [arg cmdName] which is called as the handler for errors +caught during evaluating the resulting Tcl command. + +[para] + +The list of forwarder arguments [arg arg] can contain a mix of literal +values and placeholder values. Placeholders are prefixed with a +percent symbol (%) and substituted for concrete values upon calling +the [term "forward method"]. These placeholders allow for constructing +and for manipulating the list of forwarder arguments on the fly: + +[list_begin itemized] + +[item] [const %proc] becomes substituted for the name of the [term "forward method"], i.e. [arg methodName]. + +[item] [const %self] becomes substituted for the name of the object receiving the call of the [term "forward method"]. + +[item] [const %1] becomes substituted for the first method argument passed to the call of [term "forward method"]. + +[item] {[const %@[arg index]] [arg value]} becomes substituted for the +specified [arg value] at position [arg index] in the +forwarder-arguments list, with [arg index] being either a positive +integer, a negative integer, or the literal value [const end] (such as +in Tcl's [cmd lindex]). Positive integers specify a list position +relative to the list head, negative integers give a position +relative to the list tail. + +[item] {[const %argclindex] [arg list]} becomes substituted for the +[emph n]th element of the provided [arg list] , with [emph n] +corresponding to the number of method arguments passed to the [term "forward method"] call. + +[item] [const %%] is substituted for a single literal percent (%) symbol. + +[item] [const %[arg cmdName]] is substituted for the value returned +from executing the Tcl command [arg cmdName]. + +[list_end] + +Additionally, any forwarder argument [arg arg] can be prefixed with +[const %@][arg index] to set the subsitition position in the resulting Tcl command list explicitly. [arg index] can be either a +positive integer, a negative integer, or [const end] (such as in Tcl's +[cmd lindex]). The positioning prefixes are evaluated from left to +right and should be used in ascending order. + +[para] + + +[para] +To inspect and to debug the substitutions performed by the above +placeholder values, setting the [term "switch"] [option "-verbose"] +will have the resulting Tcl command (i.e., after substitution) printed to +[const stdout]. + +[comment {# +# @parameter method The name of the delegating or forwarder method +# @parameter -default Is used for default method names (only +# in connection with %1) +# @parameter -methodprefix Prepends the specified prefix to the second +# argument of the invocation. +# @parameter -objframe Causes the target to be evaluated in +# the scope of the object. +# @parameter -onerror Register an error handler +# @parameter -returns Provide an out parameter +# specification, used to check the +# return value of the forward dispatch. +# @parameter -verbose Print the substituted command string to stderr +# before performing the command +# execution. For debugging purposes. +}] Index: doc/method.man.inc =================================================================== diff -u -rdb01a10696125a444bc827592087f56491900c2d -ref17499c6911ca6b6712384f6793acc1d7cb856e --- doc/method.man.inc (.../method.man.inc) (revision db01a10696125a444bc827592087f56491900c2d) +++ doc/method.man.inc (.../method.man.inc) (revision ef17499c6911ca6b6712384f6793acc1d7cb856e) @@ -43,6 +43,6 @@ implementing the method body can contain object-specific notation and commands (see above). Third, method calls [emph cannot] be intercepted using Tcl [cmd trace]. Note that an existing Tcl [cmd proc] can be registered as -an [term "alias method"] (see [method "[vset SCOPE] alias"]). +an [term "alias method"] with the [vset SCOPE] (see [method "[vset SCOPE] alias"]). [comment {TODO: refer to nsf::proc?}]