util/X86LINUX64/man/mann/nextto.n

   1 '\"
   2 '\" Copyright (c) 2007 Donal K. Fellows
   3 '\"
   4 '\" See the file "license.terms" for information on usage and redistribution
   5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   6 '\"
   7 .TH next n 0.1 TclOO "TclOO Commands"
   8 .\" The -*- nroff -*- definitions below are for supplemental macros used
   9 .\" in Tcl/Tk manual entries.
  10 .\"
  11 .\" .AP type name in/out ?indent?
  12 .\"     Start paragraph describing an argument to a library procedure.
  13 .\"     type is type of argument (int, etc.), in/out is either "in", "out",
  14 .\"     or "in/out" to describe whether procedure reads or modifies arg,
  15 .\"     and indent is equivalent to second arg of .IP (shouldn't ever be
  16 .\"     needed;  use .AS below instead)
  17 .\"
  18 .\" .AS ?type? ?name?
  19 .\"     Give maximum sizes of arguments for setting tab stops.  Type and
  20 .\"     name are examples of largest possible arguments that will be passed
  21 .\"     to .AP later.  If args are omitted, default tab stops are used.
  22 .\"
  23 .\" .BS
  24 .\"     Start box enclosure.  From here until next .BE, everything will be
  25 .\"     enclosed in one large box.
  26 .\"
  27 .\" .BE
  28 .\"     End of box enclosure.
  29 .\"
  30 .\" .CS
  31 .\"     Begin code excerpt.
  32 .\"
  33 .\" .CE
  34 .\"     End code excerpt.
  35 .\"
  36 .\" .VS ?version? ?br?
  37 .\"     Begin vertical sidebar, for use in marking newly-changed parts
  38 .\"     of man pages.  The first argument is ignored and used for recording
  39 .\"     the version when the .VS was added, so that the sidebars can be
  40 .\"     found and removed when they reach a certain age.  If another argument
  41 .\"     is present, then a line break is forced before starting the sidebar.
  42 .\"
  43 .\" .VE
  44 .\"     End of vertical sidebar.
  45 .\"
  46 .\" .DS
  47 .\"     Begin an indented unfilled display.
  48 .\"
  49 .\" .DE
  50 .\"     End of indented unfilled display.
  51 .\"
  52 .\" .SO ?manpage?
  53 .\"     Start of list of standard options for a Tk widget. The manpage
  54 .\"     argument defines where to look up the standard options; if
  55 .\"     omitted, defaults to "options". The options follow on successive
  56 .\"     lines, in three columns separated by tabs.
  57 .\"
  58 .\" .SE
  59 .\"     End of list of standard options for a Tk widget.
  60 .\"
  61 .\" .OP cmdName dbName dbClass
  62 .\"     Start of description of a specific option.  cmdName gives the
  63 .\"     option's name as specified in the class command, dbName gives
  64 .\"     the option's name in the option database, and dbClass gives
  65 .\"     the option's class in the option database.
  66 .\"
  67 .\" .UL arg1 arg2
  68 .\"     Print arg1 underlined, then print arg2 normally.
  69 .\"
  70 .\" .QW arg1 ?arg2?
  71 .\"     Print arg1 in quotes, then arg2 normally (for trailing punctuation).
  72 .\"
  73 .\" .PQ arg1 ?arg2?
  74 .\"     Print an open parenthesis, arg1 in quotes, then arg2 normally
  75 .\"     (for trailing punctuation) and then a closing parenthesis.
  76 .\"
  77 .\"     # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
  78 .if t .wh -1.3i ^B
  79 .nr ^l \n(.l
  80 .ad b
  81 .\"     # Start an argument description
  82 .de AP
  83 .ie !"\\$4"" .TP \\$4
  84 .el \{\
  85 .   ie !"\\$2"" .TP \\n()Cu
  86 .   el          .TP 15
  87 .\}
  88 .ta \\n()Au \\n()Bu
  89 .ie !"\\$3"" \{\
  90 \&\\$1 \\fI\\$2\\fP (\\$3)
  91 .\".b
  92 .\}
  93 .el \{\
  94 .br
  95 .ie !"\\$2"" \{\
  96 \&\\$1  \\fI\\$2\\fP
  97 .\}
  98 .el \{\
  99 \&\\fI\\$1\\fP
 100 .\}
 101 .\}
 102 ..
 103 .\"     # define tabbing values for .AP
 104 .de AS
 105 .nr )A 10n
 106 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
 107 .nr )B \\n()Au+15n
 108 .\"
 109 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
 110 .nr )C \\n()Bu+\\w'(in/out)'u+2n
 111 ..
 112 .AS Tcl_Interp Tcl_CreateInterp in/out
 113 .\"     # BS - start boxed text
 114 .\"     # ^y = starting y location
 115 .\"     # ^b = 1
 116 .de BS
 117 .br
 118 .mk ^y
 119 .nr ^b 1u
 120 .if n .nf
 121 .if n .ti 0
 122 .if n \l'\\n(.lu\(ul'
 123 .if n .fi
 124 ..
 125 .\"     # BE - end boxed text (draw box now)
 126 .de BE
 127 .nf
 128 .ti 0
 129 .mk ^t
 130 .ie n \l'\\n(^lu\(ul'
 131 .el \{\
 132 .\"     Draw four-sided box normally, but don't draw top of
 133 .\"     box if the box started on an earlier page.
 134 .ie !\\n(^b-1 \{\
 135 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 136 .\}
 137 .el \}\
 138 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 139 .\}
 140 .\}
 141 .fi
 142 .br
 143 .nr ^b 0
 144 ..
 145 .\"     # VS - start vertical sidebar
 146 .\"     # ^Y = starting y location
 147 .\"     # ^v = 1 (for troff;  for nroff this doesn't matter)
 148 .de VS
 149 .if !"\\$2"" .br
 150 .mk ^Y
 151 .ie n 'mc \s12\(br\s0
 152 .el .nr ^v 1u
 153 ..
 154 .\"     # VE - end of vertical sidebar
 155 .de VE
 156 .ie n 'mc
 157 .el \{\
 158 .ev 2
 159 .nf
 160 .ti 0
 161 .mk ^t
 162 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
 163 .sp -1
 164 .fi
 165 .ev
 166 .\}
 167 .nr ^v 0
 168 ..
 169 .\"     # Special macro to handle page bottom:  finish off current
 170 .\"     # box/sidebar if in box/sidebar mode, then invoked standard
 171 .\"     # page bottom macro.
 172 .de ^B
 173 .ev 2
 174 'ti 0
 175 'nf
 176 .mk ^t
 177 .if \\n(^b \{\
 178 .\"     Draw three-sided box if this is the box's first page,
 179 .\"     draw two sides but no top otherwise.
 180 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 181 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 182 .\}
 183 .if \\n(^v \{\
 184 .nr ^x \\n(^tu+1v-\\n(^Yu
 185 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
 186 .\}
 187 .bp
 188 'fi
 189 .ev
 190 .if \\n(^b \{\
 191 .mk ^y
 192 .nr ^b 2
 193 .\}
 194 .if \\n(^v \{\
 195 .mk ^Y
 196 .\}
 197 ..
 198 .\"     # DS - begin display
 199 .de DS
 200 .RS
 201 .nf
 202 .sp
 203 ..
 204 .\"     # DE - end display
 205 .de DE
 206 .fi
 207 .RE
 208 .sp
 209 ..
 210 .\"     # SO - start of list of standard options
 211 .de SO
 212 'ie '\\$1'' .ds So \\fBoptions\\fR
 213 'el .ds So \\fB\\$1\\fR
 214 .SH "STANDARD OPTIONS"
 215 .LP
 216 .nf
 217 .ta 5.5c 11c
 218 .ft B
 219 ..
 220 .\"     # SE - end of list of standard options
 221 .de SE
 222 .fi
 223 .ft R
 224 .LP
 225 See the \\*(So manual entry for details on the standard options.
 226 ..
 227 .\"     # OP - start of full description for a single option
 228 .de OP
 229 .LP
 230 .nf
 231 .ta 4c
 232 Command-Line Name:      \\fB\\$1\\fR
 233 Database Name:  \\fB\\$2\\fR
 234 Database Class: \\fB\\$3\\fR
 235 .fi
 236 .IP
 237 ..
 238 .\"     # CS - begin code excerpt
 239 .de CS
 240 .RS
 241 .nf
 242 .ta .25i .5i .75i 1i
 243 ..
 244 .\"     # CE - end code excerpt
 245 .de CE
 246 .fi
 247 .RE
 248 ..
 249 .\"     # UL - underline word
 250 .de UL
 251 \\$1\l'|0\(ul'\\$2
 252 ..
 253 .\"     # QW - apply quotation marks to word
 254 .de QW
 255 .ie '\\*(lq'"' ``\\$1''\\$2
 256 .\"" fix emacs highlighting
 257 .el \\*(lq\\$1\\*(rq\\$2
 258 ..
 259 .\"     # PQ - apply parens and quotation marks to word
 260 .de PQ
 261 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
 262 .\"" fix emacs highlighting
 263 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
 264 ..
 265 .\"     # QR - quoted range
 266 .de QR
 267 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
 268 .\"" fix emacs highlighting
 269 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
 270 ..
 271 .\"     # MT - "empty" string
 272 .de MT
 273 .QW ""
 274 ..
 275 .BS
 276 '\" Note:  do not modify the .SH NAME line immediately below!
 277 .SH NAME
 278 next, nextto \- invoke superclass method implementations
 279 .SH SYNOPSIS
 280 .nf
 281 package require TclOO
 282
 283 \fBnext\fR ?\fIarg ...\fR?
 284 \fBnextto\fI class\fR ?\fIarg ...\fR?
 285 .fi
 286 .BE
 287
 288 .SH DESCRIPTION
 289 .PP
 290 The \fBnext\fR command is used to call implementations of a method by a class,
 291 superclass or mixin that are overridden by the current method. It can only be
 292 used from within a method. It is also used within filters to indicate the
 293 point where a filter calls the actual implementation (the filter may decide to
 294 not go along the chain, and may process the results of going along the chain
 295 of methods as it chooses). The result of the \fBnext\fR command is the result
 296 of the next method in the method chain; if there are no further methods in the
 297 method chain, the result of \fBnext\fR will be an error. The arguments,
 298 \fIarg\fR, to \fBnext\fR are the arguments to pass to the next method in the
 299 chain.
 300 .PP
 301 The \fBnextto\fR command is the same as the \fBnext\fR command, except that it
 302 takes an additional \fIclass\fR argument that identifies a class whose
 303 implementation of the current method chain (see \fBinfo object\fR \fBcall\fR) should
 304 be used; the method implementation selected will be the one provided by the
 305 given class, and it must refer to an existing non-filter invocation that lies
 306 further along the chain than the current implementation.
 307 .SH "THE METHOD CHAIN"
 308 .PP
 309 When a method of an object is invoked, things happen in several stages:
 310 .IP [1]
 311 The structure of the object, its class, superclasses, filters, and mixins, are
 312 examined to build a \fImethod chain\fR, which contains a list of method
 313 implementations to invoke.
 314 .IP [2]
 315 The first method implementation on the chain is invoked.
 316 .IP [3]
 317 If that method implementation invokes the \fBnext\fR command, the next method
 318 implementation is invoked (with its arguments being those that were passed to
 319 \fBnext\fR).
 320 .IP [4]
 321 The result from the overall method call is the result from the outermost
 322 method implementation; inner method implementations return their results
 323 through \fBnext\fR.
 324 .IP [5]
 325 The method chain is cached for future use.
 326 .SS "METHOD SEARCH ORDER"
 327 .PP
 328 When constructing the method chain, method implementations are searched for in
 329 the following order:
 330 .IP [1]
 331 In the classes mixed into the object, in class traversal order. The list of
 332 mixins is checked in natural order.
 333 .IP [2]
 334 In the classes mixed into the classes of the object, with sources of mixing in
 335 being searched in class traversal order. Within each class, the list of mixins
 336 is processed in natural order.
 337 .IP [3]
 338 In the object itself.
 339 .IP [4]
 340 In the object's class.
 341 .IP [5]
 342 In the superclasses of the class, following each superclass in a depth-first
 343 fashion in the natural order of the superclass list.
 344 .PP
 345 Any particular method implementation always comes as \fIlate\fR in the
 346 resulting list of implementations as possible; this means that if some class,
 347 A, is both mixed into a class, B, and is also a superclass of B, the instances
 348 of B will always treat A as a superclass from the perspective of inheritance.
 349 This is true even when the multiple inheritance is processed indirectly.
 350 .SS FILTERS
 351 .PP
 352 When an object has a list of filter names set upon it, or is an instance of a
 353 class (or has mixed in a class) that has a list of filter names set upon it,
 354 before every invocation of any method the filters are processed. Filter
 355 implementations are found in class traversal order, as are the lists of filter
 356 names (each of which is traversed in natural list order). Explicitly invoking
 357 a method used as a filter will cause that method to be invoked twice, once as
 358 a filter and once as a normal method.
 359 .PP
 360 Each filter should decide for itself whether to permit the execution to go
 361 forward to the proper implementation of the method (which it does by invoking
 362 the \fBnext\fR command as filters are inserted into the front of the method
 363 call chain) and is responsible for returning the result of \fBnext\fR.
 364 .PP
 365 Filters are not invoked when processing an invocation of the \fBunknown\fR
 366 method because of a failure to locate a method implementation, or when
 367 invoking either constructors or destructors.
 368 .SH EXAMPLES
 369 .PP
 370 This example demonstrates how to use the \fBnext\fR command to call the
 371 (super)class's implementation of a method. The script:
 372 .PP
 373 .CS
 374 oo::class create theSuperclass {
 375     method example {args} {
 376         puts "in the superclass, args = $args"
 377     }
 378 }
 379 oo::class create theSubclass {
 380     superclass theSuperclass
 381     method example {args} {
 382         puts "before chaining from subclass, args = $args"
 383         \fBnext\fR a {*}$args b
 384         \fBnext\fR pureSynthesis
 385         puts "after chaining from subclass"
 386     }
 387 }
 388 theSubclass create obj
 389 oo::define obj method example args {
 390     puts "per-object method, args = $args"
 391     \fBnext\fR x {*}$args y
 392     \fBnext\fR
 393 }
 394 obj example 1 2 3
 395 .CE
 396 .PP
 397 prints the following:
 398 .PP
 399 .CS
 400 per-object method, args = 1 2 3
 401 before chaining from subclass, args = x 1 2 3 y
 402 in the superclass, args = a x 1 2 3 y b
 403 in the superclass, args = pureSynthesis
 404 after chaining from subclass
 405 before chaining from subclass, args =
 406 in the superclass, args = a b
 407 in the superclass, args = pureSynthesis
 408 after chaining from subclass
 409 .CE
 410 .PP
 411 This example demonstrates how to build a simple cache class that applies
 412 memoization to all the method calls of the objects it is mixed into, and shows
 413 how it can make a difference to computation times:
 414 .PP
 415 .CS
 416 oo::class create cache {
 417     filter Memoize
 418     method Memoize args {
 419         \fI# Do not filter the core method implementations\fR
 420         if {[lindex [self target] 0] eq "::oo::object"} {
 421             return [\fBnext\fR {*}$args]
 422         }
 423
 424         \fI# Check if the value is already in the cache\fR
 425         my variable ValueCache
 426         set key [self target],$args
 427         if {[info exist ValueCache($key)]} {
 428             return $ValueCache($key)
 429         }
 430
 431         \fI# Compute value, insert into cache, and return it\fR
 432         return [set ValueCache($key) [\fBnext\fR {*}$args]]
 433     }
 434     method flushCache {} {
 435         my variable ValueCache
 436         unset ValueCache
 437         \fI# Skip the caching\fR
 438         return -level 2 ""
 439     }
 440 }
 441
 442 oo::object create demo
 443 oo::define demo {
 444     mixin cache
 445     method compute {a b c} {
 446         after 3000 \fI;# Simulate deep thought\fR
 447         return [expr {$a + $b * $c}]
 448     }
 449     method compute2 {a b c} {
 450         after 3000 \fI;# Simulate deep thought\fR
 451         return [expr {$a * $b + $c}]
 452     }
 453 }
 454
 455 puts [demo compute  1 2 3]      \fI\(-> prints "7" after delay\fR
 456 puts [demo compute2 4 5 6]      \fI\(-> prints "26" after delay\fR
 457 puts [demo compute  1 2 3]      \fI\(-> prints "7" instantly\fR
 458 puts [demo compute2 4 5 6]      \fI\(-> prints "26" instantly\fR
 459 puts [demo compute  4 5 6]      \fI\(-> prints "34" after delay\fR
 460 puts [demo compute  4 5 6]      \fI\(-> prints "34" instantly\fR
 461 puts [demo compute  1 2 3]      \fI\(-> prints "7" instantly\fR
 462 demo flushCache
 463 puts [demo compute  1 2 3]      \fI\(-> prints "7" after delay\fR
 464 .CE
 465 .SH "SEE ALSO"
 466 oo::class(n), oo::define(n), oo::object(n), self(n)
 467 .SH KEYWORDS
 468 call, method, method chain
 469 .\" Local variables:
 470 .\" mode: nroff
 471 .\" fill-column: 78
 472 .\" End: