/interpreter/tags/at2dist091109/src/edu/vub/at/objects/ATMirrorRoot.java

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