0.9.9e/doc/Tcl.txt

sketch of the malete Tcl binding


*       records are proper Tcl data objects

A record is represented as a standard Tcl data object.
It can be assigned to a variable, a slot in an array or to a proc's
return value (the interp's result).

The objects's string rep is the standard serialization
(without trailing blank line; blank lines are ignored when de-serializing).

The object's internal rep is a Malete List, i.e. a modifiable record.


* records are accessed by views

Just like Tcl image objects are accessed using the command "image",
there are several commands to access records.

Different commands interpret the records in different ways:
A basic command provides a plain list view on the array,
while derived extensions may provide a view on
>       RecStruct       delimited structures
or other specialized record types.


Unlike the "image" command, record views are stateful. They may
-       be bound to a "current" record object
-       maintain a cursor position in the current record
-       have a current frame (subrecord)
-       have an associated field definition to resolve symbolic names
-       have an associated database name (defaulting to the view's name)

The view commands may be cloned in order to maintain several such states
in parallel. A different view command may be used for every record
resulting in a Tk-style "object oriented" feel.

The typical application, however, will use only a small number of views
like "v" and "w" or some database names.

The actual work of accessing field definitions and databases
will be handed over to additional configurable procedures,
which are typically implemented in Tcl.


*       view command

Many commands take an index expression , which
-       selects some of the record's fields
-       cuts some part out of these fields, typically subfields

When invoked with no parameters, the current record object is returned.

Most commonly used in rendering record contents is the one-parameter form 
v _index_, returning a field based on the cursor and current record.

In all other forms, the first parameter denotes a view function:
-       list _index_
        returns all data addressed by _index_ as a list
-       array _index_
        returns all data addressed by _index_ as a names and values list like
        the Tcl command "array get"
-       head _index_
        get parts of header
-       with _record_ [args ...]
        Without args, binds the view to _record_.
        With args, temporarily binds the view to _record_ for the execution of
        the view command given by args.
-       do _script_
        execute script. Syntactic sugar for with _record_ do _script_


Modifying records:
In the basic implementation,
a view may only modify a record if it's the only view bound to this record.
As the record's struct Tcl_Obj provides a twoPtrValue from which only one
pointer is needed to refer to the list,
the ptr2 may be used to point to a view for synchronization purposes
(and views bound to the same record may be chained).


Database access: read, write (ins/upd)
1	sketch of the malete Tcl binding
2
3
4	* records are proper Tcl data objects
5
6	A record is represented as a standard Tcl data object.
7	It can be assigned to a variable, a slot in an array or to a proc's
8	return value (the interp's result).
9
10	The objects's string rep is the standard serialization
11	(without trailing blank line; blank lines are ignored when de-serializing).
12
13	The object's internal rep is a Malete List, i.e. a modifiable record.
14
15
16	* records are accessed by views
17
18	Just like Tcl image objects are accessed using the command "image",
19	there are several commands to access records.
20
21	Different commands interpret the records in different ways:
22	A basic command provides a plain list view on the array,
23	while derived extensions may provide a view on
24	> RecStruct delimited structures
25	or other specialized record types.
26
27
28	Unlike the "image" command, record views are stateful. They may
29	- be bound to a "current" record object
30	- maintain a cursor position in the current record
31	- have a current frame (subrecord)
32	- have an associated field definition to resolve symbolic names
33	- have an associated database name (defaulting to the view's name)
34
35	The view commands may be cloned in order to maintain several such states
36	in parallel. A different view command may be used for every record
37	resulting in a Tk-style "object oriented" feel.
38
39	The typical application, however, will use only a small number of views
40	like "v" and "w" or some database names.
41
42	The actual work of accessing field definitions and databases
43	will be handed over to additional configurable procedures,
44	which are typically implemented in Tcl.
45
46
47	* view command
48
49	Many commands take an index expression , which
50	- selects some of the record's fields
51	- cuts some part out of these fields, typically subfields
52
53	When invoked with no parameters, the current record object is returned.
54
55	Most commonly used in rendering record contents is the one-parameter form
56	v _index_, returning a field based on the cursor and current record.
57
58	In all other forms, the first parameter denotes a view function:
59	- list _index_
60	returns all data addressed by _index_ as a list
61	- array _index_
62	returns all data addressed by _index_ as a names and values list like
63	the Tcl command "array get"
64	- head _index_
65	get parts of header
66	- with _record_ [args ...]
67	Without args, binds the view to _record_.
68	With args, temporarily binds the view to _record_ for the execution of
69	the view command given by args.
70	- do _script_
71	execute script. Syntactic sugar for with _record_ do _script_
72
73
74	Modifying records:
75	In the basic implementation,
76	a view may only modify a record if it's the only view bound to this record.
77	As the record's struct Tcl_Obj provides a twoPtrValue from which only one
78	pointer is needed to refer to the list,
79	the ptr2 may be used to point to a view for synchronization purposes
80	(and views bound to the same record may be chained).
81
82
83	Database access: read, write (ins/upd)