## Tcl9.0.3/Tk9.0.3 Documentation > Tcl Commands > configurable

### Tcl/Tk Applications | Tcl Commands | Tk Commands | [incr Tcl] Package Commands | SQLite3 Package Commands | TDBC Package Commands | tdbc::mysql Package Commands | tdbc::odbc Package Commands | tdbc::postgres Package Commands | tdbc::sqlite3 Package Commands | Thread Package Commands | Tcl C API | Tk C API | [incr Tcl] Package C API | TDBC Package C API

  NAME
    oo::configurable, configure, property — 構成設定できる級と対象を作り､構成設定可能な特性生成を支持する級 A class that makes configurable classes and objects, and supports making configurable properties
  構文 SYNOPSIS
  級の階層 CLASS HIERARCHY
  説明 DESCRIPTION
  CONFIGURE METHOD
  PROPERTY DEFINITIONS
    -get getterScript
    -kind propertyKind
    -set setterScript
  ADVANCED USAGE
    oo::configuresupport::configurable
    oo::configuresupport::configurableclass
    oo::configuresupport::configurableobject
    oo::configuresupport::readableproperties
    oo::configuresupport::writableproperties
    oo::configuresupport::objreadableproperties
    oo::configuresupport::objwritableproperties
  実装の準備 IMPLEMENTATION NOTE
  用例 　EXAMPLES
  SEE ALSO
  KEYWORDS

### NAME

oo::configurable, configure, property — 構成設定できる級と対象を作り､構成設定可能な特性生成を支持する級 A class that makes configurable classes and objects, and supports making configurable properties

### 構文 SYNOPSIS

package require TclOO
oo::configurable create class ?definitionScript?
oo::define class {
property propName ?options...? ?propName ?options...?...?
}
oo::objdefine object {
property propName ?options...? ?propName ?options...?...?
}
objectName configure
objectName configure -prop
objectName configure -prop value ?-prop value...

### 級の階層 CLASS HIERARCHY

oo::object
→ oo::class
→ oo::configurable
oo::object
→ oo::class
→ oo::configurablesupport::configurable

### 説明 DESCRIPTION

構成設定可能な対象は､configure 手段により構成設定されることを補助する対象である｡対象のそれぞれの構成設定可能な主体は対象の特性として知られている｡特性は級や即値の上で定義され得る; 対象を構成設定する時､その級又はその即値そのものによって(直接或は間接に)定義されているどの特性も構成設定され得る｡ Configurable objects are objects that support being configured with a configure method. Each of the configurable entities of the object is known as a property of the object. Properties may be defined on classes or instances; when configuring an object, any of the properties defined by its classes (direct or indirect) or by the instance itself may be configured.

