Install State handler via catch clause syntax.

Accepts either initial or {initial, opts}:

catch
  State -> 0                          # initial value
  State -> {0, output: fn r, s -> {r, s} end}  # with opts

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

Get the current state.

Examples

State.get()           # use default tag
State.get(:counter)   # use explicit tag

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

Extract the state for the given tag from an env

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

Get a value derived from the state.

Examples

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

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

Modify the state with a function, returning the old value.

Examples

State.modify(&(&1 + 1))              # use default tag
State.modify(:counter, &(&1 + 1))    # use explicit tag

@spec put(term()) :: Skuld.Comp.Types.computation()

Replace the state, returning %Change{old: old_state, new: new_state}.

Examples

State.put(42)              # use default tag
State.put(:counter, 42)    # use explicit 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 State effect data in EffectLogger snapshots
EffectLogger.with_logging(state_keys: [State.state_key(MyApp.Counter)])

# Multiple states
EffectLogger.with_logging(state_keys: [
  State.state_key(:counter),
  State.state_key(:user)
])

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

Install a scoped State handler for a computation.

Options

• tag - the state tag (default: Skuld.Effects.State)
• output - optional function (result, final_state) -> new_result to transform the result before returning.

Examples

# Simple usage with default tag
comp do
  x <- State.get()
  _ <- State.put(x + 1)
  x
end
|> State.with_handler(0)
|> Comp.run!()
#=> 0

# With explicit tag
comp do
  x <- State.get(:counter)
  _ <- State.put(:counter, x + 1)
  x
end
|> State.with_handler(0, tag: :counter)
|> Comp.run!()
#=> 0

# Include final state in result
comp do
  _ <- State.modify(&(&1 + 1))
  :done
end
|> State.with_handler(5, output: fn result, state -> {result, state} end)
|> Comp.run!()
#=> {:done, 6}

# Multiple states
comp do
  a <- State.get(:a)
  b <- State.get(:b)
  {a, b}
end
|> State.with_handler(1, tag: :a)
|> State.with_handler(2, tag: :b)
|> Comp.run!()
#=> {1, 2}