CommandLine · Standard Library

Command-line argument view construction and printing helpers.

Command view shape

CommandLine and toCommandLine2 return the same stateful command iterator.
Each item is a StringView.
size returns the remaining argument count as Int32.
next (-- command cond) advances through a mutable iterator view and returns a StringView value followed by Cond. Exhaustion returns an empty StringView and FALSE.
at (index -- command) reads relative to the current position without advancing; index must be an Int32 in the remaining range.
Copying the iterator preserves an independent position, while sharing the table and strings.

Functions

`CommandLine`

(-- commands) Constructs an empty command iterator.

Its size is zero and next returns an empty StringView followed by FALSE. To view process arguments, pass the argc/argv pair received by main to toCommandLine2; CommandLine does not obtain that pair.

`toCommandLine2`

(argumentAddress argumentCount -- commands) Builds a command view from a contiguous sequence of zero-terminated string addresses.

argumentAddress is a Natx address and argumentCount is a nonnegative Int32. For a positive count, the address must identify that many contiguous, aligned Natx pointer entries.
Each accessed entry must point to readable zero-terminated bytes whose length fits Int32; bytes are not UTF-8 validated.
The iterator borrows both the pointer table and the addressed bytes. It reads a pointer and measures its string when that argument is accessed, without copying either allocation.
Keep the table alive while the iterator may read it, and keep the bytes alive while any returned StringView is used. A returned view has a fixed byte count and immutable byte access.
A zero count reads neither table nor strings. A negative count violates the nonnegative-count contract; no eager nonnegative check is performed.

`printCommandLine`

(commands --) Prints the count and each command in guillemets.

Writes ‘Commands provided: ’ followed by commands.size. For each item, writes a line feed, two spaces, ‘«’, the item's printable bytes, and ‘»’. It adds no final line feed and does not escape item contents. Printing a CommandLine iterator uses a copy of its current position.

Examples

Runtime example: constructed view size

"Array"       use
"CommandLine" use
"String"      use
"control"     use

{} Int32 {} [
  addresses: Natx Array;
  "alpha\00" storageAddress @addresses.append
  "beta\00" storageAddress @addresses.append
  commands: addresses.data storageAddress 2 toCommandLine2;
  commands.size toString print
  LF print
  0
] "main" exportFunction