[#163] Renamed streams to CommandOutStream, SequenceOutStream

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

@@ -1,8 +1,5 @@
 package net.zscript.javaclient.commandbuilder.commandnodes;
 
-import java.io.IOException;
-import java.io.UncheckedIOException;
-import java.util.Collections;
 import java.util.Iterator;
 import java.util.List;
 import java.util.NoSuchElementException;
@@ -15,7 +12,7 @@
  * An element of a Command Sequence under construction, representing a node in the Syntax Tree of a sequence during building.
  */
 public abstract class CommandSequenceNode implements Iterable<ZscriptCommandNode<?>> {
-    protected CommandSequenceNode parent = null;
+    private CommandSequenceNode parent = null;
 
     void setParent(CommandSequenceNode parent) {
         this.parent = parent;

clients/java-client-lib/client-main/src/test/java/net/zscript/javaclient/connection/LocalZscriptConnection.java

@@ -11,8 +11,8 @@
 import org.slf4j.LoggerFactory;
 
 import net.zscript.javaclient.connectors.RawConnection;
-import net.zscript.javareceiver.core.OutStream;
 import net.zscript.javareceiver.core.OutputStreamOutStream;
+import net.zscript.javareceiver.core.SequenceOutStream;
 import net.zscript.javareceiver.core.Zscript;
 import net.zscript.javareceiver.core.ZscriptChannel;
 import net.zscript.javareceiver.execution.CommandContext;
@@ -57,7 +57,7 @@ public LocalZscriptConnection() {
         zscript.addModule(new ZscriptOuterCoreModule());
 
         TokenRingBuffer ringBuffer = TokenRingBuffer.createBufferWithCapacity(100);
-        final OutStream outStream = new OutputStreamOutStream<>(new ByteArrayOutputStream()) {
+        final SequenceOutStream outStream = new OutputStreamOutStream<>(new ByteArrayOutputStream()) {
             @Override
             public void close() {
                 responseHandler.accept(getOutputStream().toByteArray());

receivers/jvm/java-receiver/src/main/java/net/zscript/javareceiver/core/AbstractOutStream.java

@@ -2,11 +2,11 @@
 
 import java.nio.charset.StandardCharsets;
 
-import net.zscript.javareceiver.execution.ZscriptField;
+import net.zscript.javareceiver.execution.ZscriptTokenField;
 import net.zscript.model.components.Zchars;
 import net.zscript.tokenizer.BlockIterator;
 
-public abstract class AbstractOutStream implements OutStream, ZscriptCommandOutStream {
+public abstract class AbstractOutStream implements OutStream {
     /**
      * @param bytes   the bytes to write
      * @param count   how many of the bytes to write
@@ -35,14 +35,22 @@ private void appendHex(byte b, byte[] buffer, int index) {
         buffer[index + 1] = toHexChar(b & 0xf);
     }
 
-    private int appendHexTrim(byte b, byte[] buffer, int index) {
+    /**
+     * Utility that writes the supplied byte to the supplied buffer as 0, 1, or 2 hex digits.
+     *
+     * @param b          the byte to write
+     * @param buffer     the buffer to write to
+     * @param startIndex the start index within the buffer to begin writing
+     * @return the number of digits written, to facilitate advancing the index
+     */
+    private int appendHexTrim(byte b, byte[] buffer, int startIndex) {
         if ((b & 0xF0) != 0) {
-            buffer[index] = toHexChar(b >>> 4);
-            buffer[index + 1] = toHexChar(b & 0xf);
+            buffer[startIndex] = toHexChar(b >>> 4);
+            buffer[startIndex + 1] = toHexChar(b & 0xf);
             return 2;
         }
         if (b != 0) {
-            buffer[index] = toHexChar(b & 0xf);
+            buffer[startIndex] = toHexChar(b & 0xf);
             return 1;
         }
         return 0;
@@ -89,7 +97,7 @@ public void writeField(byte field, int value) {
     }
 
     @Override
-    public void writeField(ZscriptField field) {
+    public void writeField(ZscriptTokenField field) {
         if (field.isBigField()) {
             if (field.getKey() == Zchars.Z_BIGFIELD_QUOTED) {
                 writeCharAsByte('"');

receivers/jvm/java-receiver/src/main/java/net/zscript/javareceiver/core/CommandOutStream.java

@@ -0,0 +1,46 @@
+package net.zscript.javareceiver.core;
+
+import net.zscript.javareceiver.execution.ZscriptTokenField;
+
+/**
+ * Defines the operations on the response OutStream available to a command via the CommandContext. Deliberately narrowed interface - we don't want commands confused with machinery
+ * that can break the sequence flow.
+ */
+public interface CommandOutStream {
+    /**
+     * Writes the supplied field char and its 16-bit value to this stream in Zscript conventional 0-4 digit notation (ie no leading zeros, even for zero).
+     *
+     * @param field the field char
+     * @param value the 0-0xffff value to write
+     */
+    void writeField(byte field, int value);
+
+    default void writeField(char field, int value) {
+        writeField((byte) field, value);
+    }
+
+    void writeField(ZscriptTokenField field);
+
+    /**
+     * Writes the supplied string as a quoted Big Field. It is assumed to represent actual text and will be UTF-8 encoded. Forbidden chars (eg '\n', '"', '=', '\0') will be
+     * automatically Quoted-Printable escaped, eg =0a.
+     *
+     * @param text the text to write
+     */
+    void writeQuotedString(String text);
+
+    /**
+     * Writes the supplied bytes as a quoted Big Field. It is assumed to already be encoded as required, and will *not* be UTF-8 encoded. However, forbidden chars (eg '\n', '"',
+     * '=', '\0') will be automatically Quoted-Printable escaped, eg =0a.
+     *
+     * @param utf8text the text to write
+     */
+    void writeQuotedString(byte[] utf8text);
+
+    /**
+     * Writes the bytes provided as a hex big field, eg +68656c6c6f
+     *
+     * @param data the data to write
+     */
+    void writeBig(byte[] data);
+}

receivers/jvm/java-receiver/src/main/java/net/zscript/javareceiver/core/OutStream.java

@@ -1,47 +1,4 @@
 package net.zscript.javareceiver.core;
 
-/**
- * Defines the sequence-level life-cycle operations that allow responses to be sent back up to a channel.
- */
-public interface OutStream {
-
-    /**
-     * Opens the stream. Until it is opened, other operations are undefined. Calling open() may perform tasks such as allocating buffers, establishing upstream connections etc.
-     * Calling this when already open is safe.
-     */
-    void open();
-
-    /**
-     * Closes the stream. This may perform operations such as transmitting the final stream content, or shutting down the comms protocol with upstream. Calling this when already
-     * closed is safe.
-     */
-    void close();
-
-    /**
-     * Indicates whether the stream is open.
-     *
-     * @return true if open, false otherwise
-     */
-    boolean isOpen();
-
-    void writeOrElse();
-
-    void writeAndThen();
-
-    void writeOpenParen();
-
-    void writeCloseParen();
-
-    void endSequence();
-
-    void writeBytes(byte[] c);
-
-    /**
-     * Accesses the command interface to allow command-response activity.
-     *
-     * @return a command-oriented output stream
-     */
-    default ZscriptCommandOutStream asCommandOutStream() {
-        return (ZscriptCommandOutStream) this;
-    };
+public interface OutStream extends CommandOutStream, SequenceOutStream {
 }

receivers/jvm/java-receiver/src/main/java/net/zscript/javareceiver/core/SequenceOutStream.java

@@ -0,0 +1,50 @@
+package net.zscript.javareceiver.core;
+
+/**
+ * Defines the sequence-level life-cycle operations that allow responses to be sent back up to a channel.
+ * <p/>
+ * Any implementation of this interface must either also implement {@link CommandOutStream} directly, or must override {@link #asCommandOutStream()} to provide a CommandOutStream
+ * implementation.
+ */
+public interface SequenceOutStream {
+
+    /**
+     * Opens the stream. Until it is opened, other operations are undefined. Calling open() may perform tasks such as allocating buffers, establishing upstream connections etc.
+     * Calling this when already open is safe.
+     */
+    void open();
+
+    /**
+     * Closes the stream. This may perform operations such as transmitting the final stream content, or shutting down the comms protocol with upstream. Calling this when already
+     * closed is safe.
+     */
+    void close();
+
+    /**
+     * Indicates whether the stream is open.
+     *
+     * @return true if open, false otherwise
+     */
+    boolean isOpen();
+
+    void writeOrElse();
+
+    void writeAndThen();
+
+    void writeOpenParen();
+
+    void writeCloseParen();
+
+    void endSequence();
+
+    void writeBytes(byte[] c);
+
+    /**
+     * Accesses the command interface to allow command-response activity.
+     *
+     * @return a command-oriented output stream
+     */
+    default CommandOutStream asCommandOutStream() {
+        return (CommandOutStream) this;
+    }
+}

receivers/jvm/java-receiver/src/main/java/net/zscript/javareceiver/core/Zscript.java

@@ -16,7 +16,7 @@ public class Zscript {
     private final List<ActionSource>    sources        = new ArrayList<>();
     private final ZscriptExecutor       executor;
 
-    private OutStream notificationOutStream = new AbstractOutStream() {
+    private SequenceOutStream notificationOutStream = new AbstractOutStream() {
         private boolean open = false;
 
         @Override
@@ -38,7 +38,6 @@ public boolean isOpen() {
         @Override
         protected void writeBytes(byte[] bytes, int count, boolean hexMode) {
         }
-
     };
 
     public Zscript() {
@@ -90,11 +89,11 @@ public ZscriptModuleRegistry getModuleRegistry() {
         return moduleRegistry;
     }
 
-    public OutStream getNotificationOutStream() {
+    public SequenceOutStream getNotificationOutStream() {
         return notificationOutStream;
     }
 
-    public void setNotificationOutStream(OutStream out) {
+    public void setNotificationOutStream(SequenceOutStream out) {
         this.notificationOutStream = out;
     }
 

receivers/jvm/java-receiver/src/main/java/net/zscript/javareceiver/core/ZscriptChannel.java

@@ -17,15 +17,15 @@
  * </ul>
  */
 public abstract class ZscriptChannel implements ActionSource {
-    protected final SemanticParser p;
-    protected final OutStream      out;
+    protected final SemanticParser    p;
+    protected final SequenceOutStream out;
 
-    protected ZscriptChannel(final SemanticParser p, final OutStream out) {
+    protected ZscriptChannel(final SemanticParser p, final SequenceOutStream out) {
         this.p = p;
         this.out = out;
     }
 
-    protected ZscriptChannel(final TokenBuffer buffer, final OutStream out) {
+    protected ZscriptChannel(final TokenBuffer buffer, final SequenceOutStream out) {
         this(new SemanticParser(buffer.getTokenReader(), new ExecutionActionFactory()), out);
     }
 
@@ -34,7 +34,7 @@ public SemanticParser getParser() {
     }
 
     @Override
-    public OutStream getOutStream(Zscript zscript) {
+    public SequenceOutStream getOutStream(Zscript zscript) {
         return out;
     }
 

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

@@ -1,10 +1,10 @@
 package net.zscript.javareceiver.execution;
 
-import net.zscript.javareceiver.core.OutStream;
+import net.zscript.javareceiver.core.SequenceOutStream;
 import net.zscript.javareceiver.core.Zscript;
 
 public interface ActionSource {
     ZscriptAction getAction();
 
-    OutStream getOutStream(Zscript zscript);
+    SequenceOutStream getOutStream(Zscript zscript);
 }

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

@@ -2,9 +2,9 @@
 
 import java.util.Optional;
 
-import net.zscript.javareceiver.core.OutStream;
+import net.zscript.javareceiver.core.CommandOutStream;
+import net.zscript.javareceiver.core.SequenceOutStream;
 import net.zscript.javareceiver.core.Zscript;
-import net.zscript.javareceiver.core.ZscriptCommandOutStream;
 import net.zscript.javareceiver.semanticParser.ContextView;
 import net.zscript.model.components.Zchars;
 import net.zscript.model.components.ZscriptStatus;
@@ -45,8 +45,8 @@ public Optional<Integer> next() {
 
     @Override
     public boolean status(byte status) {
-        OutStream               out        = zscript.getNotificationOutStream();
-        ZscriptCommandOutStream commandOut = out.asCommandOutStream();
+        SequenceOutStream out        = zscript.getNotificationOutStream();
+        CommandOutStream  commandOut = out.asCommandOutStream();
         if (!out.isOpen()) {
             out.open();
         }