Index: TODO =================================================================== diff -u -rcf1d2fecdcc673946bba91511f9f0cb82a850c69 -r5eaa3c085b09fc995f311d18487b3411931ab25a --- TODO (.../TODO) (revision cf1d2fecdcc673946bba91511f9f0cb82a850c69) +++ TODO (.../TODO) (revision 5eaa3c085b09fc995f311d18487b3411931ab25a) @@ -5011,6 +5011,20 @@ ======================================================================== TODO: +- incremental: should we add a third operation? + + /obj/ /prop/ get /index/ + + right now, we only provide a setter facade (add, delete) for list + values, no getter one. Reasons: consistency (per-element getter + + setter), a complete getter+setter facade would also allow for + switching from a list representation of multivalued values to + another one (e.g., some mongodb data structure?) without changing + clients of the incremental interface (e.g., which now use [lindex] + etc. to retrieve elements from the property-managed list value) ... + + get would behave like (=be implemented with) lindex. + - multiplicity: Check or clarify the intended semantics of the lower bound 1 in 0..1/1..1 when it comes to the empty string "". Index: doc/property.man.inc =================================================================== diff -u -r5c386b5e1011480621bf5134e9d232dd922d27f7 -r5eaa3c085b09fc995f311d18487b3411931ab25a --- doc/property.man.inc (.../property.man.inc) (revision 5c386b5e1011480621bf5134e9d232dd922d27f7) +++ doc/property.man.inc (.../property.man.inc) (revision 5eaa3c085b09fc995f311d18487b3411931ab25a) @@ -1,13 +1,14 @@ [comment {-*- tcl -*- manpage fragment for property method, shared by nx::Object and nx::Class}] -[keywords property] +[keywords "property"] [keywords "slot object"] [keywords "call protection"] [keywords "public"] [keywords "protected"] [keywords "private"] [keywords "switch"] [keywords "value checker"] +[keywords "multiplicity"] Defines a [term property] for the scope of the [vset SCOPE]. For every property, a [term "slot object"] is created to manage the @@ -19,11 +20,6 @@ sets the level of [term "call protection"] for the getter and setter methods: [term public], [term protected], or [term private]. -[list_begin arguments] -[arg_def switch -incremental in] ... - -[list_end] - [para] By setting [option -configurable] to [const true], the property can be @@ -56,4 +52,22 @@ The last argument [arg initBlock] accepts an optional Tcl script which is passed into the initialization procedure (see [method configure]) of the [term property]'s [term "slot object"]. See -also [sectref description "[arg initBlock] for [method create] and [method new]"]. \ No newline at end of file +also [sectref description "[arg initBlock] for [method create] and [method new]"]. + +[para] + +Turning on the [term switch] [option -incremental] provides a refined +setter interface to the value managed by the [term property]. First, +setting [option -incremental] implies requesting [option -accessor] +(set to [emph public] by default, if not specified explicitly). Second, +the managed value will be considered a valid Tcl list. A [term multiplicity] of +[const 0..*] is set by default, if not specified explicitly as part of +[arg spec] (see above). Third, to manage this list value +[emph incrementally], two additional operations become available: + +[list_begin definitions] +[def "[arg obj] [arg propertyName] [method add] [arg element] [opt [arg index]]"] +Adding [arg element] to the managed list value, at the list position given by [arg index] (by default: 0). +[def "[arg obj] [arg propertyName] [method delete] [arg element] [opt [arg index]]"] +Removing the first occurrence of [arg value] from the managed list value, starting from list position [arg index] (by default: [const end]). +[list_end]