nsf

Clone
Stefan Sobernig <stefan.sobernig@wu.ac.at>
committed
4276fbd
on 08 Apr 16
Fix doc on introspection for configure options
2-1-0-rc + 44 more
doc/Object.3 (+6 -18)
450 450 resulting method registers a pre-existing Tcl command \fIcmdName\fR
451 451 under the (alias) name \fImethodName\fR with the object\&. If \fIcmdName\fR refers
452 452 to another \fBmethod\fR, the corresponding argument
453 453 should be a valid method handle\&. If a Tcl command (e\&.g\&., a
454 454 \fBproc\fR), the argument should be a fully qualified Tcl command
455 455 name\&. If aliasing a subcommand (e\&.g\&., \fBarray exists\fR) of a Tcl namespace ensemble (e\&.g\&., \fBarray\fR), \fIcmdName\fR must hold the fully qualified subcommand name (and not the ensemble name of the subcommand)\&.
456 456 .sp
457 457 As for a regular \fBobject method\fR, \fB-returns\fR
458 458 allows for setting a value checker on the values returned by
459 459 the aliased command \fIcmdName\fR\&.
460 460 .sp
461 461 When creating an alias method for
462 462 a \fIC-implemented\fR Tcl command (i\&.e\&., command defined using the
463 463 Tcl/NX C-API), \fB-frame\fR sets the scope
464 464 for variable references used in the aliased command\&. If the provided
465 465 value is \fBobject\fR, then variable references will be resolved in the
466 466 context of the called object, i\&.e\&., the object upon which the alias method is invoked, as if they were object variables\&. There is no need for using
467 467 the colon-prefix notation for identifying object variables\&. If the
468 468 value is \fBmethod\fR, 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 \fB::nx::self\fR\&. In addition, the alias method has access to the method-call context (e\&.g\&., \fBnx::next\fR)\&. If \fB-frame\fR is omitted, and by default, the variable references will resolve in the context of the caller of the alias method\&.
469 469 .sp
470   To express deprecation of the alias method \fImethodName\fR, set the \fB-deprecated\fR flag\&. Deprecated methods remain usable from client code, but their usage will be signaled to the developer and/or can be tracked using \fB::nsf::deprecated\fR\&. To register \fImethodName\fR with the debugger, set the \fB-debug\fR flag\&. Entering and exiting a method flagged for debugging can be recorded using \fB::nsf::log\fR\&.
  470 To express deprecation of the alias method \fImethodName\fR, set the \fB-deprecated\fR flag\&. Deprecated methods remain usable from client code, but their usage will be signaled to the developer and/or can be tracked using \fB::nsf::deprecated\fR\&. To register \fImethodName\fR with the debugger, set the \fB-debug\fR flag\&.  Entering and exiting a method, which was flagged for debugging, is recorded by calling the redefinable callback procs \fB::nsf::debug::call\fR and \fB::nsf::debug::exit\fR, respectively\&. By default, these callbacks forward to \fB::nsf:log\fR, which can also be customized at the script level\&.
471 471 .RE
472 472 .TP
473 473 \fBcget\fR
474 474 .RS
475 475 .TP
476 476 \fIobj\fR \fBcget\fR \fIconfigurationOption\fR
477 477 The method is used to obtain the current value of \fIconfigurationOption\fR for
478 478 \fIobj\fR\&. The configuration options
479 479 available for querying through \fBcget\fR are determined by the
480 480 configurable properties defined by the class hierarchy of \fIobj\fR\&. The
481 481 queriable configuration options for \fIobj\fR can be
482   obtained by calling \fBinfo configure\fR\&. The \fIconfigurationOption\fR can
  482 obtained by calling \fBinfo lookup syntax configure\fR\&. The \fIconfigurationOption\fR can
483 483 be set and modified using \fBconfigure\fR\&.
484 484 .CS
485 485
486 486
487 487 % nx::Object create obj
488 488 ::obj
489   % ::obj info configure
  489 % ::obj info lookup syntax configure
