Index: doc/Object.man =================================================================== diff -u -rf8e79022a6358a42c082e1637a14bddaa3798e73 -r904ff24ee84cffe6fa24e00dc75bfe6872d18cf6 --- doc/Object.man (.../Object.man) (revision f8e79022a6358a42c082e1637a14bddaa3798e73) +++ doc/Object.man (.../Object.man) (revision 904ff24ee84cffe6fa24e00dc75bfe6872d18cf6) @@ -573,9 +573,6 @@ [call [arg obj] [method {object mixin}] ...] [para] Description of [method {object mixin}] ... -[call [arg obj] [method {object variable}] ...] -[para] Description of [method {object variable}] ... - [list_end] [cmd_def require] @@ -641,8 +638,42 @@ [list_end] + +[cmd_def variable] + +[list_begin definitions] + +[comment {::nx::Object variable ?-accessor /value/? ?-incremental? ?-class /value/? ?-configurable /boolean/? ?-initblock /value/? ?-nocomplain? /spec/ ?/defaultValue/?}] + +[call [arg obj] [const object] [method variable] [opt "[option -accessor] public | protected | private"] [opt [option -incremental]] [opt "[option -class] [arg className]"] [opt "[option -configurable] [arg trueFalse]"] [opt "[option -initblock] [arg script]"] [opt [option -nocomplain]] [arg spec] [opt [arg defaultValue]]] + +[include variable.man.inc] + +[para] + +By default, the [term variable] will ascertain that a +pre-existing and equally named object variable will not be overwritten +when defining the [term variable]. In case of a conflict, an error exception +is thrown: + +[example { +% Object create obj { set :x 1 } +::obj +% ::obj object variable x 2 +object ::obj has already an instance variable named 'x' +}] + +If the [term switch] [option -nocomplain] is on, this check is omitted (continuing the above example): + +[example { +% ::obj object variable -nocomplain x 2 +% ::obj eval {set :x} +2 +}] + [list_end] +[list_end] [section {Internally called Methods}] Index: doc/property.man.inc =================================================================== diff -u -r5eaa3c085b09fc995f311d18487b3411931ab25a -r904ff24ee84cffe6fa24e00dc75bfe6872d18cf6 --- doc/property.man.inc (.../property.man.inc) (revision 5eaa3c085b09fc995f311d18487b3411931ab25a) +++ doc/property.man.inc (.../property.man.inc) (revision 904ff24ee84cffe6fa24e00dc75bfe6872d18cf6) @@ -10,19 +10,28 @@ [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 -corresponding object variable. -[para] -If [option "-accessor"] is set, a property will provide for a pair of getter -and setter methods, automatically. By default, no getter and setter -methods are created. The option value passed along [option "-accessor"] -sets the level of [term "call protection"] for the getter and setter +[comment { + At the time of writing, the only material difference between + property and variable is a different -configurable default. +}] + +Defines a [term property] for the scope of the [vset SCOPE]. By +default, a property defines a configuration option for the [vset SCOPE] to +be accessed and modified using [method cget] and [method configure], +respectively (see also [option -configurable] below). Therefore, +assuming default settings, every [term property] is managed by a [term "slot object"]. + +[para] + +If [option "-accessor"] is set explicitly, a property will provide for a pair of +getter and setter methods, automatically. By default, no getter and +setter methods are created. The option value passed along [option "-accessor"] sets +the level of [term "call protection"] for the getter and setter methods: [term public], [term protected], or [term private]. [para] -By setting [option -configurable] to [const true], the property can be +By setting [option -configurable] to [const true] (the default), the property can be accessed and modified through [method cget] and [method configure], respectively. If [const false], the interface based on [method cget] and [method configure] will not become available. In this case, and provided that @@ -34,9 +43,10 @@ [para] -A custom class for the slot object implementing the property, from -which this slot object is to be instantiated, can be provided using -[option -class]. The default value is [cmd ::nx::VariableSlot]. +Provided a [term "slot object"] managing the [term property] is to be +created, a custom class [arg className] from which this [term "slot object"] is +to be instantiated can be set using [option -class]. The +default value is [cmd ::nx::VariableSlot]. [para] @@ -59,15 +69,24 @@ 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: +(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 element-wise ([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] + +In summary, a [term "slot object"] for the [term property] is provided under any of the following conditions: +[list_begin itemized] +[item] [option -configurable] equals [const true] (by default). +[item] [option -accessor] is one of [const public], [const protected], or [const private]. +[item] [option -incremental] is turned on. +[item] [arg initBlock] is not an empty string. +[list_end] Index: doc/variable.man.inc =================================================================== diff -u --- doc/variable.man.inc (revision 0) +++ doc/variable.man.inc (revision 904ff24ee84cffe6fa24e00dc75bfe6872d18cf6) @@ -0,0 +1,109 @@ +[comment {-*- tcl -*- manpage fragment for variable method, shared by nx::Object and nx::Class}] + +[keywords "variable"] + +[comment { + At the time of writing, the only material difference between + property and variable is a different -configurable default. +}] + +Defines a [term variable] for the scope of the [vset SCOPE]. + +[para] + +If [option "-accessor"] is set explicitly, a [term variable] will provide for a pair of +getter and setter methods, automatically. By default, no getter and +setter methods are created. The option value passed along [option "-accessor"] sets +the level of [term "call protection"] for the getter and setter +methods: [term public], [term protected], or [term private]. + +[para] + +By setting [option -configurable] to [const true], the [term variable] can be +accessed and modified through [method cget] and [method configure], +respectively. If [const false] (the default), the interface based on [method cget] and +[method configure] will not become available. In this case, and provided that +[option -accessor] is set, the [term variable] can be accessed and modified via +the getter/setter methods. Alternatively, the underlying Tcl variable, which +is represented by the [term variable], can always be accessed and modified +directly, e.g., using [method eval]. By default, [option -configurable] is +[const false]. + +[para] + +Provided a [term "slot object"] managing the [term variaböe] is to be +created, a custom class [arg className] from which this [term "slot object"] is +to be instantiated can be set using [option -class]. The +default value is [cmd ::nx::VariableSlot]. + +[para] + +The [arg spec] provides the [term variable] specification in form of [arg variableName][opt ":[emph typeSpec]"]. The [arg variableName] sets +the name of the [term variable] and the corresponding Tcl variable(s). It +is, optionally, equipped with a [arg typeSpec] following a colon +delimiter which specifies a [term "value checker"] for the values +managed by the [term variable]. Optionally, a [emph defaultValue] can be defined. + +[para] + +Using [option -initblock], an optional Tcl [arg script] can be defined which becomes passed into +the initialization procedure (see [method configure]) of the [term variable]'s [term "slot object"]. See +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 variable]. First, +setting [option -incremental] implies requesting [option -accessor] +([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 element-wise ([emph incrementally]), two +additional operations become available: + +[list_begin definitions] +[def "[arg obj] [arg variableName] [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 variableName] [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] + +In summary, a [term "slot object"] for the [term variable] is provided under any of the following conditions: +[list_begin itemized] +[item] [option -configurable] equals [const true]. +[item] [option -accessor] is one of [const public], [const protected], or [const private]. +[item] [option -incremental] is turned on. +[item] [option -initblock] is not assigned an empty string. +[list_end] + + + +[comment { + # @class.method {Object variable} + # + # Defines a per-object variable. Per default, no getter and setter + # methods for this object variable are created, unless requested + # explicitly. A defaul value can be specified. + # + # @parameter -accessor:switch If provided, a pair of getter + # and setter methods, named after the variable, are + # created on the fly. + # @parameter -class Allows for specifying a class for the + # managing <<@gls slotobject>> other than the default + # slot class, i.e., <<@class VariableSlot>>. Note that a + # slot object is not necessarily created by + # '''variable''', only if needed (i.e., accessors are + # requested, an init script is provided) + # @parameter -initblock An optional Tcl script which is evaluated + # for the scope of the variable-managing <<@gls + # slotobject>> during its initialization. + # @parameter -nocomplain:switch If this flag is provided, an + # existing object variable by the property name will not + # be overwritten. Instead, an error exception is thrown. + # @parameter spec The variable specification is a single element + # which specifies the variable name, optionally followed by + # parameter types after a colon delimiter. + # @parameter defaultValue If provided, sets the default value for this + # object variable. +}]