# Class LittleGhost::Support::Callbacks

Documentation version: Edge

Canonical HTML: https://littleghostai.org/docs/LittleGhost/Support/Callbacks.html

Callbacks lets extensions prepare, replace, or cancel framework work in a
predictable order. A later callback sees any replacement made earlier in the
chain.

A callback may return Callbacks.continue, Callbacks.cancel, or
Callbacks.replace. Any other return value means continue. Replacements become
the payload for later callbacks.

Every decision responds to `continue?`, `cancel?`, and
`replace?`. A cancellation also exposes `reason`; a replacement
exposes `value`. Extensions should depend on these methods rather than a
decision's concrete class.

    callbacks = LittleGhost::Support::Callbacks.new(:prepare)
    callbacks.on(:prepare) do |payload|
      LittleGhost::Support::Callbacks.replace(payload.merge(debug: true))
    end
    decision = callbacks.run(:prepare, {})
    decision.value # => {debug: true}

## Inheritance

`LittleGhost::Support::Callbacks < Object`

## Class methods

<a id="method-c-cancel"></a>
### `.cancel`

```ruby
.cancel(reason = nil)
```

Creates a decision whose `cancel?` predicate indicates that
callback processing should stop. The returned value exposes the optional
`reason`.

<a id="method-c-continue"></a>
### `.continue`

```ruby
.continue()
```

Uses the shared decision whose `continue?` predicate indicates that
callback processing should proceed.

<a id="method-c-new"></a>
### `.new`

```ruby
.new(*names)
```

Starts an empty chain for the declared callback `names`.

<a id="method-c-replace"></a>
### `.replace`

```ruby
.replace(value)
```

Creates a decision whose `replace?` predicate indicates that later
callbacks should receive `value`.

## Instance methods

<a id="method-i-initialize_copy"></a>
### `#initialize_copy`

```ruby
#initialize_copy(source)
```

Duplicates callback arrays so subclasses and instances can extend a copy.

<a id="method-i-merge"></a>
### `#merge`

```ruby
#merge(other)
```

Combines this chain with `other` while preserving prepend ordering.

<a id="method-i-on"></a>
### `#on`

```ruby
#on(name, callable = nil, prepend: false, &block)
```

Registers a callable, block, or receiver method name for `name`.

<a id="method-i-run"></a>
### `#run`

```ruby
#run(name, payload, context: nil, receiver: nil)
```

Runs `name` until callbacks finish or one cancels the chain.

The returned decision responds to `continue?`,
`cancel?`, and `replace?`. Cancellation decisions expose
`reason`, while replacement decisions expose the final `value`.