data/TWiki/TWikiStoreRcsFileDotPm.txt,v
author Colas Nahaboo <colas@nahaboo.net>
Mon, 11 Aug 2008 20:33:37 +0200
changeset 2 7bc60a767fa4
parent 0 414e01d06fd5
permissions -rw-r--r--
TWiki-4.2.2 Release
     1 head	1.4;
     2 access;
     3 symbols;
     4 locks; strict;
     5 comment	@# @;
     6 
     7 
     8 1.4
     9 date	2008.01.22.03.21.26;	author TWikiContributor;	state Exp;
    10 branches;
    11 next	1.3;
    12 
    13 1.3
    14 date	2007.01.16.04.12.04;	author TWikiContributor;	state Exp;
    15 branches;
    16 next	1.2;
    17 
    18 1.2
    19 date	2006.06.25.16.26.33;	author TWikiContributor;	state Exp;
    20 branches;
    21 next	1.1;
    22 
    23 1.1
    24 date	2006.02.01.12.01.25;	author TWikiContributor;	state Exp;
    25 branches;
    26 next	;
    27 
    28 
    29 desc
    30 @new-topic
    31 @
    32 
    33 
    34 1.4
    35 log
    36 @buildrelease
    37 @
    38 text
    39 @---+ Package =TWiki::Store::RcsFile=
    40 
    41 This class is PACKAGE PRIVATE to Store, and should never be
    42 used from anywhere else. It is the base class of implementations of stores
    43 that manipulate RCS format files.
    44 
    45 The general contract of the methods on this class and its subclasses
    46 calls for errors to be signalled by Error::Simple exceptions.
    47 
    48 Refer to Store.pm for models of usage.
    49 
    50 
    51 %TOC%
    52 
    53 ---++ ClassMethod *new* <tt>($session,$web,$topic,$attachment)</tt>
    54 
    55 Constructor. There is one object per stored file.
    56 
    57 Note that $web, $topic and $attachment must be untainted!
    58 
    59 
    60 
    61 ---++ ObjectMethod *finish* <tt>()</tt>
    62 Break circular references.
    63 
    64 
    65 
    66 ---++ ObjectMethod *getRevisionInfo* <tt>($version) -> ($rev,$date,$user,$comment)</tt>
    67 
    68    * =$version= if 0 or undef, or out of range (version number > number of revs) will return info about the latest revision.
    69 
    70 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.
    71 
    72 Designed to be overridden by subclasses, which can call up to this method
    73 if file-based rev info is required.
    74 
    75 
    76 
    77 ---++ ObjectMethod *getLatestRevision* <tt>() -> $text</tt>
    78 
    79 Get the text of the most recent revision
    80 
    81 
    82 
    83 ---++ ObjectMethod *getLatestRevisionTime* <tt>() -> $text</tt>
    84 
    85 Get the time of the most recent revision
    86 
    87 
    88 
    89 ---++ ObjectMethod *getWorkArea* <tt>($key) -> $directorypath</tt>
    90 
    91 Gets a private directory uniquely identified by $key. The directory is
    92 intended as a work area for plugins.
    93 
    94 The standard is a directory named the same as "key" under
    95 $TWiki::cfg{WorkingDir}/work_areas
    96 
    97 
    98 
    99 ---++ ObjectMethod *getTopicNames* <tt>() -> @@topics</tt>
   100 
   101 Get list of all topics in a web
   102    * =$web= - Web name, required, e.g. ='Sandbox'=
   103 Return a topic list, e.g. =( 'WebChanges',  'WebHome', 'WebIndex', 'WebNotify' )=
   104 
   105 
   106 
   107 ---++ ObjectMethod *getWebNames* <tt>() -> @@webs</tt>
   108 
   109 Gets a list of names of subwebs in the current web
   110 
   111 
   112 
   113 ---++ ObjectMethod *searchInWebContent* <tt>($searchString,$web,\@@topics,\%options) -> \%map</tt>
   114 
   115 Search for a string in the content of a web. The search must be over all
   116 content and all formatted meta-data, though the latter search type is
   117 deprecated (use searchMetaData instead).
   118 
   119    * =$searchString= - the search string, in egrep format if regex
   120    * =$web= - The web to search in
   121    * =\@@topics= - reference to a list of topics to search
   122    * =\%options= - reference to an options hash
   123 The =\%options= hash may contain the following options:
   124    * =type= - if =regex= will perform a egrep-syntax RE search (default '')
   125    * =casesensitive= - false to ignore case (defaulkt true)
   126    * =files_without_match= - true to return files only (default false)
   127 
   128 The return value is a reference to a hash which maps each matching topic
   129 name to a list of the lines in that topic that matched the search,
   130 as would be returned by 'grep'. If =files_without_match= is specified, it will
   131 return on the first match in each topic (i.e. it will return only one
   132 match per topic, and will not return matching lines).
   133 
   134 
   135 
   136 ---++ ObjectMethod *searchInWebMetaData* <tt>($query,\@@topics) -> \%matches</tt>
   137 
   138 Search for a meta-data expression in the content of a web. =$query= must be a =TWiki::Query= object.
   139 
   140 Returns a reference to a hash that maps the names of topics that all matched
   141 to the result of the query expression (e.g. if the query expression is
   142 'TOPICPARENT.name' then you will get back a hash that maps topic names
   143 to their parent.
   144 
   145 SMELL: this is *really* inefficient!
   146 
   147 
   148 
   149 ---++ ObjectMethod *moveWeb* <tt>($newWeb)</tt>
   150 
   151 Move a web.
   152 
   153 
   154 
   155 ---++ ObjectMethod *getRevision* <tt>($version) -> $text</tt>
   156 
   157 Get the text for a given revision. The version number must be an integer.
   158 
   159 *Virtual method* - must be implemented by subclasses
   160 
   161 
   162 
   163 ---++ ObjectMethod *storedDataExists* <tt>() -> $boolean</tt>
   164 
   165 Establishes if there is stored data associated with this handler.
   166 
   167 
   168 
   169 ---++ ObjectMethod *getTimestamp* <tt>() -> $integer</tt>
   170 
   171 Get the timestamp of the file
   172 Returns 0 if no file, otherwise epoch seconds
   173 
   174 
   175 
   176 ---++ ObjectMethod *restoreLatestRevision* <tt>($user)</tt>
   177 
   178 Restore the plaintext file from the revision at the head.
   179 
   180 
   181 
   182 ---++ ObjectMethod *removeWeb* <tt>($web)</tt>
   183 
   184    * =$web= - web being removed
   185 
   186 Destroy a web, utterly. Removed the data and attachments in the web.
   187 
   188 Use with great care! No backup is taken!
   189 
   190 
   191 
   192 ---++ ObjectMethod *moveTopic* <tt>($newWeb,$newTopic)</tt>
   193 
   194 Move/rename a topic.
   195 
   196 
   197 
   198 ---++ ObjectMethod *copyTopic* <tt>($newWeb,$newTopic)</tt>
   199 
   200 Copy a topic.
   201 
   202 
   203 
   204 ---++ ObjectMethod *moveAttachment* <tt>($newWeb,$newTopic,$newAttachment)</tt>
   205 
   206 Move an attachment from one topic to another. The name is retained.
   207 
   208 
   209 
   210 ---++ ObjectMethod *copyAttachment* <tt>($newWeb,$newTopic)</tt>
   211 
   212 Copy an attachment from one topic to another. The name is retained.
   213 
   214 
   215 
   216 ---++ ObjectMethod *isAsciiDefault* <tt>() -> $boolean</tt>
   217 
   218 Check if this file type is known to be an ascii type file.
   219 
   220 
   221 
   222 ---++ ObjectMethod *setLock* <tt>($lock,$user)</tt>
   223 
   224 Set a lock on the topic, if $lock, otherwise clear it.
   225 $user is a wikiname.
   226 
   227 SMELL: there is a tremendous amount of potential for race
   228 conditions using this locking approach.
   229 
   230 
   231 
   232 ---++ ObjectMethod *isLocked* <tt>() -> ($user,$time)</tt>
   233 
   234 See if a twiki lock exists. Return the lock user and lock time if it does.
   235 
   236 
   237 
   238 ---++ ObjectMethod *setLease* <tt>($lease)</tt>
   239 
   240    * =$lease= reference to lease hash, or undef if the existing lease is to be cleared.
   241 
   242 Set an lease on the topic.
   243 
   244 
   245 
   246 ---++ ObjectMethod *getLease* <tt>() -> $lease</tt>
   247 
   248 Get the current lease on the topic.
   249 
   250 
   251 
   252 ---++ ObjectMethod *removeSpuriousLeases* <tt>($web)</tt>
   253 
   254 Remove leases that are not related to a topic. These can get left behind in
   255 some store implementations when a topic is created, but never saved.
   256 
   257 
   258 
   259 ---++ ObjectMethod *getStream* <tt>() -> \*STREAM</tt>
   260 
   261 Return a text stream that will supply the text stored in the topic.
   262 
   263 
   264 
   265 ---++ ObjectMethod *numRevisions* <tt>() -> $integer</tt>
   266 
   267 Must be provided by subclasses.
   268 
   269 Find out how many revisions there are. If there is a problem, such
   270 as a nonexistent file, returns 0.
   271 
   272 *Virtual method* - must be implemented by subclasses
   273 
   274 
   275 
   276 ---++ ObjectMethod *initBinary* <tt>()</tt>
   277 
   278 Initialise a binary file.
   279 
   280 Must be provided by subclasses.
   281 
   282 *Virtual method* - must be implemented by subclasses
   283 
   284 
   285 
   286 ---++ ObjectMethod *initText* <tt>()</tt>
   287 
   288 Initialise a text file.
   289 
   290 Must be provided by subclasses.
   291 
   292 *Virtual method* - must be implemented by subclasses
   293 
   294 
   295 
   296 ---++ ObjectMethod *addRevisionFromText* <tt>($text,$comment,$user,$date)</tt>
   297 
   298 Add new revision. Replace file with text.
   299    * =$text= of new revision
   300    * =$comment= checkin comment
   301    * =$user= is a wikiname.
   302    * =$date= in epoch seconds; may be ignored
   303 
   304 *Virtual method* - must be implemented by subclasses
   305 
   306 
   307 
   308 ---++ ObjectMethod *addRevisionFromStream* <tt>($fh,$comment,$user,$date)</tt>
   309 
   310 Add new revision. Replace file with contents of stream.
   311    * =$fh= filehandle for contents of new revision
   312    * =$comment= checkin comment
   313    * =$user= is a wikiname.
   314    * =$date= in epoch seconds; may be ignored
   315 
   316 *Virtual method* - must be implemented by subclasses
   317 
   318 
   319 
   320 ---++ ObjectMethod *replaceRevision* <tt>($text,$comment,$user,$date)</tt>
   321 
   322 Replace the top revision.
   323    * =$text= is the new revision
   324    * =$date= is in epoch seconds.
   325    * =$user= is a wikiname.
   326    * =$comment= is a string
   327 
   328 *Virtual method* - must be implemented by subclasses
   329 
   330 
   331 
   332 ---++ ObjectMethod *deleteRevision* <tt>()</tt>
   333 
   334 Delete the last revision - do nothing if there is only one revision
   335 
   336 *Virtual method* - must be implemented by subclasses
   337 
   338 
   339 
   340 ---++ ObjectMethod *revisionDiff* <tt>($rev1,$rev2,$contextLines) -> \@@diffArray</tt>
   341 
   342 rev2 newer than rev1.
   343 Return reference to an array of [ diffType, $right, $left ]
   344 
   345 *Virtual method* - must be implemented by subclasses
   346 
   347 
   348 
   349 !!!getRevision!!!
   350 
   351 ---++ ObjectMethod *getRevisionAtTime* <tt>($time) -> $rev</tt>
   352 
   353 Get a single-digit version number for the rev that was alive at the
   354 given epoch-secs time, or undef it none could be found.
   355 
   356 *Virtual method* - must be implemented by subclasses
   357 
   358 
   359 
   360 ---++ ObjectMethod *getAttachmentAttributes* <tt>($web,$topic,$attachment)</tt>
   361 
   362 returns [stat] for any given web, topic, $attachment
   363 SMELL - should this return a hash of arbitrary attributes so that 
   364 SMELL + attributes supported by the underlying filesystem are supported
   365 SMELL + (eg: windows directories supporting photo "author", "dimension" fields)
   366 
   367 
   368 
   369 ---++ ObjectMethod *getAttachmentList* <tt>($web,$topic)</tt>
   370 
   371 returns {} of filename => { key => value, key2 => value } for any given web, topic
   372 Ignores files starting with _ or ending with ,v
   373 
   374 
   375 
   376 ---++ ObjectMethod *stringify* <tt>()</tt>
   377 
   378 Generate string representation for debugging
   379 
   380 
   381 
   382 ---++ ObjectMethod *recordChange* <tt>($user,$rev,$more)</tt>
   383 Record that the file changed
   384 
   385 
   386 
   387 ---++ ObjectMethod *eachChange* <tt>($since) -> $iterator</tt>
   388 
   389 Return iterator over changes - see Store for details
   390 
   391 
   392 @
   393 
   394 
   395 1.3
   396 log
   397 @buildrelease
   398 @
   399 text
   400 @d4 1
   401 a4 1
   402 used from anywhere else. Base class of implementations of stores
   403 d23 5
   404 a50 6
   405 ---++ ObjectMethod *readMetaData* <tt>($name) -> $text</tt>
   406 
   407 Get a meta-data block for this web
   408 
   409 
   410 
   411 d57 1
   412 a57 8
   413 $TWiki::cfg{RCS}{WorkAreaDir}
   414 
   415 
   416 
   417 ---++ ObjectMethod *saveMetaData* <tt>($web,$name) -> $text</tt>
   418 
   419 Write a named meta-data string. If web is given the meta-data
   420 is stored alongside a web.
   421 d98 13
   422 d138 1
   423 a138 1
   424 ---++ ObjectMethod *restoreLatestRevision* <tt>($wikiname)</tt>
   425 a330 4
   426 sub _constructAttributesForAutoAttached
   427 as long as stat is defined, return an emulated set of attributes for that attachment.
   428 
   429 
   430 d343 11
   431 @
   432 
   433 
   434 1.2
   435 log
   436 @buildrelease
   437 @
   438 text
   439 @d14 1
   440 d16 1
   441 d24 1
   442 d35 1
   443 d41 1
   444 d47 1
   445 d78 1
   446 d107 1
   447 d121 1
   448 d140 1
   449 d150 1
   450 d156 1
   451 d162 1
   452 d168 1
   453 d196 1
   454 d209 7
   455 d278 1
   456 d298 1
   457 d338 1
   458 @
   459 
   460 
   461 1.1
   462 log
   463 @buildrelease
   464 @
   465 text
   466 @d124 1
   467 a124 1
   468 ---++ ObjectMethod *restoreLatestRevision* <tt>()</tt>
   469 d292 1
   470 d300 2
   471 d305 1
   472 d311 6
   473 @