oo::configurable 汎級は､構成設定可能可能な対象を作上げる為の､基本的な支援を級の中に取付ける｡これは､(譬えば､ oo::define 内部と､oo::objdefine 内部 の級の校正譜から)級と即値の為の､定義校正譜内で利用可能な､特性定義命令を作る事と､即値の内部で利用可能な､構成設定手段を作る事と､で構成される The oo::configurable metaclass installs basic support for making configurable objects into a class. This consists of making a property definition command available in definition scripts for the class and instances (e.g., from the class's constructor, within oo::define and within oo::objdefine) and making a configure method available within the instances.

#### CONFIGURE METHOD

configure 手段の振舞は､fconfigure/chan configure 命令を模範にしている｡ The behavior of the configure method is modelled after the fconfigure/chan configure command.

もし追加引数を何も渡さなかった場合､configure 手段は､全ての読出し可能と読み書き可能な特性とその現在値をアルファベット順に揃えた辞書を返す｡ If passed no additional arguments, the configure method returns an alphabetically sorted dictionary of all readable and read-write properties and their current values.

もし一個の追加引数を渡すと､そのconfigure手段への引数は読む為の特性の名前(又は､その為の､明確な前辞句)でなければならない; その値が返される｡ If passed a single additional argument, that argument to the configure method must be the name of a property to read (or an unambiguous prefix thereof); its value is returned.

それ以外では､もし偶数個の引数が渡されると､それぞれの引数の組が特性の名前(又は､その為の､明確な前辞句)とそれに組合せる値を指定する｡特性は指定された順に設定され､重複もありえる｡もしどれかの特性の設定が失敗すると､configure 手段全体が失敗する､先立つ対(それがあれば)は適用を続ける､亦､引続く対(それがあれば)は､適用されない｡成功すると､この様式の操作の中のconfigure手段の結果は空文字列になる｡ Otherwise, if passed an even number of arguments then each pair of arguments specifies a property name (or an unambiguous prefix thereof) and the value to set it to. The properties will be set in the order specified, including duplicates. If the setting of any property fails, the overall configure method fails, the preceding pairs (if any) will continue to have been applied, and the succeeding pairs (if any) will be not applied. On success, the result of the configure method in this mode operation will be an empty string.

#### PROPERTY DEFINITIONS

級がoo::configurable手段により製造された時､追加の特性propertyを得る｡property定義は一つ或はそれ以上の特性を定義し､それは級の即値によって露呈される｡ When a class has been manufactured by the oo::configurable metaclass (or one of its subclasses), it gains an extra definition, property. The property definition defines one or more properties that will be exposed by the class's instances.

property 命令は最初に定義する為に特性の名前を取る､先行するハイフン無しに､幾つもの特性-値対が続く､それが特性の基本的な振舞を修正する｡これに､任意の個数の他の特性定義が続き得る｡対応している指示項目は: The property command takes the name of a property to define first, without a leading hyphen, followed by a number of option-value pairs that modify the basic behavior of the property. This can then be followed by an arbitrary number of other property definitions. The supported options are:

-get getterScript
  これは特性から如何に読出すかの実装を定義する; もし特性の種類がそこから読出し可能な特性の様な場合､getterScript は､級上で定義された手段(引数を取らない)の実体になる｡手段は <ReadProp-propertyName>と名付けられ､特性として同じ名前を伴う即値変数の単純読出し､が無為設定になる(譬えば､“property xyz”は手段“<ReadProp-xyz>”が生成される事になる)｡ This defines the implementation of how to read from the property; the getterScript will become the body of a method (taking no arguments) defined on the class, if the kind of the property is such that the property can be read from. The method will be named <ReadProp-propertyName>, and will default to being a simple read of the instance variable with the same name as the property (e.g., “property xyz” will result in a method “<ReadProp-xyz>” being created).

-kind propertyKind
  これは如何なる種類の特性が生成されるかを定義する｡ propertyKind は正確に､readable か writable か readwrite(これが無為設定) の内の一つでなければならず､これは､特性をそれぞれ 読出し専用､書込み専用､読み書き にする｡読出し専用特性は､およそずっと､そこから読出しのみ可能､書込み専用は書込みのみ可能､読み書きは読出しと書込みの両方可能である｡ This defines what sort of property is being created. The propertyKind must be exactly one of readable, writable, or readwrite (which is the default) which will make the property read-only, write-only or read-write, respectively. Read-only properties can only ever be read from, write-only properties can only ever be written to, and read-write properties can be both read and written.

  註意すべきは､書込み専用は特に発見し難い､理由は､存在しない特性への書込みの試みの不都合報告書以外では､configure 手段によっては決して報告されないから｡ Note that write-only properties are not particularly discoverable as they are never reported by the configure method other than by error messages when attempting to write to a property that does not exist.

-set setterScript
  これは如何に特性に書込むかの実装を定義する; もし､特性の種類が書込まれる様な特性の場合､setterScript が級の上で定義された一個の引数 value を採る手段の本体になる｡手段は <WriteProp-propertyName> と名付けられ､特性として同じ名前を伴う即値変数の単純書込み､が無為設定になる(譬えば､“property xyz”は手段“<ReadProp-xyz>”が生成される事になる)｡ This defines the implementation of how to write to the property; the setterScript will become the body of a method taking a single argument, value, defined on the class, if the kind of the property is such that the property can be written to. The method will be named <WriteProp-propertyName>, and will default to being a simple write of the instance variable with the same name as the property (e.g., “property xyz” will result in a method “<WriteProp-xyz>” being created).

oo::configurable に生成された級の即値は､property定義にも対応している; 意味論は､特性が即値上のみで定義されることを除いて上述と正確に等しい｡ Instances of the class that was created by oo::configurable will also support property definitions; the semantics will be exactly as above except that the properties will be defined on the instance alone.

註意すべきは､特性を定義する特性実装手段は､私的とするべきではない､理由は､これは configure の実装から利用できなくするから(設計による; 特性の構成設定機構は､主に級の外側から使われることを意図している､ここで､級は直接変数を利用する)｡ Note that the property implementation methods that property defines should not be private, as this makes them inaccessible from the implementation of configure (by design; the property configuration mechanism is intended for use mainly from outside a class, whereas a class may access variables directly). The variables accessed by the default implementations of the properties may be private, if so declared.

### ADVANCED USAGE

構成設定可能な級大系は幾つかの部分から構成される｡oo::configurable 汎級は､級に混ぜ込み､亦､その他の機械設備を小出しに提供する対象生成の間の名前空間定義を設定する､ことにより働く｡実装の鍵の部分は､此処で列挙されたので､それらは､他の符号命令で使うことができる: The configurable class system is comprised of several pieces. The oo::configurable metaclass works by mixing in a class and setting definition namespaces during object creation that provide the other bits and pieces of machinery. The key pieces of the implementation are enumerated here so that they can be used by other code:

oo::configuresupport::configurable
  これは､(上述のCONFIGURE METHOD内に記述された)configure手段の実装を提供する級である｡ This is a class that provides the implementation of the configure method (described above in CONFIGURE METHOD).

oo::configuresupport::configurableclass
  これは､通用語の定義を含む名前空間であり､上述の PROPERTY DEFINITIONS の項の通りに､級内での使用(即ち､oo::define 経由､及び､通常環境下での級監督者 経由)の為の特性宣言を提供する｡それは､その特性命令に namespace exports を施すので､私的通用語定義の中で容易に使い得る｡[訳註:訳が…???] This is a namespace that contains the definition dialect that provides the property declaration for use in classes (i.e., via oo::define, and class constructors under normal circumstances), as described above in PROPERTY DEFINITIONS. It namespace exports its property command so that it may be used easily in user definition dialects.

oo::configuresupport::configurableobject
  これは､通用語定義を含む名前空間であり､上述のPROPERTY DEFINITIONS の項の通りに､即値対象内の使用(oo::objdefine 経由､及び､ oo::define 内の self 宣言経由)の為に､特性宣言を提供する｡それは､その特性命令に namespace exports を施すので､私的通用語定義の中で容易に使い得る｡ This is a namespace that contains the definition dialect that provides the property declaration for use in instance objects (i.e., via oo::objdefine, and the self declaration in oo::define), as described above in PROPERTY DEFINITIONS. It namespace exports its property command so that it may be used easily in user definition dialects.

下敷きなっている特性は､構成設定し得る特性を列挙している四つの項目(それが意味することは oo::define 参照)に依拠している機構を発見する｡これ等の項目はどの意味に於ても､唯一の名前を有し､重要な順位はなく､継承され得て､級と即値とで発見され得る事､以外は何も強制する事はしない｡ The underlying property discovery mechanism relies on four slots (see oo::define for what that implies) that list the properties that can be configured. These slots do not themselves impose any semantics on what the slots mean other than that they have unique names, no important order, can be inherited and discovered on classes and instances.

これ等の項目と､その意図された意味論は: These slots, and their intended semantics, are:

oo::configuresupport::readableproperties
  級の特性の揃い(上位の級からのものを含まない)であり､級の即値の構成設定時に､そこから読出され得る｡この項目は info class properties 命令でも読出せる｡ The set of properties of a class (not including those from its superclasses) that may be read from when configuring an instance of the class. This slot can also be read with the info class properties command.

oo::configuresupport::writableproperties
  級の特性の揃い(上位の級からのものを含まない)であり､級の即値の構成設定時に､そこに書込み得る｡この項目は info class properties 命令でも読出せる｡ The set of properties of a class (not including those from its superclasses) that may be written to when configuring an instance of the class. This slot can also be read with the info class properties command.

oo::configuresupport::objreadableproperties
  対象即値の揃い(上位の級からのものを含まない)であり､級の即値の構成設定時に､そこから読出され得る｡この項目は info object properties 命令でも読出せる｡ 　 The set of properties of an object instance (not including those from its classes) that may be read from when configuring the object. This slot can also be read with the info object properties command.

oo::configuresupport::objwritableproperties
  対象即値の揃い(上位の級からのものを含まない)であり､級の即値の構成設定時に､そこに書込み得る｡この項目は info object properties 命令でも読出せる｡ The set of properties of an object instance (not including those from its classes) that may be written to when configuring the object. This slot can also be read with the info object properties command.

註意すべきは､これらは項目であるが､標準 oo::define 名前空間や oo::objdefine 名前空間ではない; これらを記述譜定義内で使う為には､それは､略称はなく完全名で参照されねばならない｡理由は､構成設定可能な特性の建築煉瓦となる様､且つ､通常の使用者命令符号によって直接使用されない様意図されているから｡ Note that though these are slots, they are not in the standard oo::define or oo::objdefine namespaces; in order to use them inside a definition script, they need to be referred to by full name. This is because they are intended to be building bricks of configurable property system, and not directly used by normal user code.

#### 実装の準備 IMPLEMENTATION NOTE

configure 手段の実装は､如何なる特性がそれを操作するかを発見する為に､全指示項目を伴って info object properties を使う｡ The implementation of the configure method uses info object properties with the -all option to discover what properties it may manipulate.

### 用例 　EXAMPLES

此処で､単純な構成設定可能な級を作成し､それが如何に構成設定されるかを示す: Here we create a simple configurable class and demonstrate how it can be configured:

    oo::configurable create Point {
        property x y
        constructor args {
            my configure -x 0 -y 0 {*}$args
        }
        variable x y
        method print {} {
            puts "x=$x, y=$y"
        }
    }

    set pt [Point new -x 27]
    $pt print;   # x=27, y=0
    $pt configure -y 42
    $pt print;   # x=27, y=42
    puts "distance from origin: [expr {
        hypot([$pt configure -x], [$pt configure -y])
    }]";         # distance from origin: 49.92995093127971
    puts [$pt configure]
                 # -x 27 -y 42

