State

Note

Burr’s State API enables actions to talk to each other, and enables you to persist data. Burr has a State API that allows you to manipulate state in a functional way.

The State class provides the ability to manipulate state for a given action. It is entirely immutable, meaning that you can only create new states from old ones, not modify them in place.

State manipulation is done through calling methods on the State class. The most common write are:

state.update(foo=bar)  # update the state with the key "foo" set to "bar"
state.append(foo=bar)  # append "bar" to the list at "foo"
state.increment(foo=1)  # increment the value at "foo" by 1
state.wipe(keep=["foo", "bar"])  # remove all keys except "foo" and "bar"
state.wipe(delete=["foo", "bar"])  # remove "foo" and "bar" from the state

Warning

The State object can only be treated immutably! Calling state.update(foo=bar) will do nothing if you don’t use the value returned by the call.

The read operations extend from those in the Mapping interface, but there are a few extra:

state.subset(["foo", "bar"])  # return a new state with only the keys "foo" and "bar"
state.get_all()  # return a dictionary with every key/value of the state

When an update action is run, the state is first subsetted to get just the keys that are being read from, then the action is run, and a new state is written to. This state is merged back into the original state after the action is complete. Pseudocode:

current_state = ...
read_state = current_state.subset(action.reads)
result = action.run(new_state)
write_state = current_state.subset(action.writes)
new_state = action.update(result, new_state)
current_state = current_state.merge(new_state)

If you’re used to thinking about version control, this is a bit like a commit/checkout/merge mechanism.

Reloading Prior State

Note, if state is serializable, it means that if stored, it can be reloaded. This is useful for reloading state from a previous invocation (for debugging or as part of the application), or for storing state in a database. We have capabilities here, see the state-persistence section.