TWiki/TWikiStoreRcsFileDotPm.mdwn

   1 # <a name="Package &lt;code&gt;TWiki::Store::_RcsFile="></a> Package =TWiki::Store::RcsFile
   2
   3 This class is PACKAGE PRIVATE to Store, and should never be used from anywhere else. It is the base class of implementations of stores that manipulate RCS format files.
   4
   5 The general contract of the methods on this class and its subclasses calls for errors to be signalled by Error::Simple exceptions.
   6
   7 Refer to Store.pm for models of usage.
   8
   9 <div>
  10   <ul>
  11     <li><a href="#Package =TWiki::Store::_RcsFile="> Package TWiki::Store::RcsFile</a><ul>
  12         <li><a href="#ClassMethod <strong>new</strong> ($session,$web"> ClassMethod new <tt>($session,$web,$topic,$attachment)</tt></a></li>
  13         <li><a href="#ObjectMethod <strong>finish</strong> ()"> ObjectMethod finish <tt>()</tt></a></li>
  14         <li><a href="#ObjectMethod *get_RevisionInfo*"> ObjectMethod getRevisionInfo <tt>($version) -&gt; ($rev,$date,$user,$comment)</tt></a></li>
  15         <li><a href="#ObjectMethod *get_LatestRevision"> ObjectMethod getLatestRevision <tt>() -&gt; $text</tt></a></li>
  16         <li><a href="#ObjectMethod *get_LatestRevision"> ObjectMethod getLatestRevisionTime <tt>() -&gt; $text</tt></a></li>
  17         <li><a href="#ObjectMethod <strong>get_WorkArea</strong> ($ke"> ObjectMethod getWorkArea <tt>($key) -&gt; $directorypath</tt></a></li>
  18         <li><a href="#ObjectMethod <strong>get_TopicNames</strong> ()"> ObjectMethod getTopicNames <tt>() -&gt; @topics</tt></a></li>
  19         <li><a href="#ObjectMethod <strong>get_WebNames</strong> () -"> ObjectMethod getWebNames <tt>() -&gt; @webs</tt></a></li>
  20         <li><a href="#ObjectMethod *search_InWebConten"> ObjectMethod searchInWebContent <tt>($searchString,$web,\@topics,\%options) -&gt; \%map</tt></a></li>
  21         <li><a href="#ObjectMethod *search_InWebMetaDa"> ObjectMethod searchInWebMetaData <tt>($query,\@topics) -&gt; \%matches</tt></a></li>
  22         <li><a href="#ObjectMethod <strong>moveWeb</strong> ($newWeb)"> ObjectMethod moveWeb <tt>($newWeb)</tt></a></li>
  23         <li><a href="#ObjectMethod <strong>getRevision</strong> ($ver"> ObjectMethod getRevision <tt>($version) -&gt; $text</tt></a></li>
  24         <li><a href="#ObjectMethod *stored_DataExists*"> ObjectMethod storedDataExists <tt>() -&gt; $boolean</tt></a></li>
  25         <li><a href="#ObjectMethod <strong>getTimestamp</strong> () -"> ObjectMethod getTimestamp <tt>() -&gt; $integer</tt></a></li>
  26         <li><a href="#ObjectMethod *restore_LatestRevi"> ObjectMethod restoreLatestRevision <tt>($user)</tt></a></li>
  27         <li><a href="#ObjectMethod <strong>removeWeb</strong> ($web)"> ObjectMethod removeWeb <tt>($web)</tt></a></li>
  28         <li><a href="#ObjectMethod <strong>moveTopic</strong> ($newWe"> ObjectMethod moveTopic <tt>($newWeb,$newTopic)</tt></a></li>
  29         <li><a href="#ObjectMethod <strong>copyTopic</strong> ($newWe"> ObjectMethod copyTopic <tt>($newWeb,$newTopic)</tt></a></li>
  30         <li><a href="#ObjectMethod <strong>moveAttachment</strong> ($"> ObjectMethod moveAttachment <tt>($newWeb,$newTopic,$newAttachment)</tt></a></li>
  31         <li><a href="#ObjectMethod <strong>copyAttachment</strong> ($"> ObjectMethod copyAttachment <tt>($newWeb,$newTopic)</tt></a></li>
  32         <li><a href="#ObjectMethod <strong>is_AsciiDefault</strong> ("> ObjectMethod isAsciiDefault <tt>() -&gt; $boolean</tt></a></li>
  33         <li><a href="#ObjectMethod <strong>setLock</strong> ($lock,$u"> ObjectMethod setLock <tt>($lock,$user)</tt></a></li>
  34         <li><a href="#ObjectMethod <strong>isLocked</strong> () -> ($"> ObjectMethod isLocked <tt>() -&gt; ($user,$time)</tt></a></li>
  35         <li><a href="#ObjectMethod <strong>setLease</strong> ($lease)"> ObjectMethod setLease <tt>($lease)</tt></a></li>
  36         <li><a href="#ObjectMethod <strong>getLease</strong> () -> $l"> ObjectMethod getLease <tt>() -&gt; $lease</tt></a></li>
  37         <li><a href="#ObjectMethod *remove_SpuriousLea"> ObjectMethod removeSpuriousLeases <tt>($web)</tt></a></li>
  38         <li><a href="#ObjectMethod <strong>getStream</strong> () -> \"> ObjectMethod getStream <tt>() -&gt; \*STREAM</tt></a></li>
  39         <li><a href="#ObjectMethod <strong>numRevisions</strong> () -"> ObjectMethod numRevisions <tt>() -&gt; $integer</tt></a></li>
  40         <li><a href="#ObjectMethod <strong>initBinary</strong> ()"> ObjectMethod initBinary <tt>()</tt></a></li>
  41         <li><a href="#ObjectMethod <strong>initText</strong> ()"> ObjectMethod initText <tt>()</tt></a></li>
  42         <li><a href="#ObjectMethod *add_RevisionFromTe"> ObjectMethod addRevisionFromText <tt>($text,$comment,$user,$date)</tt></a></li>
  43         <li><a href="#ObjectMethod *add_RevisionFromSt"> ObjectMethod addRevisionFromStream <tt>($fh,$comment,$user,$date)</tt></a></li>
  44         <li><a href="#ObjectMethod <strong>replaceRevision</strong> ("> ObjectMethod replaceRevision <tt>($text,$comment,$user,$date)</tt></a></li>
  45         <li><a href="#ObjectMethod <strong>deleteRevision</strong> ()"> ObjectMethod deleteRevision <tt>()</tt></a></li>
  46         <li><a href="#ObjectMethod <strong>revisionDiff</strong> ($re"> ObjectMethod revisionDiff <tt>($rev1,$rev2,$contextLines) -&gt; \@diffArray</tt></a></li>
  47         <li><a href="#ObjectMethod *get_RevisionAtTime"> ObjectMethod getRevisionAtTime <tt>($time) -&gt; $rev</tt></a></li>
  48         <li><a href="#ObjectMethod *get_AttachmentAttr"> ObjectMethod getAttachmentAttributes <tt>($web,$topic,$attachment)</tt></a></li>
  49         <li><a href="#ObjectMethod *get_AttachmentList"> ObjectMethod getAttachmentList <tt>($web,$topic)</tt></a></li>
  50         <li><a href="#ObjectMethod <strong>stringify</strong> ()"> ObjectMethod stringify <tt>()</tt></a></li>
  51         <li><a href="#ObjectMethod <strong>recordChange</strong> ($us"> ObjectMethod recordChange <tt>($user,$rev,$more)</tt></a></li>
  52         <li><a href="#ObjectMethod <strong>eachChange</strong> ($sinc"> ObjectMethod eachChange <tt>($since) -&gt; $iterator</tt></a></li>
  53       </ul>
  54     </li>
  55   </ul>
  56 </div>
  57
  58 ## <a name="ClassMethod &lt;strong&gt;new&lt;/strong&gt; ($session,$web"></a> [[ClassMethod]] **new** `($session,$web,$topic,$attachment)`
  59
  60 Constructor. There is one object per stored file.
  61
  62 Note that $web, $topic and $attachment must be untainted!
  63
  64 ## <a name="ObjectMethod &lt;strong&gt;finish&lt;/strong&gt; ()"></a> [[ObjectMethod]] **finish** `()`
  65
  66 Break circular references.
  67
  68 ## <a name="ObjectMethod &lt;strong&gt;get_RevisionInfo*"></a><a name="ObjectMethod *get_RevisionInfo&lt;/strong&gt; "></a> [[ObjectMethod]] **getRevisionInfo** `($version) -> ($rev,$date,$user,$comment)`
  69
  70 - `$version` if 0 or undef, or out of range (version number &gt; number of revs) will return info about the latest revision.
  71
  72 Returns (rev, date, user, comment) where rev is the number of the rev for which the info was recovered, date is the date of that rev (epoch s), user is the login name of the user who saved that rev, and comment is the comment associated with the rev.
  73
  74 Designed to be overridden by subclasses, which can call up to this method if file-based rev info is required.
  75
  76 ## <a name="ObjectMethod &lt;strong&gt;get_LatestRevision"></a> [[ObjectMethod]] \*getLatestRevision `() -> $text`
  77
  78 Get the text of the most recent revision
  79
  80 ## <a name="ObjectMethod &lt;strong&gt;get_LatestRevision"></a> [[ObjectMethod]] \*getLatestRevisionTime `() -> $text`
  81
  82 Get the time of the most recent revision
  83
  84 ## <a name="ObjectMethod &lt;strong&gt;get_WorkArea&lt;/strong&gt; ($ke"></a> [[ObjectMethod]] **getWorkArea** `($key) -> $directorypath`
  85
  86 Gets a private directory uniquely identified by $key. The directory is intended as a work area for plugins.
  87
  88 The standard is a directory named the same as "key" under $TWiki::cfg\{WorkingDir\}/work\_areas
  89
  90 ## <a name="ObjectMethod &lt;strong&gt;get_TopicNames&lt;/strong&gt; ()"></a> [[ObjectMethod]] **getTopicNames** `() -> @topics`
  91
  92 Get list of all topics in a web
  93
  94 - `$web` - Web name, required, e.g. `'Sandbox'`
  95
  96 Return a topic list, e.g. `( 'WebChanges',  'WebHome', 'WebIndex', 'WebNotify' )`
  97
  98 ## <a name="ObjectMethod &lt;strong&gt;get_WebNames&lt;/strong&gt; () -"></a> [[ObjectMethod]] **getWebNames** `() -> @webs`
  99
 100 Gets a list of names of subwebs in the current web
 101
 102 ## <a name="ObjectMethod &lt;strong&gt;search_InWebConten"></a> [[ObjectMethod]] \*searchInWebContent `($searchString,$web,\@topics,\%options) -> \%map`
 103
 104 Search for a string in the content of a web. The search must be over all content and all formatted meta-data, though the latter search type is deprecated (use searchMetaData instead).
 105
 106 - `$searchString` - the search string, in egrep format if regex
 107 - `$web` - The web to search in
 108 - `\@topics` - reference to a list of topics to search
 109 - `\%options` - reference to an options hash
 110
 111 The `\%options` hash may contain the following options:
 112
 113 - `type` - if `regex` will perform a egrep-syntax RE search (default '')
 114 - `casesensitive` - false to ignore case (defaulkt true)
 115 - `files_without_match` - true to return files only (default false)
 116
 117 The return value is a reference to a hash which maps each matching topic name to a list of the lines in that topic that matched the search, as would be returned by 'grep'. If `files_without_match` is specified, it will return on the first match in each topic (i.e. it will return only one match per topic, and will not return matching lines).
 118
 119 ## <a name="ObjectMethod &lt;strong&gt;search_InWebMetaDa"></a> [[ObjectMethod]] \*searchInWebMetaData `($query,\@topics) -> \%matches`
 120
 121 Search for a meta-data expression in the content of a web. `$query` must be a `TWiki::Query` object.
 122
 123 Returns a reference to a hash that maps the names of topics that all matched to the result of the query expression (e.g. if the query expression is 'TOPICPARENT.name' then you will get back a hash that maps topic names to their parent.
 124
 125 SMELL: this is **really** inefficient!
 126
 127 ## <a name="ObjectMethod &lt;strong&gt;moveWeb&lt;/strong&gt; ($newWeb)"></a> [[ObjectMethod]] **moveWeb** `($newWeb)`
 128
 129 Move a web.
 130
 131 ## <a name="ObjectMethod &lt;strong&gt;getRevision&lt;/strong&gt; ($ver"></a> [[ObjectMethod]] **getRevision** `($version) -> $text`
 132
 133 Get the text for a given revision. The version number must be an integer.
 134
 135 **Virtual method** - must be implemented by subclasses
 136
 137 ## <a name="ObjectMethod &lt;strong&gt;stored_DataExists*"></a> [[ObjectMethod]] \*storedDataExists `() -> $boolean`
 138
 139 Establishes if there is stored data associated with this handler.
 140
 141 ## <a name="ObjectMethod &lt;strong&gt;getTimestamp&lt;/strong&gt; () -"></a> [[ObjectMethod]] **getTimestamp** `() -> $integer`
 142
 143 Get the timestamp of the file Returns 0 if no file, otherwise epoch seconds
 144
 145 ## <a name="ObjectMethod &lt;strong&gt;restore_LatestRevi"></a> [[ObjectMethod]] \*restoreLatestRevision `($user)`
 146
 147 Restore the plaintext file from the revision at the head.
 148
 149 ## <a name="ObjectMethod &lt;strong&gt;removeWeb&lt;/strong&gt; ($web)"></a> [[ObjectMethod]] **removeWeb** `($web)`
 150
 151 - `$web` - web being removed
 152
 153 Destroy a web, utterly. Removed the data and attachments in the web.
 154
 155 Use with great care! No backup is taken!
 156
 157 ## <a name="ObjectMethod &lt;strong&gt;moveTopic&lt;/strong&gt; ($newWe"></a> [[ObjectMethod]] **moveTopic** `($newWeb,$newTopic)`
 158
 159 Move/rename a topic.
 160
 161 ## <a name="ObjectMethod &lt;strong&gt;copyTopic&lt;/strong&gt; ($newWe"></a> [[ObjectMethod]] **copyTopic** `($newWeb,$newTopic)`
 162
 163 Copy a topic.
 164
 165 ## <a name="ObjectMethod &lt;strong&gt;moveAttachment&lt;/strong&gt; ($"></a> [[ObjectMethod]] **moveAttachment** `($newWeb,$newTopic,$newAttachment)`
 166
 167 Move an attachment from one topic to another. The name is retained.
 168
 169 ## <a name="ObjectMethod &lt;strong&gt;copyAttachment&lt;/strong&gt; ($"></a> [[ObjectMethod]] **copyAttachment** `($newWeb,$newTopic)`
 170
 171 Copy an attachment from one topic to another. The name is retained.
 172
 173 ## <a name="ObjectMethod &lt;strong&gt;is_AsciiDefault&lt;/strong&gt; ("></a> [[ObjectMethod]] **isAsciiDefault** `() -> $boolean`
 174
 175 Check if this file type is known to be an ascii type file.
 176
 177 ## <a name="ObjectMethod &lt;strong&gt;setLock&lt;/strong&gt; ($lock,$u"></a> [[ObjectMethod]] **setLock** `($lock,$user)`
 178
 179 Set a lock on the topic, if $lock, otherwise clear it. $user is a wikiname.
 180
 181 SMELL: there is a tremendous amount of potential for race conditions using this locking approach.
 182
 183 ## <a name="ObjectMethod &lt;strong&gt;isLocked&lt;/strong&gt; () - ($u"></a> [[ObjectMethod]] **isLocked** `() -> ($user,$time)`
 184
 185 See if a twiki lock exists. Return the lock user and lock time if it does.
 186
 187 ## <a name="ObjectMethod &lt;strong&gt;setLease&lt;/strong&gt; ($lease)"></a> [[ObjectMethod]] **setLease** `($lease)`
 188
 189 - `$lease` reference to lease hash, or undef if the existing lease is to be cleared.
 190
 191 Set an lease on the topic.
 192
 193 ## <a name="ObjectMethod &lt;strong&gt;getLease&lt;/strong&gt; () - $le"></a> [[ObjectMethod]] **getLease** `() -> $lease`
 194
 195 Get the current lease on the topic.
 196
 197 ## <a name="ObjectMethod &lt;strong&gt;remove_SpuriousLea"></a> [[ObjectMethod]] \*removeSpuriousLeases `($web)`
 198
 199 Remove leases that are not related to a topic. These can get left behind in some store implementations when a topic is created, but never saved.
 200
 201 ## <a name="ObjectMethod &lt;strong&gt;getStream&lt;/strong&gt; () - \*"></a> [[ObjectMethod]] **getStream** `() -> \*STREAM`
 202
 203 Return a text stream that will supply the text stored in the topic.
 204
 205 ## <a name="ObjectMethod &lt;strong&gt;numRevisions&lt;/strong&gt; () -"></a> [[ObjectMethod]] **numRevisions** `() -> $integer`
 206
 207 Must be provided by subclasses.
 208
 209 Find out how many revisions there are. If there is a problem, such as a nonexistent file, returns 0.
 210
 211 **Virtual method** - must be implemented by subclasses
 212
 213 ## <a name="ObjectMethod &lt;strong&gt;initBinary&lt;/strong&gt; ()"></a> [[ObjectMethod]] **initBinary** `()`
 214
 215 Initialise a binary file.
 216
 217 Must be provided by subclasses.
 218
 219 **Virtual method** - must be implemented by subclasses
 220
 221 ## <a name="ObjectMethod &lt;strong&gt;initText&lt;/strong&gt; ()"></a> [[ObjectMethod]] **initText** `()`
 222
 223 Initialise a text file.
 224
 225 Must be provided by subclasses.
 226
 227 **Virtual method** - must be implemented by subclasses
 228
 229 ## <a name="ObjectMethod &lt;strong&gt;add_RevisionFromTe"></a> [[ObjectMethod]] \*addRevisionFromText `($text,$comment,$user,$date)`
 230
 231 Add new revision. Replace file with text.
 232
 233 - `$text` of new revision
 234 - `$comment` checkin comment
 235 - `$user` is a wikiname.
 236 - `$date` in epoch seconds; may be ignored
 237
 238 **Virtual method** - must be implemented by subclasses
 239
 240 ## <a name="ObjectMethod &lt;strong&gt;add_RevisionFromSt"></a> [[ObjectMethod]] \*addRevisionFromStream `($fh,$comment,$user,$date)`
 241
 242 Add new revision. Replace file with contents of stream.
 243
 244 - `$fh` filehandle for contents of new revision
 245 - `$comment` checkin comment
 246 - `$user` is a wikiname.
 247 - `$date` in epoch seconds; may be ignored
 248
 249 **Virtual method** - must be implemented by subclasses
 250
 251 ## <a name="ObjectMethod &lt;strong&gt;replaceRevision&lt;/strong&gt; ("></a> [[ObjectMethod]] **replaceRevision** `($text,$comment,$user,$date)`
 252
 253 Replace the top revision.
 254
 255 - `$text` is the new revision
 256 - `$date` is in epoch seconds.
 257 - `$user` is a wikiname.
 258 - `$comment` is a string
 259
 260 **Virtual method** - must be implemented by subclasses
 261
 262 ## <a name="ObjectMethod &lt;strong&gt;deleteRevision&lt;/strong&gt; ()"></a> [[ObjectMethod]] **deleteRevision** `()`
 263
 264 Delete the last revision - do nothing if there is only one revision
 265
 266 **Virtual method** - must be implemented by subclasses
 267
 268 ## <a name="ObjectMethod &lt;strong&gt;revisionDiff&lt;/strong&gt; ($re"></a> [[ObjectMethod]] **revisionDiff** `($rev1,$rev2,$contextLines) -> \@diffArray`
 269
 270 rev2 newer than rev1. Return reference to an array of [ diffType, $right, $left ]
 271
 272 **Virtual method** - must be implemented by subclasses
 273
 274 !!!getRevision!!!
 275
 276 ## <a name="ObjectMethod &lt;strong&gt;get_RevisionAtTime"></a> [[ObjectMethod]] \*getRevisionAtTime `($time) -> $rev`
 277
 278 Get a single-digit version number for the rev that was alive at the given epoch-secs time, or undef it none could be found.
 279
 280 **Virtual method** - must be implemented by subclasses
 281
 282 ## <a name="ObjectMethod &lt;strong&gt;get_AttachmentAttr"></a> [[ObjectMethod]] \*getAttachmentAttributes `($web,$topic,$attachment)`
 283
 284 returns [stat] for any given web, topic, $attachment SMELL - should this return a hash of arbitrary attributes so that SMELL + attributes supported by the underlying filesystem are supported SMELL + (eg: windows directories supporting photo "author", "dimension" fields)
 285
 286 ## <a name="ObjectMethod &lt;strong&gt;get_AttachmentList"></a> [[ObjectMethod]] \*getAttachmentList `($web,$topic)`
 287
 288 returns \{\} of filename =&gt; \{ key =&gt; value, key2 =&gt; value \} for any given web, topic Ignores files starting with \_ or ending with ,v
 289
 290 ## <a name="ObjectMethod &lt;strong&gt;stringify&lt;/strong&gt; ()"></a> [[ObjectMethod]] **stringify** `()`
 291
 292 Generate string representation for debugging
 293
 294 ## <a name="ObjectMethod &lt;strong&gt;recordChange&lt;/strong&gt; ($us"></a> [[ObjectMethod]] **recordChange** `($user,$rev,$more)`
 295
 296 Record that the file changed
 297
 298 ## <a name="ObjectMethod &lt;strong&gt;eachChange&lt;/strong&gt; ($sinc"></a> [[ObjectMethod]] **eachChange** `($since) -> $iterator`
 299
 300 Return iterator over changes - see Store for details