Continue work on docs

src/main/java/com/laytonsmith/PureUtilities/ArgumentSuite.java

@@ -13,29 +13,29 @@
 
 /**
  * An ArgumentSuite is an ArgumentParser that supports "modes".
- * 
+ *
  * A mode is a required parameter that causes a fully separate argument parser to
  * be used to parse the remaining arguments. This allows for finer control over
  * mutually exclusive parameters in both the documentation and the validation, as
  * well as wider support for traditional use cases.
- * 
+ *
  */
 public class ArgumentSuite {
-	
+
 	private Map<String, ArgumentParser> suite;
 	private Map<String, String> aliases;
 	private String description;
-	
+
 	public ArgumentSuite(){
 		suite = new LinkedHashMap<String, ArgumentParser>();
 		aliases = new LinkedHashMap<String, String>();
 	}
-	
+
 	/**
 	 * Adds a new mode. A mode name may contain dashes, which would look like normal
 	 * argument flags, but would actually be a mode. This is useful especially for a
 	 * --help command, which shows the ArgumentSuite's help.
-	 * @param modeName The name of this mode. This may not contain spaces. 
+	 * @param modeName The name of this mode. This may not contain spaces.
 	 * @param mode The sub-ArgumentParser that will be used when in this mode.
 	 * @throws IllegalArgumentException if the name of the mode contains spaces
 	 */
@@ -44,7 +44,7 @@ public ArgumentSuite addMode(String modeName, ArgumentParser mode){
 		suite.put(modeName, mode);
 		return this;
 	}
-	
+
 	/**
 	 * Adds a mode alias. This is the recommended behavior instead of adding the
 	 * same mode with a different name, because the built description is aware
@@ -53,30 +53,30 @@ public ArgumentSuite addMode(String modeName, ArgumentParser mode){
 	 * strictly need to exist yet.
 	 * @param alias
 	 * @param realModeName
-	 * @return 
+	 * @return
 	 */
 	public ArgumentSuite addModeAlias(String alias, String realModeName){
 		validateModeName(alias);
 		aliases.put(alias, realModeName);
 		return this;
 	}
-	
+
 	private void validateModeName(String modeName){
 		if(modeName.contains(" ")){
 			throw new IllegalArgumentException("The mode name may not contain a space.");
 		}
 	}
-	
+
 	/**
 	 * Adds a description, which is used in {@see #getBuiltDescription}
 	 * @param description
-	 * @return 
+	 * @return
 	 */
 	public ArgumentSuite addDescription(String description){
 		this.description = description;
 		return this;
 	}
-	
+
 	/**
 	 * Returns a mode that was previously registered.
 	 * @param name The name of the mode to get
@@ -90,17 +90,17 @@ public ArgumentParser getMode(String name){
 			throw new IllegalArgumentException("No mode by the name \"" + name + "\" has been registered.");
 		}
 	}
-	
+
 	/**
 	 * Selects the appropriate mode, and calls match on that ArgumentParser.
 	 * @param args The pre-parsed arguments
 	 * @param defaultMode The default mode, which will be used only if no arguments were passed in.
-	 * @return 
+	 * @return
 	 * @throws ResultUseException if the mode cannot be found, or if the sub-ArgumentParser
 	 * throws an exception.
 	 */
 	public ArgumentSuiteResults match(String [] args, String defaultMode) throws ResultUseException, ValidationException {
-		String [] nonModeArgs = new String[0];
+		String [] nonModeArgs = ArrayUtils.EMPTY_STRING_ARRAY;
 		String mode;
 		if(args.length > 1){
 			mode = args[0];
@@ -120,12 +120,12 @@ public ArgumentSuiteResults match(String [] args, String defaultMode) throws Res
 			throw new ResultUseException("Mode " + mode + " was not found.");
 		}
 	}
-	
+
 	/**
 	 * Selects the appropriate mode, and calls match on that ArgumentParser.
 	 * @param args The unparsed arguments
 	 * @param defaultMode The default mode, which will be used only if no arguments were passed in.
-	 * @return 
+	 * @return
 	 * @throws ResultUseException if the mode cannot be found, or if the sub-ArgumentParser
 	 * throws an exception.
 	 */
@@ -134,11 +134,11 @@ public ArgumentSuiteResults match(String args, String defaultMode) throws Result
 		//pass that to the other match
 		return match(ArgumentParser.lex(args).toArray(new String[]{}), defaultMode);
 	}
-	
+
 	/**
 	 * Returns a built description of this ArgumentSuite, which would be appropriate
 	 * to display if no arguments are passed in (or the mode name is help, -help, --help, etc)
-	 * @return 
+	 * @return
 	 */
 	public String getBuiltDescription(){
 		StringBuilder b = new StringBuilder();
@@ -165,14 +165,14 @@ public String getBuiltDescription(){
 		}
 		return b.toString();
 	}
