silk/host_input

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 as Bytes

import silk.allocator { Allocator }

import silk.effect { Effect }

import silk.host_input as Host

import silk.option as Option

import silk.usize as usize

struct FixedInput {}

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

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

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

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

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

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

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

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

Import as HostInput with import silk.host_input.

Public declarations: 10.

`HostInputError`

pub struct HostInputError

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

`inputFailure`

pub fn inputFailure() -> HostInputError

Creates a host-input failure for a provider that cannot complete 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 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 fn argument(index: usize) -> 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 fn variable(name: &[u8]) -> 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 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.

`argumentCount`

pub effect fn argumentCount() -> usize ! HostInputError ? &mut HostInput

Returns the process argument count through the active HostInput provider.

Details

The count includes the program name at index zero. Provider failure produces HostInputError.

`argument`

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

Copies one process argument through the active HostInput provider.

Details

Returns None when index is at or past argumentCount. The returned Bytes value is independently owned and can contain bytes that are not valid UTF-8.

`variable`

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

Copies one environment value selected by a raw byte name.

Details

Returns None when the name is unset. This operation reads the provider and does not modify the process environment. The returned Bytes value is independently owned.

`variableNamed`

pub effect fn variableNamed(name: string) -> 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 variable. It returns None when the name is unset and independently owns a present value.

`workingDirectory`

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

Copies the process working directory through the active HostInput provider.

Details

The returned Bytes value is independently owned and is not required to be valid UTF-8. This operation reads the directory and does not change it.

`arguments`

pub effect 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 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.

`text`

pub fn text(values: &[u8]) -> silk/result.Result<string, 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