silk/host_input

Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, aarch64-unknown-linux-gnu-no-libc, wasm32-unknown-unknown, x86_64-unknown-linux-gnu, x86_64-unknown-linux-gnu-no-libc.

Explicit access to process arguments, environment values, and the working directory as bytes.

When to use

Require HostInput when code needs launch-time process data but should remain replaceable in tests. Use text only when the caller wants a checked UTF-8 view; keep the original bytes for lossless pass-through.

Details

Arguments include the program name at index zero and retain host order. A missing argument index or unset variable is None, while HostInputError means the provider could not answer. Returned Bytes values are independently owned, so lookup operations also carry explicit OutOfMemoryError and Allocator channels.

The service is read-only and never mutates environment variables or the process working directory. No ambient global is consulted after a provider is supplied.

Examples

Read the argument count through an application provider

import silk.bytes { Bytes }

import silk.allocator { Allocator, OutOfMemoryError }

import silk.effect { Effect }

import silk.host_input { HostInput, HostInputError }

import silk.option { Option }

import silk.usize

struct FixedInput {}

effect fn argumentCount(self: &mut FixedInput) -> usize
! HostInputError {
  return usize.ONE
}

effect fn argument(self: &mut FixedInput, index: usize) -> Option<Bytes>
! HostInputError | OutOfMemoryError
? &mut Allocator {
  fail HostInput.inputFailure()
}

effect fn variable(self: &mut FixedInput, name: &[u8]) -> Option<Bytes>
! HostInputError | OutOfMemoryError
? &mut Allocator {
  fail HostInput.inputFailure()
}

effect fn workingDirectory(self: &mut FixedInput) -> Bytes
! HostInputError | OutOfMemoryError
? &mut Allocator {
  fail HostInput.inputFailure()
}

impl HostInput for FixedInput {
  argumentCount: FixedInput.argumentCount
  argument: FixedInput.argument
  variable: FixedInput.variable
  workingDirectory: FixedInput.workingDirectory
}

effect fn program() -> i32
! HostInputError {
  let mut provider = FixedInput {}
  let total = run HostInput.argumentCount()
    |> Effect.provideMut<HostInput>(&mut provider)
  if total != usize.ONE {
    return 1
  }
  return 42
}

effect fn recover(error: HostInputError) -> i32 {
  return 0
}

pub fn main() -> i32 {
  return run Effect.catchAll(program(), recover)
}

Import as HostInput with import silk.host_input { HostInput }.

Public declarations: 2.

`HostInputError`

pub struct HostInputError

A typed failure from a host-input provider that could not answer a lookup.

`HostInput`

pub service HostInput

A portable read-only service for process arguments, environment values, and working directory.

Details

The service reads and never writes: it has no operation that sets an environment variable or changes the working directory. An absent argument index and an unset variable name are None rather than typed failures, because absence is an ordinary answer; only a host that cannot answer at all is HostInputError.

Returned byte values are independently owned. Operations that return bytes therefore require an exclusive Allocator and can also fail with OutOfMemoryError.

Operation `argumentCount`

effect<'static> fn argumentCount() -> usize ! HostInputError ? &mut HostInput

Returns the argument count, including the program name at index zero.

Details

A provider that cannot inspect the process arguments fails with HostInputError.

Operation `argument`

effect<'static> fn argument(index: usize) -> silk/option.Option<silk/bytes.Bytes> ! HostInputError | OutOfMemoryError ? &mut HostInput | &mut Allocator

Copies one argument as raw bytes, or returns None when index is out of range.

Details

The returned bytes preserve host order and do not require valid UTF-8. Provider lookup failure produces HostInputError; ownership allocation produces OutOfMemoryError.

Operation `variable`

effect<'life0> fn variable<'life0>(name: &'life0 [u8]) -> silk/option.Option<silk/bytes.Bytes> ! HostInputError | OutOfMemoryError ? &mut HostInput | &mut Allocator

Copies one environment value as raw bytes, or returns None when name is unset.

Details

This operation does not change the environment. Provider lookup failure produces HostInputError; ownership allocation produces OutOfMemoryError.

Operation `workingDirectory`

effect<'static> fn workingDirectory() -> Bytes ! HostInputError | OutOfMemoryError ? &mut HostInput | &mut Allocator

Copies the process working directory as raw bytes.

Details

This operation does not change the directory. An unavailable host value produces HostInputError; ownership allocation produces OutOfMemoryError.

Associated function `HostInput.inputFailure`

pub fn inputFailure() -> HostInputError

Creates a host-input failure for a provider that cannot complete a lookup.

Associated function `HostInput.variableNamed`

pub effect<'life0> fn variableNamed<'life0>(name: string<'life0>) -> silk/option.Option<silk/bytes.Bytes> ! HostInputError | OutOfMemoryError ? &mut HostInput | &mut Allocator

Copies one environment value selected by a valid UTF-8 name.

Details

This function borrows the UTF-8 encoding of name and delegates to HostInput.variable. It returns None when the name is unset and independently owns a present value.

Associated function `HostInput.arguments`

pub effect<'static> fn arguments() -> silk/vector.Vector<silk/bytes.Bytes> ! HostInputError | OutOfMemoryError ? &mut HostInput | &mut Allocator

Copies all process arguments into an owned vector in host order.

When to use

Use this function when the caller needs the complete argument list. Use HostInput.argument for one index without retaining all argument values.

Details

A host that reports a count it cannot then supply is a broken host, so a missing index below the count is HostInputError rather than a silently shorter sequence.

Each argument and the result vector own their storage. The operation preserves the program name at index zero.

Associated function `HostInput.text`

pub fn text<'life0>(values: &'life0 [u8]) -> silk/result.Result<string<'life0>, silk/string.InvalidUtf8>

Validates host bytes as UTF-8 and returns a borrowed textual view or InvalidUtf8.

When to use

Use this function only when the caller needs text. Keep byte-oriented code on the original slice so every host value can pass through unchanged.

Details

Host input is not required to be UTF-8. Validation does not allocate or change values. A failure identifies invalid text while the original bytes remain available to the caller.

silk/host_input

On this page