490 490 ?-object-mixins /mixinreg \&.\&.\&./? ?-class /class/? ?-object-filters /filterreg \&.\&.\&./? ?/__initblock/?
491 491 % ::obj cget -class
492 492 ::nx::Object
493 493
494 494 .CE
495 495 .RE
496 496 .TP
497 497 \fBconfigure\fR
498 498 .RS
499 499 .TP
500 500 \fIobj\fR \fBconfigure\fR ?\fIconfigurationOption\fR \fIvalue\fR \&.\&.\&.?
501 501 This method sets configuration options on an object\&. The configuration
502 502 options available for setting on \fIobj\fR are determined by the
503 503 configurable properties defined by the class hierarchy of \fIobj\fR\&. The
504 504 settable configuration options for \fIobj\fR can be
505   obtained by calling \fBinfo configure\fR\&. Furthermore, \fBconfigure\fR is
  505 obtained by calling \fBinfo lookup syntax configure\fR\&. Furthermore, \fBconfigure\fR is
506 506 also called during object construction\&. Under object construction, it receives
507 507 the arguments passed into calls of \fBcreate\fR and \fBnew\fR\&. Options
508 508 set using \fBconfigure\fR can be retrieved using \fBcget\fR\&.
509 509 .CS
510 510
511 511
512 512 % nx::Class create Foo {:property x}
513 513 ::Foo
514 514 % Foo create f1 -x 101
515 515 ::f1
516 516 % f1 cget -x
517 517 101
518 518 % f1 configure -x 200
519 519 % f1 cget -x
520 520 200
521 521
522 522 .CE
523 523 .RE
524 524 .TP
525 525 \fBcontains\fR
 
782 782 arguments are evaluated as a Tcl command call\&. That is, if present, \fItarget\fR
783 783 is interpreted as a Tcl command (e\&.g\&., a Tcl \fBproc\fR or an object)
784 784 and the remainder of the forwarder arguments \fIarg\fR as arguments passed into
785 785 this command\&. The actual method arguments to the invocation of the
786 786 forward method itself are appended to the list of forwarder
787 787 arguments\&.
788 788 If \fItarget\fR is omitted, the value of \fImethodName\fR is
789 789 implicitly set and used as \fItarget\fR\&. This way, when providing a
790 790 fully-qualified Tcl command name as \fImethodName\fR without \fItarget\fR, the
791 791 unqualified \fImethodName\fR (\fBnamespace tail\fR) is used as the
792 792 forwarder name; while the fully-qualified one serves as the \fItarget\fR\&.
793 793 .sp
794 794 As for a regular \fBobject method\fR, \fB-returns\fR allows
795 795 for setting a value checker on the values returned by the
796 796 resulting Tcl command call\&. When passing \fBobject\fR to \fB-frame\fR, the
797 797 resulting Tcl command is evaluated in the context of the object
798 798 receiving the forward method call\&. This way, variable names
799 799 used in the resulting execution of a command become resolved as
800 800 object variables\&.
801 801 .sp
802   To express deprecation of the forward method \fImethodName\fR, set the \fB-deprecated\fR flag\&. Deprecated methods remain usable from client code, but their usage will be signaled to the developer and/or can be tracked using \fB::nsf::deprecated\fR\&. To register \fImethodName\fR with the debugger, set the \fB-debug\fR flag\&. Entering and exiting a method flagged for debugging can be recorded using \fB::nsf::log\fR\&.
  802 To express deprecation of the forward method \fImethodName\fR, set the \fB-deprecated\fR flag\&. Deprecated methods remain usable from client code, but their usage will be signaled to the developer and/or can be tracked using \fB::nsf::deprecated\fR\&. To register \fImethodName\fR with the debugger, set the \fB-debug\fR flag\&.  Entering and exiting a method, which was flagged for debugging, is recorded by calling the redefinable callback procs \fB::nsf::debug::call\fR and \fB::nsf::debug::exit\fR, respectively\&. By default, these callbacks forward to \fB::nsf:log\fR, which can also be customized at the script level\&.
