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