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, delete, 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::delete
delete the context (same as namespace delete name)
name::dump
serialize context.

Example 12. 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. If not specified, files are created with the permissions defined in web::config filepermissions, which again defaults to 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 seconds (time in seconds since 1970-01-01) or date-string (any time string that Tcl can scan. Note that therefore many relative times, such as 24 hours, week, 2 weeks, tomorrow, etc. are possible. Default is now + 24 hours (i.e. cookie expires in 24 hours. (Please note that the behavior of some of these relative time specifiers changed from Tcl8.4 to Tcl8.5.) Use -expires "" to send a cookie without an expires parameter.
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 configured in web::config filepermissions, which defaults to 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 subcommands:

name config
Return a flat list of key value pairs with the filecounter's configuration.
name nextval
Return the next value.
name curval
Return the current value, that is, the value that the last call to "nextval" or "getval" reported (as opposed to the current value in the file).
name getval
Return the current value in the file. (Do not increment file as in "nextval".)

Example 13. web::filecounter

% web::filecounter fc1 -filename test.dat
fc1
% fc1 config
file test.dat handle fc1 seed 0 min 0 max 2147483647 incr 1 perms 0644 wrap false curr {not valid}
% fc1 curval
web::filecounter: no current value available
% fc1 nextval
0
% fc1 config
file test.dat handle fc1 seed 0 min 0 max 2147483647 incr 1 perms 0644 wrap false curr 0
% fc1 nextval
1
% web::filecounter fc2 -filename test.dat
fc2
% fc2 curval
web::filecounter: no current value available
% fc2 getval
1
% fc2 nextval
2
% fc2 curval
2
% fc1 curval
1
% fc1 nextval
3
% fc2 getval
3
% web::filecounter fc3 -filename othertest.dat -min 1 -max 10 -seed 1 -incr 2 -wrap 1
fc3
% fc3 config
file othertest.dat handle fc3 seed 1 min 1 max 10 incr 2 perms 0644 wrap true curr {not valid}
% fc3 nextval
1
% fc3 nextval
3
%