1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
|
[comment {-*- tcl -*- doctools manpage}]
[manpage_begin pregistry n 0.1]
[copyright {2006 Andreas Kupries <andreas_kupries@users.sourceforge.net>}]
[moddesc {Registry like data store}]
[titledesc {Registry like data store}]
[require Tcl 8.3]
[require pregistry [opt 0.1]]
[description]
[para]
This package provides a class for the creation of registry-like data
storage objects. The contents of each storage are organized in a tree,
with each node managing a set of children and attributes, each
possibly empty. Stores are not persistent by default, but can be made
so through configuring them with a tie backend to talk to.
[section {Class API}]
The package exports a single command, the class command, enabling the
creation of registry instances. Its API is:
[list_begin definitions]
[call [cmd ::pregistry] [arg object] [arg options]...]
This command creates a new registry object with the name [arg object],
initializes it, and returns the fully qualified name of the object
command as its result.
[para]
The recognized options are explained in section [sectref OPTIONS].
[list_end]
[section {Object API}]
The objects created by the class command provide the methods listed below:
[list_begin definitions]
[call [arg object] [method delete] [arg key] [opt [arg attr]]]
If the optional [arg attr] argument is present, the specified
attribute under [arg key] will be deleted from the object.
If the optional [arg attr] is omitted, the specified [arg key] and any
subkeys or attributes beneath it in the hierarchy will be deleted. If
the key could not be deleted then an error is generated. If the key
did not exist, the command has no effect.
The command returns the empty string as its result.
[call [arg object] [method mtime] [arg key] [opt [arg attr]]]
If the optional [arg attr] argument is present, the time of the last
modification of the specified attribute under [arg key] will be
returned, in seconds since the epoch.
If the optional [arg attr] is omitted, the time of the last
modification of the specified [arg key] will be returned.
If the key did not exist, the command will generate an error.
[call [arg object] [method exists] [arg key] [opt [arg attr]]]
If the optional [arg attr] argument is present, the method checks
whether the specified attribute under [arg key] is present or not.
If the optional [arg attr] is omitted, the method checks whether the
specified [arg key] is present or not.
In both cases the result returned is boolean value, [const True] if
the checked entity exists, and [const False] otherwise.
[call [arg object] [method get] [arg key] [arg attr]]
Returns the data associated with the attribute [arg attr] under the
[arg key]. If either the key or the attribute does not exist, then an
error is generated.
[call [arg object] [method get||default] [arg key] [arg attr] [arg default]]
Like method [method get], except that the [arg default] is returned if
either the key or the attribute does not exist, instead of generating
an error.
[call [arg object] [method keys] [arg key] [opt [arg pattern]]]
If [arg pattern] isn't specified, the command returns a list of names
of all the subkeys of [arg key]. If [arg pattern] is specified, only
those names matching the pattern are returned. Matching is determined
using the same rules as for [cmd {string match}]. If the specified
[arg key] does not exist, then an error is generated.
[call [arg object] [method set] [arg key] [opt "[arg attr] [arg value]"]]
If [arg attr] isn't specified, creates the [arg key] if it doesn't
already exist. If [arg attr] is specified, creates the [arg key]
keyName and attribute [arg attr] if necessary.
The contents of [arg attr] are set to [arg value]. The command returns
the [arg value] as its result.
[call [arg object] [method attrs] [arg key] [opt [arg pattern]]]
If [arg pattern] isn't specified, returns a list of names of all the
attributes of [arg key]. If [arg pattern] is specified, only those
names matching the pattern are returned. Matching is determined using
the same rules as for [cmd {string match}].
[call [arg object] [method configure]]
Returns a dictionary mapping the option of the object to their
currently configured values.
[call [arg object] [method configure] [arg option] [arg newvalue]...]
This invokation sets the configured value of option [arg option] to
[arg newvalue]. Nothing will be done if current and new value are
identical. Returns the empty string.
[call [arg object] [method configure] [arg option]]
[call [arg object] [method cget] [arg option]]
Returns the value configured for the specified option [arg option].
[list_end]
[section KEYS]
All elements in the registry are identified by a unique key, which is
a list of strings. This identifies the path from the root of the tree
to the requested element. The root itself is identified by the empty
list. Each child C of an element E have to have unique name, which
will be the last element of the key identifying this child. The head
of the key will be the key of E.
[section OPTIONS]
The registry object recognize a single option,
[list_begin options]
[opt_def -tie tiedefinition]
See the documentation of command [cmd ::tie::tie], in the package
[package tie]. The value of the option is a list of words equivalent
to the arguments "[arg dstype] [arg dsname]..." of [cmd ::tie::tie].
I.e. the identity of the tie backend to use, followed by the
specification of the location to use, per the chosen backend.
Example:
[example {
set r [pregistry %AUTO% -tie [list file $path]]
}]
[list_end]
[keywords registry {data store} tree]
[manpage_end]
|
