add new trimToNull intrinsic function

this will convert any empty strings or strings with only whitespace to a null value

Author: cwensel

tessellate-main/src/main/antora/modules/reference/pages/transforms.adoc

@@ -145,3 +145,7 @@ Def:::
 `sourcePath`:: Add the URI of the data currently being processed.
 Def:::
 - `^sourcePath{} -> to_field` - Assign the current URI to `to_field`
+
+`trimToNull`:: Convert all arguments to `null` if the string representation of the value is an empty string or only contains whitespace.
+Def:::
+- `from_field1 + fromField2 ^trimToNull{} ->` - Convert any whitespace values to null while retaining the field names

tessellate-main/src/main/java/io/clusterless/tessellate/operation/TrimToNullFunction.java

@@ -0,0 +1,62 @@
+/*
+ * Copyright (c) 2023-2025 Chris K Wensel <[email protected]>. All Rights Reserved.
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ */
+
+package io.clusterless.tessellate.operation;
+
+import cascading.flow.FlowProcess;
+import cascading.operation.BaseOperation;
+import cascading.operation.Function;
+import cascading.operation.FunctionCall;
+import cascading.operation.OperationCall;
+import cascading.tuple.Fields;
+import cascading.tuple.Tuple;
+import cascading.tuple.TupleEntry;
+
+public class TrimToNullFunction extends BaseOperation<Object[]> implements Function<Object[]> {
+
+    public TrimToNullFunction(Fields fieldDeclaration) {
+        super(fieldDeclaration);
+    }
+
+    @Override
+    public void prepare(FlowProcess flowProcess, OperationCall<Object[]> operationCall) {
+        Object[] context = new Object[]{
+                new TupleEntry(fieldDeclaration, Tuple.size(fieldDeclaration.size())),
+                new Object[fieldDeclaration.size()]
+        };
+        operationCall.setContext(context);
+    }
+
+    @Override
+    public void operate(FlowProcess flowProcess, FunctionCall<Object[]> functionCall) {
+        Object[] context = functionCall.getContext();
+        TupleEntry result = (TupleEntry) context[0];
+        Object[] values = (Object[]) context[1];
+
+        TupleEntry arguments = functionCall.getArguments();
+        for (int i = 0; i < arguments.size(); i++) {
+            String value = arguments.getString(i);
+
+            if (value == null) {
+                values[i] = null;
+            } else {
+                String intermediate = value.trim();
+
+                if (intermediate.isEmpty()) {
+                    values[i] = null;
+                } else {
+                    values[i] = arguments.getObject(i);
+                }
+            }
+        }
+
+        result.setCanonicalValues(values);
+
+        functionCall.getOutputCollector().add(result);
+    }
+}

tessellate-main/src/main/java/io/clusterless/tessellate/pipeline/Intrinsics.java

@@ -23,6 +23,7 @@ private static void add(IntrinsicBuilder intrinsicBuilder) {
 
     static {
         add(new TsidIntrinsic());
+        add(new TrimToNullIntrinsic());
         add(new SourcePathIntrinsic());
         add(new FixedWidthIntrinsic());
         add(new EnsureIntrinsic());

tessellate-main/src/main/java/io/clusterless/tessellate/pipeline/intrinsic/TrimToNullIntrinsic.java

@@ -0,0 +1,42 @@
+/*
+ * Copyright (c) 2023-2025 Chris K Wensel <[email protected]>. All Rights Reserved.
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ */
+
+package io.clusterless.tessellate.pipeline.intrinsic;
+
+import cascading.tuple.Fields;
+import io.clusterless.tessellate.operation.TrimToNullFunction;
+import io.clusterless.tessellate.parser.ast.Operation;
+
+public class TrimToNullIntrinsic extends IntrinsicBuilder {
+
+    public TrimToNullIntrinsic() {
+        super("trimToNull");
+    }
+
+    @Override
+    public Result create(Fields currentFields, Operation operation) {
+        Fields fromFields = fieldsParser().asFields(operation.arguments());
+
+        // doesn't make sense to make an empty json object
+        if (fromFields.isNone()) {
+            fromFields = Fields.ALL;
+        }
+
+        Fields toFields = fieldsParser().asFields(operation.results());
+
+        if (toFields.isNone() && fromFields.isAll()) {
+            toFields = currentFields;
+        } else if (toFields.isNone()) {
+            toFields = currentFields.select(fromFields);
+        }
+
+        TrimToNullFunction function = new TrimToNullFunction(toFields);
+
+        return new Result(fromFields, function, toFields);
+    }
+}

tessellate-main/src/test/java/io/clusterless/tessellate/operation/TrimToNullTest.java

@@ -0,0 +1,36 @@
+/*
+ * Copyright (c) 2023-2025 Chris K Wensel <[email protected]>. All Rights Reserved.
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ */
+
+package io.clusterless.tessellate.operation;
+
+import cascading.CascadingTesting;
+import cascading.tuple.Fields;
+import cascading.tuple.Tuple;
+import cascading.tuple.TupleEntry;
+import cascading.tuple.TupleListCollector;
+import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.Test;
+
+public class TrimToNullTest {
+    @Test
+    void test() {
+        verify(new Tuple(null, null, null, null, null), new Tuple(null, null, null, null, null));
+        verify(new Tuple("a", "", "\n\t", null, null), new Tuple("a", null, null, null, null));
+    }
+
+    private static void verify(Tuple arguments, Tuple results) {
+        TrimToNullFunction function = new TrimToNullFunction(Fields.size(results.size()));
+
+        try (TupleListCollector tuples = CascadingTesting.invokeFunction(function, arguments, Fields.RESULTS)) {
+            TupleEntry next = tuples.entryIterator().next();
+
+            Assertions.assertEquals(results.size(), next.size());
+            Assertions.assertEquals(results, next.getTuple());
+        }
+    }
+}