From 8797d8ac3c961f9a4d8922461c185086f41816f9 Mon Sep 17 00:00:00 2001
From: TomyLobo <tomylobo@nurfuerspam.de>
Date: Sat, 29 Oct 2011 17:24:11 +0200
Subject: [PATCH] Added element comments to all classes of the expression
 parser.

Also fixed some id() implementations.
---
 .../worldedit/expression/Expression.java      | 24 +++++++++++++++++++
 .../expression/ExpressionException.java       |  5 ++++
 .../worldedit/expression/Identifiable.java    |  5 ++++
 .../worldedit/expression/lexer/Lexer.java     |  7 ++++++
 .../expression/lexer/LexerException.java      |  5 ++++
 .../lexer/tokens/CharacterToken.java          |  5 ++++
 .../lexer/tokens/IdentifierToken.java         |  5 ++++
 .../expression/lexer/tokens/KeywordToken.java |  7 +++++-
 .../expression/lexer/tokens/NumberToken.java  |  5 ++++
 .../lexer/tokens/OperatorToken.java           |  5 ++++
 .../expression/lexer/tokens/Token.java        |  5 ++++
 .../worldedit/expression/parser/Parser.java   |  7 ++++++
 .../expression/parser/ParserException.java    |  5 ++++
 .../expression/parser/ParserProcessors.java   |  5 ++++
 .../expression/parser/PrefixOperator.java     |  5 ++++
 .../expression/parser/PseudoToken.java        |  5 ++++
 .../expression/runtime/Constant.java          |  5 ++++
 .../runtime/EvaluationException.java          |  5 ++++
 .../expression/runtime/Function.java          |  8 +++++++
 .../expression/runtime/Functions.java         |  5 ++++
 .../worldedit/expression/runtime/LValue.java  |  5 ++++
 .../expression/runtime/Operators.java         |  5 ++++
 .../worldedit/expression/runtime/RValue.java  |  5 ++++
 .../expression/runtime/Sequence.java          |  8 +++++--
 .../expression/runtime/Variable.java          |  5 ++++
 25 files changed, 153 insertions(+), 3 deletions(-)

diff --git a/src/main/java/com/sk89q/worldedit/expression/Expression.java b/src/main/java/com/sk89q/worldedit/expression/Expression.java
index 236120838..d94045ea9 100644
--- a/src/main/java/com/sk89q/worldedit/expression/Expression.java
+++ b/src/main/java/com/sk89q/worldedit/expression/Expression.java
@@ -32,6 +32,30 @@ import com.sk89q.worldedit.expression.runtime.EvaluationException;
 import com.sk89q.worldedit.expression.runtime.RValue;
 import com.sk89q.worldedit.expression.runtime.Variable;
 
