diff options
Diffstat (limited to 'doc/link.n')
-rw-r--r-- | doc/link.n | 124 |
1 files changed, 124 insertions, 0 deletions
diff --git a/doc/link.n b/doc/link.n new file mode 100644 index 0000000..e06be33 --- /dev/null +++ b/doc/link.n @@ -0,0 +1,124 @@ +'\" +'\" Copyright (c) 2011-2015 Andreas Kupries +'\" Copyright (c) 2018 Donal K. Fellows +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH link n 0.3 TclOO "TclOO Commands" +.so man.macros +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +link \- create link from command to method of object +.SH SYNOPSIS +.nf +package require tcl::oo + +\fBlink\fR \fImethodName\fR ?\fI...\fR? +\fBlink\fR \fB{\fIcommandName methodName\fB}\fR ?\fI...\fR? +.fi +.BE +.SH DESCRIPTION +The \fBlink\fR command is available within methods. It takes a series of one +or more method names (\fImethodName ...\fR) and/or pairs of command- and +method-name (\fB{\fIcommandName methodName\fB}\fR) and makes the named methods +available as commands without requiring the explicit use of the name of the +object or the \fBmy\fR command. The method does not need to exist at the time +that the link is made; if the link command is invoked when the method does not +exist, the standard \fBunknown\fR method handling system is used. +.PP +The command name under which the method becomes available defaults to the +method name, except where explicitly specified through an alias/method pair. +Formally, every argument must be a list; if the list has two elements, the +first element is the name of the command to create and the second element is +the name of the method of the current object to which the command links; +otherwise, the name of the command and the name of the method are the same +string (the first element of the list). +.PP +If the name of the command is not a fully-qualified command name, it will be +resolved with respect to the current namespace (i.e., the object namespace). +.SH EXAMPLES +This demonstrates linking a single method in various ways. First it makes a +simple link, then a renamed link, then an external link. Note that the method +itself is unexported, but that it can still be called directly from outside +the class. +.PP +.CS +oo::class create ABC { + method Foo {} { + puts "This is Foo in [self]" + } + + constructor {} { + \fBlink\fR Foo + # The method foo is now directly accessible as foo here + \fBlink\fR {bar Foo} + # The method foo is now directly accessible as bar + \fBlink\fR {::ExternalCall Foo} + # The method foo is now directly accessible in the global + # namespace as ExternalCall + } + + method grill {} { + puts "Step 1:" + Foo + puts "Step 2:" + bar + } +} + +ABC create abc +abc grill + \fI\(-> Step 1:\fR + \fI\(-> This is foo in ::abc\fR + \fI\(-> Step 2:\fR + \fI\(-> This is foo in ::abc\fR +# Direct access via the linked command +puts "Step 3:"; ExternalCall + \fI\(-> Step 3:\fR + \fI\(-> This is foo in ::abc\fR +.CE +.PP +This example shows that multiple linked commands can be made in a call to +\fBlink\fR, and that they can handle arguments. +.PP +.CS +oo::class create Ex { + constructor {} { + \fBlink\fR a b c + # The methods a, b, and c (defined below) are all now + # directly acessible within methods under their own names. + } + + method a {} { + puts "This is a" + } + method b {x} { + puts "This is b($x)" + } + method c {y z} { + puts "This is c($y,$z)" + } + + method call {p q r} { + a + b $p + c $q $r + } +} + +set o [Ex new] +$o 3 5 7 + \fI\(-> This is a\fR + \fI\(-> This is b(3)\fR + \fI\(-> This is c(5,7)\fR +.CE +.SH "SEE ALSO" +interp(n), my(n), oo::class(n), oo::define(n) +.SH KEYWORDS +command, method, object +.\" Local Variables: +.\" mode: nroff +.\" fill-column: 78 +.\" End: |