Skuld.Effects.Reader (skuld v0.1.13)

Reader effect - access an immutable environment value.

Supports both simple single-context usage and multiple independent contexts via tags.

Simple Usage (default tag)

use Skuld.Syntax
alias Skuld.Effects.Reader

comp do
  cfg <- Reader.ask()
  cfg.name
end
|> Reader.with_handler(%{name: "alice"})
|> Comp.run!()
#=> "alice"

Multiple Contexts (explicit tags)

comp do
  db <- Reader.ask(:db)
  api <- Reader.ask(:api)
  {db.host, api.url}
end
|> Reader.with_handler(%{host: "localhost"}, tag: :db)
|> Reader.with_handler(%{url: "https://api.example.com"}, tag: :api)
|> Comp.run!()
#=> {"localhost", "https://api.example.com"}

Summary

Functions

ask(tag \\ Skuld.Effects.Reader)

Read the current environment value.

asks(f)

Read and apply a function to the environment value.

asks(tag, f)

get_context(env, tag \\ Skuld.Effects.Reader)

Extract the context value for the given tag from an env

local(modify, comp)

Run a computation with a modified environment value.

local(tag, modify, comp)

state_key(tag)

Returns the env.state key used for a given tag.

with_handler(comp, value, opts \\ [])

Install a scoped Reader handler for a computation.

Functions

ask(tag \\ Skuld.Effects.Reader)

@spec ask(atom()) :: Skuld.Comp.Types.computation()

Read the current environment value.

Examples

Reader.ask()        # use default tag
Reader.ask(:config) # use explicit tag

asks(f)

@spec asks((term() -> term())) :: Skuld.Comp.Types.computation()

Read and apply a function to the environment value.

Examples

Reader.asks(&Map.get(&1, :name))           # use default tag
Reader.asks(:user, &Map.get(&1, :name))    # use explicit tag

asks(tag, f)

@spec asks(atom(), (term() -> term())) :: Skuld.Comp.Types.computation()

get_context(env, tag \\ Skuld.Effects.Reader)

@spec get_context(Skuld.Comp.Types.env(), atom()) :: term()

Extract the context value for the given tag from an env

local(modify, comp)

@spec local((term() -> term()), Skuld.Comp.Types.computation()) ::
  Skuld.Comp.Types.computation()

Run a computation with a modified environment value.

Examples

Reader.local(&Map.put(&1, :debug, true), comp)           # use default tag
Reader.local(:config, &Map.put(&1, :debug, true), comp)  # use explicit tag

local(tag, modify, comp)

@spec local(atom(), (term() -> term()), Skuld.Comp.Types.computation()) ::
  Skuld.Comp.Types.computation()

state_key(tag)

@spec state_key(atom()) :: {module(), atom()}

Returns the env.state key used for a given tag.

Useful for configuring EffectLogger's state_keys filter.

Examples

# Only capture Reader context in EffectLogger snapshots
EffectLogger.with_logging(state_keys: [Reader.state_key(:config)])

# Multiple contexts
EffectLogger.with_logging(state_keys: [
  Reader.state_key(:db),
  Reader.state_key(:api)
])

with_handler(comp, value, opts \\ [])

@spec with_handler(Skuld.Comp.Types.computation(), term(), keyword()) ::
  Skuld.Comp.Types.computation()

Install a scoped Reader handler for a computation.

Options

tag - the context tag (default: Skuld.Effects.Reader)

Examples

# Simple usage with default tag
comp do
  cfg <- Reader.ask()
  cfg.name
end
|> Reader.with_handler(%{name: "alice"})
|> Comp.run!()
#=> "alice"

# With explicit tag
comp do
  db <- Reader.ask(:db)
  db.host
end
|> Reader.with_handler(%{host: "localhost"}, tag: :db)
|> Comp.run!()
#=> "localhost"

# Multiple contexts
comp do
  db <- Reader.ask(:db)
  cache <- Reader.ask(:cache)
  {db, cache}
end
|> Reader.with_handler(%{host: "db.local"}, tag: :db)
|> Reader.with_handler(%{host: "cache.local"}, tag: :cache)
|> Comp.run!()
#=> {%{host: "db.local"}, %{host: "cache.local"}}