dfh.treepath
Class Forester<N>

java.lang.Object
  extended by dfh.treepath.Forester<N>
Type Parameters:
N - the variety of node in the trees understood by the Forester
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
AttributeLibrary, FunctionalForester

public abstract class Forester<N>
extends Object
implements Serializable

An expert on trees. A Forester answers questions about the variety of trees it knows provided these quests are asked in the form of tree path expressions.

Foresters are path factories. Their chief method if interest is path(String).

Author:
David F. Houghton - Apr 18, 2012
See Also:
Serialized Form

Field Summary
protected static Map<Class<? extends Forester<?>>,Map<String,dfh.treepath.InstanceWrapper>> attributeCache
          A cache retaining the mappings from varieties of Forester to the attributes they can handle.
protected  Map<String,dfh.treepath.InstanceWrapper> attributes
           
protected static MatchTest pathMt
          MatchTest used in compiling the path parse tree into a Path.
 
Constructor Summary
Forester(NodeTest<N>... ignorable)
          Initializes the map from attributes to methods and records the node types to ignore.
 
Method Summary
protected  List<N> ancestors(N n, NodeTest<N> t, Index<N> i)
          Ancestors of context node; implements ancestor axis.
protected  boolean attribToBoolean(Object o)
          Translates the return value of an Attribute into a boolean value.
 Object attribute(N node, String name, Collection<N> c, Index<N> i, Object... parameters)
          A convenience method that returns the value of the given attribute for a particular node in a particular context.
 Object attribute(N node, String name, Object... parameters)
          A convenience method that returns the value of the given attribute for a particular node in a generic context.
 Map<String,String[]> attributes()
          Returns an alphabetized collection of the attributes this Forester can handle, mapping each to its description, if any, and a simplified method signature.
protected  Collection<N> axis(N n, PathGrammar.Axis a, NodeTest<N> t, Index<N> i)
          Translates a node and an axis into the appropriate collection of candidate nodes.
protected abstract  List<N> children(N n, Index<N> i)
          All the children of the context node regardless of whether we are ignoring any node types.
protected  List<N> children(N n, NodeTest<N> t, Index<N> i)
          Implements child axis.
protected  Collection<N> closest(N n, NodeTest<N> t, Index<N> i)
          Implements /> expression.
protected  int depth(N n, Collection<N> c, Index<N> i)
           
protected  Collection<N> descendants(N n, NodeTest<N> t, Index<N> i)
          Implements the descendant axis.
protected  Object echo(N n, Collection<N> c, Index<N> i, Object o)
          An attribute that turns anything into an attribute, allowing it to be used in an attribute test.
protected  Boolean False(N n, Collection<N> c, Index<N> i)
          An attribute whose value is always false.
protected  Collection<N> following(N n, NodeTest<N> t, Index<N> i)
          Implements following axis.
protected  List<N> followingSiblings(N n, NodeTest<N> t, Index<N> i)
          Implements following-sibling axis.
protected  Map<String,dfh.treepath.InstanceWrapper> getAttributes()
          Returns attributes handled, checking attributeCache before discovering them by reflection.
 PrintStream getLoggingStream()
          Obtains the stream that will be used by log(Object, Collection, Index, Object...).
protected abstract  boolean hasTag(N n, String tag)
          Defines what it means for a node in this tree to have a particular tag -- the "b" in the path expression "//b".
protected  int height(N n, Collection<N> c, Index<N> i)
           
protected  String id(N n, Collection<N> c, Index<N> i)
           
 Index<N> index(N root)
          Creates an Index of the given tree.
protected  int index(N n, Collection<N> c, Index<N> in)
          Returns the index of the context node in the context collection.
protected  void init()
          Make sure this Forester knows its attributes.
protected  boolean isLeaf(N n, Collection<N> c, Index<N> i)
          A boolean attribute that evaluates to true if the context node is a leaf.
protected  boolean isRoot(N n, Collection<N> c, Index<N> i)
          A boolean attribute that evalues to true if the context node is the tree root.
protected  List<N> kids(N n, Index<N> i)
          Like children(Object, Index), but it tests the nodes against the node tests in ignore.
protected  List<N> leaves(N n, NodeTest<N> t, Index<N> i)
           
protected  Boolean log(N n, Collection<N> c, Index<N> i, Object... msg)
          A debugging attribute.
