data/TWiki/TWikiStoreRcsFileDotPm.txt
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
---+ Package =TWiki::Store::RcsFile=
colas@0
     2
colas@0
     3
This class is PACKAGE PRIVATE to Store, and should never be
colas@0
     4
used from anywhere else. It is the base class of implementations of stores
colas@0
     5
that manipulate RCS format files.
colas@0
     6
colas@0
     7
The general contract of the methods on this class and its subclasses
colas@0
     8
calls for errors to be signalled by Error::Simple exceptions.
colas@0
     9
colas@0
    10
Refer to Store.pm for models of usage.
colas@0
    11
colas@0
    12
colas@0
    13
%TOC%
colas@0
    14
colas@0
    15
---++ ClassMethod *new* <tt>($session,$web,$topic,$attachment)</tt>
colas@0
    16
colas@0
    17
Constructor. There is one object per stored file.
colas@0
    18
colas@0
    19
Note that $web, $topic and $attachment must be untainted!
colas@0
    20
colas@0
    21
colas@0
    22
colas@0
    23
---++ ObjectMethod *finish* <tt>()</tt>
colas@0
    24
Break circular references.
colas@0
    25
colas@0
    26
colas@0
    27
colas@0
    28
---++ ObjectMethod *getRevisionInfo* <tt>($version) -> ($rev,$date,$user,$comment)</tt>
colas@0
    29
colas@0
    30
   * =$version= if 0 or undef, or out of range (version number > number of revs) will return info about the latest revision.
colas@0
    31
colas@0
    32
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
    33
colas@0
    34
Designed to be overridden by subclasses, which can call up to this method
colas@0
    35
if file-based rev info is required.
colas@0
    36
colas@0
    37
colas@0
    38
colas@0
    39
---++ ObjectMethod *getLatestRevision* <tt>() -> $text</tt>
colas@0
    40
colas@0
    41
Get the text of the most recent revision
colas@0
    42
colas@0
    43
colas@0
    44
colas@0
    45
---++ ObjectMethod *getLatestRevisionTime* <tt>() -> $text</tt>
colas@0
    46
colas@0
    47
Get the time of the most recent revision
colas@0
    48
colas@0
    49
colas@0
    50
colas@0
    51
---++ ObjectMethod *getWorkArea* <tt>($key) -> $directorypath</tt>
colas@0
    52
colas@0
    53
Gets a private directory uniquely identified by $key. The directory is
colas@0
    54
intended as a work area for plugins.
colas@0
    55
colas@0
    56
The standard is a directory named the same as "key" under
colas@0
    57
$TWiki::cfg{WorkingDir}/work_areas
colas@0
    58
colas@0
    59
colas@0
    60
colas@0
    61
---++ ObjectMethod *getTopicNames* <tt>() -> @topics</tt>
colas@0
    62
colas@0
    63
Get list of all topics in a web
colas@0
    64
   * =$web= - Web name, required, e.g. ='Sandbox'=
colas@0
    65
Return a topic list, e.g. =( 'WebChanges',  'WebHome', 'WebIndex', 'WebNotify' )=
colas@0
    66
colas@0
    67
colas@0
    68
colas@0
    69
---++ ObjectMethod *getWebNames* <tt>() -> @webs</tt>
colas@0
    70
colas@0
    71
Gets a list of names of subwebs in the current web
colas@0
    72
colas@0
    73
colas@0
    74
colas@0
    75
---++ ObjectMethod *searchInWebContent* <tt>($searchString,$web,\@topics,\%options) -> \%map</tt>
colas@0
    76
colas@0
    77
Search for a string in the content of a web. The search must be over all
colas@0
    78
content and all formatted meta-data, though the latter search type is
colas@0
    79
deprecated (use searchMetaData instead).
colas@0
    80
colas@0
    81
   * =$searchString= - the search string, in egrep format if regex
colas@0
    82
   * =$web= - The web to search in
colas@0
    83
   * =\@topics= - reference to a list of topics to search
colas@0
    84
   * =\%options= - reference to an options hash