その様な構成設定可能な級は､ 副級によって展開できる､但し特性定義を使う場合は､副級も､亦､ oo::configurable によって生成されねばならない｡ 　 Such a configurable class can be extended by subclassing, though the subclass needs to also be created by oo::configurable if it will use the property definition:

    oo::configurable create Point3D {
        superclass Point
        property z
        constructor args {
            next -z 0 {*}$args
        }
    }

    set pt2 [Point3D new -x 2 -y 3 -z 4]
    puts [$pt2 configure]
                 # -x 2 -y 3 -z 4

一たび､構成設定可能な級を得ると､それに即値特性を追加できる｡ (全ての特性の為の背後変数は除去を始める｡)註意すべきは､それを設定する時､特性名の明確な前置辞を使う; これが全ての特性に関して対応しているが､通常､全名前が推奨される､理由は副級は明確な前置辞を作ろうとせず､その場合､不明確になるから｡ Once you have a configurable class, you can also add instance properties to it. (The backing variables for all properties start unset.) Note below that we are using an unambiguous prefix of a property name when setting it; this is supported for all properties though full names are normally recommended because subclasses will not make an unambiguous prefix become ambiguous in that case.

    oo::objdefine $pt {
        property color
    }
    $pt configure -c bisque
    puts [$pt configure]
                 # -color bisque -x 27 -y 42

