util/X86LINUX64/man/man3/Tcl_MethodIsPublic.3

   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 Tcl_Method 3 0.1 TclOO "TclOO Library Functions"
   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 Tcl_ClassSetConstructor, Tcl_ClassSetDestructor, Tcl_MethodDeclarerClass, Tcl_MethodDeclarerObject, Tcl_MethodIsPublic, Tcl_MethodIsType, Tcl_MethodName, Tcl_NewInstanceMethod, Tcl_NewMethod, Tcl_ObjectContextInvokeNext, Tcl_ObjectContextIsFiltering, Tcl_ObjectContextMethod, Tcl_ObjectContextObject, Tcl_ObjectContextSkippedArgs \- manipulate methods and method-call contexts
 279 .SH SYNOPSIS
 280 .nf
 281 \fB#include <tclOO.h>\fR
 282 .sp
 283 Tcl_Method
 284 \fBTcl_NewMethod\fR(\fIinterp, class, nameObj, isPublic,
 285               methodTypePtr, clientData\fR)
 286 .sp
 287 Tcl_Method
 288 \fBTcl_NewInstanceMethod\fR(\fIinterp, object, nameObj, isPublic,
 289                       methodTypePtr, clientData\fR)
 290 .sp
 291 \fBTcl_ClassSetConstructor\fR(\fIinterp, class, method\fR)
 292 .sp
 293 \fBTcl_ClassSetDestructor\fR(\fIinterp, class, method\fR)
 294 .sp
 295 Tcl_Class
 296 \fBTcl_MethodDeclarerClass\fR(\fImethod\fR)
 297 .sp
 298 Tcl_Object
 299 \fBTcl_MethodDeclarerObject\fR(\fImethod\fR)
 300 .sp
 301 Tcl_Obj *
 302 \fBTcl_MethodName\fR(\fImethod\fR)
 303 .sp
 304 int
 305 \fBTcl_MethodIsPublic\fR(\fImethod\fR)
 306 .sp
 307 int
 308 \fBTcl_MethodIsType\fR(\fImethod, methodTypePtr, clientDataPtr\fR)
 309 .sp
 310 int
 311 \fBTcl_ObjectContextInvokeNext\fR(\fIinterp, context, objc, objv, skip\fR)
 312 .sp
 313 int
 314 \fBTcl_ObjectContextIsFiltering\fR(\fIcontext\fR)
 315 .sp
 316 Tcl_Method
 317 \fBTcl_ObjectContextMethod\fR(\fIcontext\fR)
 318 .sp
 319 Tcl_Object
 320 \fBTcl_ObjectContextObject\fR(\fIcontext\fR)
 321 .sp
 322 int
 323 \fBTcl_ObjectContextSkippedArgs\fR(\fIcontext\fR)
 324 .SH ARGUMENTS
 325 .AS ClientData clientData in
 326 .AP Tcl_Interp *interp in/out
 327 The interpreter holding the object or class to create or update a method in.
 328 .AP Tcl_Object object in
 329 The object to create the method in.
 330 .AP Tcl_Class class in
 331 The class to create the method in.
 332 .AP Tcl_Obj *nameObj in
 333 The name of the method to create. Should not be NULL unless creating
 334 constructors or destructors.
 335 .AP int isPublic in
 336 A boolean flag saying whether the method is to be exported.
 337 .AP Tcl_MethodType *methodTypePtr in
 338 A description of the type of the method to create, or the type of method to
 339 compare against.
 340 .AP ClientData clientData in
 341 A piece of data that is passed to the implementation of the method without
 342 interpretation.
 343 .AP ClientData *clientDataPtr out
 344 A pointer to a variable in which to write the \fIclientData\fR value supplied
 345 when the method was created. If NULL, the \fIclientData\fR value will not be
 346 retrieved.
 347 .AP Tcl_Method method in
 348 A reference to a method to query.
 349 .AP Tcl_ObjectContext context in
 350 A reference to a method-call context. Note that client code \fImust not\fR
 351 retain a reference to a context.
 352 .AP int objc in
 353 The number of arguments to pass to the method implementation.
 354 .AP "Tcl_Obj *const" *objv in
 355 An array of arguments to pass to the method implementation.
 356 .AP int skip in
 357 The number of arguments passed to the method implementation that do not
 358 represent "real" arguments.
 359 .BE
 360 .SH DESCRIPTION
 361 .PP
 362 A method is an operation carried out on an object that is associated with the
 363 object. Every method must be attached to either an object or a class; methods
 364 attached to a class are associated with all instances (direct and indirect) of
 365 that class.
 366 .PP
 367 Given a method, the entity that declared it can be found using
 368 \fBTcl_MethodDeclarerClass\fR which returns the class that the method is
 369 attached to (or NULL if the method is not attached to any class) and
 370 \fBTcl_MethodDeclarerObject\fR which returns the object that the method is
 371 attached to (or NULL if the method is not attached to an object). The name of
 372 the method can be retrieved with \fBTcl_MethodName\fR and whether the method
 373 is exported is retrieved with \fBTcl_MethodIsPublic\fR. The type of the method
 374 can also be introspected upon to a limited degree; the function
 375 \fBTcl_MethodIsType\fR returns whether a method is of a particular type,
 376 assigning the per-method \fIclientData\fR to the variable pointed to by
 377 \fIclientDataPtr\fR if (that is non-NULL) if the type is matched.
 378 .SS "METHOD CREATION"
 379 .PP
 380 Methods are created by \fBTcl_NewMethod\fR and \fBTcl_NewInstanceMethod\fR,
 381 which
 382 create a method attached to a class or an object respectively. In both cases,
 383 the \fInameObj\fR argument gives the name of the method to create, the
 384 \fIisPublic\fR argument states whether the method should be exported
 385 initially, the \fImethodTypePtr\fR argument describes the implementation of
 386 the method (see the \fBMETHOD TYPES\fR section below) and the \fIclientData\fR
 387 argument gives some implementation-specific data that is passed on to the
 388 implementation of the method when it is called.
 389 .PP
 390 When the \fInameObj\fR argument to \fBTcl_NewMethod\fR is NULL, an
 391 unnamed method is created, which is used for constructors and destructors.
 392 Constructors should be installed into their class using the
 393 \fBTcl_ClassSetConstructor\fR function, and destructors (which must not
 394 require any arguments) should be installed into their class using the
 395 \fBTcl_ClassSetDestructor\fR function. Unnamed methods should not be used for
 396 any other purpose, and named methods should not be used as either constructors
 397 or destructors. Also note that a NULL \fImethodTypePtr\fR is used to provide
 398 internal signaling, and should not be used in client code.
 399 .SS "METHOD CALL CONTEXTS"
 400 .PP
 401 When a method is called, a method-call context reference is passed in as one
 402 of the arguments to the implementation function. This context can be inspected
 403 to provide information about the caller, but should not be retained beyond the
 404 moment when the method call terminates.
 405 .PP
 406 The method that is being called can be retrieved from the context by using
 407 \fBTcl_ObjectContextMethod\fR, and the object that caused the method to be
 408 invoked can be retrieved with \fBTcl_ObjectContextObject\fR. The number of
 409 arguments that are to be skipped (e.g. the object name and method name in a
 410 normal method call) is read with \fBTcl_ObjectContextSkippedArgs\fR, and the
 411 context can also report whether it is working as a filter for another method
 412 through \fBTcl_ObjectContextIsFiltering\fR.
 413 .PP
 414 During the execution of a method, the method implementation may choose to
 415 invoke the stages of the method call chain that come after the current method
 416 implementation. This (the core of the \fBnext\fR command) is done using
 417 \fBTcl_ObjectContextInvokeNext\fR. Note that this function does not manipulate
 418 the call-frame stack, unlike the \fBnext\fR command; if the method
 419 implementation has pushed one or more extra frames on the stack as part of its
 420 implementation, it is also responsible for temporarily popping those frames
 421 from the stack while the \fBTcl_ObjectContextInvokeNext\fR function is
 422 executing. Note also that the method-call context is \fInever\fR deleted
 423 during the execution of this function.
 424 .SH "METHOD TYPES"
 425 .PP
 426 The types of methods are described by a pointer to a Tcl_MethodType structure,
 427 which is defined as:
 428 .PP
 429 .CS
 430 typedef struct {
 431     int \fIversion\fR;
 432     const char *\fIname\fR;
 433     Tcl_MethodCallProc *\fIcallProc\fR;
 434     Tcl_MethodDeleteProc *\fIdeleteProc\fR;
 435     Tcl_CloneProc *\fIcloneProc\fR;
 436 } \fBTcl_MethodType\fR;
 437 .CE
 438 .PP
 439 The \fIversion\fR field allows for future expansion of the structure, and
 440 should always be declared equal to TCL_OO_METHOD_VERSION_CURRENT. The
 441 \fIname\fR field provides a human-readable name for the type, and is the value
 442 that is exposed via the \fBinfo class methodtype\fR and
 443 \fBinfo object methodtype\fR Tcl commands.
 444 .PP
 445 The \fIcallProc\fR field gives a function that is called when the method is
 446 invoked; it must never be NULL.
 447 .PP
 448 The \fIdeleteProc\fR field gives a function that is used to delete a
 449 particular method, and is called when the method is replaced or removed; if
 450 the field is NULL, it is assumed that the method's \fIclientData\fR needs no
 451 special action to delete.
 452 .PP
 453 The \fIcloneProc\fR field is either a function that is used to copy a method's
 454 \fIclientData\fR (as part of \fBTcl_CopyObjectInstance\fR) or NULL to indicate
 455 that the \fIclientData\fR can just be copied directly.
 456 .SS "TCL_METHODCALLPROC FUNCTION SIGNATURE"
 457 .PP
 458 Functions matching this signature are called when the method is invoked.
 459 .PP
 460 .CS
 461 typedef int \fBTcl_MethodCallProc\fR(
 462         ClientData \fIclientData\fR,
 463         Tcl_Interp *\fIinterp\fR,
 464         Tcl_ObjectContext \fIobjectContext\fR,
 465         int \fIobjc\fR,
 466         Tcl_Obj *const *\fIobjv\fR);
 467 .CE
 468 .PP
 469 The \fIclientData\fR argument to a Tcl_MethodCallProc is the value that was
 470 given when the method was created, the \fIinterp\fR is a place in which to
 471 execute scripts and access variables as well as being where to put the result
 472 of the method, and the \fIobjc\fR and \fIobjv\fR fields give the parameter
 473 objects to the method. The calling context of the method can be discovered
 474 through the \fIobjectContext\fR argument, and the return value from a
 475 Tcl_MethodCallProc is any Tcl return code (e.g. TCL_OK, TCL_ERROR).
 476 .SS "TCL_METHODDELETEPROC FUNCTION SIGNATURE"
 477 .PP
 478 Functions matching this signature are used when a method is deleted, whether
 479 through a new method being created or because the object or class is deleted.
 480 .PP
 481 .CS
 482 typedef void \fBTcl_MethodDeleteProc\fR(
 483         ClientData \fIclientData\fR);
 484 .CE
 485 .PP
 486 The \fIclientData\fR argument to a Tcl_MethodDeleteProc will be the same as
 487 the value passed to the \fIclientData\fR argument to \fBTcl_NewMethod\fR or
 488 \fBTcl_NewInstanceMethod\fR when the method was created.
 489 .SS "TCL_CLONEPROC FUNCTION SIGNATURE"
 490 .PP
 491 Functions matching this signature are used to copy a method when the object or
 492 class is copied using \fBTcl_CopyObjectInstance\fR (or \fBoo::copy\fR).
 493 .PP
 494 .CS
 495 typedef int \fBTcl_CloneProc\fR(
 496         Tcl_Interp *\fIinterp\fR,
 497         ClientData \fIoldClientData\fR,
 498         ClientData *\fInewClientDataPtr\fR);
 499 .CE
 500 .PP
 501 The \fIinterp\fR argument gives a place to write an error message when the
 502 attempt to clone the object is to fail, in which case the clone procedure must
 503 also return TCL_ERROR; it should return TCL_OK otherwise.
 504 The \fIoldClientData\fR field to a Tcl_CloneProc gives the value from the
 505 method being copied from, and the \fInewClientDataPtr\fR field will point to
 506 a variable in which to write the value for the method being copied to.
 507 .SH "SEE ALSO"
 508 Class(3), oo::class(n), oo::define(n), oo::object(n)
 509 .SH KEYWORDS
 510 constructor, method, object
 511
 512 .\" Local variables:
 513 .\" mode: nroff
 514 .\" fill-column: 78
 515 .\" End: