Formatting/Documentation

7 files changed, 282 insertions, 7 deletions

diff --git a/dice-lang/src/bjc/dicelang/dice/CompoundDie.java b/dice-lang/src/bjc/dicelang/dice/CompoundDie.java
index 16aec76..a20095a 100644
--- a/dice-lang/src/bjc/dicelang/dice/CompoundDie.java
+++ b/dice-lang/src/bjc/dicelang/dice/CompoundDie.java
@@ -1,31 +1,53 @@
 package bjc.dicelang.dice;

 

+/**

+ * A die whose rolls result from concatenating two other rolls together.

+ *

+ * @author Ben Culkin

+ */

 public class CompoundDie implements Die {

+	/*

+	 * The dice that form this die

+	 */

 	private Die left;

 	private Die right;

 

+	/**

+	 * Create a new compound die.

+	 *

+	 * @param lft The left die

+	 * @param rght The right die

+	 */

 	public CompoundDie(Die lft, Die rght) {

 		left = lft;

 		right = rght;

 	}

 

+	@Override

 	public boolean canOptimize() {

 		return left.canOptimize() && right.canOptimize();

 	}

 

+	@Override

 	public long optimize() {

 		return Long.parseLong(left.optimize() + "" + right.optimize());

 	}

 

+	@Override

 	public long roll() {

 		return Long.parseLong(left.roll() + "" + right.roll());

 	}

 

+	@Override

 	public long rollSingle() {

+		/*

+		 * We're only one die, we can't be split

+		 */

 		return roll();

 	}

 

+	@Override

 	public String toString() {

 		return left.toString() + "c" + right.toString();

 	}

-}
\ No newline at end of file
+}

diff --git a/dice-lang/src/bjc/dicelang/dice/CompoundingDie.java b/dice-lang/src/bjc/dicelang/dice/CompoundingDie.java
index 9744650..3291b52 100644
--- a/dice-lang/src/bjc/dicelang/dice/CompoundingDie.java
+++ b/dice-lang/src/bjc/dicelang/dice/CompoundingDie.java
@@ -2,16 +2,37 @@ package bjc.dicelang.dice;
 

 import java.util.function.Predicate;

 

