/interpreter/tags/at2dist091109/src/edu/vub/at/objects/ATMirrorRoot.java
Java | 784 lines | 45 code | 42 blank | 697 comment | 0 complexity | 2ffceb89072cbcbc7810c92aadb85bef MD5 | raw file
1/** 2 * AmbientTalk/2 Project 3 * JavaInterfaceAdaptor.java created on Jul 13, 2006 at 10:25:01 PM 4 * (c) Programming Technology Lab, 2006 - 2007 5 * Authors: Tom Van Cutsem & Stijn Mostinckx 6 * 7 * Permission is hereby granted, free of charge, to any person 8 * obtaining a copy of this software and associated documentation 9 * files (the "Software"), to deal in the Software without 10 * restriction, including without limitation the rights to use, 11 * copy, modify, merge, publish, distribute, sublicense, and/or 12 * sell copies of the Software, and to permit persons to whom the 13 * Software is furnished to do so, subject to the following 14 * conditions: 15 * 16 * The above copyright notice and this permission notice shall be 17 * included in all copies or substantial portions of the Software. 18 * 19 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 20 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES 21 * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 22 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT 23 * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, 24 * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 25 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR 26 * OTHER DEALINGS IN THE SOFTWARE. 27 */ 28package edu.vub.at.objects; 29 30import edu.vub.at.actors.ATAsyncMessage; 31import edu.vub.at.exceptions.InterpreterException; 32import edu.vub.at.exceptions.XDuplicateSlot; 33import edu.vub.at.exceptions.XIllegalQuote; 34import edu.vub.at.exceptions.XIllegalUnquote; 35import edu.vub.at.exceptions.XObjectOffline; 36import edu.vub.at.exceptions.XSelectorNotFound; 37import edu.vub.at.exceptions.XUndefinedSlot; 38import edu.vub.at.objects.grammar.ATSymbol; 39import edu.vub.at.objects.mirrors.NATMirage; 40import edu.vub.at.objects.natives.NATText; 41 42/** 43 * This is the interface of the root node of the intercessive mirrors delegation hierarchy. 44 * <p> 45 * Intercessive mirrors are always tied to a particular 'base' object. 46 * The default intercessive mirror is named 'defaultMirror' and is an object 47 * that understands all meta-level operations applicable on objects, implementing them using default semantics. 48 * It can be thought of as being defined as follows: 49 * 50 * <pre> 51 * def mirrorroot := object: { 52 * def base := object: { nil } mirroredBy: self // base of the mirror root is an empty mirage 53 * def init(b) { 54 * base := b 55 * } 56 * def invoke(@args) { <default native invocation behaviour on base> } 57 * def select(@args) { <default native selection behaviour on base> } 58 * ... 59 * } taggedAs: [ Mirror ] 60 * </pre> 61 * <p> 62 * This object can then simply be extended / composed by other objects to deviate from the default semantics. 63 * Note that the default semantics is applied to 'base' and *not* 'self.base', in other words: 64 * although child mirrors can define their own 'base' field, it is not taken into consideration 65 * by the mirror root. This also ensures that the mirror root is not abused to enact upon a mirage 66 * for which it was not assigned to be the mirror. 67 * <p> 68 * Hence, 'mirrors' are simply objects with the same interface as this mirrorroot object: they should be 69 * able to respond to all meta-level messages and have a 'base' field. 70 * 71 * @author tvcutsem, smostinc 72 */ 73public interface ATMirrorRoot extends ATObject { 74 75 /** 76 * The read-only field containing the mirror's base-level mirage. 77 */ 78 public NATMirage base_base() throws InterpreterException; 79 80 /* ------------------------------ 81 * -- Message Sending Protocol -- 82 * ------------------------------ */ 83 84 /** 85 * This behavioural meta-level operation reifies the act of sending 86 * an asynchronous message. 87 * 88 * When the base-level AmbientTalk code <code>rcv<-m()</code> is 89 * evaluated in the context of an object <tt>o</tt>, an asynchronous message 90 * <code><-m()</code> is first created by the current actor mirror. 91 * Subsequently, this message needs to be sent to the receiver. This 92 * meta-level operation is reified by this method, as if by invoking: 93 * <pre>(reflect: o).send(message)</pre> 94 * The default behaviour is to access the current actor's mirror and to 95 * ask the actor to send the message in this object's stead by invoking 96 * <pre>actor.send(message)</pre> 97 * @param receiver the object designated to receive the asynchronous message 98 * @param message the asynchronous message to be sent by this object 99 * 100 * @return the result of message sending, which will be the value of an 101 * asynchronous message send expression. 102 */ 103 public ATObject base_send(ATObject receiver, ATAsyncMessage message) throws InterpreterException; 104 105 /** 106 * This behavioural meta-level operation reifies the act of receiving 107 * an asynchronous message. 108 * 109 * When an asynchronous message is sent to an AmbientTalk object, its mirror 110 * is notified of this event by the invocation of this method. The method 111 * is invoked in the same execution turn as the turn in which the message 112 * is sent. This allows the receiver (e.g. a custom eventual reference proxy) 113 * to intervene in the message sending process and return a value different 114 * than the default <tt>nil</tt> value. 115 * <p> 116 * The default behaviour of a mirror on a local reference in response to 117 * the reception of an async 118 * message is to schedule this message for execution in a later turn 119 * in its owner's message queue. The actor will then later process 120 * the message by invoking 121 * <pre>msg.process(self)</pre> 122 * In turn, the default message processing behaviour is to invoke 123 * the method corresponding to the message's selector on this object. 124 * Hence, usually a <tt>receive</tt> operation is translated into 125 * a <tt>invoke</tt> operation in a later turn. The reason for having a 126 * separate <tt>receive</tt> 127 * operation is that this enables the AmbientTalk meta-level programmer to 128 * distinguish between synchronously and asynchronously received messages. 129 * 130 * Far references react to <tt>receive</tt> by transmitting their message 131 * to their remote target. 132 * 133 * @param message the message that was asynchronously sent to this object 134 * @return <tt>nil</tt>, by default 135 */ 136 public ATObject base_receive(ATAsyncMessage message) throws InterpreterException; 137 138 /** 139 * This meta-level operation reifies synchronous message sending ("method invocation"). 140 * Hence, the meta-level equivalent 141 * of the base-level code <code>o.m()</code> is: 142 * <pre>(reflect: o).invoke(o,`m,[])</pre>. 143 * 144 * Method invocation comprises selector lookup and the application of the value 145 * bound to the selector. Selector lookup first queries an object's local 146 * fields, then the method dictionary: 147 * <ul> 148 * <li>If the selector ends with <tt>:=</tt> and matches a field, the field 149 * is assigned if a unary argument list is specified (i.e. the field is treated 150 * as a mutator method). 151 * <li>Otherwise, if the selector is bound to a field containing 152 * a closure, that closure is applied to the given arguments. 153 * <li>If the field is not bound to a closure, the field value is returned provided no arguments were 154 * specified (i.e. the field is treated like an accessor method). 155 * <li>If the selector is bound to a method, the method is applied. 156 * <li>If the selector is not found, the search continues in the objects <i>dynamic parent</i>. 157 * </ul> 158 * <p> 159 * Note also that the first argument to <tt>invoke</tt> denotes the 160 * so-called "receiver" of the invocation. It is this object to which 161 * the <tt>self</tt> pseudo-variable should be bound during method execution. 162 * 163 * @see #base_doesNotUnderstand(ATSymbol) for what happens if the selector 164 * is not found. 165 * 166 * @param delegate the object to which <tt>self</tt> is bound during execution 167 * of the method 168 * @param invocation an object encapsulating at least the invocation's 169 * <tt>selector</tt> (a {@link ATSymbol}) and <tt>arguments</tt> (a {@link ATTable}). 170 * @return by default, the object returned from the invoked method 171 */ 172 public ATObject base_invoke(ATObject delegate, ATMethodInvocation invocation) throws InterpreterException; 173 174 /** 175 * This meta-level operation reifies "field selection". 176 * In other words, the base-level code 177 * <code>o.m</code> 178 * is interpreted at the meta-level as: 179 * <code>(reflect: o).invokeField(o, `m)</code> 180 * 181 * This meta-level operation is nearly identical to {@link #base_invoke(ATObject, ATMethodInvocation)} with one 182 * important difference. When the selector is bound to a field storing a closure, this meta-level operation 183 * does <b>not</b> auto-apply the closure, but returns the closure instead. 184 * 185 * For all other cases, the following equality holds: 186 * <code>o.m == o.m()</code> 187 * or, at the meta-level: 188 * <code>(reflect: o).invokeField(o, `m) == (reflect: o).invoke(o, MethodInvocation.new(`m, []))</code> 189 * 190 * This effectively means that for client objects, it should not matter whether 191 * a property is implemented as a field or as a pair of accessor/mutator methods. 192 * 193 * @param receiver the base-level object from which the 'field' should be selected. 194 * @param selector a symbol denoting the name of the method, accessor or mutator to be invoked 195 * @return the value of a field, or the return value of a nullary method. 196 */ 197 public ATObject base_invokeField(ATObject receiver, ATSymbol selector) throws InterpreterException; 198 199 /** 200 * This meta-level method is used to determine whether an object has a 201 * field or method corresponding to the given selector, without actually invoking 202 * or selecting any value associated with that selector. 203 * <p> 204 * The lookup process is the same as that for the <tt>invoke</tt> operation (i.e. 205 * not only the object's own fields and methods are searched, but also those of 206 * its dynamic parents). 207 * 208 * @param selector a symbol denoting the name of a field (accessor or mutator) or method 209 * @return a boolean denoting whether the object responds to <tt>o.selector</tt> 210 */ 211 public ATBoolean base_respondsTo(ATSymbol selector) throws InterpreterException; 212 213 /** 214 * This behavioural meta-level operation reifies a failed dynamic method or field lookup. 215 * 216 * When method invocation or field selection fails to find the selector in 217 * the dynamic parent chain of an object, rather than immediately raising an 218 * {@link XSelectorNotFound} exception, the mirror of the original receiver 219 * of the method invocation or field selection is asked to handle failed lookup. 220 * <p> 221 * The default behaviour of <tt>doesNotUnderstand</tt> is to raise an 222 * {@link XSelectorNotFound} exception. 223 * <p> 224 * This method is very reminiscent of Smalltalk's well-known 225 * <tt>doesNotUnderstand:</tt> and of Ruby's <tt>method_missing</tt> methods. 226 * There are, however, two important differences: 227 * <ul> 228 * <li> <tt>doesNotUnderstand</tt> is a <b>meta</b>-level operation in AmbientTalk. 229 * It is an operation defined on mirrors, not on regular objects. 230 * <li> <tt>doesNotUnderstand</tt> in AmbientTalk relates to <i>attribute 231 * selection</i>, not to <i>method invocation</i>. Hence, this operation is 232 * more general in AmbientTalk than in Smalltalk: it intercepts both failed 233 * method invocations as well as failed field selections. Hence, it can be used 234 * to model "virtual" fields. This shows in the interface: this operation 235 * does not consume the actual arguments of a failed method invocation. Moreover, 236 * a closure should be returned which can subsequently be applied for failed invocations. 237 * Failed selections can simply return this closure without application. Hence, arguments 238 * should be consumed by means of currying, e.g. by making <tt>doesNotUnderstand</tt> 239 * return a block which can then take the arguments table as its sole parameter. 240 * </ul> 241 * 242 * @param selector a symbol denoting the name of a method or field that could not be found 243 * @return by default, this operation does not return a value, but raises an exception instead. 244 * @throws edu.vub.at.exceptions.XSelectorNotFound the default reaction to a failed selection 245 */ 246 public ATClosure base_doesNotUnderstand(ATSymbol selector) throws InterpreterException; 247 248 /* ----------------------------- 249 * -- Object Passing protocol -- 250 * ----------------------------- */ 251 252 /** 253 * This behavioural meta-level operation reifies object serialization. 254 * 255 * When an AmbientTalk object crosses actor boundaries, e.g. by means of 256 * parameter passing, as a return value or because it was explicitly 257 * exported, this meta-level operation is invoked on the object's mirror. 258 * <p> 259 * This operation allows objects to specify themselves how they should 260 * be parameter-passed during inter-actor communication. The interpreter 261 * will never pass an object to another actor directly, but instead always 262 * parameter-passes the <i>return value</i> of invoing <tt>pass()</tt> on 263 * the object's mirror. 264 * <p> 265 * Mirrors on by-copy objects implement <tt>pass</tt> as follows: 266 * <pre>def pass() { base }</pre> 267 * Mirrors on by-reference objects implement <tt>pass</tt> by returning 268 * a far reference to their base-level object. 269 * 270 * @return the object to be parameter-passed instead of this object. For objects, 271 * the default is a far reference to themselves. For isolates, the default is 272 * to return themselves. 273 */ 274 public ATObject base_pass() throws InterpreterException; 275 276 /** 277 * This behavioural meta-level operation reifies object deserialization. 278 * 279 * When an AmbientTalk object has just crossed an actor boundary (e.g. 280 * because of inter-actor message sending) this meta-level operation 281 * is invoked on the object's mirror. 282 * <p> 283 * This meta-level operation gives objects a chance to tell the interpreter 284 * which object they actually represent, because the object retained 285 * after parameter passing is the return value of the <tt>resolve</tt> 286 * operation. 287 * <p> 288 * Mirrors on by-copy objects, like isolates, implement <tt>resolve</tt> as follows: 289 * <pre>def resolve() { base }</pre> 290 * In other words, by-copy objects represent themselves. By-reference objects 291 * are paremeter passed as far references. Mirrors on far references implement 292 * <tt>resolve</tt> by trying to resolve the far reference into a local, regular 293 * object reference (which is possible if the object they point to is located 294 * in the actor in which they just arrived). If it is not possible to resolve 295 * a far reference into a local object, the far reference remains a far reference. 296 * <p> 297 * Note that for isolates, this operation also ensures that the isolate's 298 * lexical scope is rebound to the lexical root of the recipient actor. 299 * 300 * @return the object represented by this object 301 * @throws XObjectOffline if a far reference to a local object can no longer be resolved 302 * because the object has been taken offline 303 */ 304 public ATObject base_resolve() throws InterpreterException; 305 306 /* ------------------------------------------ 307 * -- Slot accessing and mutating protocol -- 308 * ------------------------------------------ */ 309 310 /** 311 * This meta-level operation reifies first-class field or method selection. Hence, the 312 * base-level evaluation of <code>o.&x</code> is interpreted at the meta-level as: 313 * <pre>(reflect: o).select(o, `x)</pre> 314 * 315 * The selector lookup follows the same search rules as those for <tt>invoke</tt>. 316 * That is: first an object's local fields and method dictionary are searched, 317 * and only then the object's <i>dynamic parent</i>. 318 * <p> 319 * The <tt>select</tt> operation can be used to both select fields or methods from 320 * an object. When the selector is bound to a method, the return value of 321 * <tt>select</tt> is a closure that wraps the found method in the object in which 322 * the method was found. This ensures that the method retains its context information, 323 * such as the lexical scope in which it was defined and the value of <tt>self</tt>, which 324 * will be bound to the original receiver, i.e. the first argument of <tt>select</tt>. 325 * <p> 326 * If the selector matches a field, an accessor is returned. If the selector ends with 327 * <tt>:=</tt>, a mutator is returned instead. An accessor is a nullary closure which upon 328 * application yields the field's value. A mutator is a unary closure which upon 329 * application assigns the field to the specified value. 330 * Even for fields already bound to a closure, selecting the field returns an accessor 331 * closure, not the bound closure itself. 332 * 333 * @see #base_doesNotUnderstand(ATSymbol) for what happens if the selector is not found. 334 * 335 * @param receiver the dynamic receiver of the selection. If the result of the selection is 336 * a method, the closure wrapping the method will bind <tt>self</tt> to this object. 337 * @param selector a symbol denoting the name of the field or method to select. 338 * @return if selector is bound to a field, an accessor or mutator for the field; otherwise if 339 * the selector is bound to a method, a closure wrapping the method. 340 */ 341 public ATClosure base_select(ATObject receiver, ATSymbol selector) throws InterpreterException; 342 343 /** 344 * This meta-level operation reifies field definition. Hence, the base-level 345 * code <code>def x := v</code> evaluated in a lexical scope <tt>lex</tt> 346 * is interpreted at the meta-level as: 347 * <pre>(reflect: lex).defineField(`x, v)</pre> 348 * 349 * Invoking this meta-level operation on an object's mirror adds a new field 350 * to that object. An object cannot contain two or more fields with the 351 * same name. 352 * 353 * @param name a symbol denoting the name of the new field 354 * @param value the value of the new field 355 * @return nil 356 * @throws edu.vub.at.exceptions.XDuplicateSlot if the object already has a 357 * local field with the given name 358 */ 359 public ATNil base_defineField(ATSymbol name, ATObject value) throws InterpreterException; 360 361 /* ----------------------------------------- 362 * -- Cloning and instantiation protocol -- 363 * ---------------------------------------- */ 364 365 /** 366 * This meta-level operation reifies the act of cloning the base-level object. 367 * Hence, the code <code>clone: o</code> is interpreted at the meta-level as 368 * <pre>(reflect: o).clone()</pre> 369 * 370 * AmbientTalk's default cloning semantics are based on shallow copying. 371 * A cloned object has copies of the original object's fields, but the values 372 * of the fields are shared between the clones. A clone has the same methods 373 * as the original object. Methods added at a later stage to the original 374 * will not affect the clone's methods and vice versa. This means that each 375 * objects has its own independent fields and methods. 376 * <p> 377 * If the cloned AmbientTalk object contains programmer-defined field objects, 378 * each of these fields is re-instantiated with the clone as a parameter. The 379 * clone is intialized with the re-instantiated fields rather than with the 380 * fields of the original object. This property helps to ensure that each 381 * object has its own independent fields. 382 * <p> 383 * If the object has a <i>shares-a</i> relationship with its parent, the object 384 * and its clone will <b>share</b> the same parent object. Shares-a relationships 385 * are the default in AmbientTalk, and they match with the semantics of 386 * shallow copying: the dynamic parent of an object is a regular field, hence 387 * its contents is shallow-copied. 388 * <p> 389 * If the object has an <i>is-a</i> relationship with its parent object, a 390 * clone of the object will receive a clone of the parent object as its parent. 391 * Hence, is-a relationships "override" the default shallow copying semantics 392 * and recursively clone the parent of an object up to a shares-a relationship. 393 * <p> 394 * If a mirage is cloned, its mirror is automatically re-instantiated with 395 * the new mirage, to ensure that each mirage has its independent mirror. 396 * @return a clone of the mirror's <tt>base</tt> object 397 */ 398 public ATObject base_clone() throws InterpreterException; 399 400 /** 401 * This meta-level operation reifies instance creation. The default 402 * implementation of an AmbientTalk object's <tt>new</tt> method is: 403 * <pre>def new(@initargs) { (reflect: self).newInstance(initargs) }</pre> 404 * 405 * Creating a new instance of an object is a combination of: 406 * <ul> 407 * <li>creating a clone of the object 408 * <li>initializing the clone by invoking its <tt>init</tt> method 409 * </ul> 410 * 411 * The default implementation is: 412 * <pre>def newInstance(initargs) { 413 * def instance := self.clone(); 414 * instance.init(@initargs); 415 * instance; 416 *} 417 * </pre> 418 * 419 * Instance creation in AmbientTalk is designed to mimick class instantiation 420 * in a class-based language. Instantiating a class <tt>c</tt> requires <i>allocating</i> 421 * a new instance <tt>i</tt> and then invoking the <i>constructor</i> on that 422 * new instance. In AmbientTalk, class allocation is replaced by object 423 * <i>cloning</i>. The benefit is that an instantiated object its variables are 424 * already initialized to useful values, being those of the object from which 425 * it is instantiated. The <tt>init</tt> method plays the role of "constructor" 426 * in AmbientTalk. 427 * 428 * @param initargs a table denoting the actual arguments to be passed to 429 * the <tt>init</tt> method 430 * @return the new instance 431 */ 432 public ATObject base_newInstance(ATTable initargs) throws InterpreterException; 433 434 /* --------------------------------- 435 * -- Structural Access Protocol -- 436 * --------------------------------- */ 437 438 /** 439 * This structural meta-level operation adds a field object to the receiver mirror's 440 * base object. An object cannot contain two or more fields with the same name. 441 * 442 * Note that the field object passed as an argument serves as a <i>prototype</i> 443 * object: the actual field object added is an <i>instance</i> of the passed field object. 444 * A field object should always have an <tt>init</tt> method that takes as an argument 445 * the new host object to which it is added. This is often useful, as the behaviour 446 * of a field may depend on the object in which it resides. Because <tt>addField</tt> 447 * creates a new instance of the field, this gives the field object a chance to 448 * properly refer to its new host. 449 * <p> 450 * As an example, here is how to add a read-only field <tt>foo</tt> initialized 451 * to <tt>5</tt> to an object <tt>obj</tt>: 452 * <pre>def makeConstantField(nam, val) { 453 * object: { 454 * def new(newHost) { self }; // singleton pattern 455 * def name := nam; 456 * def readField() { val }; 457 * def writeField(newVal) { nil }; 458 * } 459 * }; 460 * (reflect: obj).addField(makeConstantField(`foo, 5)); 461 * </pre> 462 * 463 * @param field the prototype field object whose instance should be added 464 * to the receiver's base object 465 * @return nil 466 * @throws XDuplicateSlot if the base object already has a field with the 467 * same name as the new field 468 */ 469 public ATNil base_addField(ATField field) throws InterpreterException; 470 471 /** 472 * This structural meta-level operation adds a method to the receiver 473 * mirror's base object. An object cannot contain two or more methods 474 * with the same name. 475 * 476 * @param method a method object to add to the receiver's base object's 477 * method dictionary. 478 * @return nil 479 * @throws XDuplicateSlot if a method with the new method's selector already 480 * exists in the base object. 481 */ 482 public ATNil base_addMethod(ATMethod method) throws InterpreterException; 483 484 /** 485 * This structural meta-level operation allows the metaprogrammer to reify a 486 * field of the receiver mirror's base object. Hence, unlike <tt>select</tt> 487 * and <tt>lookup</tt>, <tt>grabField</tt> returns a <i>field object</i> rather 488 * than the <i>value</i> bound to the field. For example: one could express 489 * <code>obj.super := val</code> at the meta-level as: 490 * 491 * <pre> 492 * def superField := (reflect: obj).grabField(`super); 493 * superField.writeField(val); 494 * </pre> 495 * 496 * Another important difference between <tt>select</tt>, <tt>lookup</tt> and 497 * <tt>grabField</tt> is that <tt>grabField</tt> only considers the fields 498 * <i>local</i> to the receiver's base object. Fields of lexical or dynamic 499 * parent objects are <i>not</i> considered. 500 * 501 * @param selector a symbol representing the name of the field to select. 502 * @return a mirror on this object's field slot. 503 * @throws XUndefinedSlot if the field cannot be found within the receiver's 504 * base object. 505 */ 506 public ATField base_grabField(ATSymbol selector) throws InterpreterException; 507 508 /** 509 * This structural meta-level operation allows the metaprogrammer to 510 * reify a method defined on the receiver mirror's base object. Note that, 511 * unlike the <tt>select</tt> or <tt>lookup</tt> operations, <tt>grabMethod</tt> 512 * returns the bare method object, i.e. <i>not</i> a closure wrapping the method. 513 * <p> 514 * Also, unlike <tt>select</tt> and <tt>lookup</tt>, <tt>grabField</tt> only 515 * considers the locally defined methods of an object, methods of lexical or 516 * dynamic parent objects are <i>not</i> considered. 517 * 518 * @param selector a symbol representing the name of the method to grab from 519 * the receiver's base object. 520 * @return the bare method object bound to the given selector. 521 * @throws XSelectorNotFound if the method object cannot be found within the 522 * receiver's base object. 523 */ 524 public ATMethod base_grabMethod(ATSymbol selector) throws InterpreterException; 525 526 /** 527 * This structural meta-level operation allows access to all of the 528 * fields defined on the receiver mirror's base object. Note that 529 * this method only returns the base object's <i>locally</i> defined 530 * fields. Fields from parent objects are not returned. 531 * 532 * @see ATMirrorRoot#base_grabField(ATSymbol) for details about the returned 533 * field objects. 534 * @return a table of field objects (of type {@link ATField}). 535 */ 536 public ATTable base_listFields() throws InterpreterException; 537 538 /** 539 * This structural meta-level operation allows access to all of the 540 * methods defined on the receiver mirror's base object. Note that 541 * this method only returns the base object's <i>locally</i> defined 542 * methods. Methods from parent objects are not returned. 543 * 544 * @see ATMirrorRoot#base_grabMethod(ATSymbol) for details about the returned 545 * method objects. 546 * @return a table of method objects (of type {@link ATMethod}). 547 */ 548 public ATTable base_listMethods() throws InterpreterException; 549 550 /** 551 * This structural meta-level operation adds a slot object to the receiver mirror's 552 * base object. An object cannot contain two or more slots with the same name. 553 * 554 * A slot is either a method or a closure. A closure serves to encapsulate access to 555 * or mutation of a field. 556 * 557 * Care must be taken with closures when the object to which they are added is 558 * cloned or instantiated: the closure will be shared between clones! 559 * <p> 560 * As an example, here is how to add a read-only field <tt>foo</tt> initialized 561 * to <tt>5</tt> to an object <tt>obj</tt>: 562 * <pre> 563 * def [accessor,mutator] := /.at.lang.values.createFieldSlot(`foo, 5); 564 * (reflect: obj).addSlot(accessor); 565 * </pre> 566 * 567 * @param slot the method representing the slot to be added 568 * to the receiver's base object 569 * @return nil 570 * @throws XDuplicateSlot if the base object already has a slot with the 571 * same name as the new slot 572 */ 573 public ATNil base_addSlot(ATMethod slot) throws InterpreterException; 574 575 /** 576 * This structural meta-level operation allows the metaprogrammer to reify a 577 * slot of the receiver mirror's base object. Hence, unlike <tt>select</tt> 578 * and <tt>lookup</tt>, <tt>grabSlot</tt> returns a <i>slot object</i> rather 579 * than the <i>value</i> bound to the slot. For example: one could express 580 * <code>obj.super := val</code> at the meta-level as: 581 * 582 * <pre> 583 * def superMutator := (reflect: obj).grabSlot(`super:=); 584 * superMutator(val); 585 * </pre> 586 * 587 * Another important difference between <tt>select</tt>, <tt>lookup</tt> and 588 * <tt>grabSlot</tt> is that <tt>grabSlot</tt> only considers the slots 589 * <i>local</i> to the receiver's base object. Slots of lexical or dynamic 590 * parent objects are <i>not</i> considered. 591 * 592 * @param selector a symbol representing the name of the slot to select. 593 * @return a method representing the selected slot. 594 * @throws XUndefinedSlot if the field cannot be found within the receiver's 595 * base object. 596 */ 597 public ATMethod base_grabSlot(ATSymbol selector) throws InterpreterException; 598 599 /** 600 * This structural meta-level operation allows access to all of the 601 * slots defined on the receiver mirror's base object. Note that 602 * this method only returns the base object's <i>locally</i> defined 603 * slots. Slots from parent objects are not returned. 604 * 605 * @see ATMirrorRoot#base_grabSlot(ATSymbol) for details about the returned 606 * slot objects. 607 * @return a table of slot objects (of type {@link ATMethod}). 608 */ 609 public ATTable base_listSlots() throws InterpreterException; 610 611 /** 612 * This structural meta-level operation removes a slot from the 613 * object. Note that this method only removes slots that are 614 * <i>locally</i> defined in the object. 615 * 616 * @param selector the name of the slot to remove 617 * @return the value to which the slot was previously bound 618 * (e.g. a value or a method object) 619 * @throws XSelectorNotFound if no slot with the given name is found in the object 620 */ 621 public ATObject base_removeSlot(ATSymbol selector) throws InterpreterException; 622 623 /** 624 * This structural meta-level operation returns whether or not 625 * the receiver mirror's base object is an <i>extension</i> of its 626 * parent object. 627 * <p> 628 * In AmbientTalk, all objects are part of a dynamic parent delegation chain: 629 * each object has a <tt>super</tt> field that denotes the object to which to 630 * delegate messages the object cannot understand itself. There are, however, 631 * two kinds of delegation links: 632 * <ul> 633 * <li><b>IS-A</b> links: this kind of link denotes that the child object is 634 * a true extension of its parent, and cannot meaningfully exist without the 635 * parent's state. When the child is cloned, its parent will be cloned as well. 636 * <li><b>SHARES-A</b> links: this kind of link denotes that the child object 637 * simply delegates to its parent for purposes of sharing or code reuse. The 638 * child can meaningfully exist without the parent's state. When the child is 639 * cloned, the clone will delegate to the same parent. 640 * </ul> 641 * 642 * Examples: 643 * <pre>(reflect: (extend: parent with: code)).isExtensionOfParent() => true 644 *(reflect: (share: parent with: code)).isExtensionOfParent() => false 645 * </pre> 646 * 647 * Note that accessing the dynamic parent itself is not a meta-level operation, 648 * the dynamic parent can simply be accessed from the base level by performing 649 * <code>obj.super</code>. 650 * 651 * @return whether the base object extends its parent object via an 652 * <b>IS-A</b> link or not. 653 */ 654 public ATBoolean base_isExtensionOfParent() throws InterpreterException; 655 656 /* ------------------------------------------ 657 * -- Abstract Grammar evaluation protocol -- 658 * ------------------------------------------ */ 659 660 /** 661 * This behavioural meta-level operation reifies the evaluation of 662 * abstract grammar objects into values. For objects, this operation 663 * returns the base object itself, signifying that the evaluation 664 * function defined on objects is the identity function. In other words, 665 * objects are <i>self-evaluating</i>. Parse tree objects (first-class 666 * abstract grammar elements), however, have dedicated evaluation 667 * functions. For example, evaluating <code>x</code> is equivalent to 668 * evaluating <code>(reflect: `x).eval(ctx)</code> where <tt>ctx</tt> 669 * is a reification of the current evaluation context. 670 * 671 * @param ctx a context object that stores the current lexical scope and 672 * the current value of <tt>self</tt> 673 * @return the value of the abstract grammar element denoted by this mirror's 674 * base object. 675 * @throws XIllegalUnquote if an unquote abstract grammar element is evaluated. Such 676 * abstract grammar elements should only be encountered in a quoted parse tree. 677 */ 678 public ATObject base_eval(ATContext ctx) throws InterpreterException; 679 680 /** 681 * This behavioural meta-level operation reifies the quotation of 682 * abstract grammar elements. Regular objects simply return themselves 683 * upon quotation. When an abstract grammar element is quoted, rather 684 * than tree-recursively invoking <tt>eval</tt> on the parse trees, 685 * <tt>quote</tt> is tree-recursively invoked. When encountering 686 * an unquote, <tt>eval</tt> is again invoked on the unquoted subtree, 687 * with the context passed as an argument to <tt>quote</tt>. 688 * 689 * @param ctx a context object passed on to be used in subsequent evaluations. 690 * @throws XIllegalQuote exception whenever an unquote-splice unquotation is discovered 691 * in an Abstract Grammar node where the resulting table cannot be spliced. 692 */ 693 public ATObject base_quote(ATContext ctx) throws InterpreterException; 694 695 /** 696 * This behavioural meta-level operation reifies the act of printing 697 * the base object in the read-eval-print loop. This operation may be 698 * overridden by mirrors to customise the printed representation of 699 * their base object. 700 * 701 * @return a text value denoting a human-readable representation of the object. 702 */ 703 public NATText base_print() throws InterpreterException; 704 705 /* ---------------------------------- 706 * -- Object Relational Comparison -- 707 * ---------------------------------- */ 708 709 /** 710 * This meta-level operation determines whether this mirror's base object 711 * is related to the parameter object by a combination of cloning and 712 * extension operators. The default implementation is: 713 * 714 * <pre>def isRelatedTo(object) { 715 * self.isCloneOf(object).or: { (reflect: base.super).isRelatedTo(object) } 716 *}</pre> 717 * 718 * @param object the object to compare this mirror's base object to 719 * @return true if the given object is a clone of the base object or a clone 720 * of the base object's parents. 721 */ 722 public ATBoolean base_isRelatedTo(ATObject object) throws InterpreterException; 723 724 /** 725 * This meta-level operation determines whether this mirror's base object 726 * is a clone of the parameter object. The <i>is-clone-of</i> relation is transitive, 727 * so if <tt>martin</tt> is a clone of <tt>sally</tt> and <tt>sally</tt> is a clone of 728 * <tt>dolly</tt>, then <tt>martin</tt> is a clone of <tt>dolly</tt> as well. 729 * The relation is reflexive: <tt>dolly</tt> is a clone of itself. 730 * The relation is symmetric: <tt>dolly</tt> is also a clone of <tt>sally</tt>. 731 * 732 * @param other the object to check the is-clone-of relationship with. 733 * @return true if the base object and the parameter object are clones (i.e. one 734 * was created by cloning the other), false otherwise. 735 */ 736 public ATBoolean base_isCloneOf(ATObject other) throws InterpreterException; 737 738 /* --------------------------------- 739 * -- Type Testing and Querying -- 740 * --------------------------------- */ 741 742 /** 743 * Tests whether the receiver mirror's base object is tagged as a particular type. 744 * 745 * The default implementation first compares the object's local type tags to the given type 746 * by means of the {@link ATTypeTag#base_isSubtypeOf(ATTypeTag)} method. If no local type 747 * is found, the test is applied recursively on this object's dynamic parent. In code: 748 * <pre>def isTaggedAs(type) { 749 * (nil != (self.tagsOf: object).find: { |localType| 750 * localType.isSubtypeOf(type) 751 * }).or: { (reflect: base.super).isTaggedAs(type) } 752 * }; 753 * </pre> 754 * 755 * The primitive method <tt>is: obj taggedAs: type</tt> is defined in terms of this 756 * method: 757 * <pre> 758 * def is: obj taggedAs: type { 759 * (reflect: obj).isTaggedAs(type) 760 *}; 761 * </pre> 762 * 763 * @param type the type tag object to check for 764 * @return true if this mirror's base object or one of its parent objects is tagged 765 * with a subtype of the given type, false otherwise. 766 */ 767 public ATBoolean base_isTaggedAs(ATTypeTag type) throws InterpreterException; 768 769 /** 770 * Returns all of the local type tags of this object. The primitive method 771 * <tt>tagsOf: obj</tt> is defined in terms of this method: 772 * 773 * <pre> 774 * def tagsOf: obj { 775 * (reflect: obj).typeTags 776 *}; 777 * </pre> 778 * 779 * @return a table of the type tags that were attached directly to this mirror's base 780 * object. The type tags of its parent objects are not returned. 781 */ 782 public ATTable base_typeTags() throws InterpreterException; 783 784}