protected abstract  boolean matchesTag(N n, Pattern p)
          Defines what it means for a node in this tree to have a tag matching the specified pattern.
 void mixin(Class<? extends AttributeLibrary<N>>... mixins)
          Mix in attributes from one or more libraries.
protected  Object Null(N n, Collection<N> c, Index<N> i)
          An attribute whose value is always null.
protected abstract  N parent(N n, Index<N> i)
          Obtains the parent of the context node.
 Path<N> path(String path)
          Compiles a path expression into a Path.
protected  N pick(N n, Collection<N> c, Index<N> i, Collection<N> from, int index)
          An attribute for selecting a member from a collection of nodes returned by a path.
protected  Collection<N> preceding(N n, NodeTest<N> t, Index<N> i)
          Implements preceding axis.
protected  List<N> precedingSiblings(N n, NodeTest<N> t, Index<N> i)
          Implements the preceding-sibling axis.
protected  N root(N n, Index<N> i)
          Obtains the root of the tree containing the context node.
 void setLoggingStream(PrintStream loggingStream)
          Sets the stream to be used by log(Object, Collection, Index, Object...).
protected  List<N> siblings(N n, Index<N> i)
          Obtains context node and its siblings in their tree order.
protected  Collection<N> siblings(N n, NodeTest<N> t, Index<N> i)
          Implements the siblings axis.
protected  Collection<N> siblingsOrSelf(N n, NodeTest<N> t, Index<N> i)
          Implements the siblings-or-self axis.
protected  int size(N n, Collection<N> c, Index<N> i, Collection<N> from)
          An attribute for querying the size a collection of nodes returned by a path.
protected  N This(N n, Collection<N> c, Index<N> i)
          An attribute that returns the context node itself.
protected  Boolean True(N n, Collection<N> c, Index<N> i)
          An attribute whose value is always true.
protected  int tsize(N n, Collection<N> c, Index<N> i)
          An attribute for querying the size of a tree rooted at the context node.
protected  String uid(N n, Collection<N> c, Index<N> i)
          Returns a string uniquely identifying the node in the tree as a sequence of branch indices.
protected  int width(N n, Collection<N> c, Index<N> i)
          An attribute for querying the size of a tree rooted at the context node.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

attributeCache

protected static final Map<Class<? extends Forester<?>>,Map<String,dfh.treepath.InstanceWrapper>> attributeCache
A cache retaining the mappings from varieties of Forester to the attributes they can handle. This is used to accelerate construction by caching the results of reflective code.


attributes

protected transient Map<String,dfh.treepath.InstanceWrapper> attributes

pathMt

protected static final MatchTest pathMt
MatchTest used in compiling the path parse tree into a Path.

Constructor Detail

Forester

public Forester(NodeTest<N>... ignorable)
Initializes the map from attributes to methods and records the node types to ignore.

Parameters:
ignorable - node types to ignore; none ignored if parameter is null or empty
Method Detail

init

protected void init()
Make sure this Forester knows its attributes.


getAttributes

protected final Map<String,dfh.treepath.InstanceWrapper> getAttributes()
Returns attributes handled, checking attributeCache before discovering them by reflection.

Returns:
attributes handled by forester

attribToBoolean

protected boolean attribToBoolean(Object o)
Translates the return value of an Attribute into a boolean value. Boolean objects are interpreted via Boolean.booleanValue(). Collection objects are true if Collection.isEmpty() is false. All other values are true if they are not null.

Parameters:
o -
Returns:
whether the value returned by an attribute evaluates to true

axis

protected Collection<N> axis(N n,
                             PathGrammar.Axis a,
                             NodeTest<N> t,
                             Index<N> i)
Translates a node and an axis into the appropriate collection of candidate nodes.

Parameters:
n - context node relative to which the axis will be examined
a - axis to walk
t - node test to locate desired nodes on the specified axis
i - tree idnex
Returns:
those nodes on the given axis that pass the test

siblings

protected Collection<N> siblings(N n,
                                 NodeTest<N> t,
                                 Index<N> i)
Implements the siblings axis.

Parameters:
n - context node
t - node type of interest
i - tree index
Returns:
siblings of context node

siblingsOrSelf

protected Collection<N> siblingsOrSelf(N n,
                                       NodeTest<N> t,
                                       Index<N> i)
Implements the siblings-or-self axis.

Parameters:
n - context node
t - node type of interest
i - tree index
Returns:
context node and its siblings in tree order

