This is the preferred, type-indexed implementation of server-side state.
Glossary
A persistent entity (PE) is a time-indexed, named global value.
The current value of a PE is the value that the PE has now.
A handle gives access to a snapshot of a persistent entity at a particular time, potentially in the past.
A handle is current if the value of the PE has not been set
or add
ed to after the creation of the handle.
Documentation
init :: (Read a, Show a, Types a) => String -> a -> CGI (T a)Source
init name initialValue
creates a new PE with name name
with initial
value initialValue
and returns the handle to the initial value. If the PE
already exists, then init
returns the handle to the current value.
get :: (Read a, Types a) => T a -> CGI aSource
get handle
retrieves the value of handle
. This value may not be current
because the handle may point to a snapshot from the past.
set :: (Read a, Show a, Types a) => T a -> a -> CGI (Maybe (T a))Source
set handle newValue
tries to overwrite the value of the pe pointed to by
handle
with newValue
. Succeeds Just handle1
if handle
is current, in
this case it returns a handle to the new value. Fails Nothing
if the handle
is not current.
add :: (Read a, Show a, Types a) => T [a] -> a -> CGI (T [a])Source
add handle addValue
conceptually, this operation adds addValue
to the
set of values stored in handle
. Since this set is represented as a list,
handle
must point to a value of type [a]
. Since the PE is assumed to
contain a set, it does not matter if handle
is current. However, the
returned handle is guaranteed to be current with a value that contains
addValue
.
current :: (Read a, Types a) => T a -> CGI (Maybe (T a))Source
current handle
returns a handle to the PE pointed to by
handle
. It returns Nothing
if handle
is still current. Otherwise, it
returns Just newHandle
where newHandle
is current in the sense defined
above. Using the newHandle
obtained from current
explicitly discards the
value pointed to by handle
in favor of a value that may have been stored
by a concurrently executing script. Use with caution!