+/**

+ * Implements a compounding die.

+ *

+ * This means that the source will be rolled, and then more single rolls will be

+ * added while it meets a qualification.

+ *

+ * @author Ben Culkin

+ */

 public class CompoundingDie implements Die {

 	private Die source;

 

 	private Predicate<Long> compoundOn;

 	private String          compoundPattern;

 

+	/**

+	 * Create a new compounding die with no pattern.

+	 *

+	 * @param src The die to compound from

+	 * @param compound The conditions to compound on

+	 */

 	public CompoundingDie(Die src, Predicate<Long> compound) {

 		this(src, compound, null);

 	}

 

+	/**

+	 * Create a new compounding die with a specified pattern.

+	 *

+	 * @param src The die to compound from

+	 * @param compound The conditions to compound on

+	 * @param patt The string pattern the condition came from, for printing

+	 */

 	public CompoundingDie(Die src, Predicate<Long> compound, String patt) {

 		source = src;

 

@@ -19,14 +40,17 @@ public class CompoundingDie implements Die {
 		compoundPattern = patt;

 	}

 

+	@Override

 	public boolean canOptimize() {

 		return source.canOptimize() && source.optimize() == 0;

 	}

 

+	@Override

 	public long optimize() {

 		return 0;

 	}

 

+	@Override

 	public long roll() {

 		long res = source.roll();

 		long oldRes = res;

@@ -40,7 +64,11 @@ public class CompoundingDie implements Die {
 		return res;

 	}

 

+	@Override

 	public long rollSingle() {

+		/*

+		 * Just compound on a single roll

+		 */

 		long res = source.rollSingle();

 		long oldRes = res;

 

@@ -53,6 +81,7 @@ public class CompoundingDie implements Die {
 		return res;

 	}

 

+	@Override

 	public String toString() {

 		if(compoundPattern == null) {

 			return source + "!!";

@@ -60,4 +89,4 @@ public class CompoundingDie implements Die {
 			return source + "!!" + compoundPattern;

 		}

 	}

-}
\ No newline at end of file
+}

diff --git a/dice-lang/src/bjc/dicelang/dice/DiceBox.java b/dice-lang/src/bjc/dicelang/dice/DiceBox.java
index 4c0641a..92e58af 100644
--- a/dice-lang/src/bjc/dicelang/dice/DiceBox.java
+++ b/dice-lang/src/bjc/dicelang/dice/DiceBox.java
@@ -4,21 +4,43 @@ import java.util.Random;
 import java.util.function.Predicate;
 import java.util.regex.Pattern;
 
+/**
+ * Contains static methods for producing dice from strings.
+ *
+ * @author Ben Culkin
+ */
 public class DiceBox {
 	static final Random rng = new Random();
 
+	/**
+	 * Parse a die expression from a string.
+	 *
+	 * @return The die expression from the string, or null if it wasn't one
+	 */
 	public static DieExpression parseExpression(String exp) {
+		/*
+		 * Only bother will valid expressions
+		 */
 		if(!isValidExpression(exp)) return null;
 
 		if(scalarDiePattern.matcher(exp).matches()) {
+			/*
+			 * Parse scalar die
+			 */
 			Die scal = new ScalarDie(Long.parseLong(exp.substring(0, exp.indexOf('s'))));
 
 			return new DieExpression(scal);
 		} else if(simpleDiePattern.matcher(exp).matches()) {
+			/*
+			 * Parse simple die groups
+			 */
 			String[] dieParts = exp.split("d");
 
 			long right = Long.parseLong(dieParts[1]);
 			if(dieParts[0].equals("")) {
+				/*
+				 * Handle short-form expressions.
+				 */
 				Die scal = new SimpleDie(1, right);
 				return new DieExpression(scal);
 			} else {
@@ -26,10 +48,16 @@ public class DiceBox {
 				return new DieExpression(scal);
 			}
 		} else if(fudgeDiePattern.matcher(exp).matches()) {
+			/*
+			 * Parse fudge dice
+			 */
 			String nDice = exp.substring(0, exp.indexOf('d'));
 
 			return new DieExpression(new FudgeDie(Long.parseLong(nDice)));
 		} else if(compoundDiePattern.matcher(exp).matches()) {
+			/*
+			 * Parse compound die expressions
+			 */
 			String[] dieParts = exp.split("c");
 
 			DieExpression left  = parseExpression(dieParts[0]);
@@ -37,6 +65,9 @@ public class DiceBox {
 
 			return new DieExpression(new CompoundDie(left.scalar, right.scalar));
 		} else if(compoundingDiePattern.matcher(exp).matches()) {
+			/*
+			 * Parse compounding die expressions
+			 */
 			String[] dieParts = exp.split("!!");
 
 			DieExpression   left  = parseExpression(dieParts[0]);
@@ -45,6 +76,9 @@ public class DiceBox {
 			Die scal = new CompoundingDie(left.scalar, right, dieParts[1]);
 			return new DieExpression(scal);
 		} else if(explodingDiePattern.matcher(exp).matches()) {
+			/*
+			 * Parse exploding die expressions
+			 */
 			String[] dieParts = exp.split("!");
 
 			DieExpression   left  = parseExpression(dieParts[0]);
@@ -53,6 +87,9 @@ public class DiceBox {
 			DieList lst = new ExplodingDice(left.scalar, right, dieParts[1], false);
 			return new DieExpression(lst);
 		} else if(penetratingDiePattern.matcher(exp).matches()) {
+			/*
+			 * Parse penetrating die expressions
+			 */
 			String[] dieParts = exp.split("p!");
 
 			DieExpression   left  = parseExpression(dieParts[0]);
@@ -61,6 +98,9 @@ public class DiceBox {
 			DieList lst = new ExplodingDice(left.scalar, right, dieParts[1], true);
 			return new DieExpression(lst);
 		} else if(diceListPattern.matcher(exp).matches()) {
+			/*
+			 * Parse simple die lists
+			 */
 			String[] dieParts = exp.split("dl");
 
 			DieExpression left  = parseExpression(dieParts[0]);
@@ -70,39 +110,101 @@ public class DiceBox {
 			return new DieExpression(lst);
 		}
 
-		// @TODO give a specific error message
 		return null;
 	}
 
+	/*
+	 * The strings and patterns used for matching
+	 */
+
+	/*
+	 * Defines a comparison predicate
+	 */
 	private static final String comparePoint         = "[<>=]\\d+";
 
+	/*
+	 * Defines a scalar die.
+	 *
+	 * This is just a number.
+	 */
 	private static final String  scalarDie          = "[\\+\\-]?\\d+sd";
 	private static final Pattern scalarDiePattern   = Pattern.compile("\\A" + scalarDie + "\\Z");
 
+	/*
+	 * Defines a simple die.
+	 *
+	 * This is a group of one or more dice of the same size.
+	 */
 	private static final String  simpleDie           = "(?:\\d+)?d\\d+";
 	private static final Pattern simpleDiePattern    = Pattern.compile("\\A" + simpleDie + "\\Z");
 
+	/*
+	 * Defines a fudge die.
+	 *
+	 * This is like a simple die, but all the die give -1, 0, or 1 as
+	 * results.
+	 */
 	private static final String  fudgeDie            = "(?:\\d+)?dF";
 	private static final Pattern fudgeDiePattern     = Pattern.compile("\\A" + fudgeDie + "\\Z");
 
+	/*
+	 * Defines a compound die.
+	 *
+	 * This is like using two d10's to simulate a d100
+	 */
 	private static final String  compoundDie         = simpleDie + "c(?:(?:" + simpleDie + ")|(?:\\d+))";
 	private static final Pattern compoundDiePattern  = Pattern.compile("\\A" + compoundDie + "\\Z");
 
+	/*
+	 * Defines a compound group.
+	 *
+	 * This is used for forming die list type expressions.
+	 */
 	private static final String  compoundGroup       = "(?:(?:" + scalarDie + ")|(?:" + simpleDie + ")|(?:"
 		+ compoundDie + ")|(?:" + fudgeDie +"))";
 
+	/*
+	 * Defines a compounding die.
+	 *
+	 * This is like an exploding die, but is a single die, not a group of
+	 * them.
+	 */
 	private static final String  compoundingDie        = compoundGroup + "!!" + comparePoint;
 	private static final Pattern compoundingDiePattern = Pattern.compile("\\A" + compoundingDie + "\\Z");
 
+	/*
+	 * Defines an exploding die.
+	 *
+	 * This is a die that you reroll the component of if it meets a certain
+	 * condition.
+	 */
 	private static final String  explodingDie        = compoundGroup + "!" + comparePoint;
 	private static final Pattern explodingDiePattern = Pattern.compile("\\A" + explodingDie + "\\Z");
 
+	/*
+	 * Defines a penetrating die.
+	 *
+	 * This is like an exploding die, but the exploded result gets a -1
+	 * penalty.
+	 */
 	private static final String  penetratingDie        = compoundGroup + "!" + comparePoint;
 	private static final Pattern penetratingDiePattern = Pattern.compile("\\A" + penetratingDie + "\\Z");
 
+	/*
+	 * Defines a die list.
+	 *
+	 * This is an array of dice of the specified size
+	 */
 	private static final String  diceList            = compoundGroup + "dl" + compoundGroup;
 	private static final Pattern diceListPattern     = Pattern.compile("\\A" + diceList + "\\Z");
 
+	/**
+	 * Check if a given string is a valid die expression.
+	 *
+	 * @param exp The string to check validity of.
+	 *
+	 * @return Whether or not the string is a valid command
+	 */
 	public static boolean isValidExpression(String exp) {
 		if(scalarDiePattern.matcher(exp).matches()) {
 			return true;
@@ -125,6 +227,9 @@ public class DiceBox {
 		}
 	}
 
+	/*
+	 * Derive a predicate from a compare point
+	 */
 	private static Predicate<Long> deriveCond(String patt) {
 		long            num  = Long.parseLong(patt.substring(1));
 
diff --git a/dice-lang/src/bjc/dicelang/dice/Die.java b/dice-lang/src/bjc/dicelang/dice/Die.java
index 9f839ed..22ba522 100644
--- a/dice-lang/src/bjc/dicelang/dice/Die.java
+++ b/dice-lang/src/bjc/dicelang/dice/Die.java
@@ -1,9 +1,37 @@
 package bjc.dicelang.dice;

 

+/**

+ * Represents one or more dice that produce a scalar result.

+ * 

+ * @author Ben Culkin

+ */

 public interface Die {

+	/**

+	 * Can this die be optimized to a single number?

+	 *

+	 * @return Whether this die can be optimized or not.

+	 */

 	boolean canOptimize();

+	/**

+	 * Optimize this die to a single number.

+	 *

+	 * Calling optimize on dice that return false for canOptimize produces

+	 * undefined behavior

+	 *

+	 * @return The optimized form of this die

+	 */

 	long    optimize();

 

+	/**

+	 * Roll this die.

+	 *

+	 * @return A possible roll of this die

+	 */

 	long roll();

+	/**

+	 * Roll only a single portion of this die.

+	 *

+	 * @return A possible roll of a single portion of this die.

+	 */

 	long rollSingle();

-}
\ No newline at end of file
+}

diff --git a/dice-lang/src/bjc/dicelang/dice/DieExpression.java b/dice-lang/src/bjc/dicelang/dice/DieExpression.java
index 3bf121b..81d0b7d 100644
--- a/dice-lang/src/bjc/dicelang/dice/DieExpression.java
+++ b/dice-lang/src/bjc/dicelang/dice/DieExpression.java
@@ -2,29 +2,57 @@ package bjc.dicelang.dice;
 

 import java.util.Arrays;

 

+/**

+ * Represents either a die or a die list

+ * 

+ * @author Ben Culkin

+ */

 public class DieExpression {

+	/**

+	 * Is this expression a list?

+	 */

 	public final boolean isList;

 

+	/**

+	 * The scalar value in this expression, if there is one.

+	 */

 	public Die     scalar;

+	/**

+	 * The list value in this expression, if there is one.

+	 */

 	public DieList list;

 

+	/**

+	 * Create a scalar die expression.

+	 *

+	 * @param scal The scalar value of this expression.

+	 */

 	public DieExpression(Die scal) {

 		isList = false;

 		scalar = scal;

 	}

 

+	/**

+	 * Create a list die expression.

+	 *

+	 * @param lst The list value of this expression.

+	 */

 	public DieExpression(DieList lst) {

 		isList = true;

 		list   = lst;

 	}

 

+	@Override

 	public String toString() {

 		if(isList) return list.toString();

 		else       return scalar.toString();

 	}

 

+	/**

+	 * Get the value of this expression as a string.

+	 */

 	public String value() {

 		if(isList) return Arrays.toString(list.roll());

 		else       return Long.toString(scalar.roll());

 	}

-}
\ No newline at end of file
+}

diff --git a/dice-lang/src/bjc/dicelang/dice/DieList.java b/dice-lang/src/bjc/dicelang/dice/DieList.java
index a55f2b9..5454759 100644
--- a/dice-lang/src/bjc/dicelang/dice/DieList.java
+++ b/dice-lang/src/bjc/dicelang/dice/DieList.java
@@ -1,8 +1,30 @@
 package bjc.dicelang.dice;

 

+/**

+ * Represents a group of dice.

+ *

+ * @author Ben Culkin.

+ */

 public interface DieList {

+	/**

+	 * Can this list be optimized?

+	 *

+	 * @return Whether or not this list cna be optimized.

+	 */

 	boolean canOptimize();

+	/**

+	 * Optimize this list, if it can be done.

+	 *

+	 * Invoking this on unoptimizable expression is undefined.

+	 *

+	 * @return The optimized form of this list.

+	 */

 	long[]  optimize();

 

+	/**

+	 * Roll this group of dice.

+	 *

+	 * @param A possible roll of this group.

+	 */

 	long[] roll();

-}
\ No newline at end of file
+}

diff --git a/dice-lang/src/bjc/dicelang/dice/ExplodingDice.java b/dice-lang/src/bjc/dicelang/dice/ExplodingDice.java
index 6ab9902..59e739e 100644
--- a/dice-lang/src/bjc/dicelang/dice/ExplodingDice.java
+++ b/dice-lang/src/bjc/dicelang/dice/ExplodingDice.java
@@ -4,21 +4,58 @@ import java.util.LinkedList;
 import java.util.List;

 import java.util.function.Predicate;

 

+/**

+ * An exploding die.

+ *

+ * Represents a die list that keeps getting another added die as long as a

+ * condition is met.

+ *

+ * @author Ben Culkin

+ */

 public class ExplodingDice implements DieList {

+	/*

+	 * The source die to use.

+	 */

 	private Die             source;

 

+	/*

+	 * The conditions for exploding.

+	 */

 	private Predicate<Long> explodeOn;

 	private String          explodePattern;

 	private boolean         explodePenetrates;

 

+	/**

+	 * Create a new exploding die.

+	 *

+	 * @param src The source die for exploding.

+	 * @param explode The condition to explode on.

+	 */

 	public ExplodingDice(Die src, Predicate<Long> explode) {

 		this(src, explode, null, false);

 	}

 

+	/**

+	 * Create a new exploding die that may penetrate.

+	 *

+	 * @param src The source die for exploding.

+	 * @param explode The condition to explode on.

+	 * @param penetrate Whether or not for explosions to penetrate (-1 to

+	 * exploded die).

+	 */

 	public ExplodingDice(Die src, Predicate<Long> explode, boolean penetrate) {

 		this(src, explode, null, penetrate);

 	}

 

+	/**

+	 * Create a new exploding die that may penetrate.

+	 *

+	 * @param src The source die for exploding.

+	 * @param explode The condition to explode on.

+	 * @param penetrate Whether or not for explosions to penetrate (-1 to

+	 * exploded die).

+	 * @param patt The string the condition came from, for printing.

+	 */

 	public ExplodingDice(Die src, Predicate<Long> explode, String patt,

 			boolean penetrate) {

 		source            = src;

@@ -27,14 +64,17 @@ public class ExplodingDice implements DieList {
 		explodePenetrates = penetrate;

 	}

 

+	@Override

 	public boolean canOptimize() {

 		return false;

 	}

 

+	@Override

 	public long[] optimize() {

 		return new long[0];

 	}

 

+	@Override

 	public long[] roll() {

 		long res = source.roll();

 		long oldRes = res;

@@ -60,6 +100,7 @@ public class ExplodingDice implements DieList {
 		return newRes;

 	}

 

+	@Override

 	public String toString() {

 		if(explodePattern == null) {

 			return source + (explodePenetrates ? "p" : "") + "!";

@@ -67,4 +108,4 @@ public class ExplodingDice implements DieList {
 			return source + (explodePenetrates ? "p" : "") + "!" + explodePattern;

 		}

 	}

-}
\ No newline at end of file
+}