Jackson serialization for GREL controls

main/src/com/google/refine/grel/Control.java

@@ -35,6 +35,13 @@ package com.google.refine.grel;
 
 import java.util.Properties;
 
+import org.json.JSONException;
+import org.json.JSONWriter;
+
+import com.fasterxml.jackson.annotation.JsonInclude;
+import com.fasterxml.jackson.annotation.JsonInclude.Include;
+import com.fasterxml.jackson.annotation.JsonProperty;
+
 import com.google.refine.Jsonizable;
 import com.google.refine.expr.Evaluable;
 
@@ -47,4 +54,29 @@ public interface Control extends Jsonizable {
     public Object call(Properties bindings, Evaluable[] args);
     
     public String checkArguments(Evaluable[] args);
+    
+    @JsonProperty("description")
+    public String getDescription();
+    
+    @JsonProperty("params")
+    @JsonInclude(Include.NON_EMPTY)
+    default public String getParams() {
+        return "";
+    }
+    
+    @JsonProperty("returns")
+    public String getReturns();
+    
+    @Override
+    default public void write(JSONWriter writer, Properties options)
+        throws JSONException {
+    
+        writer.object();
+        writer.key("description"); writer.value(getDescription());
+        if (!getParams().isEmpty()) {
+            writer.key("params"); writer.value(getParams());
+        }
+        writer.key("returns"); writer.value(getReturns());
+        writer.endObject();
+    }
 }

main/src/com/google/refine/grel/controls/Filter.java

@@ -148,15 +148,17 @@ public class Filter implements Control {
     }
     
     @Override
-    public void write(JSONWriter writer, Properties options)
+    public String getDescription() {
-        throws JSONException {
+            return "Evaluates expression a to an array. Then for each array element, binds its value to variable name v, evaluates expression test which should return a boolean. If the boolean is true, pushes v onto the result array.";
+    }
     
-        writer.object();
+    @Override
-        writer.key("description"); writer.value(
+    public String getParams() {
-            "Evaluates expression a to an array. Then for each array element, binds its value to variable name v, evaluates expression test which should return a boolean. If the boolean is true, pushes v onto the result array."
+        return "expression a, variable v, expression test";
-        );
+    }
-        writer.key("params"); writer.value("expression a, variable v, expression test");
+    
-        writer.key("returns"); writer.value("array");
+    @Override
-        writer.endObject();
+    public String getReturns() {
+        return "array";
     }
 }

main/src/com/google/refine/grel/controls/ForEach.java

@@ -40,7 +40,6 @@ import java.util.Properties;
 
 import org.json.JSONArray;
 import org.json.JSONException;
-import org.json.JSONWriter;
 
 import com.google.refine.expr.EvalError;
 import com.google.refine.expr.Evaluable;
@@ -145,15 +144,17 @@ public class ForEach implements Control {
     }
     
     @Override
-    public void write(JSONWriter writer, Properties options)
+    public String getDescription() {
-        throws JSONException {
+            return "Evaluates expression a to an array. Then for each array element, binds its value to variable name v, evaluates expression e, and pushes the result onto the result array.";
+    }
     
-        writer.object();
+    @Override
-        writer.key("description"); writer.value(
+    public String getParams() {
-            "Evaluates expression a to an array. Then for each array element, binds its value to variable name v, evaluates expression e, and pushes the result onto the result array."
+        return "expression a, variable v, expression e";
-        );
+    }
-        writer.key("params"); writer.value("expression a, variable v, expression e");
+    
-        writer.key("returns"); writer.value("array");
+    @Override
-        writer.endObject();
+    public String getReturns() {
+        return "array";
     }
 }

main/src/com/google/refine/grel/controls/ForEachIndex.java

@@ -150,15 +150,17 @@ public class ForEachIndex implements Control {
     }
     
     @Override
