WIP Error and documentation overhaul

src/main/java/com/hubspot/jinjava/Jinjava.java

@@ -29,6 +29,8 @@
 import com.hubspot.jinjava.interpret.Context;
 import com.hubspot.jinjava.interpret.FatalTemplateErrorsException;
 import com.hubspot.jinjava.interpret.InterpretException;
+import com.hubspot.jinjava.interpret.InvalidArgumentException;
+import com.hubspot.jinjava.interpret.InvalidInputException;
 import com.hubspot.jinjava.interpret.JinjavaInterpreter;
 import com.hubspot.jinjava.interpret.RenderResult;
 import com.hubspot.jinjava.interpret.TemplateError;
@@ -203,7 +205,12 @@ public RenderResult renderForResult(String template, Map<String, ?> bindings, Ji
         return new RenderResult(TemplateError.fromException((TemplateSyntaxException) e), interpreter.getContext(), interpreter.getErrorsCopy());
       }
       return new RenderResult(TemplateError.fromSyntaxError(e), interpreter.getContext(), interpreter.getErrorsCopy());
-    } catch (Exception e) {
+    } catch (InvalidArgumentException e) {
+      return new RenderResult(TemplateError.fromInvalidArgumentException(e), interpreter.getContext(), interpreter.getErrorsCopy());
+    } catch (InvalidInputException e) {
+      return new RenderResult(TemplateError.fromInvalidInputException(e), interpreter.getContext(), interpreter.getErrorsCopy());
+    }
+    catch (Exception e) {
       return new RenderResult(TemplateError.fromException(e), interpreter.getContext(), interpreter.getErrorsCopy());
     } finally {
       globalContext.reset();

src/main/java/com/hubspot/jinjava/doc/annotations/JinjavaDoc.java

@@ -11,6 +11,8 @@
 
   String value() default "";
 
+  JinjavaParam[] input() default {};
+
   JinjavaParam[] params() default {};
 
   JinjavaSnippet[] snippets() default {};

src/main/java/com/hubspot/jinjava/doc/annotations/JinjavaParam.java

@@ -17,4 +17,6 @@
 
   String defaultValue() default "";
 
+  boolean required() default false;
+
 }

src/main/java/com/hubspot/jinjava/el/ExpressionResolver.java

@@ -13,8 +13,11 @@
 
 import com.google.common.collect.ImmutableMap;
 import com.hubspot.jinjava.el.ext.NamedParameter;
+import com.hubspot.jinjava.interpret.DeferredValueException;
 import com.hubspot.jinjava.interpret.DisabledException;
 import com.hubspot.jinjava.interpret.InterpretException;
+import com.hubspot.jinjava.interpret.InvalidArgumentException;
+import com.hubspot.jinjava.interpret.InvalidInputException;
 import com.hubspot.jinjava.interpret.JinjavaInterpreter;
 import com.hubspot.jinjava.interpret.TemplateError;
 import com.hubspot.jinjava.interpret.TemplateError.ErrorItem;
@@ -23,7 +26,6 @@
 import com.hubspot.jinjava.interpret.TemplateSyntaxException;
 import com.hubspot.jinjava.interpret.UnknownTokenException;
 import com.hubspot.jinjava.interpret.errorcategory.BasicTemplateErrorCategory;
-import com.hubspot.jinjava.interpret.DeferredValueException;
 import com.hubspot.jinjava.lib.fn.ELFunctionDefinition;
 
 import de.odysseus.el.tree.TreeBuilderException;