+/**
+ * Compiles and evaluates expressions.
+ *
+ * Supported operators:
+ * Logical: &&, ||, ! (unary)
+ * Bitwise: ~ (unary), >>, << 
+ * Arithmetic: +, -, *, /, % (modulo), ^ (power), - (unary), --, ++ (prefix only)
+ * Comparison: <=, >=, >, <, ==, !=, ~= (near)
+ *
+ * Supported functions: abs, acos, asin, atan, atan2, cbrt, ceil, cos, cosh, exp, floor, ln, log, log10, max, max, min, min, rint, round, sin, sinh, sqrt, tan, tanh
+ *
+ * Constants: e, pi
+ *
+ * To compile an equation, run <code>Expression.compile("expression here", "var1", "var2"...)</code>
+ * If you wish to run the equation multiple times, you can then optimize it, by calling myExpression.optimize();
+ * You can then run the equation as many times as you want by calling myExpression.evaluate(var1, var2...)
+ * You do not need to pass values for all variables specified while compiling.
+ * To query variables after evaluation, you can use myExpression.getVariable("variable name").
+ * To get a value out of these, use myVariable.getValue()
+ *
+ * Variables are also supported and can be set either by passing values to <code>evaluate</code>
+ *
+ * @author TomyLobo
+ */
 public class Expression {
     private final Map<String, RValue> variables = new HashMap<String, RValue>();
     private final String[] variableNames;
diff --git a/src/main/java/com/sk89q/worldedit/expression/ExpressionException.java b/src/main/java/com/sk89q/worldedit/expression/ExpressionException.java
index 503bfb648..00177bed8 100644
--- a/src/main/java/com/sk89q/worldedit/expression/ExpressionException.java
+++ b/src/main/java/com/sk89q/worldedit/expression/ExpressionException.java
@@ -19,6 +19,11 @@
 
 package com.sk89q.worldedit.expression;
 
+/**
+ * Thrown when there's a problem during any stage of the expression compilation or evaluation.
+ *
+ * @author TomyLobo
+ */
 public class ExpressionException extends Exception {
     private static final long serialVersionUID = 1L;
 
diff --git a/src/main/java/com/sk89q/worldedit/expression/Identifiable.java b/src/main/java/com/sk89q/worldedit/expression/Identifiable.java
index d904eea6b..331256ca5 100644
--- a/src/main/java/com/sk89q/worldedit/expression/Identifiable.java
+++ b/src/main/java/com/sk89q/worldedit/expression/Identifiable.java
@@ -19,6 +19,11 @@
 
 package com.sk89q.worldedit.expression;
 
+/**
+ * A common superinterface for everything passed to parser processors.
+ *
+ * @author TomyLobo
+ */
 public interface Identifiable {
     /**
      * Returns a character that helps identify the token, pseudo-token or invokable in question.
diff --git a/src/main/java/com/sk89q/worldedit/expression/lexer/Lexer.java b/src/main/java/com/sk89q/worldedit/expression/lexer/Lexer.java
index 9851c9341..a97f70bea 100644
--- a/src/main/java/com/sk89q/worldedit/expression/lexer/Lexer.java
+++ b/src/main/java/com/sk89q/worldedit/expression/lexer/Lexer.java
@@ -31,6 +31,13 @@ import java.util.regex.Pattern;
 
 import com.sk89q.worldedit.expression.lexer.tokens.*;
 
+/**
+ * Processes a string into a list of tokens.
+ *
+ * Tokens can be numbers, identifiers, operators and assorted other characters.
+ *
+ * @author TomyLobo
+ */
 public class Lexer {
     private final String expression;
     private int position = 0;
diff --git a/src/main/java/com/sk89q/worldedit/expression/lexer/LexerException.java b/src/main/java/com/sk89q/worldedit/expression/lexer/LexerException.java
index dc893088d..b403979fa 100644
--- a/src/main/java/com/sk89q/worldedit/expression/lexer/LexerException.java
+++ b/src/main/java/com/sk89q/worldedit/expression/lexer/LexerException.java
@@ -21,6 +21,11 @@ package com.sk89q.worldedit.expression.lexer;
 
 import com.sk89q.worldedit.expression.ExpressionException;
 
+/**
+ * Thrown when the lexer encounters a problem.
+ *
+ * @author TomyLobo
+ */
 public class LexerException extends ExpressionException {
     private static final long serialVersionUID = 1L;
 
diff --git a/src/main/java/com/sk89q/worldedit/expression/lexer/tokens/CharacterToken.java b/src/main/java/com/sk89q/worldedit/expression/lexer/tokens/CharacterToken.java
index 36dfe657d..ae91a8bff 100644
--- a/src/main/java/com/sk89q/worldedit/expression/lexer/tokens/CharacterToken.java
+++ b/src/main/java/com/sk89q/worldedit/expression/lexer/tokens/CharacterToken.java
@@ -19,6 +19,11 @@
 
 package com.sk89q.worldedit.expression.lexer.tokens;
 
+/**
+ * A single character that doesn't fit any of the other token categories.
+ *
+ * @author TomyLobo
+ */
 public class CharacterToken extends Token {
     public final char character;
 
diff --git a/src/main/java/com/sk89q/worldedit/expression/lexer/tokens/IdentifierToken.java b/src/main/java/com/sk89q/worldedit/expression/lexer/tokens/IdentifierToken.java
index 790824e9e..a4c7437d3 100644
--- a/src/main/java/com/sk89q/worldedit/expression/lexer/tokens/IdentifierToken.java
+++ b/src/main/java/com/sk89q/worldedit/expression/lexer/tokens/IdentifierToken.java
@@ -19,6 +19,11 @@
 
 package com.sk89q.worldedit.expression.lexer.tokens;
 
+/**
+ * An identifier
+ *
+ * @author TomyLobo
+ */
 public class IdentifierToken extends Token {
     public final String value;
 
diff --git a/src/main/java/com/sk89q/worldedit/expression/lexer/tokens/KeywordToken.java b/src/main/java/com/sk89q/worldedit/expression/lexer/tokens/KeywordToken.java
index d73d70db8..e76ace405 100644
--- a/src/main/java/com/sk89q/worldedit/expression/lexer/tokens/KeywordToken.java
+++ b/src/main/java/com/sk89q/worldedit/expression/lexer/tokens/KeywordToken.java
@@ -19,6 +19,11 @@
 
 package com.sk89q.worldedit.expression.lexer.tokens;
 
+/**
+ * A keyword
+ *
+ * @author TomyLobo
+ */
 public class KeywordToken extends Token {
     public final String value;
 
@@ -29,7 +34,7 @@ public class KeywordToken extends Token {
 
     @Override
     public char id() {
-        return 'i';
+        return 'k';
     }
 
     @Override
diff --git a/src/main/java/com/sk89q/worldedit/expression/lexer/tokens/NumberToken.java b/src/main/java/com/sk89q/worldedit/expression/lexer/tokens/NumberToken.java
index 1f4858e64..e0b72d18c 100644
--- a/src/main/java/com/sk89q/worldedit/expression/lexer/tokens/NumberToken.java
+++ b/src/main/java/com/sk89q/worldedit/expression/lexer/tokens/NumberToken.java
@@ -19,6 +19,11 @@
 
 package com.sk89q.worldedit.expression.lexer.tokens;
 
+/**
+ * A number
+ *
+ * @author TomyLobo
+ */
 public class NumberToken extends Token {
     public final double value;
 
diff --git a/src/main/java/com/sk89q/worldedit/expression/lexer/tokens/OperatorToken.java b/src/main/java/com/sk89q/worldedit/expression/lexer/tokens/OperatorToken.java
index 655c2e65d..1108f2c08 100644
--- a/src/main/java/com/sk89q/worldedit/expression/lexer/tokens/OperatorToken.java
+++ b/src/main/java/com/sk89q/worldedit/expression/lexer/tokens/OperatorToken.java
@@ -19,6 +19,11 @@
 
 package com.sk89q.worldedit.expression.lexer.tokens;
 
+/**
+ * A unary or binary operator.
+ *
+ * @author TomyLobo
+ */
 public class OperatorToken extends Token {
     public final String operator;
 
diff --git a/src/main/java/com/sk89q/worldedit/expression/lexer/tokens/Token.java b/src/main/java/com/sk89q/worldedit/expression/lexer/tokens/Token.java
index 4957a3499..b01743814 100644
--- a/src/main/java/com/sk89q/worldedit/expression/lexer/tokens/Token.java
+++ b/src/main/java/com/sk89q/worldedit/expression/lexer/tokens/Token.java
@@ -21,6 +21,11 @@ package com.sk89q.worldedit.expression.lexer.tokens;
 
 import com.sk89q.worldedit.expression.Identifiable;
 
+/**
+ * A token. The lexer generates these to make the parser's job easier.
+ *
+ * @author TomyLobo
+ */
 public abstract class Token implements Identifiable {
     private final int position;
 
diff --git a/src/main/java/com/sk89q/worldedit/expression/parser/Parser.java b/src/main/java/com/sk89q/worldedit/expression/parser/Parser.java
index 5429bb667..d84f49854 100644
--- a/src/main/java/com/sk89q/worldedit/expression/parser/Parser.java
+++ b/src/main/java/com/sk89q/worldedit/expression/parser/Parser.java
@@ -34,6 +34,13 @@ import com.sk89q.worldedit.expression.runtime.Constant;
 import com.sk89q.worldedit.expression.runtime.Functions;
 import com.sk89q.worldedit.expression.runtime.RValue;
 
+/**
+ * Processes a list of tokens into an executable tree.
+ *
+ * Tokens can be numbers, identifiers, operators and assorted other characters.
+ *
+ * @author TomyLobo
+ */
 public class Parser {
     private final class NullToken extends Token {
         private NullToken(int position) {
diff --git a/src/main/java/com/sk89q/worldedit/expression/parser/ParserException.java b/src/main/java/com/sk89q/worldedit/expression/parser/ParserException.java
index 03b104e05..8203369f1 100644
--- a/src/main/java/com/sk89q/worldedit/expression/parser/ParserException.java
+++ b/src/main/java/com/sk89q/worldedit/expression/parser/ParserException.java
@@ -21,6 +21,11 @@ package com.sk89q.worldedit.expression.parser;
 
 import com.sk89q.worldedit.expression.ExpressionException;
 
+/**
+ * Thrown when the parser encounters a problem.
+ *
+ * @author TomyLobo
+ */
 public class ParserException extends ExpressionException {
     private static final long serialVersionUID = 1L;
 
diff --git a/src/main/java/com/sk89q/worldedit/expression/parser/ParserProcessors.java b/src/main/java/com/sk89q/worldedit/expression/parser/ParserProcessors.java
index 44fe216e9..5a49ffaa1 100644
--- a/src/main/java/com/sk89q/worldedit/expression/parser/ParserProcessors.java
+++ b/src/main/java/com/sk89q/worldedit/expression/parser/ParserProcessors.java
@@ -13,6 +13,11 @@ import com.sk89q.worldedit.expression.runtime.RValue;
 import com.sk89q.worldedit.expression.runtime.Operators;
 import com.sk89q.worldedit.expression.runtime.Sequence;
 
+/**
+ * Helper classfor Parser. Contains processors for statements and operators.
+ *
+ * @author TomyLobo
+ */
 public final class ParserProcessors {
     private static final Map<String, String> unaryOpMap = new HashMap<String, String>();
 
diff --git a/src/main/java/com/sk89q/worldedit/expression/parser/PrefixOperator.java b/src/main/java/com/sk89q/worldedit/expression/parser/PrefixOperator.java
index d710ffe9c..2a67bcde8 100644
--- a/src/main/java/com/sk89q/worldedit/expression/parser/PrefixOperator.java
+++ b/src/main/java/com/sk89q/worldedit/expression/parser/PrefixOperator.java
@@ -2,6 +2,11 @@ package com.sk89q.worldedit.expression.parser;
 
 import com.sk89q.worldedit.expression.lexer.tokens.OperatorToken;
 
+/**
+ * The parser uses this pseudo-token to mark operators as prefix operators.
+ *
+ * @author TomyLobo
+ */
 public class PrefixOperator extends PseudoToken {
     final String operator;
 
diff --git a/src/main/java/com/sk89q/worldedit/expression/parser/PseudoToken.java b/src/main/java/com/sk89q/worldedit/expression/parser/PseudoToken.java
index 43eab155f..05199be7a 100644
--- a/src/main/java/com/sk89q/worldedit/expression/parser/PseudoToken.java
+++ b/src/main/java/com/sk89q/worldedit/expression/parser/PseudoToken.java
@@ -21,6 +21,11 @@ package com.sk89q.worldedit.expression.parser;
 
 import com.sk89q.worldedit.expression.Identifiable;
 
+/**
+ * A pseudo-token, inserted by the parser instead of the lexer.
+ *
+ * @author TomyLobo
+ */
 public abstract class PseudoToken implements Identifiable {
     private final int position;
 
diff --git a/src/main/java/com/sk89q/worldedit/expression/runtime/Constant.java b/src/main/java/com/sk89q/worldedit/expression/runtime/Constant.java
index 13819b9d7..92d226134 100644
--- a/src/main/java/com/sk89q/worldedit/expression/runtime/Constant.java
+++ b/src/main/java/com/sk89q/worldedit/expression/runtime/Constant.java
@@ -19,6 +19,11 @@
 
 package com.sk89q.worldedit.expression.runtime;
 
+/**
+ * A constant.
+ *
+ * @author TomyLobo
+ */
 public final class Constant extends RValue {
     private final double value;
 
diff --git a/src/main/java/com/sk89q/worldedit/expression/runtime/EvaluationException.java b/src/main/java/com/sk89q/worldedit/expression/runtime/EvaluationException.java
index 4e016463e..94c6fd1a1 100644
--- a/src/main/java/com/sk89q/worldedit/expression/runtime/EvaluationException.java
+++ b/src/main/java/com/sk89q/worldedit/expression/runtime/EvaluationException.java
@@ -2,6 +2,11 @@ package com.sk89q.worldedit.expression.runtime;
 
 import com.sk89q.worldedit.expression.ExpressionException;
 
+/**
+ * Thrown when there's a problem during expression evaluation.
+ *
+ * @author TomyLobo
+ */
 public class EvaluationException extends ExpressionException {
     private static final long serialVersionUID = 1L;
 
diff --git a/src/main/java/com/sk89q/worldedit/expression/runtime/Function.java b/src/main/java/com/sk89q/worldedit/expression/runtime/Function.java
index aefab8599..b9b13b78d 100644
--- a/src/main/java/com/sk89q/worldedit/expression/runtime/Function.java
+++ b/src/main/java/com/sk89q/worldedit/expression/runtime/Function.java
@@ -24,7 +24,15 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.reflect.InvocationTargetException;
 import java.lang.reflect.Method;
 
+/**
+ * Wrapper for a Java method and its arguments (other Invokables)
+ *
+ * @author TomyLobo
+ */
 public class Function extends RValue {
+    /**
+     * Add this annotation on functions that don't always return the same value for the same inputs.
+     */
     @Retention(RetentionPolicy.RUNTIME)
     public @interface Dynamic { }
 
diff --git a/src/main/java/com/sk89q/worldedit/expression/runtime/Functions.java b/src/main/java/com/sk89q/worldedit/expression/runtime/Functions.java
index b79c44532..1a687011f 100644
--- a/src/main/java/com/sk89q/worldedit/expression/runtime/Functions.java
+++ b/src/main/java/com/sk89q/worldedit/expression/runtime/Functions.java
@@ -21,6 +21,11 @@ package com.sk89q.worldedit.expression.runtime;
 
 import java.util.Arrays;
 
+/**
+ * Contains all functions that can be used in expressions.
+ *
+ * @author TomyLobo
+ */
 public final class Functions {
     public static final Function getFunction(int position, String name, RValue... args) throws NoSuchMethodException {
         final Class<?>[] parameterTypes = (Class<?>[]) new Class[args.length];
diff --git a/src/main/java/com/sk89q/worldedit/expression/runtime/LValue.java b/src/main/java/com/sk89q/worldedit/expression/runtime/LValue.java
index 79681d4f0..e868bd800 100644
--- a/src/main/java/com/sk89q/worldedit/expression/runtime/LValue.java
+++ b/src/main/java/com/sk89q/worldedit/expression/runtime/LValue.java
@@ -19,6 +19,11 @@
 
 package com.sk89q.worldedit.expression.runtime;
 
+/**
+ * A value that can be used on the left side of an assignment.
+ *
+ * @author TomyLobo
+ */
 public abstract class LValue extends RValue {
     public LValue(int position) {
         super(position);
diff --git a/src/main/java/com/sk89q/worldedit/expression/runtime/Operators.java b/src/main/java/com/sk89q/worldedit/expression/runtime/Operators.java
index a68dcb523..c28e092fc 100644
--- a/src/main/java/com/sk89q/worldedit/expression/runtime/Operators.java
+++ b/src/main/java/com/sk89q/worldedit/expression/runtime/Operators.java
@@ -19,6 +19,11 @@
 
 package com.sk89q.worldedit.expression.runtime;
 
+/**
+ * Contains all unary and binary operators.
+ *
+ * @author TomyLobo
+ */
 public final class Operators {
     public static final Function getOperator(int position, String name, RValue lhs, RValue rhs) throws NoSuchMethodException {
         if (lhs instanceof LValue) {
diff --git a/src/main/java/com/sk89q/worldedit/expression/runtime/RValue.java b/src/main/java/com/sk89q/worldedit/expression/runtime/RValue.java
index 7bc49d95e..2b8bab984 100644
--- a/src/main/java/com/sk89q/worldedit/expression/runtime/RValue.java
+++ b/src/main/java/com/sk89q/worldedit/expression/runtime/RValue.java
@@ -21,6 +21,11 @@ package com.sk89q.worldedit.expression.runtime;
 
 import com.sk89q.worldedit.expression.Identifiable;
 
+/**
+ * A value that can be used on the right side of an assignment.
+ *
+ * @author TomyLobo
+ */
 public abstract class RValue implements Identifiable {
     private final int position;
 
diff --git a/src/main/java/com/sk89q/worldedit/expression/runtime/Sequence.java b/src/main/java/com/sk89q/worldedit/expression/runtime/Sequence.java
index 321ac44a8..8123cc9b7 100644
--- a/src/main/java/com/sk89q/worldedit/expression/runtime/Sequence.java
+++ b/src/main/java/com/sk89q/worldedit/expression/runtime/Sequence.java
@@ -22,6 +22,11 @@ package com.sk89q.worldedit.expression.runtime;
 import java.util.ArrayList;
 import java.util.List;
 
+/**
+ * A sequence of operations, usually separated by semicolons in the input stream.
+ *
+ * @author TomyLobo
+ */
 public class Sequence extends RValue {
     private final RValue[] sequence;
 
@@ -33,8 +38,7 @@ public class Sequence extends RValue {
 
     @Override
     public char id() {
-        // TODO Auto-generated method stub
-        return 0;
+        return 's';
     }
 
     @Override
diff --git a/src/main/java/com/sk89q/worldedit/expression/runtime/Variable.java b/src/main/java/com/sk89q/worldedit/expression/runtime/Variable.java
index af67e9e88..f61e3e428 100644
--- a/src/main/java/com/sk89q/worldedit/expression/runtime/Variable.java
+++ b/src/main/java/com/sk89q/worldedit/expression/runtime/Variable.java
@@ -19,6 +19,11 @@
 
 package com.sk89q.worldedit.expression.runtime;
 
+/**
+ * A variable.
+ *
+ * @author TomyLobo
+ */
 public final class Variable extends LValue {
     public double value;