-    public void write(JSONWriter writer, Properties options)
+    public String getDescription() {
-        throws JSONException {
+            return "Evaluates expression a to an array. Then for each array element, binds its index to variable i and its value to variable name v, evaluates expression e, and pushes the result onto the result array.";
+    }
     
-        writer.object();
+    @Override
-        writer.key("description"); writer.value(
+    public String getParams() {
-            "Evaluates expression a to an array. Then for each array element, binds its index to variable i and its value to variable name v, evaluates expression e, and pushes the result onto the result array."
+        return "expression a, variable i, variable v, expression e";
-        );
+    }
-        writer.key("params"); writer.value("expression a, variable i, variable v, expression e");
+    
-        writer.key("returns"); writer.value("array");
+    @Override
-        writer.endObject();
+    public String getReturns() {
+        return "array";
     }
 }

main/src/com/google/refine/grel/controls/ForNonBlank.java

@@ -85,16 +85,18 @@ public class ForNonBlank implements Control {
     }
 
     @Override
-    public void write(JSONWriter writer, Properties options)
+    public String getDescription() {
-        throws JSONException {
+            return "Evaluates expression o. If it is non-blank, binds its value to variable name v, evaluates expression eNonBlank and returns the result. " +
+            "Otherwise (if o evaluates to blank), evaluates expression eBlank and returns that result instead.";
+    }
     
-        writer.object();
+    @Override
-        writer.key("description"); writer.value(
+    public String getParams() {
-            "Evaluates expression o. If it is non-blank, binds its value to variable name v, evaluates expression eNonBlank and returns the result. " +
+        return "expression o, variable v, expression eNonBlank, expression eBlank";
-            "Otherwise (if o evaluates to blank), evaluates expression eBlank and returns that result instead."
+    }
-        );
+    
-        writer.key("params"); writer.value("expression o, variable v, expression eNonBlank, expression eBlank");
+    @Override
-        writer.key("returns"); writer.value("Depends on actual arguments");
+    public String getReturns() {
-        writer.endObject();
+        return "Depends on actual arguments";
     }
 }

main/src/com/google/refine/grel/controls/ForRange.java

@@ -132,15 +132,17 @@ public class ForRange implements Control {
     }
 
     @Override
-    public void write(JSONWriter writer, Properties options)
+    public String getDescription() {
-        throws JSONException {
+        return "Iterates over the variable v starting at \"from\", incrementing by \"step\" each time while less than \"to\". At each iteration, evaluates expression e, and pushes the result onto the result array.";
+    }
     
-        writer.object();
+    @Override
-        writer.key("description"); writer.value(
+    public String getParams() {
-            "Iterates over the variable v starting at \"from\", incrementing by \"step\" each time while less than \"to\". At each iteration, evaluates expression e, and pushes the result onto the result array."
+        return "number from, number to, number step, variable v, expression e";
-        );
+    }
-        writer.key("params"); writer.value("number from, number to, number step, variable v, expression e");
+    
-        writer.key("returns"); writer.value("array");
+    @Override
-        writer.endObject();
+    public String getReturns() {
+        return "array";
     }
 }

main/src/com/google/refine/grel/controls/If.java

@@ -65,16 +65,18 @@ public class If implements Control {
     }
     
     @Override
-    public void write(JSONWriter writer, Properties options)
+    public String getDescription() {
-        throws JSONException {
+            return "Evaluates expression o. If it is true, evaluates expression eTrue and returns the result. " +
+            "Otherwise, evaluates expression eFalse and returns that result instead.";
+    }
     
-        writer.object();
+    @Override
-        writer.key("description"); writer.value(
+    public String getParams() {
-            "Evaluates expression o. If it is true, evaluates expression eTrue and returns the result. " +
+        return "expression o, expression eTrue, expression eFalse";
-            "Otherwise, evaluates expression eFalse and returns that result instead."
+    }
-        );
+    
-        writer.key("params"); writer.value("expression o, expression eTrue, expression eFalse");
+    @Override
-        writer.key("returns"); writer.value("Depends on actual arguments");
+    public String getReturns() {
-        writer.endObject();
+        return "Depends on actual arguments";
     }
 }

main/src/com/google/refine/grel/controls/IsBlank.java

