common/org.js.lolifamily.minecraftmcp.repl.scope/McpScope

McpScope

class McpScope<T>(val sink: Capture) : Iterator<T> , Continuation<Unit>

Receiver of a cross-tick iterator { ... } snippet — scope and iterator in one object, as the stdlib's SequenceBuilderIterator is. Replaces the stdlib builder for three reasons:

yield renders what it is handed. The lane drives the iterator to exhaustion and discards every element, so under the stdlib builder iterator { ...; yield(answer) } reported "(no output)" — the one snippet shape that could not answer, silently. Rendering must happen at the yield, not at the driver: by then the value is a bare Object, and a runtime type is no substitute (listOf(1, 2) reads as java.util.Arrays$ArrayList). Only a reified parameter, resolved per call site, keeps kotlin.collections.List<kotlin.Int> — and a reified yield must be inline, which rules out overriding the stdlib's abstract one.
RestrictsSuspension carries its weight. It is what makes yield the only suspension point in the body, so a step always resumes on the thread that called hasNext. Without it a snippet can kotlinx.coroutines.delay(..) — on the game loader here — and wake on a foreign thread while the lane still believes it owns the tick. The annotation is public, so we keep that guard without extending SequenceScope.
A suspended body can be ended. The stdlib only ever resumes its body with success, so one left at a yield never runs its finally blocks — and an eval that ends early leaves its body exactly there. unwind resumes it with a throw instead, and the body releases what it holds on its way out.

No yieldAll: its only remaining meaning would be "yield in bulk, silently", which is the opposite of the point. for (v in xs) yield(v) is one line and reports each element.

Constructors

McpScope

internal constructor(sink: Capture)

Types

Step

private enum class Step : Enum<McpScope.Step>

Five states: the stdlib's six, less the two that go with yieldAll's delegate-pull, plus the split of its single Failed — see Resuming.

Properties

context

open override val context: CoroutineContext

pending

private var pending: T?

sink

private val sink: Capture

Never exposed, not even as @PublishedApi: handing a snippet the Capture hands it take(), which seals the sink and drops the rest of the eval's output. emitValue is the write-only door yield needs.

step

private var step: McpScope.Step

suspended

internal val suspended: Boolean

Not yet started, or stopped at a yield: the body still has its finally blocks ahead of it.

suspendedBody

private var suspendedBody: Continuation<Unit>?

The body while it is suspended — before its first line, or at a yield. Null while it runs, and once it has ended. Resuming it runs the body on to its next yield: hasNext takes it out first, and yieldRaw puts it back as the body suspends again.

Functions

begin

internal fun begin(block: suspend McpScope<T>.() -> Unit)

Split from the constructor because createCoroutineUnintercepted needs the receiver instance — the same two-step the stdlib builder does.

emitValue

@PublishedApi

internal fun emitValue(type: String, value: Any?)

The same ValueRender.line a single-tick result goes through, so the two cannot report differently.

hasNext

open operator override fun hasNext(): Boolean

open operator override fun next(): T

One precondition, not the stdlib's next() ⇄ nextNotReady() recursion: hasNext already answers every state, so asking it IS "is there a value".

resumeWith

open override fun resumeWith(result: Result<Unit>)

Rethrow so a throw surfaces out of the hasNext that resumed it — the lane's guard turns it into partial output plus a stack. State FIRST: getOrThrow does not return on a failure, so setting it after would strand Step.Resuming and misreport the next entry as a suspension that never happened.

unwind

internal fun unwind()

End a suspended body: throw out of the yield it stopped at, so its finally blocks and use {} closes run. The body runs on the calling thread, as under hasNext, so call this where a step would run. One not yet started throws before its first line — right, since it opened nothing.

yield

inline suspend fun <reified V : T> yield(value: V, typeName: String = typeOf<V>().toString())

Suspend until the next tick, reporting value as this step's result.

yieldRaw

@PublishedApi

internal suspend fun yieldRaw(value: T)

The suspension itself — everything yield does apart from rendering. @PublishedApi for the inline call.