colas@0
    85
The =\%options= hash may contain the following options:
colas@0
    86
   * =type= - if =regex= will perform a egrep-syntax RE search (default '')
colas@0
    87
   * =casesensitive= - false to ignore case (defaulkt true)
colas@0
    88
   * =files_without_match= - true to return files only (default false)
colas@0
    89
colas@0
    90
The return value is a reference to a hash which maps each matching topic
colas@0
    91
name to a list of the lines in that topic that matched the search,
colas@0
    92
as would be returned by 'grep'. If =files_without_match= is specified, it will
colas@0
    93
return on the first match in each topic (i.e. it will return only one
colas@0
    94
match per topic, and will not return matching lines).
colas@0
    95
colas@0
    96
colas@0
    97
colas@0
    98
---++ ObjectMethod *searchInWebMetaData* <tt>($query,\@topics) -> \%matches</tt>
colas@0
    99
colas@0
   100
Search for a meta-data expression in the content of a web. =$query= must be a =TWiki::Query= object.
colas@0
   101
colas@0
   102
Returns a reference to a hash that maps the names of topics that all matched
colas@0
   103
to the result of the query expression (e.g. if the query expression is
colas@0
   104
'TOPICPARENT.name' then you will get back a hash that maps topic names
colas@0
   105
to their parent.
colas@0
   106
colas@0
   107
SMELL: this is *really* inefficient!
colas@0
   108
colas@0
   109
colas@0
   110
colas@0
   111
---++ ObjectMethod *moveWeb* <tt>($newWeb)</tt>
colas@0
   112
colas@0
   113
Move a web.
colas@0
   114
colas@0
   115
colas@0
   116
colas@0
   117
---++ ObjectMethod *getRevision* <tt>($version) -> $text</tt>
colas@0
   118
colas@0
   119
Get the text for a given revision. The version number must be an integer.
colas@0
   120
colas@0
   121
*Virtual method* - must be implemented by subclasses
colas@0
   122
colas@0
   123
colas@0
   124
colas@0
   125
---++ ObjectMethod *storedDataExists* <tt>() -> $boolean</tt>
colas@0
   126
colas@0
   127
Establishes if there is stored data associated with this handler.
colas@0
   128
colas@0
   129
colas@0
   130
colas@0
   131
---++ ObjectMethod *getTimestamp* <tt>() -> $integer</tt>
colas@0
   132
colas@0
   133
Get the timestamp of the file
colas@0
   134
Returns 0 if no file, otherwise epoch seconds
colas@0
   135
colas@0
   136
colas@0
   137
colas@0
   138
---++ ObjectMethod *restoreLatestRevision* <tt>($user)</tt>
colas@0
   139
colas@0
   140
Restore the plaintext file from the revision at the head.
colas@0
   141
colas@0
   142
colas@0
   143
colas@0
   144
---++ ObjectMethod *removeWeb* <tt>($web)</tt>
colas@0
   145
colas@0
   146
   * =$web= - web being removed
colas@0
   147
colas@0
   148
Destroy a web, utterly. Removed the data and attachments in the web.
colas@0
   149
colas@0
   150
Use with great care! No backup is taken!
colas@0
   151
colas@0
   152
colas@0
   153
colas@0
   154
---++ ObjectMethod *moveTopic* <tt>($newWeb,$newTopic)</tt>
colas@0
   155
colas@0
   156
Move/rename a topic.
colas@0
   157
colas@0
   158
colas@0
   159
colas@0
   160
---++ ObjectMethod *copyTopic* <tt>($newWeb,$newTopic)</tt>
colas@0
   161
colas@0
   162
Copy a topic.
colas@0
   163
colas@0
   164
colas@0
   165
colas@0
   166
---++ ObjectMethod *moveAttachment* <tt>($newWeb,$newTopic,$newAttachment)</tt>
colas@0
   167
colas@0
   168
Move an attachment from one topic to another. The name is retained.
colas@0
   169
colas@0
   170
colas@0
   171
colas@0
   172
---++ ObjectMethod *copyAttachment* <tt>($newWeb,$newTopic)</tt>
colas@0
   173
colas@0
   174
Copy an attachment from one topic to another. The name is retained.
colas@0
   175
colas@0
   176
colas@0
   177
colas@0
   178
---++ ObjectMethod *isAsciiDefault* <tt>() -> $boolean</tt>
colas@0
   179
colas@0
   180
Check if this file type is known to be an ascii type file.
colas@0
   181
colas@0
   182
colas@0
   183
colas@0
   184
---++ ObjectMethod *setLock* <tt>($lock,$user)</tt>
colas@0
   185
colas@0
   186
Set a lock on the topic, if $lock, otherwise clear it.
colas@0
   187
$user is a wikiname.
colas@0
   188
colas@0
   189
SMELL: there is a tremendous amount of potential for race
colas@0
   190
conditions using this locking approach.
colas@0
   191
colas@0
   192
colas@0
   193
colas@0
   194
---++ ObjectMethod *isLocked* <tt>() -> ($user,$time)</tt>
colas@0
   195
colas@0
   196
See if a twiki lock exists. Return the lock user and lock time if it does.
colas@0
   197
colas@0
   198
colas@0
   199
colas@0
   200
---++ ObjectMethod *setLease* <tt>($lease)</tt>
colas@0
   201
colas@0
   202
   * =$lease= reference to lease hash, or undef if the existing lease is to be cleared.
colas@0
   203
colas@0
   204
Set an lease on the topic.
colas@0
   205
colas@0
   206
colas@0
   207
colas@0
   208
---++ ObjectMethod *getLease* <tt>() -> $lease</tt>
colas@0
   209
colas@0
   210
Get the current lease on the topic.
colas@0
   211
colas@0
   212
colas@0
   213
colas@0
   214
---++ ObjectMethod *removeSpuriousLeases* <tt>($web)</tt>
colas@0
   215
colas@0
   216
Remove leases that are not related to a topic. These can get left behind in
colas@0
   217
some store implementations when a topic is created, but never saved.
colas@0
   218
colas@0
   219
colas@0
   220
colas@0
   221
---++ ObjectMethod *getStream* <tt>() -> \*STREAM</tt>
colas@0
   222
colas@0
   223
Return a text stream that will supply the text stored in the topic.
colas@0
   224
colas@0
   225
colas@0
   226
colas@0
   227
---++ ObjectMethod *numRevisions* <tt>() -> $integer</tt>
colas@0
   228
colas@0
   229
Must be provided by subclasses.
colas@0
   230
colas@0
   231
Find out how many revisions there are. If there is a problem, such
colas@0
   232
as a nonexistent file, returns 0.
colas@0
   233
colas@0
   234
*Virtual method* - must be implemented by subclasses
colas@0
   235
colas@0
   236
colas@0
   237
colas@0
   238
---++ ObjectMethod *initBinary* <tt>()</tt>
colas@0
   239
colas@0
   240
Initialise a binary file.
colas@0
   241
colas@0
   242
Must be provided by subclasses.
colas@0
   243
colas@0
   244
*Virtual method* - must be implemented by subclasses
colas@0
   245
colas@0
   246
colas@0
   247
colas@0
   248
---++ ObjectMethod *initText* <tt>()</tt>
colas@0
   249
colas@0
   250
Initialise a text file.
colas@0
   251
colas@0
   252
Must be provided by subclasses.
colas@0
   253
colas@0
   254
*Virtual method* - must be implemented by subclasses
colas@0
   255
colas@0
   256
colas@0
   257
colas@0
   258
---++ ObjectMethod *addRevisionFromText* <tt>($text,$comment,$user,$date)</tt>
colas@0
   259
colas@0
   260
Add new revision. Replace file with text.
colas@0
   261
   * =$text= of new revision
colas@0
   262
   * =$comment= checkin comment
colas@0
   263
   * =$user= is a wikiname.
colas@0
   264
   * =$date= in epoch seconds; may be ignored
colas@0
   265
colas@0
   266
*Virtual method* - must be implemented by subclasses
colas@0
   267
colas@0
   268
colas@0
   269
colas@0
   270
---++ ObjectMethod *addRevisionFromStream* <tt>($fh,$comment,$user,$date)</tt>
colas@0
   271
colas@0
   272
Add new revision. Replace file with contents of stream.
colas@0
   273
   * =$fh= filehandle for contents of new revision
colas@0
   274
   * =$comment= checkin comment
colas@0
   275
   * =$user= is a wikiname.
colas@0
   276
   * =$date= in epoch seconds; may be ignored
colas@0
   277
colas@0
   278
*Virtual method* - must be implemented by subclasses
colas@0
   279
colas@0
   280
colas@0
   281
colas@0
   282
---++ ObjectMethod *replaceRevision* <tt>($text,$comment,$user,$date)</tt>
colas@0
   283
colas@0
   284
Replace the top revision.
colas@0
   285
   * =$text= is the new revision
colas@0
   286
   * =$date= is in epoch seconds.
colas@0
   287
   * =$user= is a wikiname.
colas@0
   288
   * =$comment= is a string
colas@0
   289
colas@0
   290
*Virtual method* - must be implemented by subclasses
colas@0
   291
colas@0
   292
colas@0
   293
colas@0
   294
---++ ObjectMethod *deleteRevision* <tt>()</tt>
colas@0
   295
colas@0
   296
Delete the last revision - do nothing if there is only one revision
colas@0
   297
colas@0
   298
*Virtual method* - must be implemented by subclasses
colas@0
   299
colas@0
   300
colas@0
   301
colas@0
   302
---++ ObjectMethod *revisionDiff* <tt>($rev1,$rev2,$contextLines) -> \@diffArray</tt>
colas@0
   303
colas@0
   304
rev2 newer than rev1.
colas@0
   305
Return reference to an array of [ diffType, $right, $left ]
colas@0
   306
colas@0
   307
*Virtual method* - must be implemented by subclasses
colas@0
   308
colas@0
   309
colas@0
   310
colas@0
   311
!!!getRevision!!!
colas@0
   312
colas@0
   313
---++ ObjectMethod *getRevisionAtTime* <tt>($time) -> $rev</tt>
colas@0
   314
colas@0
   315
Get a single-digit version number for the rev that was alive at the
colas@0
   316
given epoch-secs time, or undef it none could be found.
colas@0
   317
colas@0
   318
*Virtual method* - must be implemented by subclasses
colas@0
   319
colas@0
   320
colas@0
   321
colas@0
   322
---++ ObjectMethod *getAttachmentAttributes* <tt>($web,$topic,$attachment)</tt>
colas@0
   323
colas@0
   324
returns [stat] for any given web, topic, $attachment
colas@0
   325
SMELL - should this return a hash of arbitrary attributes so that 
colas@0
   326
SMELL + attributes supported by the underlying filesystem are supported
colas@0
   327
SMELL + (eg: windows directories supporting photo "author", "dimension" fields)
colas@0
   328
colas@0
   329
colas@0
   330
colas@0
   331
---++ ObjectMethod *getAttachmentList* <tt>($web,$topic)</tt>
colas@0
   332
colas@0
   333
returns {} of filename => { key => value, key2 => value } for any given web, topic
colas@0
   334
Ignores files starting with _ or ending with ,v
colas@0
   335
colas@0
   336
colas@0
   337
colas@0
   338
---++ ObjectMethod *stringify* <tt>()</tt>
colas@0
   339
colas@0
   340
Generate string representation for debugging
colas@0
   341
colas@0
   342
colas@0
   343
colas@0
   344
---++ ObjectMethod *recordChange* <tt>($user,$rev,$more)</tt>
colas@0
   345
Record that the file changed
colas@0
   346
colas@0
   347
colas@0
   348
colas@0
   349
---++ ObjectMethod *eachChange* <tt>($since) -> $iterator</tt>
colas@0
   350
colas@0
   351
Return iterator over changes - see Store for details
colas@0
   352
colas@0
   353