Documentation

7 files changed, 116 insertions, 70 deletions

diff --git a/base/src/main/java/bjc/utils/PropertyDB.java b/base/src/main/java/bjc/utils/PropertyDB.java
index 77ebb3d..85f1e2f 100644
--- a/base/src/main/java/bjc/utils/PropertyDB.java
+++ b/base/src/main/java/bjc/utils/PropertyDB.java
@@ -15,9 +15,11 @@ import bjc.utils.ioutils.SimpleProperties;
  *
  */
 public class PropertyDB {
-	private static SimpleProperties regexes;
-	private static Map<String, Pattern> compiledRegexes;
+	/* Regex storage. */
+	private static SimpleProperties		regexes;
+	private static Map<String, Pattern>	compiledRegexes;
 
+	/* Format string storage. */
 	private static SimpleProperties formats;
 
 	/*
@@ -31,6 +33,7 @@ public class PropertyDB {
 	private static LambdaLock loadLock = new LambdaLock();
 
 	static {
+		/* Reload properties on class load. */
 		reloadProperties();
 	}
 
@@ -41,17 +44,13 @@ public class PropertyDB {
 	 * being loaded will block, to prevent reads from partial states.
 	 */
 	public static void reloadProperties() {
-		/*
-		 * Do the load with the write lock taken.
-		 */
+		/* * Do the load with the write lock taken. */
 		loadLock.write(() -> {
 			if(LOGLOAD) {
 				System.out.println("Reading regex properties:");
 			}
 
-			/*
-			 * Load regexes.
-			 */
+			/* * Load regexes. */
 			regexes = new SimpleProperties();
 			regexes.loadFrom(PropertyDB.class.getResourceAsStream("/regexes.sprop"), false);
 			if(LOGLOAD) {
@@ -64,9 +63,7 @@ public class PropertyDB {
 				System.out.println("Reading format properties:");
 			}
 
-			/*
-			 * Load formats.
-			 */
+			/* * Load formats. */
 			formats = new SimpleProperties();
 			formats.loadFrom(PropertyDB.class.getResourceAsStream("/formats.sprop"), false);
 			if(LOGLOAD) {
@@ -113,9 +110,7 @@ public class PropertyDB {
 				throw new NoSuchElementException(msg);
 			}
 
-			/*
-			 * Get the regex, and cache a compiled version.
-			 */
+			/* * Get the regex, and cache a compiled version. */
 			return compiledRegexes.computeIfAbsent(key, strang -> {
 				return Pattern.compile(regexes.get(strang));
 			});
diff --git a/base/src/main/java/bjc/utils/cli/objects/BlockReaderCLI.java b/base/src/main/java/bjc/utils/cli/objects/BlockReaderCLI.java
index 8c29d8c..64b56fc 100644
--- a/base/src/main/java/bjc/utils/cli/objects/BlockReaderCLI.java
+++ b/base/src/main/java/bjc/utils/cli/objects/BlockReaderCLI.java
@@ -87,6 +87,7 @@ public class BlockReaderCLI {
 		if(interactive) {
 			System.out.printf("reader-conf(%d)>", lno);
 		}
+
 		while(input.hasNextLine()) {
 			/* Read a line. */
 			String ln = input.nextLine();
@@ -123,6 +124,7 @@ public class BlockReaderCLI {
 	 * @return The status of the executed command.
 	 */
 	public CommandStatus handleCommand(Command com, boolean interactive) {
+		/* Handle each command. */
 		switch(com.nameCommand) {
 		case "def-filtered":
 			return defFiltered(com);
@@ -155,6 +157,11 @@ public class BlockReaderCLI {
 		/*
 		 * Get the block name.
 		 */
+		/*
+		 * @TODO 02/17/18 Ben Culkin :StringHandling
+		 * 	This slicing up strings by indexed characters should be abstracted into some
+		 * 	sort of class.
+		 */
 		int idx = remn.indexOf(' ');
 		if(idx == -1) {
 			LOGGER.severe(com.error("No name argument for def-filtered.\n"));
@@ -173,6 +180,7 @@ public class BlockReaderCLI {
 		/*
 		 * Get the reader name.
 		 */
+		/* :StringHandling */
 		idx = remn.indexOf(' ');
 		if(idx == -1) {
 			LOGGER.severe(com.error("No reader-name argument for def-filtered.\n"));
@@ -370,6 +378,7 @@ public class BlockReaderCLI {
 		/*
 		 * Get the block name.
 		 */
+		/* :StringHandling */
 		int idx = remn.indexOf(' ');
 		if(idx == -1) {
 			LOGGER.severe(com.error("No name argument for def-simple.\n"));
@@ -388,6 +397,7 @@ public class BlockReaderCLI {
 		/*
 		 * Get the source name.
 		 */
+		/* :StringHandling */
 		idx = remn.indexOf(' ');
 		if(idx == -1) {
 			LOGGER.severe(com.error("No source-name argument for def-simple.\n"));
@@ -414,6 +424,7 @@ public class BlockReaderCLI {
 
 		String delim = remn;
 
+		/* Get the delimiter, and create the reader. */
 		try {
 			BlockReader reader = new SimpleBlockReader(delim, stat.sources.get(sourceName));
 
diff --git a/base/src/main/java/bjc/utils/cli/objects/Command.java b/base/src/main/java/bjc/utils/cli/objects/Command.java
index c4b2a48..a48eef7 100644
--- a/base/src/main/java/bjc/utils/cli/objects/Command.java
+++ b/base/src/main/java/bjc/utils/cli/objects/Command.java
@@ -66,10 +66,12 @@ public class Command {
 	 *        The name of where the I/O came from.
 	 */
 	public Command(String ln, int lno, String ioSrc) {
+		/* :StringHandling */
 		int idx = ln.indexOf(' ');
 
 		if(idx == -1) idx = ln.length();
 
+		/* Grab command parts. */
 		fullCommand = ln;
 		nameCommand = ln.substring(0, idx).trim();
 		remnCommand = ln.substring(idx).trim();
diff --git a/base/src/main/java/bjc/utils/parserutils/StringDescaper.java b/base/src/main/java/bjc/utils/parserutils/StringDescaper.java
index fb6fe8f..e8c340a 100644
--- a/base/src/main/java/bjc/utils/parserutils/StringDescaper.java
+++ b/base/src/main/java/bjc/utils/parserutils/StringDescaper.java
@@ -13,11 +13,13 @@ import static java.util.Map.Entry;
 import static bjc.utils.PropertyDB.getRegex;
 
 /**
+<<<<<<< Updated upstream
  * Customizable string escapes.
  *
  * @author Benjamin Culkin
  */
 public class StringDescaper {
+	/* The logger. */
 	private Logger LOGGER = Logger.getLogger(StringDescaper.class.getName());
 
 	/*
diff --git a/base/src/main/java/bjc/utils/parserutils/TokenTransformer.java b/base/src/main/java/bjc/utils/parserutils/TokenTransformer.java
index 72913db..f0221be 100644
--- a/base/src/main/java/bjc/utils/parserutils/TokenTransformer.java
+++ b/base/src/main/java/bjc/utils/parserutils/TokenTransformer.java
@@ -21,8 +21,10 @@ final class TokenTransformer<TokenType> implements Consumer<TokenType> {
 	 * Handle operators
 	 */
 	private final class OperatorHandler implements UnaryOperator<ConstructorState<TokenType>> {
+		/* The handled element. */
 		private final TokenType element;
 
+		/* Create a new operator handler. */
 		public OperatorHandler(final TokenType element) {
 			this.element = element;
 		}
@@ -33,9 +35,8 @@ final class TokenTransformer<TokenType> implements Consumer<TokenType> {
 			 * Replace the current AST with the result of handling
 			 * an operator
 			 */
-			return new ConstructorState<>(pair.bindLeft(queuedASTs -> {
-				return handleOperator(queuedASTs);
-			}));
+			return new ConstructorState<>(pair.bindLeft(
+						queuedASTs -> handleOperator(queuedASTs)));
 		}
 
 		private ConstructorState<TokenType> handleOperator(final Deque<ITree<TokenType>> queuedASTs) {
@@ -66,7 +67,7 @@ final class TokenTransformer<TokenType> implements Consumer<TokenType> {
 				 * Grab the two operands
 				 */
 				final ITree<TokenType> right = queuedASTs.pop();
-				final ITree<TokenType> left = queuedASTs.pop();
+				final ITree<TokenType> left  = queuedASTs.pop();
 
 				/*
 				 * Create a new AST
@@ -86,15 +87,31 @@ final class TokenTransformer<TokenType> implements Consumer<TokenType> {
 		}
 	}
 
+	/* The initial state of the transformer. */
 	private final IHolder<ConstructorState<TokenType>> initialState;
 
+	/* The predicate tot use to detect operators. */
 	private final Predicate<TokenType> operatorPredicate;
 
-	private final Predicate<TokenType> isSpecialOperator;
-	private final Function<TokenType, QueueFlattener<TokenType>> handleSpecialOperator;
+	/* The predicate for detecting special operators. */
+	private final Predicate<TokenType>				isSpecialOperator;
+	/* The function for handling special operators. */
+	private final Function<TokenType, QueueFlattener<TokenType>>	handleSpecialOperator;
 
-	/*
+	/**
 	 * Create a new transformer
+	 *
+	 * @param initialState
+	 * 	The initial state of the transformer.
+	 *
+	 * @param operatorPredicate
+	 * 	The predicate to use to identify operators.
+	 *
+	 * @param isSpecialOperator
+	 * 	The predicate used to identify special operators.
+	 *
+	 * @param handleSpecialOperator
+	 * 	The function used for handling special operators.
 	 */
 	public TokenTransformer(final IHolder<ConstructorState<TokenType>> initialState,
 			final Predicate<TokenType> operatorPredicate, final Predicate<TokenType> isSpecialOperator,
diff --git a/base/src/main/java/bjc/utils/parserutils/TokenUtils.java b/base/src/main/java/bjc/utils/parserutils/TokenUtils.java
index dba9b74..6d27202 100644
--- a/base/src/main/java/bjc/utils/parserutils/TokenUtils.java
+++ b/base/src/main/java/bjc/utils/parserutils/TokenUtils.java
@@ -37,25 +37,30 @@ public class TokenUtils {
 	/*
 	 * Patterns and pattern parts.
 	 */
-	private static String rPossibleEscapeString = getRegex("possibleStringEscape");
 
-	private static Pattern possibleEscapePatt = Pattern.compile(rPossibleEscapeString);
+	/* Possible string escapes. */
+	private static String  rPossibleEscapeString = getRegex("possibleStringEscape");
+	private static Pattern possibleEscapePatt    = Pattern.compile(rPossibleEscapeString);
 
-	private static String rShortEscape = getRegex("shortFormStringEscape");
-	private static String rOctalEscape = getRegex("octalStringEscape");
-	private static String rUnicodeEscape = getRegex("unicodeStringEscape");
+	/* Non-single char escapes. */
+	private static String	rShortEscape	= getRegex("shortFormStringEscape");
+	private static String	rOctalEscape	= getRegex("octalStringEscape");
+	private static String	rUnicodeEscape	= getRegex("unicodeStringEscape");
 
-	private static String rEscapeString = applyFormat("stringEscape", rShortEscape, rOctalEscape, rUnicodeEscape);
+	/* All string escapes. */
+	private static String  rEscapeString = applyFormat("stringEscape",
+			rShortEscape, rOctalEscape, rUnicodeEscape);
 
 	private static Pattern escapePatt = Pattern.compile(rEscapeString);
 
-	private static String rDoubleQuoteString = applyFormat("doubleQuotes", getRegex("nonStringEscape"),
-			rPossibleEscapeString);
+	private static String rDoubleQuoteString = applyFormat("doubleQuotes",
+			getRegex("nonStringEscape"), rPossibleEscapeString);
 
 	private static Pattern doubleQuotePatt = Pattern.compile(rDoubleQuoteString);
 
 	private static Pattern quotePatt = getCompiledRegex("unescapedQuote");
 
+	/* This may do something. */
 	//private static Pattern intLitPattern = getCompiledRegex("intLiteral");
 
 	/**
@@ -64,24 +69,30 @@ public class TokenUtils {
 	 * Splits a string around instances of java-style double-quoted strings.
 	 *
 	 * @param inp
+<<<<<<< Updated upstream
 	 *        The string to split.
+=======
+	 * 	The string to split.
+>>>>>>> Stashed changes
 	 *
-	 * @return An list containing alternating bits of the string and the
-	 *         embedded double-quoted strings that separated them.
+	 * @return 
+	 * 	An list containing alternating bits of the string and the embedded double-quoted
+	 * 	strings that separated them.
 	 */
 	public static List<String> removeDQuotedStrings(final String inp) {
-		if(inp == null) throw new NullPointerException("inp must not be null");
+		/* Validate input. */
+		if (inp == null) throw new NullPointerException("inp must not be null");
 
 		/*
 		 * What we need for piece-by-piece string building
 		 */
-		StringBuffer work = new StringBuffer();
+		StringBuffer work      = new StringBuffer();
 		final List<String> res = new LinkedList<>();
 
 		/*
 		 * Matcher for proper strings and single quotes.
 		 */
-		final Matcher mt = doubleQuotePatt.matcher(inp);
+		final Matcher mt   = doubleQuotePatt.matcher(inp);
 		final Matcher corr = quotePatt.matcher(inp);
 
 		if(corr.find() && !corr.find()) {
@@ -95,7 +106,8 @@ public class TokenUtils {
 			throw new IllegalArgumentException(msg);
 		}
 
-		while(mt.find()) {
+		/* Go through every found string. */
+		while (mt.find()) {
 			/*
 			 * Remove the string until the quoted string.
 			 */
@@ -145,6 +157,9 @@ public class TokenUtils {
 	/**
 	 * Replace escape characters with their actual equivalents.
 	 *
+	 * Use {@link StringDescaper} for customizable escapes. This only handles the ones that are
+	 * built into Java strings.
+	 *
 	 * @param inp
 	 *        The string to replace escape sequences in.
 	 *
@@ -152,17 +167,19 @@ public class TokenUtils {
 	 *         characters.
 	 */
 	public static String descapeString(final String inp) {
-		if(inp == null) throw new NullPointerException("inp must not be null");
+		/* Validate input. */
+		if (inp == null) throw new NullPointerException("inp must not be null");
 
 		/*
 		 * Prepare the buffer and escape finder.
 		 */
-		final StringBuffer work = new StringBuffer();
+		final StringBuffer work            = new StringBuffer();
 		final Matcher possibleEscapeFinder = possibleEscapePatt.matcher(inp);
-		final Matcher escapeFinder = escapePatt.matcher(inp);
+		final Matcher escapeFinder         = escapePatt.matcher(inp);
 
-		while(possibleEscapeFinder.find()) {
-			if(!escapeFinder.find()) {
+		/* Go through all possible escapes. */
+		while (possibleEscapeFinder.find()) {
+			if (!escapeFinder.find()) {
 				/*
 				 * Found a possible escape that isn't actually
 				 * an escape.
@@ -209,13 +226,19 @@ public class TokenUtils {
 				escapeRep = "\\";
 				break;
 			default:
+<<<<<<< Updated upstream
 				if(escapeSeq.startsWith("u")) {
+=======
+				/* Handle a non-short form escape. */
+				if (escapeSeq.startsWith("u")) {
+>>>>>>> Stashed changes
 					escapeRep = handleUnicodeEscape(escapeSeq.substring(1));
 				} else {
 					escapeRep = handleOctalEscape(escapeSeq);
 				}
 			}
 
+			/* Replace the escape with its representation. */
 			escapeFinder.appendReplacement(work, escapeRep);
 		}
 
diff --git a/base/src/main/java/bjc/utils/parserutils/TreeConstructor.java b/base/src/main/java/bjc/utils/parserutils/TreeConstructor.java
index 7bff43e..960e61a 100644
--- a/base/src/main/java/bjc/utils/parserutils/TreeConstructor.java
+++ b/base/src/main/java/bjc/utils/parserutils/TreeConstructor.java
@@ -13,7 +13,7 @@ import bjc.utils.data.Pair;
 import bjc.utils.funcdata.IList;
 
 /**
- * Creates a parse tree from a postfix expression
+ * Creates a parse tree from a postfix expression.
  *
  * @author ben
  *
@@ -23,15 +23,13 @@ public class TreeConstructor {
 	 * Alias interface for special operator types.
 	 *
 	 * @param <TokenType>
-	 *        The token type of the tree.
+	 * 	The token type of the tree.
 	 */
 	public interface QueueFlattener<TokenType> extends Function<Deque<ITree<TokenType>>, ITree<TokenType>> {
 
 	}
 
-	/*
-	 * Alias for constructor state.
-	 */
+	/* Alias for constructor state. */
 	static final class ConstructorState<TokenType> extends Pair<Deque<ITree<TokenType>>, ITree<TokenType>> {
 		public ConstructorState(final Deque<ITree<TokenType>> left, final ITree<TokenType> right) {
 			super(left, right);
@@ -43,23 +41,25 @@ public class TreeConstructor {
 	}
 
 	/**
-	 * Construct a tree from a list of tokens in postfix notation
+	 * Construct a tree from a list of tokens in postfix notation.
 	 *
 	 * Only binary operators are accepted.
 	 *
 	 * @param <TokenType>
-	 *        The elements of the parse tree
+	 * 	The elements of the parse tree.
+	 *
 	 * @param tokens
-	 *        The list of tokens to build a tree from
+	 * 	The list of tokens to build a tree from.
+	 *
 	 * @param isOperator
-	 *        The predicate to use to determine if something is a operator
-	 * @return A AST from the expression
+	 * 	The predicate to use to determine if something is a
+	 * 	operator.
+	 *
+	 * @return A AST from the expression.
 	 */
 	public static <TokenType> ITree<TokenType> constructTree(final IList<TokenType> tokens,
 			final Predicate<TokenType> isOperator) {
-		/*
-		 * Construct a tree with no special operators
-		 */
+		/* Construct a tree with no special operators */
 		return constructTree(tokens, isOperator, op -> false, null);
 	}
 
@@ -85,7 +85,7 @@ public class TreeConstructor {
 	 * @param handleSpecialOperator
 	 *        The function to use to handle special case operators.
 	 *
-	 * @return A AST from the expression
+	 * @return A AST from the expression.
 	 *
 	 */
 	public static <TokenType> ITree<TokenType> constructTree(final IList<TokenType> tokens,
@@ -101,23 +101,19 @@ public class TreeConstructor {
 		else if(isSpecialOperator == null)
 			throw new NullPointerException("Special operator determiner must not be null");
 
-		/*
-		 * Here is the state for the tree construction
-		 */
-		final IHolder<ConstructorState<TokenType>> initialState = new Identity<>(
-				new ConstructorState<>(new LinkedList<>(), null));
+		final ConstructorState<TokenType> cstate = new ConstructorState<>(
+				new LinkedList<>(), null);
 
-		/*
-		 * Transform each of the tokens
-		 */
-		tokens.forEach(new TokenTransformer<>(initialState, isOperator, isSpecialOperator,
-				handleSpecialOperator));
+		/* Here is the state for the tree construction */
+		final IHolder<ConstructorState<TokenType>> initialState = new Identity<>(cstate);
 
-		/*
-		 * Grab the tree from the state
-		 */
-		return initialState.unwrap(pair -> {
-			return pair.getRight();
-		});
+		/* Transform each of the tokens */
+		final TokenTransformer trans = new TokenTransformer<>(initialState,
+				isOperator, isSpecialOperator, handleSpecialOperator);
+
+		tokens.forEach(trans);
+
+		/* Grab the tree from the state */
+		return initialState.unwrap(pair -> pair.getRight());
 	}
 }