+__END__
+
+=pod
+
+=encoding utf8
+
+=head1 NAME
+
+SL::Auth - Authentication and session handling
+
+=head1 FUNCTIONS
+
+=over 4
+
+=item C<set_session_value @values>
+
+=item C<set_session_value %values>
+
+Store all values of C<@values> or C<%values> in the session. Each
+member of C<@values> is tested if it is a hash reference. If it is
+then it must contain the keys C<key> and C<value> and can optionally
+contain the key C<auto_restore>. In this case C<value> is associated
+with C<key> and restored to C<$::form> upon the next request
+automatically if C<auto_restore> is trueish or if C<value> is a scalar
+value.
+
+If the current member of C<@values> is not a hash reference then it
+will be used as the C<key> and the next entry of C<@values> is used as
+the C<value> to store. In this case setting C<auto_restore> is not
+possible.
+
+Therefore the following two invocations are identical:
+
+ $::auth-E<gt>set_session_value(name =E<gt> "Charlie");
+ $::auth-E<gt>set_session_value({ key =E<gt> "name", value =E<gt> "Charlie" });
+
+All of these values are copied back into C<$::form> for the next
+request automatically if they're scalar values or if they have
+C<auto_restore> set to trueish.
+
+The values can be any Perl structure. They are stored as YAML dumps.
+
+=item C<get_session_value $key>
+
+Retrieve a value from the session. Returns C<undef> if the value
+doesn't exist.
+
+=item C<create_unique_sesion_value $value, %params>
+
+Create a unique key in the session and store C<$value>
+there.
+
+Returns the key created in the session.
+
+=item C<save_session>
+
+Stores the session values in the database. This is the only function
+that actually stores stuff in the database. Neither the various
+setters nor the deleter access the database.
+
+=item <save_form_in_session %params>
+
+Stores the content of C<$params{form}> (default: C<$::form>) in the
+session using L</create_unique_sesion_value>.
+
+If C<$params{non_scalars}> is trueish then non-scalar values will be
+stored as well. Default is to only store scalar values.
+
+The following keys will never be saved: C<login>, C<password>,
+C<stylesheet>, C<titlebar>, C<version>. Additional keys not to save
+can be given as an array ref in C<$params{skip_keys}>.
+
+Returns the unique key under which the form is stored.
+
+=item <restore_form_from_session $key, %params>
+
+Restores the form from the session into C<$params{form}> (default:
+C<$::form>).
+
+If C<$params{clobber}> is falsish then existing values with the same
+key in C<$params{form}> will not be overwritten. C<$params{clobber}>
+is on by default.
+
+Returns C<$self>.
+
+=back
+
+=head1 BUGS
+
+Nothing here yet.
+
+=head1 AUTHOR
+
+Moritz Bunkus E<lt>m.bunkus@linet-services.deE<gt>
+
+=cut