1 # <a name="Package <code>TWiki::Store::_RcsFile="></a> Package =TWiki::Store::RcsFile
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.
5 The general contract of the methods on this class and its subclasses calls for errors to be signalled by Error::Simple exceptions.
7 Refer to Store.pm for models of usage.
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) -> ($rev,$date,$user,$comment)</tt></a></li>
14 <li><a href="#ObjectMethod *get_LatestRevision"> ObjectMethod getLatestRevision <tt>() -> $text</tt></a></li>
15 <li><a href="#ObjectMethod *get_LatestRevision"> ObjectMethod getLatestRevisionTime <tt>() -> $text</tt></a></li>
16 <li><a href="#ObjectMethod <strong>read_MetaData</strong> ($n"> ObjectMethod readMetaData <tt>($name) -> $text</tt></a></li>
17 <li><a href="#ObjectMethod <strong>get_WorkArea</strong> ($ke"> ObjectMethod getWorkArea <tt>($key) -> $directorypath</tt></a></li>
18 <li><a href="#ObjectMethod <strong>save_MetaData</strong> ($w"> ObjectMethod saveMetaData <tt>($web,$name) -> $text</tt></a></li>
19 <li><a href="#ObjectMethod <strong>get_TopicNames</strong> ()"> ObjectMethod getTopicNames <tt>() -> @topics</tt></a></li>
20 <li><a href="#ObjectMethod <strong>get_WebNames</strong> () -"> ObjectMethod getWebNames <tt>() -> @webs</tt></a></li>
21 <li><a href="#ObjectMethod *search_InWebConten"> ObjectMethod searchInWebContent <tt>($searchString,$web,\@topics,\%options) -> \%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) -> $text</tt></a></li>
24 <li><a href="#ObjectMethod *stored_DataExists*"> ObjectMethod storedDataExists <tt>() -> $boolean</tt></a></li>
25 <li><a href="#ObjectMethod <strong>getTimestamp</strong> () -"> ObjectMethod getTimestamp <tt>() -> $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>() -> $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>() -> ($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>() -> $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>() -> \*STREAM</tt></a></li>
39 <li><a href="#ObjectMethod <strong>numRevisions</strong> () -"> ObjectMethod numRevisions <tt>() -> $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) -> \@diffArray</tt></a></li>
47 <li><a href="#ObjectMethod *get_RevisionAtTime"> ObjectMethod getRevisionAtTime <tt>($time) -> $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>
56 ## <a name="ClassMethod <strong>new</strong> ($session,$web"></a> [[ClassMethod]] **new** `($session,$web,$topic,$attachment)`
58 Constructor. There is one object per stored file.
60 Note that $web, $topic and $attachment must be untainted!
62 ## <a name="ObjectMethod <strong>get_RevisionInfo*"></a><a name="ObjectMethod *get_RevisionInfo</strong> "></a> [[ObjectMethod]] **getRevisionInfo** `($version) -> ($rev,$date,$user,$comment)`
64 - `$version` if 0 or undef, or out of range (version number > number of revs) will return info about the latest revision.
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.
68 Designed to be overridden by subclasses, which can call up to this method if file-based rev info is required.
70 ## <a name="ObjectMethod <strong>get_LatestRevision"></a> [[ObjectMethod]] \*getLatestRevision `() -> $text`
72 Get the text of the most recent revision
74 ## <a name="ObjectMethod <strong>get_LatestRevision"></a> [[ObjectMethod]] \*getLatestRevisionTime `() -> $text`
76 Get the time of the most recent revision
78 ## <a name="ObjectMethod <strong>read_MetaData</strong> ($n"></a> [[ObjectMethod]] **readMetaData** `($name) -> $text`
80 Get a meta-data block for this web
82 ## <a name="ObjectMethod <strong>get_WorkArea</strong> ($ke"></a> [[ObjectMethod]] **getWorkArea** `($key) -> $directorypath`
84 Gets a private directory uniquely identified by $key. The directory is intended as a work area for plugins.
86 The standard is a directory named the same as "key" under $TWiki::cfg\{RCS\}\{WorkAreaDir\}
88 ## <a name="ObjectMethod <strong>save_MetaData</strong> ($w"></a> [[ObjectMethod]] **saveMetaData** `($web,$name) -> $text`
90 Write a named meta-data string. If web is given the meta-data is stored alongside a web.
92 ## <a name="ObjectMethod <strong>get_TopicNames</strong> ()"></a> [[ObjectMethod]] **getTopicNames** `() -> @topics`
94 Get list of all topics in a web
96 - `$web` - Web name, required, e.g. `'Sandbox'`
98 Return a topic list, e.g. `( 'WebChanges', 'WebHome', 'WebIndex', 'WebNotify' )`
100 ## <a name="ObjectMethod <strong>get_WebNames</strong> () -"></a> [[ObjectMethod]] **getWebNames** `() -> @webs`
102 Gets a list of names of subwebs in the current web
104 ## <a name="ObjectMethod <strong>search_InWebConten"></a> [[ObjectMethod]] \*searchInWebContent `($searchString,$web,\@topics,\%options) -> \%map`
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).
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
113 The `\%options` hash may contain the following options:
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)
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).
121 ## <a name="ObjectMethod <strong>moveWeb</strong> ($newWeb)"></a> [[ObjectMethod]] **moveWeb** `($newWeb)`
125 ## <a name="ObjectMethod <strong>getRevision</strong> ($ver"></a> [[ObjectMethod]] **getRevision** `($version) -> $text`
127 Get the text for a given revision. The version number must be an integer.
129 **Virtual method** - must be implemented by subclasses
131 ## <a name="ObjectMethod <strong>stored_DataExists*"></a> [[ObjectMethod]] \*storedDataExists `() -> $boolean`
133 Establishes if there is stored data associated with this handler.
135 ## <a name="ObjectMethod <strong>getTimestamp</strong> () -"></a> [[ObjectMethod]] **getTimestamp** `() -> $integer`
137 Get the timestamp of the file Returns 0 if no file, otherwise epoch seconds
139 ## <a name="ObjectMethod <strong>restore_LatestRevi"></a> [[ObjectMethod]] \*restoreLatestRevision `($wikiname)`
141 Restore the plaintext file from the revision at the head.
143 ## <a name="ObjectMethod <strong>removeWeb</strong> ($web)"></a> [[ObjectMethod]] **removeWeb** `($web)`
145 - `$web` - web being removed
147 Destroy a web, utterly. Removed the data and attachments in the web.
149 Use with great care! No backup is taken!
151 ## <a name="ObjectMethod <strong>moveTopic</strong> ($newWe"></a> [[ObjectMethod]] **moveTopic** `($newWeb,$newTopic)`
155 ## <a name="ObjectMethod <strong>copyTopic</strong> ($newWe"></a> [[ObjectMethod]] **copyTopic** `($newWeb,$newTopic)`
159 ## <a name="ObjectMethod <strong>moveAttachment</strong> ($"></a> [[ObjectMethod]] **moveAttachment** `($newWeb,$newTopic,$newAttachment)`
161 Move an attachment from one topic to another. The name is retained.
163 ## <a name="ObjectMethod <strong>copyAttachment</strong> ($"></a> [[ObjectMethod]] **copyAttachment** `($newWeb,$newTopic)`
165 Copy an attachment from one topic to another. The name is retained.
167 ## <a name="ObjectMethod <strong>is_AsciiDefault</strong> ("></a> [[ObjectMethod]] **isAsciiDefault** `() -> $boolean`
169 Check if this file type is known to be an ascii type file.
171 ## <a name="ObjectMethod <strong>setLock</strong> ($lock,$u"></a> [[ObjectMethod]] **setLock** `($lock,$user)`
173 Set a lock on the topic, if $lock, otherwise clear it. $user is a wikiname.
175 SMELL: there is a tremendous amount of potential for race conditions using this locking approach.
177 ## <a name="ObjectMethod <strong>isLocked</strong> () - ($u"></a> [[ObjectMethod]] **isLocked** `() -> ($user,$time)`
179 See if a twiki lock exists. Return the lock user and lock time if it does.
181 ## <a name="ObjectMethod <strong>setLease</strong> ($lease)"></a> [[ObjectMethod]] **setLease** `($lease)`
183 - `$lease` reference to lease hash, or undef if the existing lease is to be cleared.
185 Set an lease on the topic.
187 ## <a name="ObjectMethod <strong>getLease</strong> () - $le"></a> [[ObjectMethod]] **getLease** `() -> $lease`
189 Get the current lease on the topic.
191 ## <a name="ObjectMethod <strong>remove_SpuriousLea"></a> [[ObjectMethod]] \*removeSpuriousLeases `($web)`
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.
195 ## <a name="ObjectMethod <strong>getStream</strong> () - \*"></a> [[ObjectMethod]] **getStream** `() -> \*STREAM`
197 Return a text stream that will supply the text stored in the topic.
199 ## <a name="ObjectMethod <strong>numRevisions</strong> () -"></a> [[ObjectMethod]] **numRevisions** `() -> $integer`
201 Must be provided by subclasses.
203 Find out how many revisions there are. If there is a problem, such as a nonexistent file, returns 0.
205 **Virtual method** - must be implemented by subclasses
207 ## <a name="ObjectMethod <strong>initBinary</strong> ()"></a> [[ObjectMethod]] **initBinary** `()`
209 Initialise a binary file.
211 Must be provided by subclasses.
213 **Virtual method** - must be implemented by subclasses
215 ## <a name="ObjectMethod <strong>initText</strong> ()"></a> [[ObjectMethod]] **initText** `()`
217 Initialise a text file.
219 Must be provided by subclasses.
221 **Virtual method** - must be implemented by subclasses
223 ## <a name="ObjectMethod <strong>add_RevisionFromTe"></a> [[ObjectMethod]] \*addRevisionFromText `($text,$comment,$user,$date)`
225 Add new revision. Replace file with text.
227 - `$text` of new revision
228 - `$comment` checkin comment
229 - `$user` is a wikiname.
230 - `$date` in epoch seconds; may be ignored
232 **Virtual method** - must be implemented by subclasses
234 ## <a name="ObjectMethod <strong>add_RevisionFromSt"></a> [[ObjectMethod]] \*addRevisionFromStream `($fh,$comment,$user,$date)`
236 Add new revision. Replace file with contents of stream.
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
243 **Virtual method** - must be implemented by subclasses
245 ## <a name="ObjectMethod <strong>replaceRevision</strong> ("></a> [[ObjectMethod]] **replaceRevision** `($text,$comment,$user,$date)`
247 Replace the top revision.
249 - `$text` is the new revision
250 - `$date` is in epoch seconds.
251 - `$user` is a wikiname.
252 - `$comment` is a string
254 **Virtual method** - must be implemented by subclasses
256 ## <a name="ObjectMethod <strong>deleteRevision</strong> ()"></a> [[ObjectMethod]] **deleteRevision** `()`
258 Delete the last revision - do nothing if there is only one revision
260 **Virtual method** - must be implemented by subclasses
262 ## <a name="ObjectMethod <strong>revisionDiff</strong> ($re"></a> [[ObjectMethod]] **revisionDiff** `($rev1,$rev2,$contextLines) -> \@diffArray`
264 rev2 newer than rev1. Return reference to an array of [ diffType, $right, $left ]
266 **Virtual method** - must be implemented by subclasses
270 ## <a name="ObjectMethod <strong>get_RevisionAtTime"></a> [[ObjectMethod]] \*getRevisionAtTime `($time) -> $rev`
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.
274 **Virtual method** - must be implemented by subclasses
276 ## <a name="ObjectMethod <strong>get_AttachmentAttr"></a> [[ObjectMethod]] \*getAttachmentAttributes `($web,$topic,$attachment)`
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)
280 sub \_constructAttributesForAutoAttached as long as stat is defined, return an emulated set of attributes for that attachment.
282 ## <a name="ObjectMethod <strong>get_AttachmentList"></a> [[ObjectMethod]] \*getAttachmentList `($web,$topic)`
284 returns \{\} of filename => \{ key => value, key2 => value \} for any given web, topic Ignores files starting with \_ or ending with ,v
286 ## <a name="ObjectMethod <strong>stringify</strong> ()"></a> [[ObjectMethod]] **stringify** `()`
288 Generate string representation for debugging