silk.system.host_input.

When to use#

Require &mut HostInput in code that reads process arguments or environment variables, so a test can provide its own values. Use HostInput.text when you need text. Keep the bytes when you only pass a value on, because a host value is not always valid UTF-8.

Details#

Argument 0 is the program name. The arguments keep the order of the host. A missing argument index or an unset variable gives an absent Option, not an error. Each returned value is an owned Bytes, so the lookups need an Allocator.

This effect only reads. It does not change environment variables or the working directory.

Errors#

• HostInputError if the provider cannot answer.

• OutOfMemoryError if the Allocator cannot supply a returned value.

Examples#

Provide arguments in a test#

import silk.mem.allocator { Allocator, OutOfMemoryError }
import silk.collections.bytes { Bytes }
import silk.core.effect { Effect }
import silk.system.host_input { HostInput, HostInputError }
import silk.core.option { Option }

struct FixedInput {}

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

effect fn argument(self: &mut FixedInput, index: usize) -> Option<Bytes>
  ! HostInputError | OutOfMemoryError
  ? &mut Allocator {
  if index == 1 {
    return Option<Bytes>.some(run Bytes.copy(&b"--verbose"))
  }
  return Option<Bytes>.none()
}

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

effect fn workingDirectory(self: &mut FixedInput) -> Bytes
  ! HostInputError | OutOfMemoryError
  ? &mut Allocator {
  return run Bytes.copy(&b"/")
}

impl HostInput for FixedInput {
  argumentCount: FixedInput.argumentCount

  argument: FixedInput.argument

  variable: FixedInput.variable

  workingDirectory: FixedInput.workingDirectory
}

pub effect fn main() -> i32
  ! HostInputError | OutOfMemoryError {
  let mut allocator = Allocator.systemAllocatorProvider()
  let mut provider = FixedInput {}
  let flag = run HostInput.argument(1) |> Effect.provideMut<HostInput>(&mut provider)
    |> Effect.provideMut<Allocator>(&mut allocator)
  let length = match move flag {
    Option<Bytes>.Some { value } => Bytes.length(&value)
    Option<Bytes>.None => 0
  }
  if length != 9 {
    return 1
  }
  return 0
}

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

Public declarations: 2.

HostInputError#

pub struct HostInputError

The error when a host input provider cannot answer a lookup.

Implementation Debug for HostInputError#

impl Debug for HostInputError

Operation debug#

effect fn debug(self: &Self, formatter: &mut Formatter) -> () ! WriterError ? &mut Writer

Writes HostInputError.

HostInput#

pub service HostInput

The effect that reads process arguments, environment variables, and the working directory, as bytes.

When to use#

Require &mut HostInput in code that reads process arguments or environment variables, so a test can provide its own values. Use HostInput.text when you need text. Keep the bytes when you only pass a value on, because a host value is not always valid UTF-8.

Details#

Argument 0 is the program name. The arguments keep the order of the host. This effect only reads. It does not change environment variables or the working directory. Each returned value is an owned Bytes, so the lookups need an Allocator.

An absent argument and an unset variable are normal answers, so they give an absent Option. Only a provider that cannot answer fails with HostInputError. Each returned value is owned by the caller.

Operation argumentCount#

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

Returns the number of arguments, including the program name at index 0.

Errors#

• HostInputError if the provider cannot read the arguments.

Operation argument#

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

Returns a copy of argument index as bytes. Returns an absent option if index is not less than the argument count.

Errors#

• HostInputError if the provider cannot read the arguments.

• OutOfMemoryError if the Allocator cannot supply the copy.

Operation variable#

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

Returns a copy of the value of the environment variable name. Returns an absent option if the variable is not set.

Errors#

• HostInputError if the provider cannot read the environment.

• OutOfMemoryError if the Allocator cannot supply the copy.

Operation workingDirectory#

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

Returns a copy of the working directory path as bytes.

Errors#

• HostInputError if the provider cannot read the working directory.

• OutOfMemoryError if the Allocator cannot supply the copy.

Implementation HostInput#

impl HostInput

Associated function inputFailure#

pub fn inputFailure() -> HostInputError

Returns a HostInputError. Providers use it when a lookup fails.

Associated function variableNamed#

pub effect fn variableNamed(
    name: string
  ) -> Option<Bytes> ! HostInputError | OutOfMemoryError ? &mut HostInput | &mut Allocator

Returns a copy of the value of the environment variable name. Returns an absent option if the variable is not set.

When to use#

Use it for a name that is a string literal, such as "HOME". It calls HostInput.variable with the UTF-8 bytes of name.

Errors#

• HostInputError if the provider cannot read the environment.

• OutOfMemoryError if the Allocator cannot supply the copy.

Associated function arguments#

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

Returns copies of all arguments, in order, with the program name at index 0.

When to use#

Use it when you need all arguments. Use HostInput.argument to read one argument without copying the others.

Errors#

• HostInputError if the provider cannot read the arguments, or if it reports a count and then has no argument for an index below that count.

• OutOfMemoryError if the Allocator cannot supply the copies.

Associated function text#

pub fn text(values: &[u8]) -> Result<string, InvalidUtf8>

Returns values as a string if it is valid UTF-8. It does not copy.

When to use#

Use it when you need a host value as text, for example to compare an argument with "--help". To pass a value on, keep the bytes.

Errors#

• InvalidUtf8 if values is not valid UTF-8. values does not change.

Category: System.

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