@@ -97,6 +99,10 @@ public Object resolveExpression(String expression) {
     } catch (DeferredValueException e) {
       // Re-throw so that it can be handled in JinjavaInterpreter
       throw e;
+    } catch (InvalidInputException e) {
+      interpreter.addError(TemplateError.fromInvalidInputException(e));
+    } catch (InvalidArgumentException e) {
+      interpreter.addError(TemplateError.fromInvalidArgumentException(e));
     } catch (Exception e) {
       interpreter.addError(TemplateError.fromException(new InterpretException(
           String.format("Error resolving expression [%s]: " + getRootCauseMessage(e), expression), e, interpreter.getLineNumber(), interpreter.getPosition())));

src/main/java/com/hubspot/jinjava/interpret/InvalidArgumentException.java

@@ -0,0 +1,52 @@
+package com.hubspot.jinjava.interpret;
+
+import com.hubspot.jinjava.lib.Importable;
+
+public class InvalidArgumentException extends RuntimeException {
+
+  private final int lineNumber;
+  private final int startPosition;
+  private final String message;
+  private final String name;
+
+  public InvalidArgumentException(JinjavaInterpreter interpreter, Importable importable, InvalidReason invalidReason, int argumentNumber, Object... errorMessageArgs) {
+    this.message = String.format("Invalid argument in '%s': %s",
+        importable.getName(),
+        String.format("%s %s", formatArgumentNumber(argumentNumber + 1), String.format(invalidReason.getErrorMessage(), errorMessageArgs)));
+
+    this.lineNumber = interpreter.getLineNumber();
+    this.startPosition = interpreter.getPosition();
+    this.name = importable.getName();
+  }
+
+  public String getMessage() {
+    return message;
+  }
+
+  public int getLineNumber() {
+    return lineNumber;
+  }
+
+  public int getStartPosition() {
+    return startPosition;
+  }
+
+  public String getName() {
+    return name;
+  }
+
+  private static String formatArgumentNumber(int argumentNumber) {
+
+    String base = "th";
+    int remainder = argumentNumber % 10;
+    if (remainder == 1) {
+      base = "st";
+    } else if (remainder == 2) {
+      base = "nd";
+    } else if (remainder == 3) {
+      base = "rd";
+    }
+
+    return String.format("%d%s", argumentNumber, base);
+  }
+}

src/main/java/com/hubspot/jinjava/interpret/InvalidInputException.java

@@ -0,0 +1,37 @@
+package com.hubspot.jinjava.interpret;
+
+import com.hubspot.jinjava.lib.Importable;
+
+public class InvalidInputException extends RuntimeException {
+
+  private final int lineNumber;
+  private final int startPosition;
+  private final String message;
+  private final String name;
+
+  public InvalidInputException(JinjavaInterpreter interpreter, Importable importable, InvalidReason invalidReason, Object... errorMessageArgs) {
+    this.message = String.format("Invalid input in '%s': input variable %s",
+        importable.getName(),
+        String.format(invalidReason.getErrorMessage(), errorMessageArgs));
+
+    this.lineNumber = interpreter.getLineNumber();
+    this.startPosition = interpreter.getPosition();
+    this.name = importable.getName();
+  }
+
+  public String getMessage() {
+    return message;
+  }
+
+  public int getLineNumber() {
+    return lineNumber;
+  }
+
+  public int getStartPosition() {
+    return startPosition;
+  }
+
+  public String getName() {
+    return name;
+  }
+}

src/main/java/com/hubspot/jinjava/interpret/InvalidReason.java

@@ -0,0 +1,23 @@
+package com.hubspot.jinjava.interpret;
+
+public enum InvalidReason {
+  NUMBER_FORMAT("with value '%s' must be a number"),
+  NULL("cannot be null"),
+  STRING("must be a string"),
+  EXPRESSION_TEST("with value %s must be the name of an expression test"),
+  TEMPORAL_UNIT("with value %s must be a valid temporal unit"),
+  JSON_READ("could not be converted to an object"),
+  JSON_WRITE("object could not be written as a string"),
+  REGEX("with value %s must be valid regex")
+  ;
+
+  private final String errorMessage;
+
+  InvalidReason(String errorMessage) {
+    this.errorMessage = errorMessage;
+  }
+
+  public String getErrorMessage() {
+    return errorMessage;
+  }
+}

src/main/java/com/hubspot/jinjava/interpret/TemplateError.java

@@ -26,6 +26,8 @@ public enum ErrorReason {
     EXCEPTION,
     MISSING,
     DISABLED,
+    INVALID_ARGUMENT,
+    INVALID_INPUT,
     OTHER
   }
 
@@ -67,6 +69,28 @@ public static TemplateError fromException(TemplateSyntaxException ex) {
     return new TemplateError(ErrorType.FATAL, ErrorReason.SYNTAX_ERROR, ErrorItem.OTHER, ExceptionUtils.getMessage(ex), fieldName, ex.getLineNumber(), ex.getStartPosition(), ex);
   }
 
+  public static TemplateError fromInvalidArgumentException(InvalidArgumentException ex) {
+    return new TemplateError(ErrorType.FATAL,
+        ErrorReason.INVALID_ARGUMENT,
+        ErrorItem.PROPERTY,
+        ex.getMessage(),
+        ex.getName(),
+        ex.getLineNumber(),
+        ex.getStartPosition(),
+        ex);
+  }
+
+  public static TemplateError fromInvalidInputException(InvalidInputException ex) {
+    return new TemplateError(ErrorType.FATAL,
+        ErrorReason.INVALID_INPUT,
+        ErrorItem.PROPERTY,
+        ex.getMessage(),
+        ex.getName(),
+        ex.getLineNumber(),
+        ex.getStartPosition(),
+        ex);
+  }
+
   public static TemplateError fromException(Exception ex) {
     int lineNumber = -1;
     int startPosition = -1;

src/main/java/com/hubspot/jinjava/interpret/TemplateSyntaxException.java

@@ -5,24 +5,32 @@ public class TemplateSyntaxException extends InterpretException {
 
   private final String code;
 
+  @Deprecated
   public TemplateSyntaxException(String code, String message, int lineNumber, int startPosition) {
-    super("Syntax error in '" + code + "': " + message, lineNumber, startPosition);
+    super(String.format("Syntax error in '%s': %s", code, message), lineNumber, startPosition);
     this.code = code;
   }
 
+  @Deprecated
   public TemplateSyntaxException(String code, String message, int lineNumber) {
     this(code, message, lineNumber, -1);
   }
 
+  @Deprecated
   public TemplateSyntaxException(String code, String message, int lineNumber, int startPosition, Throwable t) {
     super(message, t, lineNumber, startPosition);
     this.code = code;
   }
 
+  @Deprecated
   public TemplateSyntaxException(String code, String message, int lineNumber, Throwable t) {
     this(code, message, lineNumber, -1, t);
   }
 
+  public TemplateSyntaxException(JinjavaInterpreter interpreter, String code, String message) {
+    this(code, message, interpreter.getLineNumber(), interpreter.getPosition());
+  }
+
   public String getCode() {
     return code;
   }

src/main/java/com/hubspot/jinjava/lib/exptest/IsContainingAllExpTest.java

@@ -2,10 +2,21 @@
 
 import java.util.Objects;
 
+import com.hubspot.jinjava.doc.annotations.JinjavaDoc;
+import com.hubspot.jinjava.doc.annotations.JinjavaParam;
+import com.hubspot.jinjava.doc.annotations.JinjavaSnippet;
 import com.hubspot.jinjava.interpret.JinjavaInterpreter;
 import com.hubspot.jinjava.util.ForLoop;
 import com.hubspot.jinjava.util.ObjectIterator;
 
+@JinjavaDoc(
+    value = "Returns true if a list contains all values in a second list",
+    input = @JinjavaParam(value = "list", type="list", required = true),
+    params = @JinjavaParam(value = "list_two", type="list", desc = "The second list to check if every element is in the first list", required = true),
+    snippets = {
+        @JinjavaSnippet(
+            code = "{{ [1, 2, 3] is containingall [2, 3] }}")
+    })
 public class IsContainingAllExpTest implements ExpTest {
 
   @Override

src/main/java/com/hubspot/jinjava/lib/exptest/IsContainingExpTest.java

@@ -2,10 +2,21 @@
 
 import java.util.Objects;
 
+import com.hubspot.jinjava.doc.annotations.JinjavaDoc;
+import com.hubspot.jinjava.doc.annotations.JinjavaParam;
+import com.hubspot.jinjava.doc.annotations.JinjavaSnippet;
 import com.hubspot.jinjava.interpret.JinjavaInterpreter;
 import com.hubspot.jinjava.util.ForLoop;
 import com.hubspot.jinjava.util.ObjectIterator;
 
+@JinjavaDoc(
+    value = "Returns true if a list contains a value",
+    input = @JinjavaParam(value = "list", type = "list", required = true),
+    params = @JinjavaParam(value = "value", type = "object", desc = "The value to check is in the list", required = true),
+    snippets = {
+        @JinjavaSnippet(
+            code = "{{ [1, 2, 3] is containing 2 }}")
+    })
 public class IsContainingExpTest implements ExpTest {
 
   @Override

src/main/java/com/hubspot/jinjava/lib/exptest/IsDefinedExpTest.java

@@ -1,11 +1,13 @@
 package com.hubspot.jinjava.lib.exptest;
 
 import com.hubspot.jinjava.doc.annotations.JinjavaDoc;
+import com.hubspot.jinjava.doc.annotations.JinjavaParam;
 import com.hubspot.jinjava.doc.annotations.JinjavaSnippet;
 import com.hubspot.jinjava.interpret.JinjavaInterpreter;
 
 @JinjavaDoc(
     value = "Return true if the variable is defined",
+    input = @JinjavaParam(value = "value", type = "object", required = true),
     snippets = {
         @JinjavaSnippet(
             code = "{% if variable is defined %}\n" +

src/main/java/com/hubspot/jinjava/lib/exptest/IsDivisibleByExpTest.java

@@ -3,13 +3,15 @@
 import com.hubspot.jinjava.doc.annotations.JinjavaDoc;
 import com.hubspot.jinjava.doc.annotations.JinjavaParam;
 import com.hubspot.jinjava.doc.annotations.JinjavaSnippet;
-import com.hubspot.jinjava.interpret.InterpretException;
+import com.hubspot.jinjava.interpret.InvalidArgumentException;
+import com.hubspot.jinjava.interpret.InvalidReason;
 import com.hubspot.jinjava.interpret.JinjavaInterpreter;
+import com.hubspot.jinjava.interpret.TemplateSyntaxException;
 
-@JinjavaDoc(value = "Check if a variable is divisible by a number",
-    params = {
-        @JinjavaParam(value = "num", type = "number", desc = "The number to check whether a number is divisble by")
-    },
+@JinjavaDoc(
+    value = "Returns true if a variable is divisible by a number",
+    input = @JinjavaParam(value = "num", type = "number", required = true),
+    params = @JinjavaParam(value = "divisor", type = "number", desc = "The number to check whether a number is divisible by", required = true),
     snippets = {
         @JinjavaSnippet(
             code = "{% if variable is divisbleby 5 %}\n" +
@@ -34,8 +36,16 @@ public boolean evaluate(Object var, JinjavaInterpreter interpreter, Object... ar
       return false;
     }
 
-    if (args.length == 0 || args[0] == null || !Number.class.isAssignableFrom(args[0].getClass())) {
-      throw new InterpretException(getName() + " test requires a numeric argument");
+    if (args.length == 0) {
+      throw new TemplateSyntaxException(interpreter, getName(), "requires 1 argument (name of expression test to filter by)");
+    }
+
+    if (args[0] == null) {
+      return false;
+    }
+
+    if (!Number.class.isAssignableFrom(args[0].getClass())) {
+      throw new InvalidArgumentException(interpreter, this, InvalidReason.NUMBER_FORMAT, 0, args[0].toString());
     }
 
     return ((Number) var).intValue() % ((Number) args[0]).intValue() == 0;

src/main/java/com/hubspot/jinjava/lib/exptest/IsEqualToExpTest.java

@@ -4,16 +4,17 @@
 import com.hubspot.jinjava.doc.annotations.JinjavaParam;
 import com.hubspot.jinjava.doc.annotations.JinjavaSnippet;
 import com.hubspot.jinjava.el.TruthyTypeConverter;
-import com.hubspot.jinjava.interpret.InterpretException;
 import com.hubspot.jinjava.interpret.JinjavaInterpreter;
+import com.hubspot.jinjava.interpret.TemplateSyntaxException;
 
 import de.odysseus.el.misc.BooleanOperations;
 import de.odysseus.el.misc.TypeConverter;
 
 @JinjavaDoc(
-    value = "Check if an object has the same value as another object",
+    value = "Returns true if an object has the same value as another object",
+    input = @JinjavaParam(value = "first", type = "object", required = true),
     params = {
-        @JinjavaParam(value = "other", type = "object", desc = "Another object to check equality against")
+        @JinjavaParam(value = "other", type = "object", desc = "Another object to check equality against", required = true)
     },
     snippets = {
         @JinjavaSnippet(
@@ -36,7 +37,7 @@ public String getName() {
   @Override
   public boolean evaluate(Object var, JinjavaInterpreter interpreter, Object... args) {
     if (args.length == 0) {
-      throw new InterpretException(getName() + " test requires 1 argument");
+      throw new TemplateSyntaxException(interpreter, getName(), "requires 1 argument (other object to check equality against)");
     }
 
     return BooleanOperations.eq(TYPE_CONVERTER, var, args[0]);