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. 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 *get_RevisionInfo*"> ObjectMethod getRevisionInfo <tt>($version) -&gt; ($rev,$date,$user,$comment)</tt></a></li>
  14         <li><a href="#ObjectMethod *get_LatestRevision"> ObjectMethod getLatestRevision <tt>() -&gt; $text</tt></a></li>
  15         <li><a href="#ObjectMethod *get_LatestRevision"> ObjectMethod getLatestRevisionTime <tt>() -&gt; $text</tt></a></li>
  16         <li><a href="#ObjectMethod <strong>read_MetaData</strong> ($n"> ObjectMethod readMetaData <tt>($name) -&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>save_MetaData</strong> ($w"> ObjectMethod saveMetaData <tt>($web,$name) -&gt; $text</tt></a></li>
  19         <li><a href="#ObjectMethod <strong>get_TopicNames</strong> ()"> ObjectMethod getTopicNames <tt>() -&gt; @topics</tt></a></li>
  20         <li><a href="#ObjectMethod <strong>get_WebNames</strong> () -"> ObjectMethod getWebNames <tt>() -&gt; @webs</tt></a></li>
  21         <li><a href="#ObjectMethod *search_InWebConten"> ObjectMethod searchInWebContent <tt>($searchString,$web,\@topics,\%options) -&gt; \%map</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>($wikiname)</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       </ul>
  52     </li>
  53   </ul>
  54 </div>
  55
  56 ## <a name="ClassMethod &lt;strong&gt;new&lt;/strong&gt; ($session,$web"></a> [[ClassMethod]] **new** `($session,$web,$topic,$attachment)`
  57
  58 Constructor. There is one object per stored file.
  59
  60 Note that $web, $topic and $attachment must be untainted!
  61
  62 ## <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)`
  63
  64 - `$version` if 0 or undef, or out of range (version number &gt; number of revs) will return info about the latest revision.
  65
  66 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.
  67
  68 Designed to be overridden by subclasses, which can call up to this method if file-based rev info is required.
  69
  70 ## <a name="ObjectMethod &lt;strong&gt;get_LatestRevision"></a> [[ObjectMethod]] \*getLatestRevision `() -> $text`
  71
  72 Get the text of the most recent revision
  73
  74 ## <a name="ObjectMethod &lt;strong&gt;get_LatestRevision"></a> [[ObjectMethod]] \*getLatestRevisionTime `() -> $text`
  75
  76 Get the time of the most recent revision
  77
  78 ## <a name="ObjectMethod &lt;strong&gt;read_MetaData&lt;/strong&gt; ($n"></a> [[ObjectMethod]] **readMetaData** `($name) -> $text`
  79
  80 Get a meta-data block for this web
  81
  82 ## <a name="ObjectMethod &lt;strong&gt;get_WorkArea&lt;/strong&gt; ($ke"></a> [[ObjectMethod]] **getWorkArea** `($key) -> $directorypath`
  83
  84 Gets a private directory uniquely identified by $key. The directory is intended as a work area for plugins.
  85
  86 The standard is a directory named the same as "key" under $TWiki::cfg\{RCS\}\{WorkAreaDir\}
  87
  88 ## <a name="ObjectMethod &lt;strong&gt;save_MetaData&lt;/strong&gt; ($w"></a> [[ObjectMethod]] **saveMetaData** `($web,$name) -> $text`
  89
  90 Write a named meta-data string. If web is given the meta-data is stored alongside a web.
  91
  92 ## <a name="ObjectMethod &lt;strong&gt;get_TopicNames&lt;/strong&gt; ()"></a> [[ObjectMethod]] **getTopicNames** `() -> @topics`
  93
  94 Get list of all topics in a web
  95
  96 - `$web` - Web name, required, e.g. `'Sandbox'`
  97
  98 Return a topic list, e.g. `( 'WebChanges',  'WebHome', 'WebIndex', 'WebNotify' )`
  99
 100 ## <a name="ObjectMethod &lt;strong&gt;get_WebNames&lt;/strong&gt; () -"></a> [[ObjectMethod]] **getWebNames** `() -> @webs`
 101
 102 Gets a list of names of subwebs in the current web
 103
 104 ## <a name="ObjectMethod &lt;strong&gt;search_InWebConten"></a> [[ObjectMethod]] \*searchInWebContent `($searchString,$web,\@topics,\%options) -> \%map`
 105
 106 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).
 107
 108 - `$searchString` - the search string, in egrep format if regex
 109 - `$web` - The web to search in
 110 - `\@topics` - reference to a list of topics to search
 111 - `\%options` - reference to an options hash
 112
 113 The `\%options` hash may contain the following options:
 114
 115 - `type` - if `regex` will perform a egrep-syntax RE search (default '')
 116 - `casesensitive` - false to ignore case (defaulkt true)
 117 - `files_without_match` - true to return files only (default false)
 118
 119 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).
 120
 121 ## <a name="ObjectMethod &lt;strong&gt;moveWeb&lt;/strong&gt; ($newWeb)"></a> [[ObjectMethod]] **moveWeb** `($newWeb)`
 122
 123 Move a web.
 124
 125 ## <a name="ObjectMethod &lt;strong&gt;getRevision&lt;/strong&gt; ($ver"></a> [[ObjectMethod]] **getRevision** `($version) -> $text`
 126
 127 Get the text for a given revision. The version number must be an integer.
 128
 129 **Virtual method** - must be implemented by subclasses
 130
 131 ## <a name="ObjectMethod &lt;strong&gt;stored_DataExists*"></a> [[ObjectMethod]] \*storedDataExists `() -> $boolean`
 132
 133 Establishes if there is stored data associated with this handler.
 134
 135 ## <a name="ObjectMethod &lt;strong&gt;getTimestamp&lt;/strong&gt; () -"></a> [[ObjectMethod]] **getTimestamp** `() -> $integer`
 136
 137 Get the timestamp of the file Returns 0 if no file, otherwise epoch seconds
 138
 139 ## <a name="ObjectMethod &lt;strong&gt;restore_LatestRevi"></a> [[ObjectMethod]] \*restoreLatestRevision `($wikiname)`
 140
 141 Restore the plaintext file from the revision at the head.
 142
 143 ## <a name="ObjectMethod &lt;strong&gt;removeWeb&lt;/strong&gt; ($web)"></a> [[ObjectMethod]] **removeWeb** `($web)`
 144
 145 - `$web` - web being removed
 146
 147 Destroy a web, utterly. Removed the data and attachments in the web.
 148
 149 Use with great care! No backup is taken!
 150
 151 ## <a name="ObjectMethod &lt;strong&gt;moveTopic&lt;/strong&gt; ($newWe"></a> [[ObjectMethod]] **moveTopic** `($newWeb,$newTopic)`
 152
 153 Move/rename a topic.
 154
 155 ## <a name="ObjectMethod &lt;strong&gt;copyTopic&lt;/strong&gt; ($newWe"></a> [[ObjectMethod]] **copyTopic** `($newWeb,$newTopic)`
 156
 157 Copy a topic.
 158
 159 ## <a name="ObjectMethod &lt;strong&gt;moveAttachment&lt;/strong&gt; ($"></a> [[ObjectMethod]] **moveAttachment** `($newWeb,$newTopic,$newAttachment)`
 160
 161 Move an attachment from one topic to another. The name is retained.
 162
 163 ## <a name="ObjectMethod &lt;strong&gt;copyAttachment&lt;/strong&gt; ($"></a> [[ObjectMethod]] **copyAttachment** `($newWeb,$newTopic)`
 164
 165 Copy an attachment from one topic to another. The name is retained.
 166
 167 ## <a name="ObjectMethod &lt;strong&gt;is_AsciiDefault&lt;/strong&gt; ("></a> [[ObjectMethod]] **isAsciiDefault** `() -> $boolean`
 168
 169 Check if this file type is known to be an ascii type file.
 170
 171 ## <a name="ObjectMethod &lt;strong&gt;setLock&lt;/strong&gt; ($lock,$u"></a> [[ObjectMethod]] **setLock** `($lock,$user)`
 172
 173 Set a lock on the topic, if $lock, otherwise clear it. $user is a wikiname.
 174
 175 SMELL: there is a tremendous amount of potential for race conditions using this locking approach.
 176
 177 ## <a name="ObjectMethod &lt;strong&gt;isLocked&lt;/strong&gt; () - ($u"></a> [[ObjectMethod]] **isLocked** `() -> ($user,$time)`
 178
 179 See if a twiki lock exists. Return the lock user and lock time if it does.
 180
 181 ## <a name="ObjectMethod &lt;strong&gt;setLease&lt;/strong&gt; ($lease)"></a> [[ObjectMethod]] **setLease** `($lease)`
 182
 183 - `$lease` reference to lease hash, or undef if the existing lease is to be cleared.
 184
 185 Set an lease on the topic.
 186
 187 ## <a name="ObjectMethod &lt;strong&gt;getLease&lt;/strong&gt; () - $le"></a> [[ObjectMethod]] **getLease** `() -> $lease`
 188
 189 Get the current lease on the topic.
 190
 191 ## <a name="ObjectMethod &lt;strong&gt;remove_SpuriousLea"></a> [[ObjectMethod]] \*removeSpuriousLeases `($web)`
 192
 193 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.
 194
 195 ## <a name="ObjectMethod &lt;strong&gt;getStream&lt;/strong&gt; () - \*"></a> [[ObjectMethod]] **getStream** `() -> \*STREAM`
 196
 197 Return a text stream that will supply the text stored in the topic.
 198
 199 ## <a name="ObjectMethod &lt;strong&gt;numRevisions&lt;/strong&gt; () -"></a> [[ObjectMethod]] **numRevisions** `() -> $integer`
 200
 201 Must be provided by subclasses.
 202
 203 Find out how many revisions there are. If there is a problem, such as a nonexistent file, returns 0.
 204
 205 **Virtual method** - must be implemented by subclasses
 206
 207 ## <a name="ObjectMethod &lt;strong&gt;initBinary&lt;/strong&gt; ()"></a> [[ObjectMethod]] **initBinary** `()`
 208
 209 Initialise a binary file.
 210
 211 Must be provided by subclasses.
 212
 213 **Virtual method** - must be implemented by subclasses
 214
 215 ## <a name="ObjectMethod &lt;strong&gt;initText&lt;/strong&gt; ()"></a> [[ObjectMethod]] **initText** `()`
 216
 217 Initialise a text file.
 218
 219 Must be provided by subclasses.
 220
 221 **Virtual method** - must be implemented by subclasses
 222
 223 ## <a name="ObjectMethod &lt;strong&gt;add_RevisionFromTe"></a> [[ObjectMethod]] \*addRevisionFromText `($text,$comment,$user,$date)`
 224
 225 Add new revision. Replace file with text.
 226
 227 - `$text` of new revision
 228 - `$comment` checkin comment
 229 - `$user` is a wikiname.
 230 - `$date` in epoch seconds; may be ignored
 231
 232 **Virtual method** - must be implemented by subclasses
 233
 234 ## <a name="ObjectMethod &lt;strong&gt;add_RevisionFromSt"></a> [[ObjectMethod]] \*addRevisionFromStream `($fh,$comment,$user,$date)`
 235
 236 Add new revision. Replace file with contents of stream.
 237
 238 - `$fh` filehandle for contents of new revision
 239 - `$comment` checkin comment
 240 - `$user` is a wikiname.
 241 - `$date` in epoch seconds; may be ignored
 242
 243 **Virtual method** - must be implemented by subclasses
 244
 245 ## <a name="ObjectMethod &lt;strong&gt;replaceRevision&lt;/strong&gt; ("></a> [[ObjectMethod]] **replaceRevision** `($text,$comment,$user,$date)`
 246
 247 Replace the top revision.
 248
 249 - `$text` is the new revision
 250 - `$date` is in epoch seconds.
 251 - `$user` is a wikiname.
 252 - `$comment` is a string
 253
 254 **Virtual method** - must be implemented by subclasses
 255
 256 ## <a name="ObjectMethod &lt;strong&gt;deleteRevision&lt;/strong&gt; ()"></a> [[ObjectMethod]] **deleteRevision** `()`
 257
 258 Delete the last revision - do nothing if there is only one revision
 259
 260 **Virtual method** - must be implemented by subclasses
 261
 262 ## <a name="ObjectMethod &lt;strong&gt;revisionDiff&lt;/strong&gt; ($re"></a> [[ObjectMethod]] **revisionDiff** `($rev1,$rev2,$contextLines) -> \@diffArray`
 263
 264 rev2 newer than rev1. Return reference to an array of [ diffType, $right, $left ]
 265
 266 **Virtual method** - must be implemented by subclasses
 267
 268 !!!getRevision!!!
 269
 270 ## <a name="ObjectMethod &lt;strong&gt;get_RevisionAtTime"></a> [[ObjectMethod]] \*getRevisionAtTime `($time) -> $rev`
 271
 272 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.
 273
 274 **Virtual method** - must be implemented by subclasses
 275
 276 ## <a name="ObjectMethod &lt;strong&gt;get_AttachmentAttr"></a> [[ObjectMethod]] \*getAttachmentAttributes `($web,$topic,$attachment)`
 277
 278 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)
 279
 280 sub \_constructAttributesForAutoAttached as long as stat is defined, return an emulated set of attributes for that attachment.
 281
 282 ## <a name="ObjectMethod &lt;strong&gt;get_AttachmentList"></a> [[ObjectMethod]] \*getAttachmentList `($web,$topic)`
 283
 284 returns \{\} of filename =&gt; \{ key =&gt; value, key2 =&gt; value \} for any given web, topic Ignores files starting with \_ or ending with ,v
 285
 286 ## <a name="ObjectMethod &lt;strong&gt;stringify&lt;/strong&gt; ()"></a> [[ObjectMethod]] **stringify** `()`
 287
 288 Generate string representation for debugging