10 files changed, 249 insertions, 18 deletions

diff --git a/src/main/java/bjc/data/BooleanToggle.java b/src/main/java/bjc/data/BooleanToggle.java
index 56cbdf0..41f2564 100644
--- a/src/main/java/bjc/data/BooleanToggle.java
+++ b/src/main/java/bjc/data/BooleanToggle.java
@@ -83,7 +83,7 @@ public class BooleanToggle implements Toggle<Boolean> {
 		final BooleanToggle other = (BooleanToggle) obj;
 
 		if (val != other.val) return false;
-		else                  return true;
+		return true;
 	}
 
 	@Override
diff --git a/src/main/java/bjc/data/Either.java b/src/main/java/bjc/data/Either.java
index 42d2e99..07845f6 100644
--- a/src/main/java/bjc/data/Either.java
+++ b/src/main/java/bjc/data/Either.java
@@ -185,6 +185,14 @@ public class Either<LeftType, RightType> {
 		return rightVal;
 	}
 
+	/**
+	 * Change the type of the right-side of this either.
+	 * 
+	 * Works only for left Eithers.
+	 * 
+	 * @param <T> The new type for the right side
+	 * @return The either with the new type.
+	 */
 	@SuppressWarnings("unchecked")
 	public <T> Either<LeftType, T> newRight() {
 		if (isLeft) return (Either<LeftType, T>) this;
@@ -192,6 +200,14 @@ public class Either<LeftType, RightType> {
 		throw new NoSuchElementException("Can't replace right type on right Either");
 	}
 	
+	/**
+	 * Change the type of the left-side of this either.
+	 * 
+	 * Works only for right Eithers.
+	 * 
+	 * @param <T> The new type for the left side
+	 * @return The either with the new type.
+	 */
 	@SuppressWarnings("unchecked")
 	public <T> Either<T, RightType> newLeft() {
 		if (isLeft) 
@@ -199,6 +215,14 @@ public class Either<LeftType, RightType> {
 		return (Either<T, RightType>) this;
 	}
 	
+	/**
+	 * Collapse an Either with the same type on both sides.
+	 * 
+	 * @param <T> The type of the either
+	 * @param eth The either to collapse
+	 * 
+	 * @return The collapsed either
+	 */
 	public static <T> T collapse(Either<T, T> eth) {
 		return eth.extract(ID.id(), ID.id());
 	}
diff --git a/src/main/java/bjc/data/FlatMapIterator.java b/src/main/java/bjc/data/FlatMapIterator.java
new file mode 100644
index 0000000..47bc06c
--- /dev/null
+++ b/src/main/java/bjc/data/FlatMapIterator.java
@@ -0,0 +1,52 @@
+package bjc.data;
+
+import java.util.*;
+import java.util.function.Function;
+
+/**
+ * Create an iterator that applies a flat-map function
+ * 
+ * @author bjcul
+ * 
+ * @param <T1> The source type
+ * @param <T2> The output type
+ *
+ */
+public class FlatMapIterator<T1, T2> implements Iterator<T2> {
+	private Function<T1, Iterator<T2>> action;
+
+	private Iterator<T1> source;
+	private Iterator<T2> output;
+	/**
+	 * Create a new flat-map iterator
+	 * 
+	 * @param source The source iterator
+	 * @param action The action to apply to the iterator
+	 */
+	public FlatMapIterator(Iterator<T1> source, Function<T1, Iterator<T2>> action) {
+		this.source = source;
+		this.action = action;
+		
+	}
+	
+	@Override
+	public boolean hasNext() {
+		if (output != null && output.hasNext()) return true;
+		while (source.hasNext()) {
+			output = action.apply(source.next());
+			if (output.hasNext()) return true;
+		}
+		return false;
+	}
+
+	@Override
+	public T2 next() {
+		if (output != null && output.hasNext()) return output.next();
+		while (source.hasNext()) {
+			output = action.apply(source.next());
+			if (output.hasNext()) return output.next();
+		}
+		throw new NoSuchElementException();
+	}
+
+}
diff --git a/src/main/java/bjc/data/Lazy.java b/src/main/java/bjc/data/Lazy.java
index 45293e2..436e4c3 100644
--- a/src/main/java/bjc/data/Lazy.java
+++ b/src/main/java/bjc/data/Lazy.java
@@ -87,10 +87,7 @@ public class Lazy<ContainedType> implements Holder<ContainedType> {
 		}
 		
 
-		final Supplier<ContainedType> supplier = () -> {
-			if (valueMaterialized) return heldValue;
-			else                   return valueSupplier.get();
-		};
+		final Supplier<ContainedType> supplier = () -> valueMaterialized ? heldValue : valueSupplier.get();
 
 		return new BoundLazy<>(() -> new Lazy<>(supplier, pendingActions), binder);
 	}
@@ -128,18 +125,18 @@ public class Lazy<ContainedType> implements Holder<ContainedType> {
 		if (valueMaterialized) {
 			if (actions.isEmpty()) {
 				return String.format("value[v='%s']", heldValue);
-			} else {
-				return String.format("value[v='%s'] (has %d pending transforms)",
-						heldValue, actions.getSize());
 			}
+			
+			return String.format("value[v='%s'] (has %d pending transforms)",
+					heldValue, actions.getSize());
 		}
 
 		if (actions.isEmpty()) {
 			return"(unmaterialized)";
-		} else {
-			return String.format("(unmaterialized; has %d pending transforms",
-					actions.getSize());
 		}
+		
+		return String.format("(unmaterialized; has %d pending transforms",
+				actions.getSize());
 	}
 
 	@Override
diff --git a/src/main/java/bjc/data/OneWayToggle.java b/src/main/java/bjc/data/OneWayToggle.java
index 0705344..c427af3 100644
--- a/src/main/java/bjc/data/OneWayToggle.java
+++ b/src/main/java/bjc/data/OneWayToggle.java
@@ -57,8 +57,7 @@ public class OneWayToggle<E> implements Toggle<E> {
 
 	@Override
 	public E peek() {
-		if (gotFirst) return second;
-		else          return first;
+		return gotFirst ? second : first;
 	}
 
 	@Override
diff --git a/src/main/java/bjc/data/Pair.java b/src/main/java/bjc/data/Pair.java
index fe65936..dd6ff7c 100644
--- a/src/main/java/bjc/data/Pair.java
+++ b/src/main/java/bjc/data/Pair.java
@@ -268,6 +268,15 @@ public interface Pair<LeftType, RightType> extends Bifunctor<LeftType, RightType
 		return new SimplePair<>(left, right);
 	}
 	
+	/**
+	 * Swap the left & right sides of this pair
+	 * 
+	 * @return The pair with the left and right types swapped
+	 */
+	public default Pair<RightType, LeftType> swap() {
+		return merge((l, r) -> Pair.pair(r, l));
+	}
+	
 	@Override
 	default void formatTo(Formatter formatter, int flags, int width, int precision) {
 		if ((flags & FormattableFlags.ALTERNATE) != 0) {
diff --git a/src/main/java/bjc/data/PetriNet.java b/src/main/java/bjc/data/PetriNet.java
index b4c08e1..2dea6d6 100644
--- a/src/main/java/bjc/data/PetriNet.java
+++ b/src/main/java/bjc/data/PetriNet.java
@@ -31,11 +31,19 @@ public class PetriNet<Label> {
 	private Map<Label, Integer> nodes;
 	private Map<Label, PetriTransition<Label>> transitions;
 
+	/**
+	 * Create a new Petri net
+	 */
 	public PetriNet() {
 		nodes = new HashMap<>();
 		transitions = new HashMap<>();
 	}
 
+	/**
+	 * Merge this Petri net for another.
+	 * 
+	 * @param net The other Petri net.
+	 */
 	public void merge(PetriNet<Label> net) {
 		for (Entry<Label, Integer> node : net.nodes.entrySet()) {
 			int value = node.getValue();
@@ -50,6 +58,15 @@ public class PetriNet<Label> {
 		}
 	}
 	
+	/**
+	 * Create a Petri net from merging others.
+	 * 
+	 * @param <Label> The type of the labels in the Petri net
+	 * @param nets The nets to merge
+	 * 
+	 * @return A net formed by merging all of the provided ones.
+	 */
+	@SafeVarargs
 	public static <Label> PetriNet<Label> merged(PetriNet<Label>... nets) {
 		PetriNet<Label> result = new PetriNet<>();
 
diff --git a/src/main/java/bjc/data/PetriTransition.java b/src/main/java/bjc/data/PetriTransition.java
index 79f879d..6aba5a5 100644
--- a/src/main/java/bjc/data/PetriTransition.java
+++ b/src/main/java/bjc/data/PetriTransition.java
@@ -20,12 +20,22 @@ package bjc.data;
 import java.util.*;
 import java.util.Map.Entry;
 
+/**
+ * Represents a transition in a Petri net
+ * @author bjcul
+ *
+ * @param <Label> The type of the label
+ */
 public class PetriTransition<Label> {
 	private final Label name;
 
 	private Map<Label, Integer> sources;
 	private Map<Label, Integer> destinations;
 
+	/**
+	 * Create a new transition
+	 * @param name The name for this transition
+	 */
 	public PetriTransition(Label name) {
 		this.name = name;
 
@@ -33,22 +43,54 @@ public class PetriTransition<Label> {
 		destinations = new HashMap<>();
 	}
 
+	/**
+	 * Add a source to this transition
+	 * 
+	 * @param lab The label to move from
+	 * @param tokens The number of tokens to move
+	 */
 	public void addSource(Label lab, int tokens) {
 		sources.merge(lab, tokens, (k, v) -> v + tokens);
 	}
 
+	/**
+	 * Remove a source from this transition
+	 * 
+	 * @param lab The source to remove
+	 * @return The number of tokens that would've been moved
+	 */
 	public int removeSource(Label lab) {
 		return sources.remove(lab);
 	}
 
+	/**
+	 * Add a destination to this transition.
+	 * 
+	 * @param lab The label for the destination
+	 * @param tokens The number of tokens to add
+	 */
 	public void addDestination(Label lab, int tokens) {
 		destinations.merge(lab, tokens, (k, v) -> v + tokens);
 	}
 
-	public int removeDestination(Label lab, int tokens) {
+	/**
+	 * Remove a destination from this transition
+	 * 
+	 * @param lab The destination to remove
+	 * 
+	 * @return The number of tokens which would've moved
+	 */
+	public int removeDestination(Label lab) {
 		return destinations.remove(lab);
 	}
 
+	/**
+	 * Apply this transition to a map
+	 * 
+	 * @param nodes The map to apply the transition to
+	 * 
+	 * @return Whether the transition was successfully applied.
+	 */
 	public boolean apply(Map<Label, Integer> nodes) {
 		Set<Entry<Label, Integer>> debts = new HashSet<>();
 		boolean failed = false;
@@ -100,6 +142,11 @@ public class PetriTransition<Label> {
 		return true;
 	}
 	
+	/**
+	 * Merge this transition with another one
+	 * 
+	 * @param transition The transition to merge
+	 */
 	public void merge(PetriTransition<Label> transition) {
 		for (Entry<Label, Integer> source : transition.sources.entrySet()) {
 			int val = source.getValue();
@@ -133,6 +180,16 @@ public class PetriTransition<Label> {
 				&& Objects.equals(sources, other.sources);
 	}
 
+	/**
+	 * Create a transition from merging a bunch
+	 * 
+	 * @param <Label> The type of the label
+	 * 
+	 * @param mergeName The label for the merged transition
+	 * @param transitions The transitions to merge
+	 * 
+	 * @return A transition created by merging the given ones
+	 */
 	@SafeVarargs
 	public static <Label> PetriTransition<Label> merged(Label mergeName, PetriTransition<Label>... transitions) {
 		PetriTransition<Label> result = new PetriTransition<>(mergeName);
diff --git a/src/main/java/bjc/data/Triple.java b/src/main/java/bjc/data/Triple.java
new file mode 100644
index 0000000..296a169
--- /dev/null
+++ b/src/main/java/bjc/data/Triple.java
@@ -0,0 +1,78 @@
+package bjc.data;
+
+/**
+ * Represents a tuple of three values
+ * @author bjcul
+ *
+ * @param <Left> The type of the first value
+ * @param <Middle> The type of the second value
+ * @param <Right> The type of the third value
+ */
+public interface Triple<Left, Middle, Right> {
+	// TODO: fill this out more; mapping and the like
+	/**
+	 * Get the left value for this triple.
+	 * 
+	 * @return The left value for this triple.
+	 */
+	public Left left();
+	
+	/**
+	 * Get the right value for this triple.
+	 * 
+	 * @return The right value for this triple.
+	 */
+	public Right right();
+
+	/**
+	 * Get the middle value for this triple.
+	 * 
+	 * @return The middle value for this triple.
+	 */
+	public Middle middle();
+	
+	/**
+	 * Create a new triple
+	 * 
+	 * @param <Left> The type for the left
+	 * @param <Middle> The type for the middle
+	 * @param <Right> The type for the right
+	 * 
+	 * @param l The left value
+	 * @param m The middle value
+	 * @param r The right value
+	 * 
+	 * @return A triple of the given values
+	 */
+	public static <Left, Middle, Right> Triple<Left, Middle, Right> of(Left l, Middle m, Right r) {
+		return new SimpleTriple<>(r, m, l);
+	}
+}
+
+final class SimpleTriple<Left, Middle, Right> implements Triple<Left, Middle, Right> {
+	private final Right r;
+	private final Middle m;
+	private final Left l;
+
+	SimpleTriple(Right r, Middle m, Left l) {
+		this.r = r;
+		this.m = m;
+		this.l = l;
+	}
+	
+	
+	@Override
+	public Left left() {
+		return l;
+	}
+
+	@Override
+	public Right right() {
+		return r;
+	}
+
+	@Override
+	public Middle middle() {
+		return m;
+	}
+}
\ No newline at end of file
diff --git a/src/main/java/bjc/data/ValueToggle.java b/src/main/java/bjc/data/ValueToggle.java
index 4e9f7c0..4e72fa6 100644
--- a/src/main/java/bjc/data/ValueToggle.java
+++ b/src/main/java/bjc/data/ValueToggle.java
@@ -54,14 +54,12 @@ public class ValueToggle<E> implements Toggle<E> {
 
 	@Override
 	public E get() {
-		if (alignment.get()) return lft;
-		else                 return rght;
+		return alignment.get() ? lft : rght;
 	}
 
 	@Override
 	public E peek() {
-		if (alignment.peek()) return lft;
-		else                  return rght;
+		return alignment.peek() ? lft : rght;
 	}
 
 	@Override