General cleanup and documentation.

Cleanup files, and add missing comments in places.

1 files changed, 237 insertions, 33 deletions

diff --git a/base/src/main/java/bjc/utils/ioutils/ReportWriter.java b/base/src/main/java/bjc/utils/ioutils/ReportWriter.java
index 647d4fe..ea7c8cf 100644
--- a/base/src/main/java/bjc/utils/ioutils/ReportWriter.java
+++ b/base/src/main/java/bjc/utils/ioutils/ReportWriter.java
@@ -5,29 +5,46 @@ import java.io.Writer;
 
 import bjc.utils.esodata.DefaultList;
 
+/**
+ * A writer with support for some formatting operations, such as autoindentation
+ * and pagination.
+ * 
+ * @author bjculkin
+ *
+ */
 public class ReportWriter extends Writer {
+	/*
+	 * Storage of indentation values.
+	 */
 	private static class IndentVal {
+		// # of character positions indentStr occupies
 		public int indentStrPos;
 
+		// String that is printed for the indent.
 		public String indentStr;
+		// Indent string w/ tabs replaced with spaces
 		public String indentStrSpacedTabs;
 
 		public IndentVal() {
 		}
 	}
 
+	// Writer to print to
 	private Writer contained;
 
-	// # of character positions indentStr occupies
+	// Current indentation level
 	private int indentLevel;
+	// Current # of columns the indentation occupies
 	private int indentPos = 0;
 
+	// The indentation values to use
 	private DefaultList<IndentVal> iVals;
-	private IndentVal              defIVal;
+	// The default indentation value.
+	private IndentVal defIVal;
 
 	// # of char. positions to the tab
-	private int tabEqv       = 8;
-	// @NOTE 9/17/19
+	private int tabEqv = 8;
+	// @NOTE 9/17/18
 	//
 	// Consider adding support for both the vertical tab, and variable tab
 	// stops.
@@ -35,86 +52,192 @@ public class ReportWriter extends Writer {
 	// For variable tab stops, decide between a set of numbers saying 'This
 	// level tab is counted as X spaces' and a set of numbers saying 'A tab
 	// advances to the next tab stop that has not been passed'
+
+	// The total count of lines printed
 	private int linesWritten = 0;
-	private int linePos      = 0;
+	// The current position in the line
+	private int linePos = 0;
 
+	// The number of newlines to print for every newline encountered.
 	private int lineSpacing = 1;
 
-	private int pageLine     = 0;
-	private int pageNum      = 0;
+	// The current line on the page
+	private int pageLine = 0;
+	// The current page number
+	private int pageNum = 0;
+	// The number of lines per page
 	private int linesPerPage = 20;
 
+	// Whether or not to print tabs as spaces.
 	private boolean printTabsAsSpaces;
 
+	// Whether or not the last character was a newline
 	private boolean lastCharWasNL;
-	private char    lastChar;
+	// The last character encountered
+	private char lastChar;
 
 	// Really wish java had public `readonly` properties. I wouldn't even
 	// care if that was a restriction that was only enforced by the compiler
+
+	/**
+	 * Get the current indent level.
+	 * 
+	 * @return The current indent level.
+	 */
 	public int getLevel() {
 		return indentLevel;
 	}
 
+	/**
+	 * Get the current line-spacing.
+	 * 
+	 * This is the number of blank lines to print out every time a blank
+	 * line is encountered in the input, and is set to 1 by default.
+	 * 
+	 * @return The current line spacing.
+	 */
 	public int getLineSpacing() {
 		return lineSpacing;
 	}
 
+	/**
+	 * Get the current line on the page.
+	 * 
+	 * @return The current line on the page.
+	 */
 	public int getPageLine() {
 		return pageLine;
 	}
 
+	/**
+	 * Get the current page number.
+	 * 
+	 * @return The current page number.
+	 */
 	public int getPageNum() {
 		return pageNum;
 	}
 
+	/**
+	 * Get the number of lines per page.
+	 * 
+	 * @return The number of lines per page.
+	 */
 	public int getLinesPerPage() {
 		return linesPerPage;
 	}
 
+	/**
+	 * Get the current indent position.
+	 * 
+	 * This is the count of columns the indentation occupies.
+	 * 
+	 * @return The current indent position.
+	 */
 	public int getIndentPos() {
 		return indentPos;
 	}
 
+	/**
+	 * Get the string of the default indentation value.
+	 * 
+	 * @return The string for the default indentation value.
+	 */
 	public String getString() {
 		return defIVal.indentStr;
 	}
 
+	/**
+	 * Get the string of a specific indentation value.
+	 * 
+	 * @param lvl
+	 *                The level to get the value for.
+	 * @return The string for the specified indentation value.
+	 */
 	public String getString(int lvl) {
 		return iVals.get(lvl).indentStr;
 	}
 
+	/**
+	 * Get the number of spaces to a tab.
+	 * 
+	 * @return The number of spaces to a tab.
+	 */
 	public int getTabEqv() {
 		return tabEqv;
 	}
 
+	/**
+	 * Get the total number of lines written.
+	 * 
+	 * @return The total number of lines written.
+	 */
 	public int getLinesWritter() {
 		return linesWritten;
 	}
 
+	/**
+	 * Get the current position in the line.
+	 * 
+	 * @return The current position in the line.
+	 */
 	public int getLinePos() {
 		return linePos;
 	}
 
+	/**
+	 * Get the last character printed.
+	 * 
+	 * @return The last character printed.
+	 */
 	public char getLastChar() {
 		return lastChar;
 	}
 
+	/**
+	 * Get the contained writer.
+	 * 
+	 * @return The contained writer.
+	 */
 	public Writer getWriter() {
 		return contained;
 	}
 
+	/**
+	 * Check if the last character was a newline.
+	 * 
+	 * @return Was the last character a new line?
+	 */
 	public boolean isLastCharNL() {
 		return lastCharWasNL;
 	}
 
+	/**
+	 * Check if tabs are being printed as spaces.
+	 * 
+	 * @return Are tabs being printed as spaces?
+	 */
 	public boolean isPrintingTabsAsSpaces() {
 		return printTabsAsSpaces;
 	}
 
+	/**
+	 * Set the line spacing.
+	 * 
+	 * @param spacing
+	 *                The number of lines to print for every blank line
+	 *                encountered.
+	 */
 	public void setLineSpacing(int spacing) {
 		lineSpacing = spacing;
 	}
 
+	/**
+	 * Set whether tabs are being printed as spaces.
+	 * 
+	 * @param tabsAsSpaces
+	 *                Whether to print tabs as spaces.
+	 */
 	public void setPrintTabsAsSpaces(boolean tabsAsSpaces) {
 		printTabsAsSpaces = tabsAsSpaces;
 
@@ -122,6 +245,12 @@ public class ReportWriter extends Writer {
 		refreshIndents(-1);
 	}
 
+	/**
+	 * Set the number of lines per page.
+	 * 
+	 * @param lines
+	 *                The number of lines per page.
+	 */
 	public void setLinesPerPage(int lines) {
 		linesPerPage = lines;
 
@@ -141,10 +270,22 @@ public class ReportWriter extends Writer {
 		}
 	}
 
+	/**
+	 * Set the current indentation level.
+	 * 
+	 * @param level
+	 *                The indentation level.
+	 */
 	public void setLevel(int level) {
 		indentLevel = level;
 	}
 
+	/**
+	 * Set the current amount of spaces per tab.
+	 * 
+	 * @param eqv
+	 *                The amount of spaces per tab.
+	 */
 	public void setTabEqv(int eqv) {
 		tabEqv = eqv;
 
@@ -157,12 +298,30 @@ public class ReportWriter extends Writer {
 	// Weirdness may occur if the indent string has a
 	// newline in it, since that newline won't be considered
 	// to exist by the IndentWriter
+
+	/**
+	 * Set the default indentation string to use.
+	 * 
+	 * NOTE: Using a string that contains a newline may cause weirdness of
+	 * various sorts to happen.
+	 * 
+	 * @param str
+	 *                The string to use for default indentation.
+	 */
 	public void setString(String str) {
 		defIVal.indentStr = str;
 
 		refreshIndents(-2);
 	}
 
+	/**
+	 * Set the indentation string for a specific indentation level.
+	 * 
+	 * @param lvl
+	 *                The level to set the indentation string for.
+	 * @param str
+	 *                The indentation string to use.
+	 */
 	public void setString(int lvl, String str) {
 		iVals.get(lvl).indentStr = str;
 
@@ -174,6 +333,14 @@ public class ReportWriter extends Writer {
 	// Pass a index to refresh that level
 	// Pass -1 to refresh all indexes
 	// Pass -2 to refresh the default index
+	/**
+	 * Refresh the indentation settings.
+	 * 
+	 * @param lvl
+	 *                The level of indents to refresh. Passing a number >= 0
+	 *                refreshes that level, -1 refreshes every level, and -2
+	 *                refreshes just the default indentation.
+	 */
 	private void refreshIndents(int lvl) {
 		if (lvl == -2) {
 			refreshIndent(defIVal);
@@ -181,21 +348,24 @@ public class ReportWriter extends Writer {
 			for (IndentVal ival : iVals) {
 				refreshIndent(ival);
 			}
+			
+			refreshIndent(defIVal);
 		} else {
 			refreshIndent(iVals.get(lvl));
 		}
 	}
 
+	// Refresh an indent val to respect current settings
 	private void refreshIndent(IndentVal vl) {
 		vl.indentStrPos = 0;
 
 		int indentLength = vl.indentStr.length();
 
 		StringBuilder conv = new StringBuilder();
-		for(int i = 0; i < indentLength; i++) {
+		for (int i = 0; i < indentLength; i++) {
 			char c = vl.indentStr.charAt(i);
-			if(c == '\t') {
-				for(int j = 0; j < tabEqv; j++) {
+			if (c == '\t') {
+				for (int j = 0; j < tabEqv; j++) {
 					conv.append(' ');
 				}
 
@@ -209,25 +379,30 @@ public class ReportWriter extends Writer {
 		vl.indentStrSpacedTabs = conv.toString();
 	}
 
+	/**
+	 * Duplicate this writers settings.
+	 * @param contents The internal writer to use.
+	 * @return A new writer, sharing this ones settings, but writing to the provided Writer instead.
+	 */
 	public ReportWriter duplicate(Writer contents) {
 		ReportWriter rw = new ReportWriter(contents);
 
-		rw.iVals       = iVals;
-		rw.defIVal     = defIVal;
+		rw.iVals = iVals;
+		rw.defIVal = defIVal;
 
 		rw.indentLevel = indentLevel;
-		rw.indentPos   = indentPos;
+		rw.indentPos = indentPos;
 
 		rw.tabEqv = tabEqv;
 
 		rw.linesWritten = linesWritten;
-		rw.linePos      = linePos;
-		rw.lineSpacing  = lineSpacing;
+		rw.linePos = linePos;
+		rw.lineSpacing = lineSpacing;
 
 		rw.printTabsAsSpaces = printTabsAsSpaces;
 
-		rw.pageLine     = pageLine;
-		rw.pageNum      = pageNum;
+		rw.pageLine = pageLine;
+		rw.pageNum = pageNum;
 		rw.linesPerPage = linesPerPage;
 
 		// @NOTE 9/5/18
@@ -238,10 +413,20 @@ public class ReportWriter extends Writer {
 		return rw;
 	}
 
+	/**
+	 * Create a new ReportWriter.
+	 * @param write The place to write to.
+	 */
 	public ReportWriter(Writer write) {
 		this(write, 0, "\t");
 	}
 
+	/**
+	 * Create a new ReportWriter with the specified default indentation values.
+	 * @param write The place to write to.
+	 * @param level The current indentation level.
+	 * @param indentStr The indentation string.
+	 */
 	public ReportWriter(Writer write, int level, String indentStr) {
 		super();
 
@@ -250,19 +435,30 @@ public class ReportWriter extends Writer {
 		indentLevel = level;
 
 		defIVal = new IndentVal();
-		iVals   = new DefaultList<>(defIVal);
+		iVals = new DefaultList<>(defIVal);
 
 		setString(indentStr);
 	}
 
+	/**
+	 * Indent a specific number of levels.
+	 * @param lvl The number of levels to indent.
+	 */
 	public void indent(int lvl) {
 		indentLevel += lvl;
 	}
 
+	/**
+	 * Indent one level.
+	 */
 	public void indent() {
 		indent(1);
 	}
 
+	/**
+	 * Dedent a specific number of levels.
+	 * @param lvl The number of levels to dedent.
+	 */
 	public void dedent(int lvl) {
 		// @NOTE 9/5/18
 		//
@@ -271,10 +467,18 @@ public class ReportWriter extends Writer {
 		indentLevel = Math.max(0, indentLevel - lvl);
 	}
 
+	/**
+	 * Dedent 1 level.
+	 */
 	public void dedent() {
 		dedent(1);
 	}
 
+	/**
+	 * Writes a buffer to the output, then clears it.
+	 * @param sb The buffer to write and clear.
+	 * @throws IOException If something goes wrong writing the buffer.
+	 */
 	public void writeBuffer(StringBuffer sb) throws IOException {
 		write(sb.toString());
 
@@ -289,14 +493,14 @@ public class ReportWriter extends Writer {
 	// next page, or just printing the actual form-feed and hoping whatever
 	// reading software handles it properly
 	private void writePage() {
-		pageNum  += 1;
+		pageNum += 1;
 		pageLine -= linesPerPage;
 	}
 
 	private void writeNL(char c) throws IOException {
 		// Count lines written
 		linesWritten += lineSpacing;
-		pageLine     += lineSpacing;
+		pageLine += lineSpacing;
 
 		lastCharWasNL = true;
 
@@ -317,41 +521,40 @@ public class ReportWriter extends Writer {
 			writePage();
 		}
 
-
-		linePos   = 0;
+		linePos = 0;
 		indentPos = 0;
 	}
 
 	@Override
 	public void write(char[] cbuf, int off, int len) throws IOException {
 		// Skip empty writes
-		if(len == 0) return;
+		if (len == 0) return;
 
 		// Last character was a new line, print the indent string
-		if(lastCharWasNL) {
+		if (lastCharWasNL) {
 			lastCharWasNL = false;
 
 			printIndents();
 		}
 
-		for(int i = 0; i < len; i++) {
+		for (int i = 0; i < len; i++) {
 			int idx = i + off;
 
 			char c = cbuf[idx];
 
-			if(c == '\n' || c == '\r' || (c == '\n' && lastChar != '\r') || c == '\f') {
+			if (c == '\n' || c == '\r' || (c == '\n' && lastChar != '\r') || c == '\f') {
 				writeNL(c);
 			} else {
-				if(lastCharWasNL) {
+				if (lastCharWasNL) {
 					lastCharWasNL = false;
 
 					printIndents();
 				}
 
-				if(c == '\t') {
+				if (c == '\t') {
 					linePos += tabEqv;
 
-					for(int j = 0; j < tabEqv; j++) {
+					for (int j = 0; j < tabEqv; j++) {
 						contained.write(' ');
 					}
 				} else {
@@ -368,10 +571,11 @@ public class ReportWriter extends Writer {
 		for (int j = 0; j < indentLevel; j++) {
 			IndentVal ival = iVals.get(j);
 
-			if (printTabsAsSpaces) contained.write(ival.indentStrSpacedTabs);
-			else                   contained.write(ival.indentStr);
+			if (printTabsAsSpaces)
+				contained.write(ival.indentStrSpacedTabs);
+			else contained.write(ival.indentStr);
 
-			linePos   += ival.indentStrPos;
+			linePos += ival.indentStrPos;
 			indentPos += ival.indentStrPos;
 		}
 	}