-	
+
 	/**
 	 * A convenience method to get the real mode name registered for this
 	 * alias, or null if no such alias exists. If the alias is actually a mode,
 	 * it is simply returned. Useful for perhaps a help mode, to resolve the actual
 	 * mode named. If {@code alias} is null, null is returned.
 	 * @param alias
-	 * @return 
+	 * @return
 	 */
 	public String getModeFromAlias(String alias){
 		if(alias == null){
@@ -186,7 +186,7 @@ public String getModeFromAlias(String alias){
 			return null;
 		}
 	}
-	
+
 	/**
 	 * A convenience method to get the underlying ArgumentParser
 	 * based on the mode name given. Aliases will not suffice, but you
@@ -195,7 +195,7 @@ public String getModeFromAlias(String alias){
 	 * a help mode, to generically display a mode's help. If {@see mode}
 	 * is null, null is returned.
 	 * @param mode
-	 * @return 
+	 * @return
 	 */
 	public ArgumentParser getModeFromName(String mode){
 		if(mode == null){
@@ -207,7 +207,7 @@ public ArgumentParser getModeFromName(String mode){
 			return null;
 		}
 	}
-	
+
 	public static class ArgumentSuiteResults{
 		private ArgumentParser mode;
 		private ArgumentParserResults results;
@@ -217,33 +217,33 @@ private ArgumentSuiteResults(String modeName, ArgumentParser mode, ArgumentParse
 			this.mode = mode;
 			this.results = results;
 		}
-		
+
 		/**
 		 * Returns the name of the mode that was selected. (Not the alias)
-		 * @return 
+		 * @return
 		 */
 		public String getModeName(){
 			return modeName;
 		}
-		
+
 		/**
 		 * The ArgumentParser for the given mode. This will be a reference
 		 * to the mode passed in, so you can do == on it.
-		 * @return 
+		 * @return
 		 */
 		public ArgumentParser getMode(){
 			return mode;
 		}
-		
+
 		/**
 		 * The ArgumentParserResults for the ArgumentParser mode
-		 * @return 
+		 * @return
 		 */
 		public ArgumentParserResults getResults(){
 			return results;
 		}
 	}
-	
+
 	public static void main(String [] args){
 		ArgumentSuite suite = new ArgumentSuite();
 		ArgumentParser mode1 = ArgumentParser.GetParser();
@@ -289,13 +289,13 @@ public static void main(String [] args){
 		} catch (ResultUseException ex) {
 			showHelp(suite);
 		} catch (ValidationException ex) {
-			showHelp(suite);			
+			showHelp(suite);
 		}
 	}
-	
+
 	private static void showHelp(ArgumentSuite suite){
 		StreamUtils.GetSystemOut().println(suite.getBuiltDescription());
 		System.exit(1);
 	}
-	
+
 }

src/main/java/com/laytonsmith/PureUtilities/CommandExecutor.java

@@ -20,7 +20,7 @@
  *
  */
 public class CommandExecutor {
-	
+
 	/**
 	 * If you're in a hurry, and all you want is to get the output of System.out
 	 * from a process started with a string, this will do it for you.
@@ -38,7 +38,7 @@ public static String Execute(String command) throws InterruptedException, IOExce
 	 * @return
 	 */
 	public static String Execute(String [] args) throws InterruptedException, IOException{
-		final List<Byte> output = new ArrayList<Byte>();
+		final List<Byte> output = new ArrayList<>();
 		CommandExecutor c = new CommandExecutor(args);
 		OutputStream os = new BufferedOutputStream(new OutputStream() {
 
@@ -86,7 +86,7 @@ public CommandExecutor(String [] command){
 	}
 
 	/**
-	 * Starts this CommandExecutor. Afterwards, you can call .waitFor to wait
+	 * Starts this CommandExecutor. Afterwards, you can call {@link #waitFor()} to wait
 	 * until the process has finished.
 	 * @return
 	 * @throws IOException
@@ -226,6 +226,12 @@ public CommandExecutor setWorkingDir(File workingDir){
 		return this;
 	}
 
+	/**
+	 * Blocks until the underlying process has finished. If the process has already finished, the
+	 * method will return immediately.
+	 * @return The process's exit code
+	 * @throws InterruptedException
+	 */
 	public int waitFor() throws InterruptedException {
 		int ret = process.waitFor();
 		if(out != null){
@@ -248,7 +254,7 @@ public int waitFor() throws InterruptedException {
 	}
 
 	/**
-	 * Sets the inputs and outputs to be System.in, System.out, and StreamUtils.GetSystemErr().
+	 * Sets the inputs and outputs to be System.in, StreamUtils.GetSystemOut(), and StreamUtils.GetSystemErr().
 	 * @return
 	 */
 	public CommandExecutor setSystemInputsAndOutputs(){

src/main/java/com/laytonsmith/PureUtilities/Common/Annotations/CheckOverrides.java

@@ -2,6 +2,7 @@
 
 import com.laytonsmith.PureUtilities.ClassLoading.ClassDiscovery;
 import com.laytonsmith.PureUtilities.ClassLoading.ClassMirror.ClassMirror;
+import com.laytonsmith.PureUtilities.Common.ArrayUtils;
 import com.laytonsmith.PureUtilities.Common.ClassUtils;
 import com.laytonsmith.PureUtilities.Common.StreamUtils;
 import com.laytonsmith.PureUtilities.Common.StringUtils;
@@ -37,7 +38,7 @@
 @SupportedAnnotationTypes({"java.lang.Override", "com.laytonsmith.annotations.MustUseOverride"})
 @SupportedSourceVersion(SourceVersion.RELEASE_7)
 public class CheckOverrides extends AbstractProcessor {
-	
+
 	private static final boolean enabled = true;
 
 	private static Map<Class, Set<Method>> methods = null;
@@ -92,7 +93,7 @@ public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment
 						String inner = m.group(1);
 						String[] args;
 						if ("".equals(inner.trim())) {
-							args = new String[0];
+							args = ArrayUtils.EMPTY_STRING_ARRAY;
 						} else {
 							//Take out generics, since we can't really deal with them, and they make parsing
 							//the args harder.
@@ -320,7 +321,7 @@ private static Class getClassFromName(String className) throws ClassNotFoundExce
 	private static void setup() {
 		if (methods == null) {
 			methods = new HashMap<>();
-			
+
 			List<ClassMirror<?>> classes = ClassDiscovery.getDefaultInstance().getKnownClasses(ClassDiscovery.GetClassContainer(CheckOverrides.class));
 			for (ClassMirror cm : classes) {
 				Class c = cm.loadClass(CheckOverrides.class.getClassLoader(), false);

src/main/java/com/laytonsmith/PureUtilities/Common/ArrayUtils.java

@@ -106,6 +106,12 @@ public class ArrayUtils {
 	 * as a "default" value for an array, consider using this instead to increase performance.
 	 */
 	public static final Boolean[] EMPTY_BOOLEAN_OBJ_ARRAY = new Boolean[0];
+	/**
+	 * Instantiating a new 0 length array is *usually* inefficient, unless you
+	 * are doing reference comparisons later. If you are generating it simply to use
+	 * as a "default" value for an array, consider using this instead to increase performance.
+	 */
+	public static final String[] EMPTY_STRING_ARRAY = new String[0];
 
 
 	/***************************************************************************

src/main/java/com/laytonsmith/PureUtilities/Common/StackTraceUtils.java

@@ -3,27 +3,50 @@
 import java.io.PrintWriter;
 import java.io.StringWriter;
 import java.io.Writer;
+import java.util.logging.Level;
+import java.util.logging.Logger;
 
 /**
  *
- * 
+ *
  */
 public class StackTraceUtils {
-
-	private StackTraceUtils(){}
-
-    public static String GetStacktrace(Throwable t){
-        final Writer result = new StringWriter();
-		final PrintWriter printWriter = new PrintWriter(result);
-		boolean first = true;
-		Throwable tt = t;
-		do {
-			if(!first){
-				printWriter.append("Caused by: ");
-			}
-			first = false;
-			tt.printStackTrace(printWriter);
-		} while((tt = tt.getCause()) != null);
-        return result.toString();
+
+    private StackTraceUtils() {
+    }
+
+    public static String GetStacktrace(Throwable t) {
+	final Writer result = new StringWriter();
+	final PrintWriter printWriter = new PrintWriter(result);
+	boolean first = true;
+	Throwable tt = t;
+	do {
+	    if (!first) {
+		printWriter.append("Caused by: ");
+	    }
+	    first = false;
+	    tt.printStackTrace(printWriter);
+	} while ((tt = tt.getCause()) != null);
+	return result.toString();
+    }
+
+    public static Class<?> getCallingClass() {
+	try {
+	    // This is the class that called us. Calls may bounce around that class,
+	    // but we ultimately want to return that class that called the original
+	    // method within this class.
+	    StackTraceElement[] st = Thread.currentThread().getStackTrace();
+	    String doNotReturn = st[2].getClassName();
+	    for(int i = 3; i < st.length; i++) {
+		if(!st[i].getClassName().equals(doNotReturn)) {
+		    return Class.forName(st[i].getClassName());
+		}
+	    }
+	    // The only way this can get here is if this were the bootstrap class.
+	    // I doubt the JVM is calling us first thing, so just throw an Error.
+	    throw new Error();
+	} catch (ClassNotFoundException ex) {
+	    throw new RuntimeException(ex);
+	}
     }
 }