Index: doc/Object.3 =================================================================== diff -u -rf52d344b772763bfd59bc41294e7a45a336b2346 -r63ef94e81bbdfb6c0c233d65520a3e7b3e47f706 --- doc/Object.3 (.../Object.3) (revision f52d344b772763bfd59bc41294e7a45a336b2346) +++ doc/Object.3 (.../Object.3) (revision 63ef94e81bbdfb6c0c233d65520a3e7b3e47f706) @@ -1,8 +1,8 @@ '\" '\" Generated from file 'Object\&.man' by tcllib/doctools with format 'nroff' -'\" Copyright (c) 2014-16 Stefan Sobernig , Gustaf Neumann ; available under the Creative Commons Attribution 3\&.0 Austria license (CC BY 3\&.0 AT)\&. +'\" Copyright (c) 2014-19 Stefan Sobernig , Gustaf Neumann ; available under the Creative Commons Attribution 3\&.0 Austria license (CC BY 3\&.0 AT)\&. '\" -.TH "nx::Object" 3 2\&.1\&.0 Object "NX API" +.TH "nx::Object" 3 2\&.3a0 Object "NX API" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" @@ -346,6 +346,8 @@ .sp \fIobj\fR \fBunknown\fR \fIunknownMethodName\fR ?\fIarg\fR \&.\&.\&.? .sp +\fIobj\fR \fBuplevel\fR ?\fIlevel\fR? \fIarg1\fR ?\fIarg2\fR \&.\&.\&.? +.sp \fIobj\fR \fBobject variable\fR ?\fB-accessor\fR \fBpublic\fR | \fBprotected\fR | \fBprivate\fR? ?\fB-incremental\fR? ?\fB-class\fR \fIclassName\fR? ?\fB-configurable\fR \fItrueFalse\fR? ?\fB-initblock\fR \fIscript\fR? ?\fB-trace\fR \fBset\fR | \fBget\fR | \fBdefault\fR? ?\fB-nocomplain\fR? \fIspec\fR ?\fIdefaultValue\fR? .sp .BE @@ -912,8 +914,11 @@ .TP \fIobj\fR \fBinfo lookup\fR \fIsubmethod\fR ?\fIarg\fR \&.\&.\&.? A collection of submethods to retrieve structural features (e\&.g\&. -configuration options, slot objects) and behavioral -features (e\&.g\&. methods, filters) available for \fIobj\fR from the perspective of a client to \fIobj\fR\&. Features provided by \fIobj\fR itself and by the classes in its current linearisation list are considered\&. +configuration options, slot objects) and behavioral features +(e\&.g\&. methods, filters) available for \fIobj\fR from the +perspective of a client to \fIobj\fR\&. Features provided by \fIobj\fR +itself and by the classes in its current linearization list are +considered\&. .RS .TP \fIobj\fR \fBinfo lookup filter\fR \fIname\fR @@ -939,7 +944,8 @@ .TP \fIobj\fR \fBinfo lookup mixins\fR ?\fB-guards\fR? ?\fInamePattern\fR? Returns the object names of all mixin classes which are -currently active on \fIobj\fR\&. By turning on the switch \fB-guards\fR, the corresponding guard expressions, if any, are also reported as a +currently active on \fIobj\fR\&. By turning on the switch +\fB-guards\fR, the corresponding guard expressions, if any, are also reported as a three-element list for each mixin class: \fIclassName\fR -guard \fIguardExpr\fR\&. The returned mixin classes can be limited to those whose names match \fInamePattern\fR (see \fBstring match\fR)\&. @@ -955,9 +961,14 @@ managing properties, variables, and relations of \fIobj\fR\&. The returned slot objects can be limited according to any or a combination of the following criteria: First, slot objects -can be filtered based on their command names matching \fInamePattern\fR (see -\fBstring match\fR)\&. Second, \fB-type\fR allows one to select -slot objects which are instantiated from a subclass \fIclassName\fR of \fBnx::Slot\fR (default: \fBnx::Slot\fR) \&. Third, \fB-source\fR restricts slot objects returned according to their provenance in either the NX \fIsystem\fR classes or the \fIapplication\fR classes present in the linearisation list of \fIobj\fR (default: \fIall\fR)\&. +can be filtered based on their command names matching \fInamePattern\fR +(see \fBstring match\fR)\&. Second, \fB-type\fR +allows one to select slot objects which are instantiated from +a subclass \fIclassName\fR of \fBnx::Slot\fR (default: \fBnx::Slot\fR) +\&. Third, \fB-source\fR restricts slot objects returned +according to their provenance in either the NX \fIsystem\fR classes +or the \fIapplication\fR classes present in the linearization list of +\fIobj\fR (default: \fIall\fR)\&. .sp To extract details of each slot object, use the \fBinfo\fR submethods available for each slot object\&. @@ -971,7 +982,8 @@ .TP \fIobj\fR \fBinfo lookup variables\fR Returns the command names of all slot objects responsible for -managing properties and variables of \fIobj\fR, if provided by \fIobj\fR or the classes in the linearisation list of \fIobj\fR\&. +managing properties and variables of \fIobj\fR, if provided by \fIobj\fR +or the classes in the linearization list of \fIobj\fR\&. .sp This is equivalent to calling: \fIobj\fR \fBinfo lookup slots\fR -type ::nx::VariableSlot -source all ?\fInamePattern\fR?\&. .sp @@ -1101,7 +1113,7 @@ \fIobj\fR \fBinfo precedence\fR ?\fB-intrinsic\fR? ?\fIpattern\fR? Lists the classes from which \fIobj\fR inherits structural (e\&.g\&. properties) and behavioral features (e\&.g\&. methods) and methods, in -order of the linearisation scheme in NX\&. By setting the +order of the linearization scheme in NX\&. By setting the switch \fB-intrinsic\fR, only classes which participate in superclass/subclass relationships (i\&.e\&., intrinsic classes) are returned\&. If a \fIpattern\fR is provided only classes whose @@ -1384,9 +1396,55 @@ This method is called implicitly whenever an unknown method is invoked\&. \fIunknownMethodName\fR indicates the unresolvable method name, followed by the remainder of the original argument vector as a number -of \fIarg\fR of the indirected method invocation\&. +of \fIarg\fR of the calling method invocation\&. .RE .TP +\fBuplevel\fR +.RS +.TP +\fIobj\fR \fBuplevel\fR ?\fIlevel\fR? \fIarg1\fR ?\fIarg2\fR \&.\&.\&.? +Evaluate a script or a command at a different stack-frame +level\&. Behaves like Tcl's \fBuplevel\fR, with the following +important exceptions\&. +.RS +.IP \(bu +If the \fIlevel\fR specifier is omitted, \fBuplevel\fR +will skip any auxiliary frames added to the stack by active filters and +mixins\&. +.IP \(bu +If the \fIlevel\fR specifier is omitted, \fBuplevel\fR gives +preference to the innermost frame corresponding to a proc, method, or +apply call\&. Any frames inbetween, incl\&. those of filters +and mixins (see above), will be skipped\&. +.IP \(bu +If the \fIlevel\fR specifier is provided (relative, or +absolute), \fBuplevel\fR will move execution into the requested +stack-frame level (incl\&. those introduced by active active filters and +mixins), if valid\&. +.RE +.CS + + + % nx::Object create ::obj + % ::obj public object method foo {varName} { + :uplevel set $varName 1; return + } + ::obj + % namespace eval ::ns1 { + ::obj foo BAR + } + % namespace eval ::ns1 { + info exists BAR + } + 1 + +.CE +.RE +.IP +Note, in the example above, \fBuplevel\fR is guaranteed to +resolve to the calling context of \fBfoo\fR (ns1) despite +mixins and filters being (potentially) registered on \fBobj\fR\&. +.TP \fBvariable\fR .RS .TP @@ -1510,7 +1568,7 @@ Objects are naturally recursive, with methods of an object \fB::obj\fR frequently invoking other methods in the same object \fB::obj\fR and accessing \fB::obj\fR's object variables\&. To represent these -self-references effectively in method bodies, and dependening on the +self-references effectively in method bodies, and depending on the usage scenario, NX offers two alternative notations for self-references: one based on a special-purpose syntax token ("colon prefix"), the other based on the command \fBnx::current\fR\&. @@ -1569,6 +1627,6 @@ .CE .SH COPYRIGHT .nf -Copyright (c) 2014-16 Stefan Sobernig , Gustaf Neumann ; available under the Creative Commons Attribution 3\&.0 Austria license (CC BY 3\&.0 AT)\&. +Copyright (c) 2014-19 Stefan Sobernig , Gustaf Neumann ; available under the Creative Commons Attribution 3\&.0 Austria license (CC BY 3\&.0 AT)\&. -.fi +.fi \ No newline at end of file Index: doc/Object.man =================================================================== diff -u -rf52d344b772763bfd59bc41294e7a45a336b2346 -r63ef94e81bbdfb6c0c233d65520a3e7b3e47f706 --- doc/Object.man (.../Object.man) (revision f52d344b772763bfd59bc41294e7a45a336b2346) +++ doc/Object.man (.../Object.man) (revision 63ef94e81bbdfb6c0c233d65520a3e7b3e47f706) @@ -20,7 +20,7 @@ [vset CMD "obj"] [vset MODIFIER "object"] -[copyright {2014-16 Stefan Sobernig , Gustaf Neumann ; available under the Creative Commons Attribution 3.0 Austria license (CC BY 3.0 AT).}] +[copyright {2014-19 Stefan Sobernig , Gustaf Neumann ; available under the Creative Commons Attribution 3.0 Austria license (CC BY 3.0 AT).}] [moddesc "NX API"] [titledesc {API reference of the base class in the NX object system}] @@ -743,6 +743,55 @@ [list_end] +[cmd_def uplevel] + +[list_begin definitions] + +[call [arg obj] [method uplevel] [opt [arg level]] [arg arg1] [opt "[arg arg2] ..."]] + +Evaluate a script or a command at a different stack-frame +level. Behaves like Tcl's [cmd uplevel], with the following +important exceptions. + +[list_begin itemized] + +[item] If the [arg level] specifier is omitted, [method "uplevel"] +will skip any auxiliary frames added to the stack by active [term "filter"]s and +[term "mixin"]s. + +[item] If the [arg level] specifier is omitted, [method uplevel] gives +preference to the innermost frame corresponding to a proc, method, or +apply call. Any frames inbetween, incl. those of filters +and mixins (see above), will be skipped. + +[item] If the [arg level] specifier is provided (relative, or +absolute), [method "uplevel"] will move execution into the requested +stack-frame level (incl. those introduced by active active [term "filter"]s and +[term "mixin"]s), if valid. + +[list_end] + +[example { + % nx::Object create ::obj + % ::obj public object method foo {varName} { + :uplevel set $varName 1; return + } + ::obj + % namespace eval ::ns1 { + ::obj foo BAR + } + % namespace eval ::ns1 { + info exists BAR + } + 1 +}] + +[list_end] + +Note, in the example above, [method "uplevel"] is guaranteed to +resolve to the calling context of [method "foo"] ([term "ns1"]) despite +mixins and filters being (potentially) registered on [cmd "obj"]. + [cmd_def variable] [list_begin definitions]