TWiki/TWikiMetaDotPm.mdwn

   1 # <a name="Package &lt;code&gt;TWiki::Meta="></a> Package =TWiki::Meta
   2
   3 Meta-data handling.
   4
   5 A meta-data object is a hash of different types of meta-data (keyed on the type, such as 'FIELD' and 'TOPICINFO').
   6
   7 Each entry in the hash is an array, where each entry in the array contains another hash of the key=value pairs, corresponding to a single meta-datum.
   8
   9 If there may be multiple entries of the same top-level type (i.e. for FIELD and FILEATTACHMENT) then the array hash multiple entries. These types are referred to as "keyed" types. The array entries are keyed with the attribute 'name' which must be in each entry in the array.
  10
  11 For unkeyed types, the array has only one entry.
  12
  13 The module knows nothing about how meta-data is stored. That is entirely the responsibility of the Store module.
  14
  15 Meta-data objects are created by the Store engine when topics are read. They are populated using the `put` method.
  16
  17 <div>
  18   <ul>
  19     <li><a href="#Package =TWiki::Meta="> Package TWiki::Meta</a><ul>
  20         <li><a href="#ClassMethod <strong>new</strong> ($session,$web"> ClassMethod new <tt>($session,$web,$topic)</tt></a></li>
  21         <li><a href="#ClassMethod <strong>web</strong> ()"> ClassMethod web <tt>()</tt></a></li>
  22         <li><a href="#ClassMethod <strong>topic</strong> ()"> ClassMethod topic <tt>()</tt></a></li>
  23         <li><a href="#ObjectMethod <strong>put</strong> ($type,\%args"> ObjectMethod put <tt>($type,\%args)</tt></a></li>
  24         <li><a href="#ObjectMethod <strong>putKeyed</strong> ($type,\"> ObjectMethod putKeyed <tt>($type,\%args)</tt></a></li>
  25         <li><a href="#ObjectMethod *putAll*"> ObjectMethod putAll <tt></tt></a></li>
  26         <li><a href="#ObjectMethod <strong>get</strong> ($type,$key)"> ObjectMethod get <tt>($type,$key) -&gt; \%hash</tt></a></li>
  27         <li><a href="#ObjectMethod <strong>find</strong> ($type) -> @"> ObjectMethod find <tt>($type) -&gt; @values</tt></a></li>
  28         <li><a href="#StaticMethod *index_ByKey*"> StaticMethod indexByKey <tt></tt></a></li>
  29         <li><a href="#ObjectMethod <strong>remove</strong> ($type,$ke"> ObjectMethod remove <tt>($type,$key)</tt></a></li>
  30         <li><a href="#ObjectMethod <strong>copyFrom</strong> ($otherM"> ObjectMethod copyFrom <tt>($otherMeta,$type,$nameFilter)</tt></a></li>
  31         <li><a href="#ObjectMethod <strong>count</strong> ($type) ->"> ObjectMethod count <tt>($type) -&gt; $integer</tt></a></li>
  32         <li><a href="#ObjectMethod *get_RevisionInfo*"> ObjectMethod getRevisionInfo <tt>($fromrev) -&gt; ($date,$author,$rev,$comment)</tt></a></li>
  33         <li><a href="#ObjectMethod <strong>merge</strong> ($otherMeta"> ObjectMethod merge <tt>($otherMeta,$formDef)</tt></a></li>
  34         <li><a href="#ObjectMethod <strong>stringify</strong> ($types"> ObjectMethod stringify <tt>($types) -&gt; $string</tt></a></li>
  35         <li><a href="#ObjectMethod *for_EachSelectedVa"> ObjectMethod forEachSelectedValue <tt>($types,$keys,\&amp;fn,\%options)</tt></a></li>
  36         <li><a href="#ObjectMethod <strong>getParent</strong> () -> $"> ObjectMethod getParent <tt>() -&gt; $parent</tt></a></li>
  37         <li><a href="#ObjectMethod <strong>get_FormName</strong> () -"> ObjectMethod getFormName <tt>() -&gt; $formname</tt></a></li>
  38       </ul>
  39     </li>
  40   </ul>
  41 </div>
  42
  43 ## <a name="ClassMethod &lt;strong&gt;new&lt;/strong&gt; ($session,$web"></a> [[ClassMethod]] **new** `($session,$web,$topic)`
  44
  45 Construct a new, empty Meta collection.
  46
  47 ## <a name="ClassMethod &lt;strong&gt;web&lt;/strong&gt; ()"></a> [[ClassMethod]] **web** `()`
  48
  49 Get the web name
  50
  51 ## <a name="ClassMethod &lt;strong&gt;topic&lt;/strong&gt; ()"></a> [[ClassMethod]] **topic** `()`
  52
  53 Get the topic name
  54
  55 ## <a name="ObjectMethod &lt;strong&gt;put&lt;/strong&gt; ($type,\%args"></a> [[ObjectMethod]] **put** `($type,\%args)`
  56
  57 Put a hash of key=value pairs into the given type set in this meta.
  58
  59 See the main comment for this package to understand how meta-data is represented.
  60
  61 ## <a name="ObjectMethod &lt;strong&gt;putKeyed&lt;/strong&gt; ($type,\"></a> [[ObjectMethod]] **putKeyed** `($type,\%args)`
  62
  63 Put a hash of key=value pairs into the given type set in this meta. The entries are keyed by 'name'.
  64
  65 See the main comment for this package to understand how meta-data is represented.
  66
  67 ## <a name="ObjectMethod &lt;strong&gt;putAll*"></a><a name="ObjectMethod *putAll&lt;/strong&gt; "></a> [[ObjectMethod]] **putAll** ``
  68
  69 Replaces all the items of a given key with a new array This is the logical inverse of the find method
  70
  71 ## <a name="ObjectMethod &lt;strong&gt;get&lt;/strong&gt; ($type,$key)"></a><a name="ObjectMethod &lt;strong&gt;get&lt;/strong&gt; ($type,$key) "></a> [[ObjectMethod]] **get** `($type,$key) -> \%hash`
  72
  73 Find the value of a meta-datum in the map. If the type is keyed, the $key parameter is required to say _which_ entry you want. Otherwise it can be undef.
  74
  75 WARNING SMELL If key is undef but the type is keyed you get the FIRST entry If you want all the keys of a given type use the 'find' method.
  76
  77 The result is a reference to the hash for the item.
  78
  79 ## <a name="ObjectMethod &lt;strong&gt;find&lt;/strong&gt; ($type) - @v"></a> [[ObjectMethod]] **find** `($type) -> @values`
  80
  81 Get all meta data for a specific type Returns the array stored for the type. This will be zero length if there are no entries.
  82
  83 ## <a name="StaticMethod &lt;strong&gt;index_ByKey*"></a><a name="StaticMethod *index_ByKey&lt;/strong&gt; "></a> [[StaticMethod]] **indexByKey** ``
  84
  85 See tests/unit/MetaTests.pm for an example
  86
  87 The result is a hash the same as the array provided by find but keyed by the keyName. NB. results are indeterminate if the key you choose is not unique in the find.
  88
  89 Flattens a keyed hash structure, taking only the values. Returns a hash.
  90
  91 See tests/unit/MetaTests.pm for an example
  92
  93 ## <a name="ObjectMethod &lt;strong&gt;remove&lt;/strong&gt; ($type,$ke"></a> [[ObjectMethod]] **remove** `($type,$key)`
  94
  95 With no type, will remove all the contents of the object.
  96
  97 With a $type but no $key, will remove _all_ items of that type (so for example if $type were FILEATTACHMENT it would remove all of them)
  98
  99 With a $type and a $key it will remove only the specific item.
 100
 101 ## <a name="ObjectMethod &lt;strong&gt;copyFrom&lt;/strong&gt; ($otherM"></a> [[ObjectMethod]] **copyFrom** `($otherMeta,$type,$nameFilter)`
 102
 103 Copy all entries of a type from another meta data set. This will destroy the old values for that type, unless the copied object doesn't contain entries for that type, in which case it will retain the old values.
 104
 105 If $type is undef, will copy ALL TYPES.
 106
 107 If $nameFilter is defined (an RE), it will copy only data where \{name\} matches $nameFilter.
 108
 109 SMELL: This is a shallow copy
 110
 111 ## <a name="ObjectMethod &lt;strong&gt;count&lt;/strong&gt; ($type) - $"></a> [[ObjectMethod]] **count** `($type) -> $integer`
 112
 113 Return the number of entries of the given type that are in this meta set
 114
 115 ## <a name="ObjectMethod &lt;strong&gt;get_RevisionInfo*"></a><a name="ObjectMethod *get_RevisionInfo&lt;/strong&gt; "></a> [[ObjectMethod]] **getRevisionInfo** `($fromrev) -> ($date,$author,$rev,$comment)`
 116
 117 Try and get revision info from the meta information, or, if it is not present, kick down to the Store module for the same information.
 118
 119 Returns ( $revDate, $author, $rev, $comment )
 120
 121 $rev is an integer revision number.
 122
 123 ## <a name="ObjectMethod &lt;strong&gt;merge&lt;/strong&gt; ($otherMeta"></a> [[ObjectMethod]] **merge** `($otherMeta,$formDef)`
 124
 125 - `$otherMeta` - a block of meta-data to merge with $this
 126 - `$formDef` reference to a TWiki::Form that gives the types of the fields in $this
 127
 128 Merge the data in the other meta block.
 129
 130 - File attachments that only appear in one set are preserved.
 131 - Form fields that only appear in one set are preserved.
 132 - Form field values that are different in each set are text-merged
 133 - We don't merge for field attributes or title
 134 - Topic info is not touched
 135 - The `mergeable` method on the form def is used to determine if that fields is mergeable. if it isn't, the value currently in meta will _not_ be changed.
 136
 137 ## <a name="ObjectMethod &lt;strong&gt;stringify&lt;/strong&gt; ($types"></a> [[ObjectMethod]] **stringify** `($types) -> $string`
 138
 139 Return a string version of the meta object. Uses \\n to separate lines. If $types is specified, return only types specified by that RE.
 140
 141 ## <a name="ObjectMethod &lt;strong&gt;for_EachSelectedVa"></a> [[ObjectMethod]] \*forEachSelectedValue `($types,$keys,\&fn,\%options)`
 142
 143 Iterate over the values selected by the regular expressions in $types and $keys.
 144
 145 - `$types` - regular expression matching the names of fields to be processed. Will default to qr/^[A-Z]+$/ if undef.
 146 - `$keys` - regular expression matching the names of keys to be processed. Will default to qr/^[a-z]+$/ if undef.
 147
 148 Iterates over each value, calling `\&fn` on each, and replacing the value with the result of \\&amp;fn.
 149
 150 \\%options will be passed on to $fn, with the following additions:
 151
 152 - `_type` =&gt; the type name (e.g. "FILEATTACHMENT")
 153 - `_key` =&gt; the key name (e.g. "user")
 154
 155 ## <a name="ObjectMethod &lt;strong&gt;getParent&lt;/strong&gt; () - $p"></a> [[ObjectMethod]] **getParent** `() -> $parent`
 156
 157 Gets the TOPICPARENT name.
 158
 159 ## <a name="ObjectMethod &lt;strong&gt;get_FormName&lt;/strong&gt; () -"></a> [[ObjectMethod]] **getFormName** `() -> $formname`
 160
 161 Returns the name of the FORM, or '' if none.