conditions

Source: /nix/store/mls72plk3raskl1r5afh3cl9ik3rn969-source/nix/conditions.nix

Module Description

Common Lisp style condition system for resumable error handling.

The condition system provides signaling, handling, and restart mechanisms that go beyond simple exceptions. Key features:

Conditions - Signals that can be handled without unwinding
Handlers - Dynamic scoped responders to conditions
Restarts - Named recovery strategies available at signal site
Resumption - Continue execution after handling (not just unwind)

Condition System Flow

Code signals a condition with available restarts
Handler examines condition and chooses a restart
Restart continues execution from signal point (or unwinds)

Example

# Define function with restarts
parseConfig = file:
  withRestart "use-default" (dflt: pure dflt)
    (withRestart "retry" (_: parseConfig file)
      (map (_: throw "Parse failed")
        (signal { type = "parse-error"; file = file; })));

# Handle with restart selection
parsed = runFx (
  handle "parse-error" (cond:
    if canRecover cond.file
    then invokeRestart "use-default" defaultConfig
    else invokeRestart "retry" {})
  (parseConfig "config.json")
);

Comparison to Exceptions

Feature	Exceptions	Conditions
Signaling	throw	signal
Handling	catch (unwinds)	handle (can resume)
Recovery	return value	invoke restart
Stack	Unwound	Preserved (if resuming)

Combinators

`cerror`

Signals a continuable error with a default restart.

Convenience for errors that have a sensible way to continue. Automatically defines a “continue” restart that returns the provided default value.

Type Signature

String -> V -> String -> Attrset -> Fx<S, V>

Parameters

continueMessage: Message shown for continue option
defaultValue: Value if continue chosen
errorMessage: Error description
details: Error details

Example

cerror "Use default config" defaultConfig
  "Config parse failed" { file = "config.json"; }

# Handler can:
# - invokeRestart "continue" {} -> returns defaultConfig
# - invokeRestart "abort" cond -> aborts

`error`

Signals a non-resumable error condition.

Convenience function for signaling errors. Unlike general conditions, errors are not meant to be resumed from. Handlers should invoke a restart (typically “abort”) rather than returning a value.

Type Signature

String -> Attrset -> Fx<S, V>

Parameters

message: Error message
details: Additional error details

Example

error "File not found" { file = "config.json"; }

# Handler must invoke restart:
handle "error" (cond:
  invokeRestart "abort" cond
) code

`findRestart`

Checks if a restart is available.

Searches the restart stack without invoking. Useful for handlers that want to check available recovery options.

Type Signature

String -> Fx<{restarts: [Restart]}, Bool>

Parameters

name: Restart name to find

Example

func (ctx:
  if findRestart "retry" ctx
  then invokeRestart "retry" {}
  else invokeRestart "abort" {}
)

`handle`

Establishes a handler for conditions of given type.

Handlers are dynamically scoped - they apply to all conditions signaled during the effect’s execution. Handlers are checked from innermost to outermost.

Type Signature

String -> (Condition -> Fx<S, V>) -> Fx<S, V> -> Fx<S, V>

Parameters

conditionType: Type of condition to handle (“*” matches all)
handler: Function receiving condition, returns effect
effect: Effect to protect with handler

Example

handle "parse-error" (cond:
  # Can invoke restart, return value, or signal
  invokeRestart "use-default" defaultConfig
) (
  parseFile "config.json"
)

Handler Actions

The handler can:

invokeRestart name value - Resume at signal point
pure value - Provide value (if condition resumable)
signal otherCondition - Chain handling
Decline by signaling { type = "decline"; }

`handleBind`

Establishes multiple handlers at once.

Convenience for binding several handlers in one scope. Equivalent to nested handle calls but more concise.

Type Signature

[{pattern: String, action: Handler}] -> Fx<S, V> -> Fx<S, V>

Parameters

bindings: List of {pattern, action} handlers
effect: Protected effect

Example

handleBind [
  { pattern = "error"; action = cond: invokeRestart "abort" cond; }
  { pattern = "warning"; action = cond: logWarning cond; }
] code

`ignoreErrors`

Ignores all error conditions, returning default value.

Convenience handler that catches all errors and provides a fallback value. Useful for optional operations.

Type Signature

V -> Fx<S, V> -> Fx<S, V>

Parameters

default: Value to return on any error
effect: Effect that might error

Example

ignoreErrors {} (
  parseConfig "optional.json"
)  # Returns {} if parse fails

`invokeRestart`

Finds and invokes a restart by name.

Searches the dynamic restart stack for a restart with the given name and invokes it with the provided value. This is how handlers resume or recover from conditions.

Type Signature

String -> Value -> Fx<{restarts: [Restart]}, V>

Parameters

name: Name of restart to invoke
value: Value to pass to restart action

Example

handle "parse-error" (cond:
  if recoverable cond
  then invokeRestart "use-default" defaultConfig
  else invokeRestart "abort" { error = cond; }
) protectedCode

Behavior

Searches restarts innermost to outermost
Throws if restart not found
Invokes restart action with value
Control transfers to restart point

`restart`

Direct restart invocation (for use within signal context).

Lower-level primitive for invoking restarts. Typically used within handler code when the restart is known to be available.

Type Signature

String -> Value -> Fx<S, V>

Parameters

name: Restart name
value: Value for restart

Example

handle "error" (cond:
  restart "abort" { error = cond; }
) code

`signal`

Signals a condition, requesting handler from context.

Unlike exceptions that unwind the stack, signaling a condition requests a handler without unwinding. The handler can:

Invoke a restart to resume
Return a value
Signal another condition
Decline (no match), bubbling to outer handlers

Type Signature

Condition -> Fx<{handlers: [Handler], restarts: [Restart]}, {}>

Parameters

condition: Attrset describing the condition
- type: String identifying condition type (required)
- Other fields provide context

Example

# Signal parse error
signal { 
  type = "parse-error"; 
  file = "config.json";
  line = 42;
}

# Handler will be invoked without unwinding

Notes

Signal itself returns unit after handler completes
To abort with error, handler must invoke abort restart
Multiple handlers can be established (innermost first)

message: Warning message
details: Additional context

Example

warn "Deprecated option" { option = "oldName"; }

# Handler can log or collect:
handle "warning" (cond:
  trace cond.message (pure {})
) code

name: Restart name (e.g., “retry”, “use-default”, “abort”)
action: Function invoked when restart chosen
effect: Effect protected by this restart

Example

withRestart "use-default" (dflt: pure dflt)
  (withRestart "retry" (_: tryAgain)
    (parseFile "config.json"))

Common Restart Names

abort - Abandon operation, return error
retry - Try operation again
use-value - Use provided value instead
use-default - Use default value
skip - Skip problematic operation
continue - Proceed despite warning

Keyboard shortcuts

nfx