[#163] unified field writing to NumberField.append

clients/java-client-lib/client-command-api/src/main/java/net/zscript/javaclient/commandbuilder/commandnodes/ZscriptCommandNode.java

@@ -5,6 +5,8 @@
 import java.util.Map;
 import java.util.stream.Collectors;
 
+import static net.zscript.javaclient.commandPaths.NumberField.fieldOf;
+
 import net.zscript.javaclient.commandPaths.BigField;
 import net.zscript.javaclient.commandPaths.ZscriptFieldSet;
 import net.zscript.javaclient.commandbuilder.Respondable;
@@ -59,7 +61,7 @@ public String asString() {
         for (int i = 'A'; i <= 'Z'; i++) {
             if (fields.get((byte) i) != null) {
                 int value = fields.get((byte) i);
-                b.appendByte((byte) i).appendNumeric16(value);
+                fieldOf((byte) i, value).appendTo(b);
             }
         }
         for (BigField f : bigFields) {

clients/java-client-lib/client-core/src/main/java/net/zscript/javaclient/addressing/ZscriptAddress.java

@@ -3,6 +3,7 @@
 import java.util.Arrays;
 import java.util.List;
 
+import static net.zscript.javaclient.commandPaths.NumberField.fieldOf;
 import static net.zscript.tokenizer.TokenBuffer.TokenReader.ReadToken;
 
 import net.zscript.model.components.Zchars;
@@ -126,7 +127,7 @@ public String toString() {
     public void appendTo(ByteStringBuilder builder) {
         byte pre = Zchars.Z_ADDRESSING;
         for (int a : addressParts) {
-            builder.appendByte(pre).appendNumeric16(a);
+            fieldOf(pre, a).appendTo(builder);
             pre = Zchars.Z_ADDRESSING_CONTINUE;
         }
     }

clients/java-client-lib/client-core/src/main/java/net/zscript/javaclient/commandPaths/NumberField.java

@@ -9,6 +9,10 @@ public class NumberField implements ZscriptField, ByteString.ByteAppendable {
     private byte key;
     private int  value;
 
+    public static NumberField fieldOf(byte key, int value) {
+        return new NumberField(key, value);
+    }
+
     public NumberField(byte key, int value) {
         this.key = key;
         this.value = value;
@@ -36,10 +40,6 @@ public BlockIterator iterator() {
 
     @Override
     public void appendTo(ByteStringBuilder builder) {
-        append(key, value, builder);
-    }
-
-    public static void append(byte key, int value, ByteStringBuilder builder) {
         builder.appendByte(key).appendNumeric16(value);
     }
 }

clients/java-client-lib/client-core/src/main/java/net/zscript/javaclient/commandPaths/ZscriptFieldSet.java

@@ -8,6 +8,7 @@
 import java.util.OptionalInt;
 
 import static java.util.Collections.emptyList;
+import static net.zscript.javaclient.commandPaths.NumberField.fieldOf;
 
 import net.zscript.model.components.Zchars;
 import net.zscript.tokenizer.TokenBuffer;
@@ -98,10 +99,6 @@ public int getFieldVal(byte key) {
         return fields[key - 'A'];
     }
 
-    public int getFieldVal(char key) {
-        return fields[key - 'A'];
-    }
-
     /**
      * Aggregates all big-fields in this field-set and returns the concatenated result.
      *
@@ -115,11 +112,11 @@ public ByteString getBigFieldAsByteString() {
     @Override
     public void appendTo(ByteStringBuilder builder) {
         if (fields['Z' - 'A'] != -1) {
-            NumberField.append(Zchars.Z_CMD, fields['Z' - 'A'], builder);
+            fieldOf(Zchars.Z_CMD, fields['Z' - 'A']).appendTo(builder);
         }
         for (int i = 0; i < fields.length; i++) {
             if (i + 'A' != 'Z' && fields[i] != -1) {
-                NumberField.append((byte) (i + 'A'), fields[i], builder);
+                fieldOf((byte) (i + 'A'), fields[i]).appendTo(builder);
             }
         }
         for (BigField big : bigFields) {

clients/java-client-lib/client-core/src/main/java/net/zscript/javaclient/commandPrinting/StandardCommandGrapher.java

@@ -106,7 +106,7 @@ private void explainBitField(TextBox box, ZscriptDataModel.GenericField field, C
     private void explainField(TextBox box, ZscriptDataModel.GenericField field, boolean[] doneFields, ZscriptFieldSet fieldSet, CommandPrintSettings settings) {
         box.startNewLine(1);
 
-        char key = field.getKey();
+        byte key = (byte) field.getKey();
         box.append(upperFirst(field.getName()));
         box.append(" (");
         box.append(key);
@@ -157,7 +157,7 @@ private void explainStatus(ZscriptModel model, CommandPrintSettings settings, Zs
             ZscriptFieldSet fieldSet, ZscriptDataModel.CommandModel command) {
         box.startNewLine(1);
 
-        char key = field.getKey();
+        byte key = (byte) field.getKey();
         box.append(upperFirst(field.getName()));
         box.append(" (").append(key).append("): ");
         doneFields[key - 'A'] = true;
@@ -226,7 +226,7 @@ public AsciiFrame explainCommand(Command target, ZscriptModel model, CommandPrin
 
         ZscriptFieldSet fieldSet = target.getFields();
 
-        int commandValue = fieldSet.getFieldVal('Z');
+        int commandValue = fieldSet.getFieldVal(Zchars.Z_CMD);
         box.startNewLine(0);
         if (fieldSet.isEmpty()) {
             box.append("Empty Command");
@@ -273,7 +273,7 @@ public AsciiFrame explainCommand(Command target, ZscriptModel model, CommandPrin
     }
 
     public AsciiFrame explainResponse(Command source, Response target, ZscriptModel model, CommandPrintSettings settings) {
-        int             commandValue = source.getFields().getFieldVal('Z');
+        int             commandValue = source.getFields().getFieldVal(Zchars.Z_CMD);
         ZscriptFieldSet fieldSet     = target.getFields();
 
         TextBox box = new TextBox(settings.indentString);

clients/java-client-lib/client-core/src/main/java/net/zscript/javaclient/sequence/CommandSequence.java

@@ -2,6 +2,7 @@
 
 import java.util.Collection;
 
+import static net.zscript.javaclient.commandPaths.NumberField.fieldOf;
 import static net.zscript.tokenizer.TokenBuffer.TokenReader.ReadToken;
 
 import net.zscript.javaclient.commandPaths.CommandExecutionPath;
@@ -74,7 +75,7 @@ private CommandSequence(CommandExecutionPath executionPath, int echoField, Zscri
     public void appendTo(ByteStringBuilder builder) {
         locks.appendTo(builder);
         if (echoField != -1) {
-            builder.appendByte(Zchars.Z_ECHO).appendNumeric16(echoField);
+            fieldOf(Zchars.Z_ECHO, echoField).appendTo(builder);
         }
         executionPath.appendTo(builder);
     }

clients/java-client-lib/client-core/src/main/java/net/zscript/javaclient/sequence/ResponseSequence.java

@@ -1,5 +1,7 @@
 package net.zscript.javaclient.sequence;
 
+import static net.zscript.javaclient.commandPaths.NumberField.fieldOf;
+
 import net.zscript.javaclient.commandPaths.ResponseExecutionPath;
 import net.zscript.model.components.Zchars;
 import net.zscript.tokenizer.TokenBuffer;
@@ -68,10 +70,10 @@ public int getResponseValue() {
     public void appendTo(ByteStringBuilder builder) {
         // FIXME: should there only be a '!' when it's been set? Can this even happen?
         if (responseField != -1) {
-            builder.appendByte(Zchars.Z_RESPONSE_MARK).appendNumeric16(responseField);
+            fieldOf(Zchars.Z_RESPONSE_MARK, responseField).appendTo(builder);
         }
         if (echoField != -1) {
-            builder.appendByte(Zchars.Z_ECHO).appendNumeric16(echoField);
+            fieldOf(Zchars.Z_ECHO, echoField).appendTo(builder);
         }
         executionPath.appendTo(builder);
     }

receivers/jvm/java-tokenizer/src/main/java/net/zscript/tokenizer/TokenBuffer.java

@@ -231,6 +231,8 @@ default boolean isSequenceEndMarker() {
 
             /**
              * Creates an OptIterator over the completed tokens from this token's position forward, such that  calling next() will first supply this token.
+             * <p/>
+             * Extension tokens are never returned; they're accessed via the previous token that was extended.
              *
              * @return an iterator over available ReadTokens.
              */