@@ -37,7 +37,7 @@ import com.google.refine.expr.ExpressionUtils;
 
 public class IsBlank extends IsTest {
     @Override
-    protected String getDescription() {
+    public String getDescription() {
         return "Returns whether o is null or an empty string";
     }
 

main/src/com/google/refine/grel/controls/IsEmptyString.java

@@ -2,7 +2,7 @@ package com.google.refine.grel.controls;
 
 public class IsEmptyString extends IsTest {
     @Override
-    protected String getDescription() {
+    public String getDescription() {
         return "Returns whether o is an empty string";
     }
 

main/src/com/google/refine/grel/controls/IsError.java

@@ -37,7 +37,7 @@ import com.google.refine.expr.ExpressionUtils;
 
 public class IsError extends IsTest {
     @Override
-    protected String getDescription() {
+    public String getDescription() {
         return "Returns whether o is an error";
     }
 

main/src/com/google/refine/grel/controls/IsNonBlank.java

@@ -37,7 +37,7 @@ import com.google.refine.expr.ExpressionUtils;
 
 public class IsNonBlank extends IsTest {
     @Override
-    protected String getDescription() {
+    public String getDescription() {
         return "Returns whether o is not null and not an empty string";
     }
 

main/src/com/google/refine/grel/controls/IsNotNull.java

@@ -35,7 +35,7 @@ package com.google.refine.grel.controls;
 
 public class IsNotNull extends IsTest {
     @Override
-    protected String getDescription() {
+    public String getDescription() {
         return "Returns whether o is not null";
     }
 

main/src/com/google/refine/grel/controls/IsNull.java

@@ -35,7 +35,7 @@ package com.google.refine.grel.controls;
 
 public class IsNull extends IsTest {
     @Override
-    protected String getDescription() {
+    public String getDescription() {
         return "Returns whether o is null";
     }
 

main/src/com/google/refine/grel/controls/IsNumeric.java

@@ -37,7 +37,7 @@ import org.apache.commons.lang3.StringUtils;
 
 public class IsNumeric extends IsTest {
     @Override
-    protected String getDescription() {
+    public String getDescription() {
         return "Returns whether o can represent a number";
     }
 

main/src/com/google/refine/grel/controls/IsTest.java

@@ -35,9 +35,6 @@ package com.google.refine.grel.controls;
 
 import java.util.Properties;
 
-import org.json.JSONException;
-import org.json.JSONWriter;
-
 import com.google.refine.expr.EvalError;
 import com.google.refine.expr.Evaluable;
 import com.google.refine.grel.Control;
@@ -64,17 +61,14 @@ abstract class IsTest implements Control {
     }
     
     @Override
-    public void write(JSONWriter writer, Properties options)
+    public String getParams() {
-        throws JSONException {
+        return "expression o";
+    }
     
-        writer.object();
+    @Override
-        writer.key("description"); writer.value(getDescription());
+    public String getReturns() {
-        writer.key("params"); writer.value("expression o");
+        return "boolean";
-        writer.key("returns"); writer.value("boolean");
-        writer.endObject();
     }
     
     abstract protected boolean test(Object v);
-    
-    abstract protected String getDescription();
 }

main/src/com/google/refine/grel/controls/With.java

@@ -35,9 +35,6 @@ package com.google.refine.grel.controls;
 
 import java.util.Properties;
 
-import org.json.JSONException;
-import org.json.JSONWriter;
-
 import com.google.refine.expr.Evaluable;
 import com.google.refine.grel.Control;
 import com.google.refine.grel.ControlFunctionRegistry;
@@ -82,15 +79,17 @@ public class With implements Control {
     }
     
     @Override
-    public void write(JSONWriter writer, Properties options)
+    public String getDescription() {
-        throws JSONException {
+            return "Evaluates expression o and binds its value to variable name v. Then evaluates expression e and returns that result";
+    }
     
-        writer.object();
+    @Override
-        writer.key("description"); writer.value(
+    public String getParams() {
-            "Evaluates expression o and binds its value to variable name v. Then evaluates expression e and returns that result"
+        return "expression o, variable v, expression e";
-        );
+    }
-        writer.key("params"); writer.value("expression o, variable v, expression e");
+    
-        writer.key("returns"); writer.value("Depends on actual arguments");
+    @Override
-        writer.endObject();
+    public String getReturns() {
+        return "Depends on actual arguments";
     }
 }