Display and Ask with show / ask

show and ask are Touba user-interaction primitives.

They resemble print and scanf, with one important difference: interaction goes through the host and remains observable by the runtime.

show

show asks the host to display text.

Shape:

source.tb

show
    with message as <Text expression>

Example:

source.tb

show
    with message as "Touba ready"

With a primitive value:

source.tb

show
    with message as "age is: " ++ text(age)

With the default touba run mode, this message appears in the terminal:

Output

Touba ready

Touba does not implicitly convert an Int, Float, or Boolean to text. Use text(expr) to explicitly render a primitive value into a string. Interpolation such as "age is: [age]" is not the documented syntax. Structured types, lists, runtime objects, secrets, and memories are not rendered by text(expr).

The runtime also traces that a display was requested. The message must not contain a resolved secret value.

ask

ask requests user input.

Shape:

source.tb

ask
    with prompt as <Text expression>
    into binding

Example:

source.tb

ask
    with prompt as "Search query?"
    into query

In Touba, the runtime does not read the terminal automatically. On a sequential path without explicit input, execution pauses; parallel branches require an answer per occurrence as described below.

Terminal

touba run program.air.json \
  --user-inputs user-inputs.json \
  --trace-out trace.json

The user-inputs.json file maps interaction references to answers supplied by the host.

For a manual test, the CLI can request the answer in the terminal with an explicit option:

Terminal

touba run program.air.json --interactive-user-inputs

This option belongs to the CLI runner. It does not change language semantics: AIR still contains no stdin read, and the ask event does not trace the entered value.

If the program displays that value with show, it appears in user-facing messages. The trace records user_interaction_shown and its references, without copying the message text.

In VS Code, the Touba: Run Current File button plays the same explicit host role: when an ask is reached, VS Code opens an input box and reruns with the supplied answer.

show Is Not give

show displays text during execution.

give returns the final value of the current path and terminates that path. A statement after give or stop is refused as unreachable.

To display several values:

source.tb

show
    with message as "Query: " ++ query

show
    with message as "Test: " ++ test

give query ++ " / " ++ test

There must be a single give per execution path. An if/else may have a give in each branch if no statement follows that if in the same sequence.

Why Not in function

A Touba function remains pure.

If a value must be formatted and displayed, use:

1. a function to compute or format;
2. a skill or strategy to call show.

source.tb

function FormatDatasetTitle
    takes title as Text
    gives Text
    do
        give "Dataset: " ++ title

skill PresentDatasetTitle
    takes title as Text
    gives Text
    do
        FormatDatasetTitle
            with title as title
            into message

        show
            with message as message

        give message

Security

• The ask event does not trace the exact answer value.
• An entered value can become a business output through show or give; review these outputs separately from the trace.
• show and ask must not receive a resolved secret value.
• These controls belong to a broader sensitive-data classification and handling policy.

Interactions inside parallel groups

show messages retain each branch's local order and are returned in input order at the join. The project server exposes them in results and sessions through messages and messages_truncated, separately from the value returned by give. SSE progress events do not carry the raw message content.

A parallel ask requires a host answer for its occurrence reference, through Engine userInputs or CLI --user-inputs-json. Hosts embedding the runtime may provide an asynchronous userInputProvider. Answers are copied, journaled and reused on resume, never shared with another branch. An unanswered ask pauses the group with user_input_pending. The host reads pendingInteractions (JavaScript) or pending_interactions (Python), saves the parallel checkpoint and supplies occurrence-specific answers through userInputs / user_inputs. Resumption retains completed branches and consumed budgets. Each answer belongs to one occurrence. See the SDK guide and Human validation.