Formatting tweaks

7 files changed, 142 insertions, 229 deletions

diff --git a/base/src/main/java/bjc/utils/ioutils/LevelSplitter.java b/base/src/main/java/bjc/utils/ioutils/LevelSplitter.java
index c2467ae..22cf2c5 100644
--- a/base/src/main/java/bjc/utils/ioutils/LevelSplitter.java
+++ b/base/src/main/java/bjc/utils/ioutils/LevelSplitter.java
@@ -8,7 +8,7 @@ import java.util.regex.Pattern;
 /**
  * Splits a string on a delimiter, respecting grouping delimiters.
  *
- * By default, grouping delimiters are (), [], {}, and <>, as well as single and
+ * By default, grouping delimiters are (), [], {}, and &lt;&gt;, as well as single and
  * double quoted strings.
  *
  * @author bjculkin
diff --git a/base/src/main/java/bjc/utils/ioutils/blocks/Block.java b/base/src/main/java/bjc/utils/ioutils/blocks/Block.java
index b8c611b..313a91b 100644
--- a/base/src/main/java/bjc/utils/ioutils/blocks/Block.java
+++ b/base/src/main/java/bjc/utils/ioutils/blocks/Block.java
@@ -1,55 +1,38 @@
 package bjc.utils.ioutils.blocks;
 
-/**
- * Represents a block of text read in from a source.
+/** Represents a block of text read in from a source.
  *
- * @author EVE
- *
- */
+ * @author EVE */
 public class Block {
-	/**
-	 * The contents of this block.
-	 */
+	/** The contents of this block. */
 	public final String contents;
 
-	/**
-	 * The line of the source this block started on.
-	 */
+	/** The line of the source this block started on. */
 	public final int startLine;
 
-	/**
-	 * The line of the source this block ended on.
-	 */
+	/** The line of the source this block ended on. */
 	public final int endLine;
 
-	/**
-	 * The number of this block.
-	 */
+	/** The number of this block. */
 	public final int blockNo;
 
-	/**
-	 * The line offset number for this block.
+	/** The line offset number for this block.
 	 *
 	 * Essentially, this is the absolute number of lines that this block is into
 	 * whatever source it came from, where as startLine and endLine are relative to
-	 * the BlockReader this Block is from.
-	 */
+	 * the BlockReader this Block is from. */
 	public int lineOffset;
 
-	/**
-	 * Create a new block.
+	/** Create a new block.
 	 *
-	 * @param blockNo
-	 *                  The number of this block.
-	 * @param contents
-	 *                  The contents of this block.
-	 * @param startLine
-	 *                  The line this block started on.
-	 * @param endLine
-	 *                  The line this block ended.
-	 */
-	public Block(final int blockNo, final String contents, final int startLine,
-			final int endLine) {
+	 * @param blockNo The number of this block.
+	 * @param contents The contents of this block.
+	 * @param startLine The line this block started on.
+	 * @param endLine The line this block ended. */
+	public Block(
+			final int blockNo, final String contents, final int startLine,
+			final int endLine)
+	{
 		this.contents = contents;
 		this.startLine = startLine;
 		this.endLine = endLine;
@@ -62,8 +45,11 @@ public class Block {
 			String fmt
 					= "Block #%d (from lines %d (%d) to %d (%d)), length: %d characters";
 
-			return String.format(fmt, blockNo, startLine + lineOffset, startLine,
-					endLine + lineOffset, endLine + lineOffset, contents.length());
+			return String.format(fmt, 
+					blockNo,
+					startLine + lineOffset, startLine,
+					endLine + lineOffset,   endLine,
+					contents.length());
 		}
 
 		String fmt = "Block #%d (from lines %d to %d), length: %d characters";
diff --git a/base/src/main/java/bjc/utils/ioutils/blocks/BlockReader.java b/base/src/main/java/bjc/utils/ioutils/blocks/BlockReader.java
index f111244..0968050 100644
--- a/base/src/main/java/bjc/utils/ioutils/blocks/BlockReader.java
+++ b/base/src/main/java/bjc/utils/ioutils/blocks/BlockReader.java
@@ -1,58 +1,50 @@
 package bjc.utils.ioutils.blocks;
 
-import java.io.IOException;
-import java.util.Iterator;
-import java.util.function.Consumer;
+import java.io.*;
+import java.util.*;
+import java.util.function.*;
 
-/**
- * A source of blocks of characters, marked with line numbers as to block
+// @NOTE Ben Culkin 12/16/2020 :IterableIterator
+// Having this class implement both Iterator and Iterable is somewhat suspect.
+// I understand why it was done, because that allows easy use of the 'for-each'
+// loop semantics, but there is a question of whether it is a good idea to have
+// instances of Iterable that will always give the same Iterator without
+// explicitly saying that is what they are doing.
+
+/** A source of blocks of characters, marked with line numbers as to block
  * start/block end.
  *
- * @author bjculkin
- *
- */
-public interface BlockReader extends AutoCloseable, Iterator<Block>, Iterable<Block> {
-	/**
-	 * Check if this reader has an available block.
+ * @author bjculkin */
+public interface
+BlockReader extends AutoCloseable, Iterator<Block>, Iterable<Block> {
+	/** Check if this reader has an available block.
 	 *
-	 * @return Whether or not another block is available.
-	 */
+	 * @return Whether or not another block is available. */
 	boolean hasNextBlock();
 
-	/**
-	 * Get the current block.
+	/** Get the current block.
 	 *
-	 * @return The current block, or null if there is no current block.
-	 */
+	 * @return The current block, or null if there is no current block. */
 	Block getBlock();
 
-	/**
-	 * Move to the next block.
+	/** Move to the next block.
 	 *
-	 * @return Whether or not the next block was successfully read.
-	 */
+	 * @return Whether or not the next block was successfully read. */
 	boolean nextBlock();
 
-	/**
-	 * Retrieve the number of blocks that have been read so far.
+	/** Retrieve the number of blocks that have been read so far.
 	 *
-	 * @return The number of blocks read so far.
-	 */
+	 * @return The number of blocks read so far. */
 	int getBlockCount();
 
 	@Override
 	void close() throws IOException;
 
-	/*
-	 * Methods with default impls.
-	 */
+	/* Methods with default impls. */
 
-	/**
-	 * Execute an action for each remaining block.
+	/** Execute an action for each remaining block.
 	 *
-	 * @param action
-	 *               The action to execute for each block
-	 */
+	 * @param action The action to execute for each block. */
 	default void forEachBlock(final Consumer<Block> action) {
 		while (hasNext()) {
 			action.accept(next());
diff --git a/base/src/main/java/bjc/utils/ioutils/blocks/BlockReaders.java b/base/src/main/java/bjc/utils/ioutils/blocks/BlockReaders.java
index 615af85..16d50c0 100644
--- a/base/src/main/java/bjc/utils/ioutils/blocks/BlockReaders.java
+++ b/base/src/main/java/bjc/utils/ioutils/blocks/BlockReaders.java
@@ -1,81 +1,62 @@
 package bjc.utils.ioutils.blocks;
 
-import java.io.Reader;
+import java.io.*;
 
-/**
- * Utility methods for constructing instances of {@link BlockReader}
+/** Utility methods for constructing instances of {@link BlockReader}
  *
- * @author bjculkin
- *
- */
+ * @author bjculkin */
 public class BlockReaders {
-	/**
-	 * Create a new simple block reader that works off a regex.
-	 *
-	 * @param blockDelim
-	 *                   The regex that separates blocks.
+	/** Create a new simple block reader that works off a regex.
 	 *
-	 * @param source
-	 *                   The reader to get blocks from.
+	 * @param blockDelim The regex that separates blocks.
+	 * @param source The reader to get blocks from.
 	 *
-	 * @return A configured simple reader.
-	 */
-	public static SimpleBlockReader simple(final String blockDelim, final Reader source) {
+	 * @return A configured simple reader. */
+	public static SimpleBlockReader simple(
+			final String blockDelim, final Reader source) 
+	{
 		return new SimpleBlockReader(blockDelim, source);
 	}
 
-	/**
-	 * Create a new pushback block reader.
+	/** Create a new pushback block reader.
 	 *
-	 * @param src
-	 *            The block reader to read blocks from.
+	 * @param src The block reader to read blocks from.
 	 *
-	 * @return A configured pushback reader.
-	 */
+	 * @return A configured pushback reader. */
 	public static PushbackBlockReader pushback(final BlockReader src) {
 		return new PushbackBlockReader(src);
 	}
 
-	/**
-	 * Create a new triggered block reader.
+	/** Create a new triggered block reader.
 	 *
-	 * @param source
-	 *               The block reader to read blocks from.
+	 * @param source The block reader to read blocks from.
+	 * @param action The action to execute before reading a block.
 	 *
-	 * @param action
-	 *               The action to execute before reading a block.
-	 *
-	 * @return A configured triggered block reader.
-	 */
-	public static BlockReader trigger(final BlockReader source, final Runnable action) {
+	 * @return A configured triggered block reader. */
+	public static BlockReader trigger(
+			final BlockReader source, final Runnable action)
+	{
 		return new TriggeredBlockReader(source, action);
 	}
 
-	/**
-	 * Create a new layered block reader.
-	 *
-	 * @param primary
-	 *                  The first source to read blocks from.
+	/** Create a new layered block reader.
 	 *
-	 * @param secondary
-	 *                  The second source to read blocks from.
+	 * @param primary The first source to read blocks from.
+	 * @param secondary The second source to read blocks from.
 	 *
-	 * @return A configured layered block reader.
-	 */
-	public static BlockReader layered(final BlockReader primary,
-			final BlockReader secondary) {
+	 * @return A configured layered block reader. */
+	public static BlockReader layered(
+			final BlockReader primary, final BlockReader secondary)
+	{
 		return new LayeredBlockReader(primary, secondary);
 	}
 
-	/**
-	 * Create a new serial block reader.
+	/** Create a new serial block reader.
 	 *
-	 * @param readers
-	 *                The readers to pull from, in the order to pull from them.
+	 * @param readers The readers to pull from, in the order to pull from them.
 	 *
-	 * @return A configured serial block reader.
-	 */
+	 * @return A configured serial block reader. */
 	public static BlockReader serial(final BlockReader... readers) {
 		return new SerialBlockReader(readers);
 	}
-}
\ No newline at end of file
+}
diff --git a/base/src/main/java/bjc/utils/ioutils/blocks/BoundBlockReader.java b/base/src/main/java/bjc/utils/ioutils/blocks/BoundBlockReader.java
index 0bd0991..04a8375 100644
--- a/base/src/main/java/bjc/utils/ioutils/blocks/BoundBlockReader.java
+++ b/base/src/main/java/bjc/utils/ioutils/blocks/BoundBlockReader.java
@@ -1,30 +1,20 @@
 package bjc.utils.ioutils.blocks;
 
-import java.io.IOException;
-import java.util.function.BooleanSupplier;
-import java.util.function.Supplier;
+import java.io.*;
+import java.util.function.*;
 
-/**
- * A block reader composed from functions.
+/** A block reader composed from functions.
  *
- * @author EVE
- *
- */
+ * @author EVE */
 public class BoundBlockReader implements BlockReader {
-	/**
-	 * A function that serves to close an I/O source.
-	 *
-	 * @author EVE
+	/** A function that serves to close an I/O source.
 	 *
-	 */
+	 * @author EVE */
 	@FunctionalInterface
 	public interface Closer {
-		/**
-		 * Close the I/O source this is attached to.
+		/** Close the I/O source this is attached to.
 		 *
-		 * @throws IOException
-		 *                     If something goes wrong
-		 */
+		 * @throws IOException If something goes wrong */
 		public void close() throws IOException;
 	}
 
@@ -36,21 +26,19 @@ public class BoundBlockReader implements BlockReader {
 
 	private int blockNo;
 
-	/**
-	 * Create a new bound block reader.
+	/** Create a new bound block reader.
 	 *
-	 * @param blockChecker
-	 *                     Predicate for checking if a block is available
-	 * @param blockGetter
-	 *                     Function to retrieve a block
-	 * @param blockCloser
-	 *                     Function to close a block source
-	 */
-	public BoundBlockReader(BooleanSupplier blockChecker, Supplier<Block> blockGetter,
-			Closer blockCloser) {
+	 * @param blockChecker Predicate for checking if a block is available
+	 * @param blockGetter Function to retrieve a block
+	 * @param blockCloser Function to close a block source */
+	public BoundBlockReader(
+			BooleanSupplier blockChecker,
+			Supplier<Block> blockGetter,
+			Closer blockCloser)
+	{
 		checker = blockChecker;
-		getter = blockGetter;
-		closer = blockCloser;
+		getter  = blockGetter;
+		closer  = blockCloser;
 
 		blockNo = 0;
 	}
@@ -72,9 +60,9 @@ public class BoundBlockReader implements BlockReader {
 			blockNo += 1;
 
 			return true;
+		} else {
+			return false;
 		}
-
-		return false;
 	}
 
 	@Override
diff --git a/base/src/main/java/bjc/utils/ioutils/blocks/SimpleBlockReader.java b/base/src/main/java/bjc/utils/ioutils/blocks/SimpleBlockReader.java
index 94405c9..3eb57d0 100644
--- a/base/src/main/java/bjc/utils/ioutils/blocks/SimpleBlockReader.java
+++ b/base/src/main/java/bjc/utils/ioutils/blocks/SimpleBlockReader.java
@@ -1,49 +1,34 @@
 package bjc.utils.ioutils.blocks;
 
-import java.io.IOException;
-import java.io.Reader;
-import java.util.NoSuchElementException;
-import java.util.Scanner;
-import java.util.regex.Pattern;
+import java.io.*;
+import java.util.*;
+import java.util.regex.*;
 
-import bjc.utils.funcutils.StringUtils;
+import bjc.utils.funcutils.*;
 
-/**
- * Simple implementation of {@link BlockReader}.
+/** Simple implementation of {@link BlockReader}.
  *
  * NOTE: The EOF marker is always treated as a delimiter. You are expected to
  * handle blocks that may be shorter than you expect.
  *
- * @author EVE
- *
- */
+ * @author EVE */
 public class SimpleBlockReader implements BlockReader {
-	/*
-	 * I/O source for blocks.
-	 */
+	/* I/O source for blocks. */
 	private final Scanner blockReader;
 
-	/*
-	 * The current block.
-	 */
+	/* The current block. */
 	private Block currBlock;
 
-	/*
-	 * Info about the current block.
-	 */
+	/* Info about the current block. */
 	private int blockNo;
 	private int lineNo;
 
-	/**
-	 * Create a new block reader.
+	/** Create a new block reader.
 	 *
-	 * @param blockDelim
-	 *                   The pattern that separates blocks. Note that the end of
+	 * @param blockDelim The pattern that separates blocks. Note that the end of
 	 *                   file is always considered to end a block.
 	 *
-	 * @param source
-	 *                   The source to read blocks from.
-	 */
+	 * @param source The source to read blocks from. */
 	public SimpleBlockReader(final String blockDelim, final Reader source) {
 		blockReader = new Scanner(source);
 
@@ -55,17 +40,13 @@ public class SimpleBlockReader implements BlockReader {
 		lineNo = 1;
 	}
 
-	/**
-	 * Create a new block reader.
+	/** Create a new block reader.
 	 *
-	 * @param blockDelim
-	 *                   The pattern that separates blocks. Note that the end of
+	 * @param blockDelim The pattern that separates blocks. Note that the end of
 	 *                   file is always considered to end a block.
 	 *
-	 * @param source
-	 *                   The source to read blocks from. NOTE: This does modify the
-	 *                   provided scanner.
-	 */
+	 * @param source The source to read blocks from. NOTE: This does modify the
+	 *                   provided scanner. */
 	public SimpleBlockReader(final String blockDelim, final Scanner source) {
 		blockReader = source;
 
@@ -90,19 +71,19 @@ public class SimpleBlockReader implements BlockReader {
 	@Override
 	public boolean nextBlock() {
 		try {
-			/*
-			 * Read in a new block, and keep the line numbers sane.
-			 */
+			/* Read in a new block, and keep the line numbers sane. */
 			final String blockContents = blockReader.next();
 
+			final int numLines = StringUtils.countMatches(blockContents, "\\R");
+
 			final int blockStartLine = lineNo;
-			final int blockEndLine
-					= lineNo + StringUtils.countMatches(blockContents, "\\R");
+			final int blockEndLine   = lineNo + numLines;
 
-			lineNo = blockEndLine;
+			lineNo   = blockEndLine;
 			blockNo += 1;
 
-			currBlock = new Block(blockNo, blockContents, blockStartLine, blockEndLine);
+			currBlock = new Block(
+					blockNo, blockContents, blockStartLine, blockEndLine);
 
 			return true;
 		} catch (final NoSuchElementException nseex) {
@@ -124,19 +105,17 @@ public class SimpleBlockReader implements BlockReader {
 		blockReader.close();
 	}
 
-	/**
-	 * Set the delimiter used to separate blocks.
+	/** Set the delimiter used to separate blocks.
 	 *
-	 * @param delim
-	 *              The delimiter used to separate blocks.
-	 */
+	 * @param delim The delimiter used to separate blocks. */
 	public void setDelimiter(final String delim) {
 		blockReader.useDelimiter(delim);
 	}
 
 	@Override
 	public String toString() {
-		return String.format("SimpleBlockReader [currBlock=%s, blockNo=%s]", currBlock,
-				blockNo);
+		return String.format(
+				"SimpleBlockReader [currBlock=%s, blockNo=%s]",
+				currBlock, blockNo);
 	}
 }
diff --git a/base/src/main/java/bjc/utils/ioutils/blocks/ToggledBlockReader.java b/base/src/main/java/bjc/utils/ioutils/blocks/ToggledBlockReader.java
index 12568c8..d1737f5 100644
--- a/base/src/main/java/bjc/utils/ioutils/blocks/ToggledBlockReader.java
+++ b/base/src/main/java/bjc/utils/ioutils/blocks/ToggledBlockReader.java
@@ -1,15 +1,12 @@
 package bjc.utils.ioutils.blocks;
 
-import java.io.IOException;
+import java.io.*;
 
-import bjc.data.BooleanToggle;
+import bjc.data.*;
 
-/**
- * A block reader that toggles between two sources.
+/** A block reader that toggles between two sources.
  *
- * @author EVE
- *
- */
+ * @author EVE */
 public class ToggledBlockReader implements BlockReader {
 	private BlockReader leftSource;
 	private BlockReader rightSource;
@@ -19,16 +16,12 @@ public class ToggledBlockReader implements BlockReader {
 
 	private int blockNo;
 
-	/**
-	 * Create a new toggling block reader.
+	/** Create a new toggling block reader.
 	 *
-	 * @param left
-	 *              The first block reader to use.
-	 * @param right
-	 *              The second block reader to use.
-	 */
+	 * @param left The first block reader to use.
+	 * @param right The second block reader to use. */
 	public ToggledBlockReader(BlockReader left, BlockReader right) {
-		leftSource = left;
+		leftSource  = left;
 		rightSource = right;
 
 		blockNo = 0;
@@ -38,20 +31,14 @@ public class ToggledBlockReader implements BlockReader {
 
 	@Override
 	public boolean hasNextBlock() {
-		if (leftToggle.peek()) {
-			return leftSource.hasNextBlock();
-		}
-
-		return rightSource.hasNextBlock();
+		if (leftToggle.peek()) return leftSource.hasNextBlock();
+		else                   return rightSource.hasNextBlock();
 	}
 
 	@Override
 	public Block getBlock() {
-		if (leftToggle.peek()) {
-			return leftSource.getBlock();
-		}
-
-		return rightSource.getBlock();
+		if (leftToggle.peek()) return leftSource.getBlock();
+		else                   return rightSource.getBlock();
 	}
 
 	@Override
@@ -64,8 +51,8 @@ public class ToggledBlockReader implements BlockReader {
 			succ = rightSource.nextBlock();
 		}
 
-		if (succ)
-			blockNo += 1;
+		if (succ) blockNo += 1;
+
 		return succ;
 	}