Zaphod::Session->new ARGS

Creates a new session.

The following fields can be set through the constructor:

    clients  - hashref of preexisting clients
    document - arrayref of the document
    timeout  - client session timeout in seconds
    cookie   - the secret cookie
    name     - the session name

$session->log TYPE, MSG

Logging callback. Currently just prints to STDOUT

$session->api API

Factory method to produce and instantiate the APIs. Currently, the only supported API is

$session->action_from_client CLIENT,STATE,ACTIONS

Insert actions from a client, advancing the master state.

Returns a true value if all actions applied without problems. If there were some actions that couldn't be merged without a conflict, returns a false value. All other actions got applied.

The conflicting action is silently discarded at the moment, at least there's no feedback mechanism for the client yet.

$session->actions_for_client CLIENT, STATE

Returns the actions that bring the client from its current state to the current state of the master.

$session->gen_cookie CLIENT

Generates a shared secret for identifying a connected client.


Returns a free color number

$session->valid_cookie COOKIE

Returns true if the given cookie is a valid client connection. In fact, the value returned is the hash entry for the relevant client.

$session->connect_client VISUAL

Adds/connects a new client.

The current client attributes are

  state           - state of the client document
  last_seen       - epoch when the client last connected
  cursor_position - offset of the client position
  visual          - the name of the client

The function returns the handle to be used in all future function calls of the client.

$session->sane_username VISUAL

Returns true if the username VISUAL is considered sane enough.

Currently this means it doesn't start with, end with or contain multiple whitespace characters.

HTML entities are not yet handled (see TODO)

$session->unique_username VISUAL

Returns true if the username VISUAL is considered unique enough.

$session->saw_client CLIENT

Resets the timeout counter for CLIENT if it exits. Returns the hashref corresponding to CLIENT if it exists.


Returns the number of logged in users

$session->client_cursor CLIENT, OFFSET

Sets the offset for the cursor position of the client

$session->disconnect_client CLIENT

Removes the client from the session

$session->prune_clients TIMEOUT

Disconnects all clients that haven't polled since TIMEOUT seconds. If TIMEOUT is not given, the value of the timeout accessor is used.

If a disconnected client later connects again, the connection is rejected and the client will have to log in again.

$session->users_for_client CLIENT

Returns the list of the other users and their positions for the session

$session->set_name NEWNAME

Sets the name of the current session, permissions provided.

The new name will be broadcast to the other clients. The name change is currently out-of-band with the editor, so there is no undo/redo functionality for it.

$session->save DIR

Serializes the session to disk. This will create two files in DIR, $session.document and $session.meta. The .document file will contain the document, and .meta file will contain metadata. The following metadata is saved:


If more elaborate session management comes to frutition, also the session owner and allowed viewers etc. will be saved in the .meta file. The .meta file is a simple custom file format of key-value pairs matching


and will be read and written as UTF-8. The document will be read and written via :utf8 as well.

Zaphod::Session->load FILE, ARGS

Constructor to intialize and then load a session from a file.

The filename can be either the name of the document file or the name of the metafile.

Currently, persistent_values is not checked against the keys loaded from the .meta file.


(Class method)

Returns all keys except document that persist on-disk.


Written by Max Maischein <>

Copyright Max Maischein 2005,2006; All Rights Reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.