data/TWiki/TWikiStoreRcsFileDotPm.txt,v
changeset 0 414e01d06fd5
equal deleted inserted replaced
-1:000000000000 0:414e01d06fd5
       
     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 @