data/TWiki/TWikiStoreRcsFileDotPm.txt
changeset 0 414e01d06fd5
     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/data/TWiki/TWikiStoreRcsFileDotPm.txt	Sat Jan 26 15:50:53 2008 +0100
     1.3 @@ -0,0 +1,353 @@
     1.4 +---+ Package =TWiki::Store::RcsFile=
     1.5 +
     1.6 +This class is PACKAGE PRIVATE to Store, and should never be
     1.7 +used from anywhere else. It is the base class of implementations of stores
     1.8 +that manipulate RCS format files.
     1.9 +
    1.10 +The general contract of the methods on this class and its subclasses
    1.11 +calls for errors to be signalled by Error::Simple exceptions.
    1.12 +
    1.13 +Refer to Store.pm for models of usage.
    1.14 +
    1.15 +
    1.16 +%TOC%
    1.17 +
    1.18 +---++ ClassMethod *new* <tt>($session,$web,$topic,$attachment)</tt>
    1.19 +
    1.20 +Constructor. There is one object per stored file.
    1.21 +
    1.22 +Note that $web, $topic and $attachment must be untainted!
    1.23 +
    1.24 +
    1.25 +
    1.26 +---++ ObjectMethod *finish* <tt>()</tt>
    1.27 +Break circular references.
    1.28 +
    1.29 +
    1.30 +
    1.31 +---++ ObjectMethod *getRevisionInfo* <tt>($version) -> ($rev,$date,$user,$comment)</tt>
    1.32 +
    1.33 +   * =$version= if 0 or undef, or out of range (version number > number of revs) will return info about the latest revision.
    1.34 +
    1.35 +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.
    1.36 +
    1.37 +Designed to be overridden by subclasses, which can call up to this method
    1.38 +if file-based rev info is required.
    1.39 +
    1.40 +
    1.41 +
    1.42 +---++ ObjectMethod *getLatestRevision* <tt>() -> $text</tt>
    1.43 +
    1.44 +Get the text of the most recent revision
    1.45 +
    1.46 +
    1.47 +
    1.48 +---++ ObjectMethod *getLatestRevisionTime* <tt>() -> $text</tt>
    1.49 +
    1.50 +Get the time of the most recent revision
    1.51 +
    1.52 +
    1.53 +
    1.54 +---++ ObjectMethod *getWorkArea* <tt>($key) -> $directorypath</tt>
    1.55 +
    1.56 +Gets a private directory uniquely identified by $key. The directory is
    1.57 +intended as a work area for plugins.
    1.58 +
    1.59 +The standard is a directory named the same as "key" under
    1.60 +$TWiki::cfg{WorkingDir}/work_areas
    1.61 +
    1.62 +
    1.63 +
    1.64 +---++ ObjectMethod *getTopicNames* <tt>() -> @topics</tt>
    1.65 +
    1.66 +Get list of all topics in a web
    1.67 +   * =$web= - Web name, required, e.g. ='Sandbox'=
    1.68 +Return a topic list, e.g. =( 'WebChanges',  'WebHome', 'WebIndex', 'WebNotify' )=
    1.69 +
    1.70 +
    1.71 +
    1.72 +---++ ObjectMethod *getWebNames* <tt>() -> @webs</tt>
    1.73 +
    1.74 +Gets a list of names of subwebs in the current web
    1.75 +
    1.76 +
    1.77 +
    1.78 +---++ ObjectMethod *searchInWebContent* <tt>($searchString,$web,\@topics,\%options) -> \%map</tt>
    1.79 +
    1.80 +Search for a string in the content of a web. The search must be over all
    1.81 +content and all formatted meta-data, though the latter search type is
    1.82 +deprecated (use searchMetaData instead).
    1.83 +
    1.84 +   * =$searchString= - the search string, in egrep format if regex
    1.85 +   * =$web= - The web to search in
    1.86 +   * =\@topics= - reference to a list of topics to search
    1.87 +   * =\%options= - reference to an options hash
    1.88 +The =\%options= hash may contain the following options:
    1.89 +   * =type= - if =regex= will perform a egrep-syntax RE search (default '')
    1.90 +   * =casesensitive= - false to ignore case (defaulkt true)
    1.91 +   * =files_without_match= - true to return files only (default false)
    1.92 +
    1.93 +The return value is a reference to a hash which maps each matching topic
    1.94 +name to a list of the lines in that topic that matched the search,
    1.95 +as would be returned by 'grep'. If =files_without_match= is specified, it will
    1.96 +return on the first match in each topic (i.e. it will return only one
    1.97 +match per topic, and will not return matching lines).
    1.98 +
    1.99 +
   1.100 +
   1.101 +---++ ObjectMethod *searchInWebMetaData* <tt>($query,\@topics) -> \%matches</tt>
   1.102 +
   1.103 +Search for a meta-data expression in the content of a web. =$query= must be a =TWiki::Query= object.
   1.104 +
   1.105 +Returns a reference to a hash that maps the names of topics that all matched
   1.106 +to the result of the query expression (e.g. if the query expression is
   1.107 +'TOPICPARENT.name' then you will get back a hash that maps topic names
   1.108 +to their parent.
   1.109 +
   1.110 +SMELL: this is *really* inefficient!
   1.111 +
   1.112 +
   1.113 +
   1.114 +---++ ObjectMethod *moveWeb* <tt>($newWeb)</tt>
   1.115 +
   1.116 +Move a web.
   1.117 +
   1.118 +
   1.119 +
   1.120 +---++ ObjectMethod *getRevision* <tt>($version) -> $text</tt>
   1.121 +
   1.122 +Get the text for a given revision. The version number must be an integer.
   1.123 +
   1.124 +*Virtual method* - must be implemented by subclasses
   1.125 +
   1.126 +
   1.127 +
   1.128 +---++ ObjectMethod *storedDataExists* <tt>() -> $boolean</tt>
   1.129 +
   1.130 +Establishes if there is stored data associated with this handler.
   1.131 +
   1.132 +
   1.133 +
   1.134 +---++ ObjectMethod *getTimestamp* <tt>() -> $integer</tt>
   1.135 +
   1.136 +Get the timestamp of the file
   1.137 +Returns 0 if no file, otherwise epoch seconds
   1.138 +
   1.139 +
   1.140 +
   1.141 +---++ ObjectMethod *restoreLatestRevision* <tt>($user)</tt>
   1.142 +
   1.143 +Restore the plaintext file from the revision at the head.
   1.144 +
   1.145 +
   1.146 +
   1.147 +---++ ObjectMethod *removeWeb* <tt>($web)</tt>
   1.148 +
   1.149 +   * =$web= - web being removed
   1.150 +
   1.151 +Destroy a web, utterly. Removed the data and attachments in the web.
   1.152 +
   1.153 +Use with great care! No backup is taken!
   1.154 +
   1.155 +
   1.156 +
   1.157 +---++ ObjectMethod *moveTopic* <tt>($newWeb,$newTopic)</tt>
   1.158 +
   1.159 +Move/rename a topic.
   1.160 +
   1.161 +
   1.162 +
   1.163 +---++ ObjectMethod *copyTopic* <tt>($newWeb,$newTopic)</tt>
   1.164 +
   1.165 +Copy a topic.
   1.166 +
   1.167 +
   1.168 +
   1.169 +---++ ObjectMethod *moveAttachment* <tt>($newWeb,$newTopic,$newAttachment)</tt>
   1.170 +
   1.171 +Move an attachment from one topic to another. The name is retained.
   1.172 +
   1.173 +
   1.174 +
   1.175 +---++ ObjectMethod *copyAttachment* <tt>($newWeb,$newTopic)</tt>
   1.176 +
   1.177 +Copy an attachment from one topic to another. The name is retained.
   1.178 +
   1.179 +
   1.180 +
   1.181 +---++ ObjectMethod *isAsciiDefault* <tt>() -> $boolean</tt>
   1.182 +
   1.183 +Check if this file type is known to be an ascii type file.
   1.184 +
   1.185 +
   1.186 +
   1.187 +---++ ObjectMethod *setLock* <tt>($lock,$user)</tt>
   1.188 +
   1.189 +Set a lock on the topic, if $lock, otherwise clear it.
   1.190 +$user is a wikiname.
   1.191 +
   1.192 +SMELL: there is a tremendous amount of potential for race
   1.193 +conditions using this locking approach.
   1.194 +
   1.195 +
   1.196 +
   1.197 +---++ ObjectMethod *isLocked* <tt>() -> ($user,$time)</tt>
   1.198 +
   1.199 +See if a twiki lock exists. Return the lock user and lock time if it does.
   1.200 +
   1.201 +
   1.202 +
   1.203 +---++ ObjectMethod *setLease* <tt>($lease)</tt>
   1.204 +
   1.205 +   * =$lease= reference to lease hash, or undef if the existing lease is to be cleared.
   1.206 +
   1.207 +Set an lease on the topic.
   1.208 +
   1.209 +
   1.210 +
   1.211 +---++ ObjectMethod *getLease* <tt>() -> $lease</tt>
   1.212 +
   1.213 +Get the current lease on the topic.
   1.214 +
   1.215 +
   1.216 +
   1.217 +---++ ObjectMethod *removeSpuriousLeases* <tt>($web)</tt>
   1.218 +
   1.219 +Remove leases that are not related to a topic. These can get left behind in
   1.220 +some store implementations when a topic is created, but never saved.
   1.221 +
   1.222 +
   1.223 +
   1.224 +---++ ObjectMethod *getStream* <tt>() -> \*STREAM</tt>
   1.225 +
   1.226 +Return a text stream that will supply the text stored in the topic.
   1.227 +
   1.228 +
   1.229 +
   1.230 +---++ ObjectMethod *numRevisions* <tt>() -> $integer</tt>
   1.231 +
   1.232 +Must be provided by subclasses.
   1.233 +
   1.234 +Find out how many revisions there are. If there is a problem, such
   1.235 +as a nonexistent file, returns 0.
   1.236 +
   1.237 +*Virtual method* - must be implemented by subclasses
   1.238 +
   1.239 +
   1.240 +
   1.241 +---++ ObjectMethod *initBinary* <tt>()</tt>
   1.242 +
   1.243 +Initialise a binary file.
   1.244 +
   1.245 +Must be provided by subclasses.
   1.246 +
   1.247 +*Virtual method* - must be implemented by subclasses
   1.248 +
   1.249 +
   1.250 +
   1.251 +---++ ObjectMethod *initText* <tt>()</tt>
   1.252 +
   1.253 +Initialise a text file.
   1.254 +
   1.255 +Must be provided by subclasses.
   1.256 +
   1.257 +*Virtual method* - must be implemented by subclasses
   1.258 +
   1.259 +
   1.260 +
   1.261 +---++ ObjectMethod *addRevisionFromText* <tt>($text,$comment,$user,$date)</tt>
   1.262 +
   1.263 +Add new revision. Replace file with text.
   1.264 +   * =$text= of new revision
   1.265 +   * =$comment= checkin comment
   1.266 +   * =$user= is a wikiname.
   1.267 +   * =$date= in epoch seconds; may be ignored
   1.268 +
   1.269 +*Virtual method* - must be implemented by subclasses
   1.270 +
   1.271 +
   1.272 +
   1.273 +---++ ObjectMethod *addRevisionFromStream* <tt>($fh,$comment,$user,$date)</tt>
   1.274 +
   1.275 +Add new revision. Replace file with contents of stream.
   1.276 +   * =$fh= filehandle for contents of new revision
   1.277 +   * =$comment= checkin comment
   1.278 +   * =$user= is a wikiname.
   1.279 +   * =$date= in epoch seconds; may be ignored
   1.280 +
   1.281 +*Virtual method* - must be implemented by subclasses
   1.282 +
   1.283 +
   1.284 +
   1.285 +---++ ObjectMethod *replaceRevision* <tt>($text,$comment,$user,$date)</tt>
   1.286 +
   1.287 +Replace the top revision.
   1.288 +   * =$text= is the new revision
   1.289 +   * =$date= is in epoch seconds.
   1.290 +   * =$user= is a wikiname.
   1.291 +   * =$comment= is a string
   1.292 +
   1.293 +*Virtual method* - must be implemented by subclasses
   1.294 +
   1.295 +
   1.296 +
   1.297 +---++ ObjectMethod *deleteRevision* <tt>()</tt>
   1.298 +
   1.299 +Delete the last revision - do nothing if there is only one revision
   1.300 +
   1.301 +*Virtual method* - must be implemented by subclasses
   1.302 +
   1.303 +
   1.304 +
   1.305 +---++ ObjectMethod *revisionDiff* <tt>($rev1,$rev2,$contextLines) -> \@diffArray</tt>
   1.306 +
   1.307 +rev2 newer than rev1.
   1.308 +Return reference to an array of [ diffType, $right, $left ]
   1.309 +
   1.310 +*Virtual method* - must be implemented by subclasses
   1.311 +
   1.312 +
   1.313 +
   1.314 +!!!getRevision!!!
   1.315 +
   1.316 +---++ ObjectMethod *getRevisionAtTime* <tt>($time) -> $rev</tt>
   1.317 +
   1.318 +Get a single-digit version number for the rev that was alive at the
   1.319 +given epoch-secs time, or undef it none could be found.
   1.320 +
   1.321 +*Virtual method* - must be implemented by subclasses
   1.322 +
   1.323 +
   1.324 +
   1.325 +---++ ObjectMethod *getAttachmentAttributes* <tt>($web,$topic,$attachment)</tt>
   1.326 +
   1.327 +returns [stat] for any given web, topic, $attachment
   1.328 +SMELL - should this return a hash of arbitrary attributes so that 
   1.329 +SMELL + attributes supported by the underlying filesystem are supported
   1.330 +SMELL + (eg: windows directories supporting photo "author", "dimension" fields)
   1.331 +
   1.332 +
   1.333 +
   1.334 +---++ ObjectMethod *getAttachmentList* <tt>($web,$topic)</tt>
   1.335 +
   1.336 +returns {} of filename => { key => value, key2 => value } for any given web, topic
   1.337 +Ignores files starting with _ or ending with ,v
   1.338 +
   1.339 +
   1.340 +
   1.341 +---++ ObjectMethod *stringify* <tt>()</tt>
   1.342 +
   1.343 +Generate string representation for debugging
   1.344 +
   1.345 +
   1.346 +
   1.347 +---++ ObjectMethod *recordChange* <tt>($user,$rev,$more)</tt>
   1.348 +Record that the file changed
   1.349 +
   1.350 +
   1.351 +
   1.352 +---++ ObjectMethod *eachChange* <tt>($since) -> $iterator</tt>
   1.353 +
   1.354 +Return iterator over changes - see Store for details
   1.355 +
   1.356 +