/** * DemeterF Main package: transformation/traversals with optional arguments. * * <p> Traversals are parametrized by a function objects. * Each function class (<tt>FC</tt>) implements <tt>combine</tt> and/or * <tt>update</tt> methods, which are called by a traversal when walking a * structure.</p> * * <p><i>Note</i>: <tt>update</tt> methods are only called when the <tt>Traversal</tt> * <tt>traverse(Object o, Object a)</tt> method is called; i.e., when the * original traversal is passed a starting context. See * {@link edu.neu.ccs.demeterf.examples Examples} for, well... some examples.</p> * * <ul> * <li><font size=5><tt>combine</tt></font> methods have the form: * <blockquote> * <code>Ret combine(Target t, ..., Arg a)</code> * </blockquote> * for datatypes to be * reconstructed, <i>after</i> the traversal of any subobjects.</p> * * <p><code>Ret</code> is (of course) the return type, <code>Target</code> * should be replaced by the type (or a supertype) at which the method will be * called, and <code>Arg</code> should be the expected traversal context type. * The [<code>...</code>] should be a list of types and bindings * (i.e., formal method parameters) that are expected from sub-traversals of * the (<tt>Target</tt>) datatype's fields; no fields? no extra parameters * needed.</p> * * <p>All parameters are optional, but <b>order</b> matters: e.g., if a method * accepts less than the number of actual parameters available, then it may still * be called if the types <i>match</i>. See {@link edu.neu.ccs.demeterf.dispatch Dispatch} * for method matching/dispatch description.</p></li><br/> * * <li><font size=5><tt>update</tt></font>: methods have the form: * <blockquote> * <code>Ret update(Target t, Target.field f, Arg a)</code> * </blockquote> * for datatypes where the traversal argument needs to be modified for * subtraversals. <code>Ret</code> should be the new argument type (it can be * different), <code>Target</code> is where this method should be called (on the * way down), <code>Arg</code> is the type of the previous traversal argument, and * <code>Target.field</code> is an encoding of which field of <code>Target</code> * we are about to traverse.</p> * <p>We encode the field to be traversed by using an inner <code>public static * class</code> that shares the <i>name</i> of the field. There must be a * <code>public</code> path (the outer classes must be public, all the way up) in * order for the encoding to work. The <code>DemeterF</code> class generator does * this automatically... see examples package for some hand-coded examples.</p> * * <p>The <code>Arg</code> and <code>Ret</code> types should generally be the * same type (or share a common supertype), but anything is possible.<br/> * e.g., implementing: * <blockquote> * <code>Object update(Object o){ return o; }</code> * </blockquote> * will give each <code>combine</code> method access to its parent as a traversal * context.</p> * </li><br> </ul> * * Return types of these methods can be as specific or general as you like. Argument * types are used for method execution selection, so they should match expected * subtraversal return values. For development safety, during traversal a * <tt>BuilderException</tt> is thrown if no <tt>combine</tt> method * with an applicable signature is found. * * See the individual packages/classes for more info. */ package edu.neu.ccs.demeterf;