それを読出しのみになすこと､及び､それを計算する記述譜を提供すること､により､特性の派生化が可能である｡ You can also do derived properties by making them read-only and supplying a script that computes them.

    oo::configurable create PointMk2 {
        property x y
        property distance -kind readable -get {
            return [expr {hypot($x, $y)}]
        }
        variable x y
        constructor args {
            my configure -x 0 -y 0 {*}$args
        }
    }

    set pt3 [PointMk2 new -x 3 -y 4]
    puts [$pt3 configure -distance]
                 # 5.0
    $pt3 configure -distance 10
                 # ERROR: bad property "-distance": must be -x or -y

設定譜は特性の型の検証に使われる: Setters are used to validate the type of a property:

    oo::configurable create PointMk3 {
        property x -set {
            if {![string is double -strict $value]} {
                error "-x property must be a number"
            }
            set x $value
        }
        property y -set {
            if {![string is double -strict $value]} {
                error "-y property must be a number"
            }
            set y $value
        }
        variable x y
        constructor args {
            my configure -x 0 -y 0 {*}$args
        }
    }

    set pt4 [PointMk3 new]
    puts [$pt4 configure]
                 # -x 0 -y 0
    $pt4 configure -x 3 -y 4
    puts [$pt4 configure]
                 # -x 3 -y 4
    $pt4 configure -x "obviously not a number"
                 # ERROR: -x property must be a number

### SEE ALSO

info, oo::class, oo::define

### KEYWORDS

class, object, properties, configuration
Copyright © 2019 Donal K. Fellows