Console services¶
A console program runs top to bottom in a terminal, with no window. On macOS such a program can still use files, hashing, sound and the network. This page shows how to switch each of those on when you launch a program, what each one does today, and what happens in the browser, where they are not available.
Each of these services comes from a provider, the part of the host that supplies files (or sound, or the network). The compiled program file, .dbc, declares which ones it needs; you attach them explicitly when you launch; each has the same tests written in both Python and d/BASIC, d/OS's other language, which shares the same runtime; and none of them exists in the browser build, where a program that needs one is declined with a message naming what is missing.
Files¶
--file-mount DIR attaches the file provider to a directory you choose. Inside the program that directory appears as mount 0, named flash, and paths are relative to it; which host directory it maps to is the launcher's business, not the program's. A program that declares FILES and is launched without a mount is declined before it runs. The example creates or replaces dpython-note.txt, commits the staged write, reads every byte back and checks it; cancelling a staged write leaves the previous file untouched. The eight basic file operations are tested in both languages, comparing every request and reply byte and the state of the filesystem after each step, including committing and cancelling a staged write. Ordinary Python open() is not yet supported, and the compiler tells you so.
Hashing¶
# fragment: examples/console_hash.py, which runs in the browser too
import dos
payload = dos.array("i16", [0x6261, 0x0063]) # "abc" as little-endian byte pairs
digest = dos.array("i16", [0] * 16)
dos.intent("COMPUTE", "SHA256", 3, payload, digest)
dos.intent("COMPUTE", "SHA256", byte_length, payload, digest) hashes up to 24,576 bytes per call, in bounded steps so the system stays responsive, and writes the 32-byte digest only once the whole hash has succeeded. A program gets this service when it declares BULK, whether it is launched from the console or with a window. The tests check exact digests, that the digest is not written early, and buffer aliasing. Python's hashlib and the COMPUTE.VECTOR_I16 intent are not yet supported. The example prints SHA-256(abc): ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad on macOS and in the playground alike, because the hasher is built into the shared runtime rather than supplied by the host.
Sound¶
# fragment: examples/console_sound.py
import dos
# voice, frequency in Hz, volume 0-255, waveform, duration in 60 Hz ticks
dos.intent("AUDIO", "TONE_PLAY", 0, 440, 200, 0, 30)
When the program declares SOUND, the native audio provider serves TONE_PLAY, PCM_DEFINE, PCM_PLAY, PCM_RELEASE, VOICE_STOP and STOP_ALL; a console program can play sound without a window. The mixer holds eight clips of up to 8,192 frames each and plays four voices at once; defining a clip copies its samples, so you can reuse your buffer afterwards. The tests compare complete calls, stereo samples computed independently, the copying of PCM data, stopping and releasing, shutdown and failure cases. They capture audio offline on purpose; that capture is a test tool, not a stand-in for a missing sound device.
Network¶
--net-endpoint attaches the network provider for a program that declares NETWORK. A program that only asks NET.QUERY_LINK about the link may learn that no provider is present without holding any network permission, and a program that declares only queries cannot use the option to get more. The example resolves the numeric loopback address locally and prints Loopback IPv4: 127.0.0.1 without a DNS request or a connection. The tests cover link status, resolving numeric IPv4 and IPv6 addresses, and TCP OPEN, SEND, RECV, CLOSE, LISTEN and ACCEPT against real local peers: binary payloads, end of stream, stale handles, listener replay, independently accepted connections, and requests that are captured and then withdrawn. They also cover the cases where a program is declined before anything reaches the provider. POLL, PING and CTL are not yet supported by the native provider; they wait for their full specifications.
Program arguments and services¶
Arguments after -- belong to the program. dos.service("READ_LINE") returns d/OS byte strings and stops with the shared end-of-input message when there is no more input. Python's input() goes through a separate line-reading service so that a genuine end of input raises EOFError while errors from the host or from storage are still reported as errors. A console program shares the live terminal host with d/BASIC: streamed output, real clock time and sleep, native MATH intents, and the hashing provider.
In the browser¶
The file, audio and network providers are not present in the playground. A program that declares FILES, SOUND or NETWORK still compiles, but the runtime declines it before it starts, before any output, and says which class of service is missing and which rule applies. The site's own build check confirms that console_files.py, console_sound.py and console_network.py are declined by this exact bundle. MATH and the SHA-256 hasher are built into the shared runtime and work in the browser. That is the honest state, and the status page records it.