children

protected List<N> children(N n,
                           NodeTest<N> t,
                           Index<N> i)
Implements child axis.

Parameters:
n - context node
t - nodes of interest
i - tree index
Returns:
children of context node

path

public final Path<N> path(String path)
Compiles a path expression into a Path.

Parameters:
path - path expression
Returns:
compiled path expression

isLeaf

@Attribute(value="leaf",
           description="whether the context node is a leaf")
protected boolean isLeaf(N n,
                                                   Collection<N> c,
                                                   Index<N> i)
A boolean attribute that evaluates to true if the context node is a leaf.

Parameters:
n - context node
c - collection of which context node is a member; required for method signature but ignored
i - tree index
Returns:
whether n is a leaf

pick

@Attribute(description="picks a node from a collection")
protected final N pick(N n,
                                            Collection<N> c,
                                            Index<N> i,
                                            Collection<N> from,
                                            int index)
An attribute for selecting a member from a collection of nodes returned by a path. E.g., @pick(foo//bar, 1). The index is zero-based.

Parameters:
n - context node
c - collection of which context node is a member; required for method signature but ignored
i - tree index
from - a collection of candidates selected by some path
index - the index in the collection selected from corresponding to the node selected
Returns:
the node selected, or null if there is no appropriate node

size

@Attribute(description="the size of the node collection")
protected int size(N n,
                                        Collection<N> c,
                                        Index<N> i,
                                        Collection<N> from)
An attribute for querying the size a collection of nodes returned by a path. E.g., @size(foo//bar).

Parameters:
n - context node
c - collection of which context node is a member; required for method signature but ignored
i - tree index
from - a candidate node set selected by a path
Returns:
the number of nodes selected by the path

tsize

@Attribute(description="the size in nodes of the tree rooted at node")
protected int tsize(N n,
                                         Collection<N> c,
                                         Index<N> i)
An attribute for querying the size of a tree rooted at the context node. E.g., //foo[@tsize = 3].

Parameters:
n - context node
c - collection of which context node is a member; required for method signature but ignored
i - tree index
from - a candidate node set selected by a path
Returns:
the number of nodes selected by the path

width

@Attribute(description="the number of leaves under node; 1 if node is a leaf")
protected int width(N n,
                                         Collection<N> c,
                                         Index<N> i)
An attribute for querying the size of a tree rooted at the context node. E.g., //foo[@tsize = 3].

Parameters:
n - context node
c - collection of which context node is a member; required for method signature but ignored
i - tree index
from - a candidate node set selected by a path
Returns:
the number of nodes selected by the path

depth

@Attribute(description="the number of steps between node and root")
protected int depth(N n,
                                         Collection<N> c,
                                         Index<N> i)

height

@Attribute(description="the longest path between node and a leaf; 1 if node is a leaf")
protected int height(N n,
                                          Collection<N> c,
                                          Index<N> i)

isRoot

@Attribute(value="root",
           description="whether the node is root")
protected boolean isRoot(N n,
                                                   Collection<N> c,
                                                   Index<N> i)
A boolean attribute that evalues to true if the context node is the tree root.

Parameters:
n - context node
c - collection of which context node is a member; required for method signature but ignored
i - tree index
Returns:
whether n is the tree root

id

@Attribute(description="the nodes string id, if any")
protected String id(N n,
                                         Collection<N> c,
                                         Index<N> i)
Parameters:
n -
c -
i -
Returns:
the identifying string, if any, of this node

Null

@Attribute(value="null",
           description="the null value")
protected final Object Null(N n,
                                                      Collection<N> c,
                                                      Index<N> i)
An attribute whose value is always null. This attribute cannot be overridden.

Parameters:
n - context node; required for method signature but ignored
c - collection of which context node is a member; required for method signature but ignored
i - tree index; required for method signature but ignored
Returns:
null

True

@Attribute(value="true",
           description="the true value")
protected final Boolean True(N n,
                                                       Collection<N> c,
                                                       Index<N> i)
An attribute whose value is always true. This attribute cannot be overridden.

Parameters:
n - context node; required for method signature but ignored
c - collection of which context node is a member; required for method signature but ignored
i - tree index; required for method signature but ignored
Returns:
true

False

@Attribute(value="false",
           description="the false value")
protected final Boolean False(N n,
                                                        Collection<N> c,
                                                        Index<N> i)
An attribute whose value is always false. This attribute cannot be overridden.

Parameters:
n - context node; required for method signature but ignored
c - collection of which context node is a member; required for method signature but ignored
i - tree index
Returns:
false

This

@Attribute(value="this",
           description="the context node")
protected final N This(N n,
                                                 Collection<N> c,
                                                 Index<N> i)
An attribute that returns the context node itself.

Parameters:
n - context node
c - collection of which context node is a member; required for method signature but ignored
i - tree index; required for method signature but ignored
Returns:
the context node n

leaves

protected List<N> leaves(N n,
                         NodeTest<N> t,
                         Index<N> i)

ancestors

protected List<N> ancestors(N n,
                            NodeTest<N> t,
                            Index<N> i)
Ancestors of context node; implements ancestor axis.

Parameters:
n - context node
t - node types of interest
i - tree index
Returns:
ancestors of context node from youngest to oldest

descendants

protected Collection<N> descendants(N n,
                                    NodeTest<N> t,
                                    Index<N> i)
Implements the descendant axis.

Parameters:
n - context node
t - node types of interest
i - tree index
Returns:
descendants of context node

closest

protected Collection<N> closest(N n,
                                NodeTest<N> t,
                                Index<N> i)
Implements /> expression.

Parameters:
n - context node
t - nodes of interest
i - tree index
Returns:
nearest nodes of interest dominated by the context node

precedingSiblings

protected List<N> precedingSiblings(N n,
                                    NodeTest<N> t,
                                    Index<N> i)
Implements the preceding-sibling axis.

Parameters:
n - context node
t - node types of interest
i - tree index
Returns:
preceding siblings of context node

siblings

protected List<N> siblings(N n,
                           Index<N> i)
Obtains context node and its siblings in their tree order.

Parameters:
n - context node
i - tree index
Returns:
context node and its siblings

followingSiblings

protected List<N> followingSiblings(N n,
                                    NodeTest<N> t,
                                    Index<N> i)
Implements following-sibling axis.

Parameters:
n - context node
t - node types of interest
i - tree index
Returns:
siblings following context node

preceding

protected Collection<N> preceding(N n,
                                  NodeTest<N> t,
                                  Index<N> i)
Implements preceding axis.

Parameters:
n - context node
t - node types of interest
i - tree index
Returns:
nodes preceding the context node in the tree

following

protected Collection<N> following(N n,
                                  NodeTest<N> t,
                                  Index<N> i)
Implements following axis.

Parameters:
n - context node
t - node types of interest
i - tree index
Returns:
nodes following the context node in the tree

index

@Attribute(description="the index of the context node in the context collection")
protected int index(N n,
                                         Collection<N> c,
                                         Index<N> in)
Returns the index of the context node in the context collection.

Parameters:
n -
Returns:
index of n in its context collection; -1 if n is root

children

protected abstract List<N> children(N n,
                                    Index<N> i)
All the children of the context node regardless of whether we are ignoring any node types.

Parameters:
n - context node
i - tree index
Returns:
the children of n

kids

protected final List<N> kids(N n,
                             Index<N> i)
Like children(Object, Index), but it tests the nodes against the node tests in ignore.

Parameters:
n - context node
i - tree index
Returns:
children remaining after dropping those to be ignored

hasTag

protected abstract boolean hasTag(N n,
                                  String tag)
Defines what it means for a node in this tree to have a particular tag -- the "b" in the path expression "//b".

Parameters:
n - context node
tag - tag
Returns:
whether the node bears the given tag

matchesTag

protected abstract boolean matchesTag(N n,
                                      Pattern p)
Defines what it means for a node in this tree to have a tag matching the specified pattern. See hasTag(Object, String).

Parameters:
n - context node
p - tag pattern
Returns:
whether the pattern matches the node's tag or tags

parent

protected abstract N parent(N n,
                            Index<N> i)
Obtains the parent of the context node.

Parameters:
n - context node
i - tree index
Returns:
the parent of n

root

protected N root(N n,
                 Index<N> i)
Obtains the root of the tree containing the context node.

Parameters:
n - context node
i - tree index used to find the root
Returns:
the root of the tree containing n

index

public Index<N> index(N root)
Creates an Index of the given tree. It must be overridden by foresters that require more of an index than a map from identifiers to nodes and references back to the forester and the tree root.

Parameters:
root -
Returns:
and index of the given tree

attributes

public Map<String,String[]> attributes()
Returns an alphabetized collection of the attributes this Forester can handle, mapping each to its description, if any, and a simplified method signature. E.g., from MatchPath.main(String[])
 ...
        public static void main(String[] args) {
                int length = 0;
                for (String s : MatchPath.standard().attributes.keySet())
                        length = Math.max(length, s.length());
                String format = "@%-" + length + "s : %s%n%" + length + "s    %s%n";
                for (Entry<String, String[]> e : MatchPath.standard().attributes()
                                .entrySet()) {
                        System.out.printf(format, e.getKey(), e.getValue()[0], "",
                                        e.getValue()[1]);
                }
        }
 ...
 
 @assertion       : whether node is an assertion
                    public boolean dfh.treepath.MatchPath.assertion(...)
 @defined         : whether the parameter value is non-null
                    protected final Boolean dfh.treepath.Forester.defined(...,Object)
 @explicit        : whether the rule generating this node is explicitly defined
                    public boolean dfh.treepath.MatchPath.explicit(...)
 ...
 
This method serves to make foresters somewhat self-documenting.

Returns:
an alphabetized collection of the attributes this Forester can handle

getLoggingStream

public PrintStream getLoggingStream()
Obtains the stream that will be used by log(Object, Collection, Index, Object...). This is by default System.err.

Returns:
the PrintStream used by the log(Object, Collection, Index, Object...) attribute

setLoggingStream

public void setLoggingStream(PrintStream loggingStream)
Sets the stream to be used by log(Object, Collection, Index, Object...).

Parameters:
loggingStream - the PrintStream used by the log(Object, Collection, Index, Object...) attribute

log

@Attribute(description="records parameters to a log stream")
protected final Boolean log(N n,
                                                 Collection<N> c,
                                                 Index<N> i,
                                                 Object... msg)
A debugging attribute. It performs no filtering but can be used to output messages to a debugging stream.

Parameters:
n - context node; ignored by this attribute but required in the method signature
c - context node collection; ignored by this attribute but required in the method signature
i - tree index; ignored by this attribute but required in the method signature
msg - 0 or more messages to print, one per line, to the debugging stream
Returns:
true -- this attribute does no filtering

attribute

public Object attribute(N node,
                        String name,
                        Object... parameters)
A convenience method that returns the value of the given attribute for a particular node in a generic context. This method delegates to attribute(Object, String, Collection, Index, Object...), setting the context collection and tree index to null.

Parameters:
node - context node
name - attribute name
parameters - any attribute parameters
Returns:
the value of the given attribute for the given node evaluated in a generic context

attribute

public Object attribute(N node,
                        String name,
                        Collection<N> c,
                        Index<N> i,
                        Object... parameters)
A convenience method that returns the value of the given attribute for a particular node in a particular context. If the collection or index is null, a fresh one wil be created. The collection will be a single member list containing only the context node. The index will be the index generated by index(Object), which treats the context node as the root of its own tree.

If you can calculate the attribute value directly, this will be more efficient as it will involve no reflection and possible guesswork as to the evaluation context.

Parameters:
node - context node
name - attribute name
c - a selection context -- the set of nodes the context node has been selected with
i - tree index
parameters - any parameters for the attribute
Returns:
the value of the given attribute for the given node selected in the given context

uid

@Attribute(description="unique id of context node representing its position in its tree")
protected final String uid(N n,
                                                Collection<N> c,
                                                Index<N> i)
Returns a string uniquely identifying the node in the tree as a sequence of branch indices. For instance, the root node will be "/", the leftmost node under the root will be "/0", the second node under the leftmost node under root will be "/0/1", and so on.

This attribute is chiefly useful in debugging.

Parameters:
n - context node
c - collection of which context node is a member; required for method signature but ignored
i - tree index
Returns:
true

echo

@Attribute(description="converts anything into an attribute")
protected final Object echo(N n,
                                                 Collection<N> c,
                                                 Index<N> i,
                                                 Object o)
An attribute that turns anything into an attribute, allowing it to be used in an attribute test. E.g., //a[@echo(foo//bar) = 3].

Parameters:
n - context node
c - collection of which context node is a member; required for method signature but ignored
i - tree index
o - some object
Returns:
the o parameter

mixin

public void mixin(Class<? extends AttributeLibrary<N>>... mixins)
Mix in attributes from one or more libraries.

Parameters:
mixins - libraries to mix in