[#163] renamed various iterator methods for clarity

clients/java-client-lib/client-command-builders/src/test/java/net/zscript/model/modules/testing/test/JavaCommandBuilderResponseTest.java

@@ -237,7 +237,7 @@ private <R extends ZscriptResponse> void checkResponse(final String responseChar
         ResponseCaptor<R>     captor = ResponseCaptor.create();
         ZscriptCommandNode<R> cmd    = commandBuilder.capture(captor).build();
 
-        listener.accept(cmd.parseResponse(new ZscriptTokenExpression(tokenReader::iterator)));
+        listener.accept(cmd.parseResponse(new ZscriptTokenExpression(tokenReader::tokenIterator)));
     }
 
 }

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

@@ -17,15 +17,15 @@ public class CompleteAddressedResponse {
     private final ResponseSequence     content;
 
     public static CompleteAddressedResponse parse(TokenReader reader) {
-        OptIterator<ReadToken> iterEnding = reader.iterator();
+        OptIterator<ReadToken> iterEnding = reader.tokenIterator();
         for (Optional<ReadToken> opt = iterEnding.next(); opt.isPresent(); opt = iterEnding.next()) {
             if (opt.get().isSequenceEndMarker()) {
                 if (opt.get().getKey() != Tokenizer.NORMAL_SEQUENCE_END) {
                     throw new RuntimeException("Parse failed with Tokenizer error: " + Integer.toHexString(opt.get().getKey()));
                 }
             }
         }
-        OptIterator<ReadToken> iter      = reader.iterator();
+        OptIterator<ReadToken> iter      = reader.tokenIterator();
         List<ZscriptAddress>   addresses = new ArrayList<>();
         ResponseSequence       seq       = null;
         for (Optional<ReadToken> opt = iter.next(); opt.isPresent(); opt = iter.next()) {

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

@@ -52,7 +52,7 @@ public static ZscriptAddress parse(ReadToken token) {
         }
 
         // Note, tokenizer will only write one Address; subsequent addresses are inside the single token envelope.
-        int[] parts = token.getNextTokens().stream()
+        int[] parts = token.tokenIterator().stream()
                 .takeWhile(t -> Zchars.isAddressing(t.getKey()))
                 .mapToInt(ReadToken::getData16)
                 .toArray();

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

@@ -65,7 +65,7 @@ private static List<CommandBuilder> createLinkedPaths(ReadToken start) {
             return builders;
         }
 
-        TokenBufferIterator iterator = start.getNextTokens();
+        TokenBufferIterator iterator = start.tokenIterator();
         for (Optional<ReadToken> opt = iterator.next(); opt.isPresent(); opt = iterator.next()) {
             ReadToken token = opt.get();
             if (last.getStart() == null) {

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

@@ -50,7 +50,7 @@ private static List<ResponseBuilder> createLinkedPath(ReadToken start) {
         if (start == null) {
             return builders;
         }
-        TokenBufferIterator iterator = start.getNextTokens();
+        TokenBufferIterator iterator = start.tokenIterator();
         for (Optional<ReadToken> opt = iterator.next(); opt.isPresent(); opt = iterator.next()) {
             ReadToken token = opt.get();
             if (last.getStart() == null) {

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

@@ -34,11 +34,11 @@ public static ZscriptFieldSet fromTokens(TokenBuffer.TokenReader.ReadToken start
         Arrays.fill(fields, -1);
         boolean hasClash = false;
 
-        TokenBufferIterator iterator = start.getNextTokens();
+        TokenBufferIterator iterator = start.tokenIterator();
         for (Optional<TokenBuffer.TokenReader.ReadToken> opt = iterator.next(); opt.filter(t -> !t.isMarker()).isPresent(); opt = iterator.next()) {
             TokenBuffer.TokenReader.ReadToken token = opt.get();
             if (Zchars.isBigField(token.getKey())) {
-                bigFields.add(new BigField(ByteString.from(token.blockIterator()), token.getKey() == Zchars.Z_BIGFIELD_QUOTED));
+                bigFields.add(new BigField(ByteString.from(token.dataIterator()), token.getKey() == Zchars.Z_BIGFIELD_QUOTED));
             } else {
                 if (fields[token.getKey() - 'A'] != -1 || token.getDataSize() > 2 || !Zchars.isNumericKey(token.getKey())) {
                     hasClash = true;

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

@@ -41,7 +41,7 @@ public static CommandSequence from(CommandExecutionPath path, int echoField, Zsc
     public static CommandSequence parse(ZscriptModel model, ReadToken start, boolean supports32Locks) {
         ZscriptLockSet      locks     = null;
         int                 echoField = -1;
-        TokenBufferIterator iter      = start.getNextTokens();
+        TokenBufferIterator iter      = start.tokenIterator();
         ReadToken           current   = iter.next().orElse(null);
         while (current != null && (current.getKey() == Zchars.Z_LOCKS || current.getKey() == Zchars.Z_ECHO)) {
             if (current.getKey() == Zchars.Z_LOCKS) {

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

@@ -18,7 +18,7 @@ public static ResponseSequence parse(TokenBuffer.TokenReader.ReadToken start) {
         int echoField     = -1;
         int responseField = -1;
 
-        TokenBufferIterator iter = start.getNextTokens();
+        TokenBufferIterator iter = start.tokenIterator();
 
         TokenBuffer.TokenReader.ReadToken current = iter.next().orElse(null);
         if (current == null || current.getKey() != Zchars.Z_RESPONSE_MARK) {

clients/java-client-lib/client-core/src/test/java/net/zscript/javaclient/addressing/ZscriptAddressTest.java

@@ -54,7 +54,7 @@ public void shouldParseSimpleAddress() {
     public void shouldNotParseMultipleAddresses() {
         tokenize("@12.34.56 @78.ab Z1A2+34\n");
 
-        List<ZscriptAddress> addresses = tokenReader.iterator().stream()
+        List<ZscriptAddress> addresses = tokenReader.tokenIterator().stream()
                 .filter(t -> t.getKey() == Zchars.Z_ADDRESSING)
                 .map(ZscriptAddress::parse)
                 .collect(toList());

receivers/jvm/java-receiver/src/main/java/net/zscript/javareceiver/execution/AddressingContext.java

@@ -22,19 +22,19 @@ public AddressingContext(final Zscript zscript, final ContextView contextView) {
     }
 
     public BlockIterator getAddressedData() {
-        OptIterator<ReadToken> iterator = contextView.getReader().iterator();
+        OptIterator<ReadToken> iterator = contextView.getReader().tokenIterator();
         for (Optional<ReadToken> opt = iterator.next(); opt.isPresent(); opt = iterator.next()) {
             ReadToken token = opt.get();
             if (token.getKey() == Tokenizer.ADDRESSING_FIELD_KEY) {
-                return token.blockIterator();
+                return token.dataIterator();
             }
         }
         throw new IllegalStateException("No data with addressing");
     }
 
     public OptIterator<Integer> getAddressSegments() {
         return new OptIterator<>() {
-            final OptIterator<ReadToken> internal = contextView.getReader().iterator();
+            final OptIterator<ReadToken> internal = contextView.getReader().tokenIterator();
 
             @Override
             public Optional<Integer> next() {
@@ -58,7 +58,7 @@ public boolean status(byte status) {
     }
 
     public int getAddressedDataSize() {
-        final OptIterator<ReadToken> it = contextView.getReader().iterator();
+        final OptIterator<ReadToken> it = contextView.getReader().tokenIterator();
         for (Optional<ReadToken> opt = it.next(); opt.isPresent(); opt = it.next()) {
             ReadToken token = opt.get();
             if (token.getKey() == Tokenizer.ADDRESSING_FIELD_KEY) {
@@ -72,7 +72,7 @@ public boolean verify() {
         boolean hasReachedData = false;
         int     i              = 0;
 
-        OptIterator<ReadToken> iterator = contextView.getReader().iterator();
+        OptIterator<ReadToken> iterator = contextView.getReader().tokenIterator();
         for (Optional<ReadToken> opt = iterator.next(); opt.isPresent(); opt = iterator.next()) {
             ReadToken token = opt.get();
             i++;

receivers/jvm/java-receiver/src/main/java/net/zscript/javareceiver/execution/CommandContext.java

@@ -32,7 +32,7 @@ public CommandContext(final Zscript zscript, final ContextView contextView, fina
         super(contextView);
         this.zscript = zscript;
         this.out = out;
-        this.expression = new ZscriptTokenExpression(() -> contextView.getReader().iterator());
+        this.expression = new ZscriptTokenExpression(() -> contextView.getReader().tokenIterator());
     }
 
     public CommandOutStream getOutStream() {
@@ -65,8 +65,8 @@ public boolean hasBigField() {
      *
      * @return fully big-field-aware data iterator
      */
-    public BlockIterator getBigField() {
-        return expression.getBigField();
+    public BlockIterator bigFieldDataIterator() {
+        return expression.bigFieldDataIterator();
     }
 
     @Override

receivers/jvm/java-receiver/src/main/java/net/zscript/javareceiver/modules/scriptSpaces/ScriptSpaceWriteCommand.java

@@ -37,7 +37,7 @@ public static void execute(List<ScriptSpace> spaces, CommandContext ctx) {
         }
 
         Tokenizer tok = new Tokenizer(writer.getTokenWriter(), 2);
-        for (Iterator<Byte> iterator = ctx.getBigField(); iterator.hasNext(); ) {
+        for (Iterator<Byte> iterator = ctx.bigFieldDataIterator(); iterator.hasNext(); ) {
             tok.accept(iterator.next());
         }
         writer.commitChanges();

receivers/jvm/java-receiver/src/main/java/net/zscript/javareceiver/semanticParser/SemanticParser.java

@@ -68,7 +68,7 @@ private void dealWithTokenBufferFlags() {
          * @return the Marker token that was found, or empty if none
          */
         private Optional<ReadToken> seekMarker(final boolean seekSeqEnd, final boolean flush) {
-            final TokenBufferIterator it = reader.iterator();
+            final TokenBufferIterator it = reader.tokenIterator();
             Optional<ReadToken>       token;
 
             Predicate<ReadToken> p = seekSeqEnd ? ReadToken::isSequenceEndMarker : ReadToken::isMarker;
@@ -470,7 +470,7 @@ private ActionType flowControl(final byte marker) {
      */
     private boolean seekSecondMarker() {
         // starts pointing at a marker - we want to know if there's another one after it, or if we're out of tokens!
-        final TokenBufferIterator it = reader.iterator();
+        final TokenBufferIterator it = reader.tokenIterator();
 
         // skip the current (Marker) token, and then
         it.next();
@@ -507,7 +507,7 @@ private void parseSequenceLevel() {
                     state = State.ERROR_LOCKS;
                     return;
                 }
-                locks = LockSet.from(first.blockIterator());
+                locks = LockSet.from(first.dataIterator());
                 hasLocks = true;
             }
             reader.flushFirstReadToken(); // safe as key is checked, not a Marker

receivers/jvm/java-receiver/src/main/java/net/zscript/javareceiver/treeParser/ZscriptTreeParser.java

@@ -16,7 +16,7 @@ public static ZscriptSequenceUnitPlace parseAll(ReadToken start) {
         int lowest     = 0;
         int parenCount = 0;
 
-        OptIterator<ReadToken> it = start.getNextTokens();
+        OptIterator<ReadToken> it = start.tokenIterator();
         for (Optional<ReadToken> opt = it.next(); opt.isPresent() && !opt.get().isSequenceEndMarker(); opt = it.next()) {
             ReadToken t = opt.get();
             if (t.getKey() == Tokenizer.CMD_END_OPEN_PAREN) {
@@ -42,7 +42,7 @@ static ZscriptSequenceUnit parse(ReadToken start, byte endMarker, int parenStart
 
         boolean hadNonParen = false;
 
-        OptIterator<ReadToken> it = start.getNextTokens();
+        OptIterator<ReadToken> it = start.tokenIterator();
         for (Optional<ReadToken> opt = it.next(); opt.isPresent()
                 && (parenLevel != 0 || opt.get().getKey() != endMarker) && !opt.get().isSequenceEndMarker(); opt = it.next()) {
             ReadToken t = opt.get();
@@ -71,7 +71,7 @@ static ZscriptSequenceUnit parse(ReadToken start, byte endMarker, int parenStart
         }
 
         ReadToken firstOnLevel = null;
-        it = start.getNextTokens();
+        it = start.tokenIterator();
         parenLevel = parenStartCount;
         for (Optional<ReadToken> opt = it.next(); opt.isPresent()
                 && (parenLevel != 0 || opt.get().getKey() != endMarker) && !isSequenceEndMarker(opt.get().getKey()); opt = it.next()) {
@@ -100,7 +100,7 @@ static ZscriptSequenceUnit parse(ReadToken start, byte endMarker, int parenStart
         boolean   hasTokens   = false;
         boolean   lastWasOpen = false;
         parenLevel = parenStartCount;
-        it = start.getNextTokens();
+        it = start.tokenIterator();
         Optional<ReadToken> opt;
         for (opt = it.next(); opt.isPresent()
                 && (parenLevel != 0 && !isSequenceEndMarker(opt.get().getKey()) || opt.get().getKey() != endMarker); opt = it.next()) {
@@ -127,7 +127,7 @@ static ZscriptSequenceUnit parse(ReadToken start, byte endMarker, int parenStart
             }
         }
         if (!hasTokens) {
-            it = start.getNextTokens();
+            it = start.tokenIterator();
             for (opt = it.next(); opt.isPresent() && !opt.get().isMarker(); opt = it.next()) {
             }
             //            System.out.println("Command2: " + (char) start.getKey() + " : " + Integer.toHexString(Byte.toUnsignedInt(endMarker)));

receivers/jvm/java-receiver/src/test/java/net/zscript/javareceiver/semanticParser/ParserActionTester.java

@@ -33,7 +33,7 @@ void parseSnippet(final String text, final List<ActionType> actionTypes) {
         // feed all chars into tokens/buffer
         text.chars().forEachOrdered(c -> tokenizer.accept((byte) c));
 
-        buffer.getTokenReader().iterator().forEach(t -> System.out.print(t + " "));
+        buffer.getTokenReader().tokenIterator().forEach(t -> System.out.print(t + " "));
         System.out.println();
 
         actionTypes.forEach(t -> {
@@ -52,7 +52,7 @@ void parseSnippet(final String text, String output) {
         // feed all chars into tokens/buffer
         text.chars().forEachOrdered(c -> tokenizer.accept((byte) c));
 
-        buffer.getTokenReader().iterator().forEach(t -> System.out.print(t + " "));
+        buffer.getTokenReader().tokenIterator().forEach(t -> System.out.print(t + " "));
         System.out.println();
 
         SemanticAction a1;
@@ -68,7 +68,7 @@ void parseSnippet(final String text, ActionType expectedActionType, State endSta
         // feed all chars into tokens/buffer
         text.chars().forEachOrdered(c -> tokenizer.accept((byte) c));
 
-        buffer.getTokenReader().iterator().forEach(t -> System.out.print(t + " "));
+        buffer.getTokenReader().tokenIterator().forEach(t -> System.out.print(t + " "));
         System.out.println();
 
         SemanticAction action = parser.getAction();

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

@@ -295,7 +295,7 @@ private class ArrayTokenBufferReader implements TokenReader {
          * Token Iterator which iterates all the available tokens that have been (completely) written to the buffer. It's aware of the extension tokens and excludes them from the
          * iteration.
          *
-         * @see #iterator()
+         * @see #tokenIterator()
          */
         private class ArrayBufferTokenIterator implements TokenBufferIterator {
             private int index;
@@ -349,7 +349,7 @@ public TokenBufferFlags getFlags() {
          * {@inheritDoc}
          */
         @Override
-        public TokenBufferIterator iterator() {
+        public TokenBufferIterator tokenIterator() {
             return new ArrayBufferTokenIterator(readStart);
         }
 
@@ -377,7 +377,7 @@ public ReadToken getFirstReadToken() {
          */
         @Override
         public void flushFirstReadToken() {
-            final TokenBufferIterator it = iterator();
+            final TokenBufferIterator it = tokenIterator();
             it.next();
             it.flushBuffer();
         }
@@ -414,12 +414,12 @@ private ArrayBufferToken(final int index) {
              * {@inheritDoc}
              */
             @Override
-            public TokenBufferIterator getNextTokens() {
+            public TokenBufferIterator tokenIterator() {
                 return new ArrayBufferTokenIterator(index);
             }
 
             @Override
-            public BlockIterator blockIterator() {
+            public BlockIterator dataIterator() {
                 if (isMarker()) {
                     throw new IllegalStateException("Cannot get data from marker token");
                 }

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

@@ -159,7 +159,7 @@ interface TokenReader {
          *
          * @return an iterator over ReadTokens available.
          */
-        TokenBufferIterator iterator();
+        TokenBufferIterator tokenIterator();
 
         /**
          * Checks whether any tokens can be read.
@@ -195,12 +195,6 @@ default byte getFirstKey() {
          * Represents a single Token in the token buffer.
          */
         interface ReadToken {
-            /**
-             * Creates an OptIterator over the completed tokens from this token's position forward, such that  calling next() will first supply this token.
-             *
-             * @return an iterator over available ReadTokens.
-             */
-            TokenBufferIterator getNextTokens();
 
             /**
              * Determines the key associated with this token.
@@ -235,13 +229,20 @@ default boolean isSequenceEndMarker() {
                 return TokenBuffer.isSequenceEndMarker(getKey());
             }
 
+            /**
+             * Creates an OptIterator over the completed tokens from this token's position forward, such that  calling next() will first supply this token.
+             *
+             * @return an iterator over available ReadTokens.
+             */
+            TokenBufferIterator tokenIterator();
+
             /**
              * Exposes this token's data as a stream of bytes or byte[] blocks. It manages aggregating across extension segments, and breaks caused by circularity in ring-buffers.
              *
              * @return an iterator that exposes the data either as a succession of individual bytes, or as byte[] blocks of contiguous bytes.
              * @throws IllegalStateException if this token is any kind of Marker - check first!
              */
-            BlockIterator blockIterator();
+            BlockIterator dataIterator();
 
             /**
              * Exposes the data as a single number (uint32).

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

@@ -72,7 +72,7 @@ public int getBigFieldSize() {
 
     @Override
     public ByteString getBigFieldAsByteString() {
-        return ByteString.from(getBigField());
+        return ByteString.from(bigFieldDataIterator());
     }
 
     /**
@@ -81,7 +81,7 @@ public ByteString getBigFieldAsByteString() {
      *
      * @return fully big-field-aware data iterator
      */
-    public BlockIterator getBigField() {
+    public BlockIterator bigFieldDataIterator() {
         return new BlockIterator() {
             final OptIterator<ReadToken> it = iteratorToMarker();
 
@@ -96,7 +96,7 @@ public boolean hasNext() {
                     ReadToken token = opt.get();
                     if (Zchars.isBigField(token.getKey())) {
                         // note that the token's blockIterator handles extension blocks
-                        internal = token.blockIterator();
+                        internal = token.dataIterator();
                         if (internal.hasNext()) {
                             return true;
                         }

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

@@ -27,6 +27,6 @@ public boolean isBigField() {
 
     @Override
     public BlockIterator iterator() {
-        return token.blockIterator();
+        return token.dataIterator();
     }
 }