803 803 .sp
804 804 The list of forwarder arguments \fIarg\fR can contain as its elements
805 805 a mix of literal values and placeholders\&. Placeholders are prefixed
806 806 with a percent symbol (%) and substituted for concrete values upon
807 807 calling the forward method\&. These placeholders allow for
808 808 constructing and for manipulating the arguments to be passed into the
809 809 resulting command call on the fly:
810 810 .RS
811 811 .IP \(bu
812 812 \fB%method\fR becomes substituted for the name of the forward method, i\&.e\&. \fImethodName\fR\&.
813 813 .IP \(bu
814 814 \fB%self\fR becomes substituted for the name of the object receiving the call of the forward method\&.
815 815 .IP \(bu
816 816 \fB%1\fR becomes substituted for the first method argument passed to the call of forward method\&. This requires, in turn, that \fIat least\fR one argument is passed along with the method call\&.
817 817 .sp
818 818 Alternatively, \fB%1\fR accepts an optional argument \fIdefaults\fR: {\fB%1\fR \fIdefaults\fR}\&.
819 819 \fIdefaults\fR must be a valid Tcl list of two elements\&. For the first
820 820 element, \fB%1\fR is substituted when there is no first method
821 821 argument which can be consumed by \fB%1\fR\&. The second element is
822 822 inserted upon availability of a first method argument with the
 
897 897 Verifies whether \fIobj\fR has a given \fBnx::Class\fR \fIclassName\fR registered as a mixin class (returns: \fBtrue\fR) or not (returns: \fBfalse\fR)\&.
898 898 .TP
899 899 \fIobj\fR \fBinfo has namespace\fR
900 900 Checks whether the object has a companion Tcl namespace (returns:
901 901 \fBtrue\fR) or not (returns: \fBfalse\fR)\&. The namespace could
902 902 have been created using, for example, \fBobject require namespace\fR\&.
903 903 .TP
904 904 \fIobj\fR \fBinfo has type\fR \fIclassName\fR
905 905 Tests whether the \fBnx::Class\fR \fIclassName\fR is a type of the
906 906 object (returns: \fBtrue\fR) or not (returns: \fBfalse\fR)\&. That
907 907 is, the method checks whether the object is a direct instance of \fIclassName\fR or
908 908 an indirect instance of one of the superclasses of \fIclassName\fR\&.
909 909 .RE
910 910 .TP
911 911 \fIobj\fR \fBinfo lookup\fR \fIsubmethod\fR ?\fIarg\fR \&.\&.\&.?
912 912 A collection of submethods to retrieve structural features (e\&.g\&.
913 913 configuration options, slot objects) and behavioral
914 914 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\&.
915 915 .RS
916 916 .TP
917   \fIobj\fR \fBinfo lookup configure parameters\fR ?\fInamePattern\fR?
918   Returns all configuration options available for \fIobj\fR as a list of
919   method-parameter definitions\&. They can be used, for example, to
920   define a custom method refinement for \fBconfigure\fR\&. The returned
921   configuration options can be limited to those whose names match \fIpattern\fR
922   (see \fBstring match\fR)\&.
923   .TP
924   \fIobj\fR \fBinfo lookup configure syntax\fR
925   Returns all configuration options available for \fIobj\fR as a
926   concrete-syntax description to be used in human-understandable
927   messages (e\&.g\&. errors or warnings, documentation strings)\&.
928   .TP
929 917 \fIobj\fR \fBinfo lookup filter\fR \fIname\fR
930 918 Returns the method handle for the filter method \fIname\fR, if
931 919 currently registered\&. If there is no filter \fIname\fR registered, an
932 920 empty string is returned\&.
933 921 .TP
934 922 \fIobj\fR \fBinfo lookup filters\fR ?\fB-guards\fR? ?\fInamePattern\fR?
935 923 Returns the method handles of all filters which are active on \fIobj\fR\&. By
936 924 turning on the switch \fB-guards\fR, the corresponding guard
937 925 expressions, if any, are also reported for each filter as a three-element list: \fImethodHandle\fR -guard \fIguardExpr\fR\&. The returned filters can be limited to
938 926 those whose names match \fInamePattern\fR (see \fBstring match\fR)\&.
939 927 .TP
940 928 \fIobj\fR \fBinfo lookup method\fR \fIname\fR
941 929 Returns the method handle for a method \fIname\fR if a
942 930 so-named method can be invoked on \fIobj\fR\&. If there is no method
943 931 \fIname\fR, an empty string is returned\&.
944 932 .TP
945 933 \fIobj\fR \fBinfo lookup methods\fR ?\fInamePattern\fR?
946 934 Returns the names of all methods (including aliases and forwarders)
947 935 which can be invoked on \fIobj\fR\&. The returned methods can be limited
948 936 to those whose names match \fInamePattern\fR (see \fBstring match\fR)\&.
 
1137 1125 the method \fIparameters\fR and a method \fIbody\fR\&.
1138 1126 .sp
1139 1127 \fIparameters\fR accepts a Tcl \fBlist\fR containing an arbitrary
1140 1128 number of non-positional and positional parameter definitions\&. Each parameter
1141 1129 definition comprises a parameter name, a parameter-specific value checker, and
1142 1130 parameter options\&.
1143 1131 .sp
1144 1132 The \fIbody\fR contains the method implementation as a script
1145 1133 block\&. In this body script, the colon-prefix notation is available to
1146 1134 denote an object variable and a self call\&. In addition, the
1147 1135 context of the object receiving the method call (i\&.e\&., the message)
1148 1136 can be accessed (e\&.g\&., using \fBnx::self\fR) and the call stack can be
1149 1137 introspected (e\&.g\&., using \fBnx::current\fR)\&.
1150 1138 .sp
1151 1139 Optionally, \fB-returns\fR allows for setting a value checker on
1152 1140 values returned by the method implementation\&. By setting
1153 1141 the switch \fB-checkalways\fR, value checking on
1154 1142 arguments and return value is guaranteed to be performed, even if
1155 1143 value checking is temporarily disabled; see \fBnx::configure\fR)\&.
1156 1144 .sp
1157   To express deprecation of the method \fIname\fR, set the \fB-deprecated\fR flag\&. Deprecated methods remain usable from client code, but their usage will be signaled to the developer and/or can be tracked using \fB::nsf::deprecated\fR\&. To register \fIname\fR with the debugger, set the \fB-debug\fR flag\&. Entering and exiting a method flagged for debugging can be recorded using \fB::nsf::log\fR\&.
  1145 To express deprecation of the method \fIname\fR, set the \fB-deprecated\fR flag\&. Deprecated methods remain usable from client code, but their usage will be signaled to the developer and/or can be tracked using \fB::nsf::deprecated\fR\&. To register \fIname\fR with the debugger, set the \fB-debug\fR flag\&. Entering and exiting a method, which was flagged for debugging, is recorded by calling the redefinable callback procs \fB::nsf::debug::call\fR and \fB::nsf::debug::exit\fR, respectively\&. By default, these callbacks forward to \fB::nsf:log\fR, which can also be customized at the script level\&.
1158 1146 .sp
1159 1147 A method closely resembles a Tcl \fBproc\fR, but it differs in some
1160 1148 important aspects: First, a method can define non-positional
1161 1149 parameters and value checkers on arguments\&. Second, the script
1162 1150 implementing the method body can contain object-specific notation and
1163 1151 commands (see above)\&. Third, method calls \fIcannot\fR be intercepted
1164 1152 using Tcl \fBtrace\fR\&. Note that an existing Tcl \fBproc\fR can be
1165 1153 registered as an alias method with the object (see
1166 1154 \fBobject alias\fR)\&.
1167 1155 .RE
1168 1156 .TP
1169 1157 \fBmove\fR
1170 1158 .RS
1171 1159 .TP
1172 1160 \fIobj\fR \fBmove\fR \fInewObjectName\fR
1173 1161 Effectively renames an object\&. First, the source object \fIobj\fR is
1174 1162 cloned into a target object \fInewObjectName\fR using \fBcopy\fR\&. Second,
1175 1163 the source object \fIobj\fR is destroyed by invoking \fBdestroy\fR\&.
1176 1164 \fBmove\fR is also called internally when \fBrename\fR is
1177 1165 performed for a Tcl command representing an object\&.