Context handling

web::context

Creation

web::context name

Creates a namespace name with the following commands:

name::subcommand args

Subcommands are: cset, cappend, clappend, cget, cexists, cunset, carray, cnames, and dump. Manages data of the context. The subcommands behave like the Tcl commands with similar names.

name::cset key value
store value.
name::cappend key value ?value? ?...?
append value to existing value for key.
name::clappend key value ?value? ?...?
append value to existing list of values for key.
name::cget key ?default?
access the value for key key, or return default if key does not exist in the context. If default is omitted, an empty string is returned if key is unknown.
name::cexists key
returns true (1) if key exists in context, false (0) otherwise.
name::cunset key
remove key from context.
name::carray option key arg
array manipulation as known from the Tcl command array.
name::cnames ?pattern?
lists existing keys of context matching pattern.
name::dump
serialize context.

Example 9. web::context

	    % web::context sc
	    % sc::cset lang FR
	    FR
	    % # ... some code ...
	    % set lang [sc::cget lang EN]
	    FR
	    %
	  

web::filecontext

Creation:

web::filecontext name ?options?

Options are: -perm, -path, -crypt, -idgen, and -attachto. Creates a namespace name to manage file-based context data:

name::subcommand args

Subcommands are: cset, cappend, clappend, cget, cexists, cunset, carray, cnames, init, new, commit, invalidate, and id. Manages file-based context data. The subcommands have their familiar behaviour of the Tcl commands with similar names. Please refer to the section context management for a description of the commands cset, cappend, clappend, cget, cexists, cunset, carray, and cnames.

name::init ?id?
load an existing session context with id id, or create a new one, if possible. Automation depends on the settings of the actual context manager settings, see below.
If you specify an id, you must decide when to create a new file and when to use the old one, if any, by yourself.
name::new ?id?
create a new session context. Automation depends on the settings of the actual context manager settings, see below.
name::commit
make session context persistent.
name::id
return id of session.
name::invalidate
delete session in memory and on file system.

Options:

web::filecontext name -perm perm

set the file permissions of the session context files perm is an unix-like octal value like 0644.

web::filecontext name -path path
specify where to store session context files and how to name them. Suppose that the session id is 99. -path [file join .. data s%d.dat] would then cause filecontext to save the session context as ../data/s99.dat.
web::filecontext name -crypt boolean
Flag to turn crypting of session context on and off. Default is on.
web::filecontext name -idgen idgen
Sets command idgen to find a new session id. See doc of web::filecounter below for an implementation provided with Websh.
idgen is used in case that no id argument has been passed to init or new.
web::filecontext name -attachto idparam
the next using the querystring (this is one reason why the querystring is encrypted). After web::dispatch has parsed the querystring, web::param will report the current session id, if any. Note that you can maintain several sessions in parallel, and attach every session to its own idparam.
Using web::dispatch -track further automates the passing of session ids from request to request.

Note: Whenever you create a new file-based context, the context is initialized and you loose whatever information that you might have stored in the context before you initialized it as a file-based session context.

web::cookiecontext

Creation:

web::cookiecontext name ?options?

Options are: -expires, -path, -domain, -secure, -crypt, and -channel. Creates a namespace name to manage cookie-based context data:

name::subcommand args
Subcommands are: cset, cappend, clappend, cget, cexists, cunset, carray, cnames, init, new, commit, invalidate, and id.

name::init ?id?
load an existing session context (cookie must have been sent by the client).
name::new ?id?
create a new session context.
name::commit
send a cookie.
name::id
return id of session.
name::invalidate
delete session in memory and on client side.

Options:

web::cookiecontext name -expires time
set the expiration date of the cookie. Possible values for time are day (lifetime: one day), week, today, seconds (time in seconds since 1-1-1970) or date-string.
web::cookiecontext name -path path
set the path property of the cookie.
web::cookiecontext name -domain domain
set the domain property of the cookie.
web::cookiecontext name -secure boolean
set the secure property of the cookie.
web::cookiecontext name -crypt boolean
Flag to turn crypting of cookie context on and off. Default is on.
web::cookiecontext name -channel channelName
The response object to send the cookie to (see also web::response).

Because cookies are client-based, in principle no id is needed. Websh uses id to name the cookie, however, and the new, init, and load commands still require the id argument. (fixme: any changes?) Please note that property settings of a cookie context can only be changed before anything is output on the respective channel.

web::filecounter

This is a numeric sequence-number generator which stores its state in a file. Basic usage:

Creation:
web::filecounter name -filename fname ?options?
Options are: -min, -max, -seed, -incr, -mask, -wrap
-filename filename
uses filename to store the current value (no default)
-min value
uses this value as a minimum at start and after wrap, if wrap is true (default is 0).
-max value
uses this value as a maximum, if wrap is true (default is 2147483647).
-seed value
if persistent file does not yet exists, use this value as a starting point (default is 0).
-incr value
uses this value as an increment for each 'nextval' (default is 1).
-perms value
sets the permissions on the newly created files (default is 0644).
-wrap boolean
indicates whether this counter should wrap around its values (from min to max) (default is false).

After creation, a new command name is registered with the following two subcommands:

name nextval
return the next value.
name curval
return the current value, that is, the value that the last call to "nextval" reported (as opposed to the current value in the file).

Example 10. web::filecounter

	  % web::filecounter handleName -filename "test.dat"
	  handleName
	  % # from now on, use handleName <curval|nextval|config>
	  % handleName config
	  file test.dat handle handleName seed 0 min 0 max 2147483647 incr 1 wrap false curr {not valid}
	  % web::filecounter otherHandleName -filename "othertest.dat" -min 1 -max 10 -seed 1 -incr 2 -wrap 1
	  otherHandleName
	  % otherHandleName config
	  file othertest.dat handle otherHandleName seed 1 min 1 max 10 incr 2 wrap true curr {not valid}
	  %