data/TWiki/TWikiStoreDotPm.txt
author Colas Nahaboo <colas@nahaboo.net>
Sat, 26 Jan 2008 15:50:53 +0100
changeset 0 414e01d06fd5
child 2 7bc60a767fa4
permissions -rw-r--r--
RELEASE 4.2.0 freetown
colas@0
     1
---+ Package =TWiki::Store=
colas@0
     2
colas@0
     3
This module hosts the generic storage backend. This module provides
colas@0
     4
the interface layer between the "real" store provider - which is hidden
colas@0
     5
behind a handler - and the rest of the system. it is responsible for
colas@0
     6
checking for topic existance, access permissions, and all the other
colas@0
     7
general admin tasks that are common to all store implementations.
colas@0
     8
colas@0
     9
This module knows nothing about how the data is actually _stored_ -
colas@0
    10
that knowledge is entirely encapsulated in the handlers.
colas@0
    11
colas@0
    12
The general contract for methods in the class requires that errors
colas@0
    13
are signalled using exceptions. TWiki::AccessControlException is
colas@0
    14
used for access control exceptions, and Error::Simple for all other
colas@0
    15
types of error.
colas@0
    16
colas@0
    17
colas@0
    18
%TOC%
colas@0
    19
colas@0
    20
---++ ClassMethod *new* <tt>($session)</tt>
colas@0
    21
colas@0
    22
Construct a Store module, linking in the chosen sub-implementation.
colas@0
    23
colas@0
    24
colas@0
    25
colas@0
    26
---++ ObjectMethod *finish* <tt>()</tt>
colas@0
    27
Break circular references.
colas@0
    28
colas@0
    29
colas@0
    30
colas@0
    31
---++ ObjectMethod *readTopic* <tt>($user,$web,$topic,$version) -> ($metaObject,$text)</tt>
colas@0
    32
colas@0
    33
Reads the given version of a topic and it's meta-data. If the version
colas@0
    34
is undef, then read the most recent version. The version number must be
colas@0
    35
an integer, or undef for the latest version.
colas@0
    36
colas@0
    37
if $user is defined, view permission will be required for the topic
colas@0
    38
read to be successful.  Access control violations are flagged by a
colas@0
    39
TWiki::AccessControlException. Permissions are checked for the user
colas@0
    40
name passed in.
colas@0
    41
colas@0
    42
If the topic contains a web specification (is of the form Web.Topic) the
colas@0
    43
web specification will override whatever is passed in $web.
colas@0
    44
colas@0
    45
The metadata and topic text are returned separately, with the metadata in a
colas@0
    46
TWiki::Meta object.  (The topic text is, as usual, just a string.)
colas@0
    47
colas@0
    48
colas@0
    49
colas@0
    50
---++ ObjectMethod *_findAttachments* <tt>($session,$web,$topic,$knownAttachments) -> @attachmentsFoundInPub</tt>
colas@0
    51
colas@0
    52
Synchronise the attachment list with what's actually on disk Returns an ARRAY
colas@0
    53
of FILEATTACHMENTs. These can be put in the new meta using
colas@0
    54
meta->put('FILEATTACHMENTS', $tree) 
colas@0
    55
colas@0
    56
This function is only called when the AutoAttachPubFiles configuration option is set.
colas@0
    57
colas@0
    58
IDEA On Windows machines where the underlying filesystem can store arbitary
colas@0
    59
meta data against files, this might replace/fulfil the COMMENT purpose
colas@0
    60
colas@0
    61
TODO consider logging when things are added to metadata
colas@0
    62
colas@0
    63
colas@0
    64
colas@0
    65
---++ ObjectMethod *readTopicRaw* <tt>($user,$web,$topic,$version) -> $topicText</tt>
colas@0
    66
colas@0
    67
Reads the given version of a topic, without separating out any embedded
colas@0
    68
meta-data. If the version is undef, then read the most recent version.
colas@0
    69
The version number must be an integer or undef.
colas@0
    70
colas@0
    71
If $user is defined, view permission will be required for the topic
colas@0
    72
read to be successful.  Access control violations are flagged by a
colas@0
    73
TWiki::AccessControlException. Permissions are checked for the user
colas@0
    74
name passed in.
colas@0
    75
colas@0
    76
If the topic contains a web specification (is of the form Web.Topic) the
colas@0
    77
web specification will override whatever is passed in $web.
colas@0
    78
colas@0
    79
SMELL: DO NOT CALL THIS METHOD UNLESS YOU HAVE NO CHOICE. This method breaks
colas@0
    80
encapsulation of the store, as it assumes meta is stored embedded in the text.
colas@0
    81
Other implementors of store will be forced to insert meta-data to ensure
colas@0
    82
correct operation of View raw=debug and the 'repRev' mode of Edit.
colas@0
    83
colas@0
    84
$web and $topic _must_ be untainted.
colas@0
    85
colas@0
    86
colas@0
    87
colas@0
    88
---++ ObjectMethod *moveAttachment* <tt>($oldWeb,$oldTopic,$oldAttachment,$newWeb,$newTopic,$newAttachment,$user)</tt>
colas@0
    89
colas@0
    90
Move an attachment from one topic to another.
colas@0
    91
colas@0
    92
The caller to this routine should check that all topics are valid.
colas@0
    93
colas@0
    94
All parameters must be defined, and must be untainted.
colas@0
    95
colas@0
    96
colas@0
    97
colas@0
    98
---++ ObjectMethod *getAttachmentStream* <tt>($user,$web,$topic,$attName) -> \*STREAM</tt>
colas@0
    99
colas@0
   100
   * =$user= - the user doing the reading, or undef if no access checks
colas@0
   101
   * =$web= - The web
colas@0
   102
   * =$topic= - The topic
colas@0
   103
   * =$attName= - Name of the attachment
colas@0
   104
colas@0
   105
Open a standard input stream from an attachment.
colas@0
   106
colas@0
   107
If $user is defined, view permission will be required for the topic
colas@0
   108
read to be successful.  Access control violations and errors will
colas@0
   109
cause exceptions to be thrown.
colas@0
   110
colas@0
   111
Permissions are checked for the user name passed in.
colas@0
   112
colas@0
   113
colas@0
   114
colas@0
   115
---++ ObjectMethod *getAttachmentList* <tt>($web,$topic)</tt>
colas@0
   116
colas@0
   117
returns @($attachmentName => [stat]) for any given web, topic
colas@0
   118
colas@0
   119
colas@0
   120
colas@0
   121
---++ ObjectMethod *attachmentExists* <tt>($web,$topic,$att) -> $boolean</tt>
colas@0
   122
colas@0
   123
Determine if the attachment already exists on the given topic
colas@0
   124
colas@0
   125
colas@0
   126
colas@0
   127
---++ ObjectMethod *_removeAutoAttachmentsFromMeta* <tt></tt>
colas@0
   128
colas@0
   129
This is where we are going to remove from meta any entry that is marked as an automatic attachment.
colas@0
   130
colas@0
   131
colas@0
   132
colas@0
   133
---++ ObjectMethod *moveTopic* <tt>($oldWeb,$oldTopic,$newWeb,$newTopic,$user)</tt>
colas@0
   134
colas@0
   135
All parameters must be defined and must be untainted.
colas@0
   136
colas@0
   137
colas@0
   138
colas@0
   139
---++ ObjectMethod *moveWeb* <tt>($oldWeb,$newWeb,$user)</tt>
colas@0
   140
colas@0
   141
Move a web.
colas@0
   142
colas@0
   143
All parrameters must be defined and must be untainted.
colas@0
   144
colas@0
   145
colas@0
   146
colas@0
   147
---++ ObjectMethod *readAttachment* <tt>($user,$web,$topic,$attachment,$theRev) -> $text</tt>
colas@0
   148
colas@0
   149
Read the given version of an attachment, returning the content.
colas@0
   150
colas@0
   151
View permission on the topic is required for the
colas@0
   152
read to be successful.  Access control violations are flagged by a
colas@0
   153
TWiki::AccessControlException. Permissions are checked for the user
colas@0
   154
passed in.
colas@0
   155
colas@0
   156
If $theRev is not given, the most recent rev is assumed.
colas@0
   157
colas@0
   158
colas@0
   159
colas@0
   160
---++ ObjectMethod *getRevisionNumber* <tt>($web,$topic,$attachment) -> $integer</tt>
colas@0
   161
colas@0
   162
Get the revision number of the most recent revision. Returns
colas@0
   163
the integer revision number or '' if the topic doesn't exist.
colas@0
   164
colas@0
   165
WORKS FOR ATTACHMENTS AS WELL AS TOPICS
colas@0
   166
colas@0
   167
colas@0
   168
colas@0
   169
---++ ObjectMethod *getWorkArea* <tt>($key) -> $directorypath</tt>
colas@0
   170
colas@0
   171
Gets a private directory uniquely identified by $key. The directory is
colas@0
   172
intended as a work area for plugins. The directory will exist.
colas@0
   173
colas@0
   174
colas@0
   175
colas@0
   176
---++ ObjectMethod *getRevisionDiff* <tt>($user,$web,$topic,$rev1,$rev2,$contextLines) -> \@diffArray</tt>
colas@0
   177
colas@0
   178
Return reference to an array of [ diffType, $right, $left ]
colas@0
   179
   * =$user= - the user id, or undef to suppress access control checks
colas@0
   180
   * =$web= - the web
colas@0
   181
   * =$topic= - the topic
colas@0
   182
   * =$rev1= Integer revision number
colas@0
   183
   * =$rev2= Integer revision number
colas@0
   184
   * =$contextLines= - number of lines of context required
colas@0
   185
colas@0
   186
colas@0
   187
colas@0
   188
---++ ObjectMethod *getRevisionInfo* <tt>($web,$topic,$rev,$attachment) -> ($date,$user,$rev,$comment)</tt>
colas@0
   189
colas@0
   190
Get revision info of a topic.
colas@0
   191
   * =$web= Web name, optional, e.g. ='Main'=
colas@0
   192
   * =$topic= Topic name, required, e.g. ='TokyoOffice'=
colas@0
   193
   * =$rev= revision number. If 0, undef, or out-of-range, will get info about the most recent revision.
colas@0
   194
   * =$attachment= attachment filename; undef for a topic
colas@0
   195
Return list with: ( last update date, last user id, =
colas@0
   196
| $date | in epochSec |
colas@0
   197
| $user | user *object* |
colas@0
   198
| $rev | the revision number |
colas@0
   199
| $comment | WHAT COMMENT? |
colas@0
   200
e.g. =( 1234561, 'phoeny', 5, 'no comment' )
colas@0
   201
colas@0
   202
NOTE NOTE NOTE if you are working within the TWiki code DO NOT USE THIS
colas@0
   203
FUNCTION FOR GETTING REVISION INFO OF TOPICS - use
colas@0
   204
TWiki::Meta::getRevisionInfo instead. This is essential to allow clean
colas@0
   205
transition to a topic object model later, and avoids the risk of confusion
colas@0
   206
coming from meta and Store revision information being out of step.
colas@0
   207
(it's OK to use it for attachments)
colas@0
   208
colas@0
   209
colas@0
   210
colas@0
   211
---++ StaticMethod *dataEncode* <tt>($uncoded) -> $coded</tt>
colas@0
   212
colas@0
   213
Encode meta-data fields, escaping out selected characters. The encoding
colas@0
   214
is chosen to avoid problems with parsing the attribute values, while
colas@0
   215
minimising the number of characters encoded so searches can still work
colas@0
   216
(fairly) sensibly.
colas@0
   217
colas@0
   218
The encoding has to be exported because TWiki (and plugins) use
colas@0
   219
encoded field data in other places e.g. RDiff, mainly as a shorthand
colas@0
   220
for the properly parsed meta object. Some day we may be able to
colas@0
   221
eliminate that....
colas@0
   222
colas@0
   223
colas@0
   224
colas@0
   225
---++ StaticMethod *dataDecode* <tt>($encoded) -> $decoded</tt>
colas@0
   226
colas@0
   227
Decode escapes in a string that was encoded using dataEncode
colas@0
   228
colas@0
   229
The encoding has to be exported because TWiki (and plugins) use
colas@0
   230
encoded field data in other places e.g. RDiff, mainly as a shorthand
colas@0
   231
for the properly parsed meta object. Some day we may be able to
colas@0
   232
eliminate that....
colas@0
   233
colas@0
   234
colas@0
   235
colas@0
   236
---++ ObjectMethod *saveTopic* <tt>($user,$web,$topic,$text,$meta,$options)</tt>
colas@0
   237
colas@0
   238
   * =$user= - user doing the saving (object)
colas@0
   239
   * =$web= - web for topic
colas@0
   240
   * =$topic= - topic to atach to
colas@0
   241
   * =$text= - topic text
colas@0
   242
   * =$meta= - topic meta-data
colas@0
   243
   * =$options= - Ref to hash of options
colas@0
   244
=$options= may include:
colas@0
   245
| =dontlog= | don't log this change in twiki log |
colas@0
   246
| =hide= | if the attachment is to be hidden in normal topic view |
colas@0
   247
| =comment= | comment for save |
colas@0
   248
| =file= | Temporary file name to upload |
colas@0
   249
| =minor= | True if this is a minor change (used in log) |
colas@0
   250
| =savecmd= | Save command |
colas@0
   251
| =forcedate= | grr |
colas@0
   252
| =unlock= | |
colas@0
   253
colas@0
   254
Save a new revision of the topic, calling plugins handlers as appropriate.
colas@0
   255
colas@0
   256
colas@0
   257
colas@0
   258
---++ ObjectMethod *saveAttachment* <tt>($web,$topic,$attachment,$user,$opts)</tt>
colas@0
   259
colas@0
   260
   * =$user= - user doing the saving
colas@0
   261
   * =$web= - web for topic
colas@0
   262
   * =$topic= - topic to atach to
colas@0
   263
   * =$attachment= - name of the attachment
colas@0
   264
   * =$opts= - Ref to hash of options
colas@0
   265
=$opts= may include:
colas@0
   266
| =dontlog= | don't log this change in twiki log |
colas@0
   267
| =comment= | comment for save |
colas@0
   268
| =hide= | if the attachment is to be hidden in normal topic view |
colas@0
   269
| =stream= | Stream of file to upload |
colas@0
   270
| =file= | Name of a file to use for the attachment data. ignored is stream is set. |
colas@0
   271
| =filepath= | Client path to file |
colas@0
   272
| =filesize= | Size of uploaded data |
colas@0
   273
| =filedate= | Date |
colas@0
   274
| =tmpFilename= | Pathname of the server file the stream is attached to. Required if stream is set. |
colas@0
   275
colas@0
   276
Saves a new revision of the attachment, invoking plugin handlers as
colas@0
   277
appropriate.
colas@0
   278
colas@0
   279
If file is not set, this is a properties-only save.
colas@0
   280
colas@0
   281
colas@0
   282
colas@0
   283
---++ ObjectMethod *repRev* <tt>($user,$web,$topic,$text,$meta,$options)</tt>
colas@0
   284
colas@0
   285
Replace last (top) revision with different text.
colas@0
   286
colas@0
   287
Parameters and return value as saveTopic, except
colas@0
   288
   * =$options= - as for saveTopic, with the extra option:
colas@0
   289
      * =timetravel= - if we want to force the deposited revision to look as much like the revision specified in =$rev= as possible.
colas@0
   290
      * =operation= - set to the name of the operation performing the save. This is used only in the log, and is normally =cmd= or =save=. It defaults to =save=.
colas@0
   291
colas@0
   292
Used to try to avoid the deposition of 'unecessary' revisions, for example
colas@0
   293
where a user quickly goes back and fixes a spelling error.
colas@0
   294
colas@0
   295
Also provided as a means for administrators to rewrite history (timetravel).
colas@0
   296
colas@0
   297
It is up to the store implementation if this is different
colas@0
   298
to a normal save or not.
colas@0
   299
colas@0
   300
colas@0
   301
colas@0
   302
---++ ObjectMethod *delRev* <tt>($user,$web,$topic,$text,$meta,$options)</tt>
colas@0
   303
colas@0
   304
Parameters and return value as saveTopic.
colas@0
   305
colas@0
   306
Provided as a means for administrators to rewrite history.
colas@0
   307
colas@0
   308
Delete last entry in repository, restoring the previous
colas@0
   309
revision.
colas@0
   310
colas@0
   311
It is up to the store implementation whether this actually
colas@0
   312
does delete a revision or not; some implementations will
colas@0
   313
simply promote the previous revision up to the head.
colas@0
   314
colas@0
   315
colas@0
   316
colas@0
   317
---++ ObjectMethod *lockTopic* <tt>($web,$topic)</tt>
colas@0
   318
colas@0
   319
Grab a topic lock on the given topic. A topic lock will cause other
colas@0
   320
processes that also try to claim a lock to block. A lock has a
colas@0
   321
maximum lifetime of 2 minutes, so operations on a locked topic
colas@0
   322
must be completed within that time. You cannot rely on the
colas@0
   323
lock timeout clearing the lock, though; that should always
colas@0
   324
be done by calling unlockTopic. The best thing to do is to guard
colas@0
   325
the locked section with a try..finally clause. See man Error for more info.
colas@0
   326
colas@0
   327
Topic locks are used to make store operations atomic. They are
colas@0
   328
_note_ the locks used when a topic is edited; those are Leases
colas@0
   329
(see =getLease=)
colas@0
   330
colas@0
   331
colas@0
   332
colas@0
   333
---++ ObjectMethod *unlockTopic* <tt>($user,$web,$topic)</tt>
colas@0
   334
colas@0
   335
Release the topic lock on the given topic. A topic lock will cause other
colas@0
   336
processes that also try to claim a lock to block. It is important to
colas@0
   337
release a topic lock after a guard section is complete. This should
colas@0
   338
normally be done in a 'finally' block. See man Error for more info.
colas@0
   339
colas@0
   340
Topic locks are used to make store operations atomic. They are
colas@0
   341
_note_ the locks used when a topic is edited; those are Leases
colas@0
   342
(see =getLease=)
colas@0
   343
colas@0
   344
colas@0
   345
colas@0
   346
---++ ObjectMethod *webExists* <tt>($web) -> $boolean</tt>
colas@0
   347
colas@0
   348
Test if web exists
colas@0
   349
   * =$web= - Web name, required, e.g. ='Sandbox'=
colas@0
   350
colas@0
   351
A web _has_ to have a preferences topic to be a web.
colas@0
   352
colas@0
   353
colas@0
   354
colas@0
   355
---++ ObjectMethod *topicExists* <tt>($web,$topic) -> $boolean</tt>
colas@0
   356
colas@0
   357
Test if topic exists
colas@0
   358
   * =$web= - Web name, optional, e.g. ='Main'=
colas@0
   359
   * =$topic= - Topic name, required, e.g. ='TokyoOffice'=, or ="Main.TokyoOffice"=
colas@0
   360
colas@0
   361
colas@0
   362
colas@0
   363
---++ ObjectMethod *getTopicParent* <tt>($web,$topic) -> $string</tt>
colas@0
   364
colas@0
   365
Get the name of the topic parent. Needs to be fast because
colas@0
   366
of use by Render.pm.
colas@0
   367
colas@0
   368
colas@0
   369
colas@0
   370
---++ ObjectMethod *getTopicLatestRevTime* <tt>($web,$topic) -> $epochSecs</tt>
colas@0
   371
colas@0
   372
Get an approximate rev time for the latest rev of the topic. This method
colas@0
   373
is used to optimise searching. Needs to be as fast as possible.
colas@0
   374
colas@0
   375
colas@0
   376
colas@0
   377
---++ ObjectMethod *eachChange* <tt>($web,$time) -> $iterator</tt>
colas@0
   378
colas@0
   379
Get an iterator over the list of all the changes in the given web between
colas@0
   380
=$time= and now. $time is a time in seconds since 1st Jan 1970, and is not
colas@0
   381
guaranteed to return any changes that occurred before (now - 
colas@0
   382
{Store}{RememberChangesFor}). Changes are returned in most-recent-first
colas@0
   383
order.
colas@0
   384
colas@0
   385
colas@0
   386
colas@0
   387
---++ ObjectMethod *getTopicNames* <tt>($web) -> @topics</tt>
colas@0
   388
colas@0
   389
Get list of all topics in a web
colas@0
   390
   * =$web= - Web name, required, e.g. ='Sandbox'=
colas@0
   391
Return a topic list, e.g. =( 'WebChanges',  'WebHome', 'WebIndex', 'WebNotify' )=
colas@0
   392
colas@0
   393
colas@0
   394
colas@0
   395
---++ ObjectMethod *getListOfWebs* <tt>($filter) -> @webNames</tt>
colas@0
   396
colas@0
   397
Gets a list of webs, filtered according to the spec in the $filter,
colas@0
   398
which may include one of:
colas@0
   399
   1 'user' (for only user webs)
colas@0
   400
   2 'template' (for only template webs)
colas@0
   401
$filter may also contain the word 'public' which will further filter
colas@0
   402
webs on whether NOSEARCHALL is specified for them or not.
colas@0
   403
'allowed' filters out webs that the user is denied access to by a *WEBVIEW.
colas@0
   404
colas@0
   405
If $TWiki::cfg{EnableHierarchicalWebs} is set, will also list
colas@0
   406
sub-webs recursively.
colas@0
   407
colas@0
   408
colas@0
   409
colas@0
   410
---++ ObjectMethod *createWeb* <tt>($user,$newWeb,$baseWeb,$opts)</tt>
colas@0
   411
colas@0
   412
$newWeb is the name of the new web.
colas@0
   413
colas@0
   414
$baseWeb is the name of an existing web (a template web). If the
colas@0
   415
base web is a system web, all topics in it
colas@0
   416
will be copied into the new web. If it is a normal web, only topics starting
colas@0
   417
with 'Web' will be copied. If no base web is specified, an empty web
colas@0
   418
(with no topics) will be created. If it is specified but does not exist,
colas@0
   419
an error will be thrown.
colas@0
   420
colas@0
   421
$opts is a ref to a hash that contains settings to be modified in
colas@0
   422
the web preferences topic in the new web.
colas@0
   423
colas@0
   424
colas@0
   425
colas@0
   426
---++ ObjectMethod *removeWeb* <tt>($user,$web)</tt>
colas@0
   427
colas@0
   428
   * =$user= - user doing the removing (for the history)
colas@0
   429
   * =$web= - web being removed
colas@0
   430
colas@0
   431
Destroy a web, utterly. Removed the data and attachments in the web.
colas@0
   432
colas@0
   433
Use with great care!
colas@0
   434
colas@0
   435
The web must be a known web to be removed this way.
colas@0
   436
colas@0
   437
colas@0
   438
colas@0
   439
---++ ObjectMethod *getDebugText* <tt>($meta,$text) -> $text</tt>
colas@0
   440
colas@0
   441
Generate a debug text form of the text/meta, for use in debug displays,
colas@0
   442
by annotating the text with meta informtion.
colas@0
   443
colas@0
   444
colas@0
   445
colas@0
   446
---++ ObjectMethod *cleanUpRevID* <tt>($rev) -> $integer</tt>
colas@0
   447
colas@0
   448
Cleans up (maps) a user-supplied revision ID and converts it to an integer
colas@0
   449
number that can be incremented to create a new revision number.
colas@0
   450
colas@0
   451
This method should be used to sanitise user-provided revision IDs.
colas@0
   452
colas@0
   453
colas@0
   454
colas@0
   455
---++ ObjectMethod *copyTopic* <tt>($user,$fromweb,$fromtopic,$toweb,$totopic)</tt>
colas@0
   456
colas@0
   457
Copy a topic and all it's attendant data from one web to another.
colas@0
   458
colas@0
   459
SMELL: Does not fix up meta-data!
colas@0
   460
colas@0
   461
colas@0
   462
colas@0
   463
---++ ObjectMethod *searchMetaData* <tt>($params) -> $text</tt>
colas@0
   464
colas@0
   465
Search meta-data associated with topics. Parameters are passed in the $params hash,
colas@0
   466
which may contain:
colas@0
   467
| =type= | =topicmoved=, =parent= or =field= |
colas@0
   468
| =topic= | topic to search for, for =topicmoved= and =parent= |
colas@0
   469
| =name= | form field to search, for =field= type searches. May be a regex. |
colas@0
   470
| =value= | form field value. May be a regex. |
colas@0
   471
| =title= | Title prepended to the returned search results |
colas@0
   472
| =default= | defualt value if there are no results |
colas@0
   473
| =web= | web to search in, default is all webs |
colas@0
   474
| =format= | string for custom formatting results |
colas@0
   475
The idea is that people can search for meta-data values without having to be
colas@0
   476
aware of how or where meta-data is stored.
colas@0
   477
colas@0
   478
SMELL: should be replaced with a proper SQL-like search, c.f. Plugins.DBCacheContrib.
colas@0
   479
colas@0
   480
colas@0
   481
colas@0
   482
---++ ObjectMethod *searchInWebMetaData* <tt>($query,$web,\@topics) -> \%matches</tt>
colas@0
   483
colas@0
   484
Search for a meta-data expression in the content of a web. =$query= must be a =TWiki::Query= object.
colas@0
   485
colas@0
   486
Returns a reference to a hash that maps the names of topics that all matched
colas@0
   487
to the result of the query expression (e.g. if the query expression is
colas@0
   488
'TOPICPARENT.name' then you will get back a hash that maps topic names
colas@0
   489
to their parent.
colas@0
   490
colas@0
   491
colas@0
   492
colas@0
   493
---++ ObjectMethod *searchInWebContent* <tt>($searchString,$web,\@topics,\%options) -> \%map</tt>
colas@0
   494
colas@0
   495
Search for a string in the content of a web. The search must be over all
colas@0
   496
content and all formatted meta-data, though the latter search type is
colas@0
   497
deprecated (use searchMetaData instead).
colas@0
   498
colas@0
   499
   * =$searchString= - the search string, in egrep format if regex
colas@0
   500
   * =$web= - The web to search in
colas@0
   501
   * =\@topics= - reference to a list of topics to search
colas@0
   502
   * =\%options= - reference to an options hash
colas@0
   503
The =\%options= hash may contain the following options:
colas@0
   504
   * =type= - if =regex= will perform a egrep-syntax RE search (default '')
colas@0
   505
   * =casesensitive= - false to ignore case (defaulkt true)
colas@0
   506
   * =files_without_match= - true to return files only (default false)
colas@0
   507
colas@0
   508
The return value is a reference to a hash which maps each matching topic
colas@0
   509
name to a list of the lines in that topic that matched the search,
colas@0
   510
as would be returned by 'grep'. If =files_without_match= is specified, it will
colas@0
   511
return on the first match in each topic (i.e. it will return only one
colas@0
   512
match per topic, and will not return matching lines).
colas@0
   513
colas@0
   514
colas@0
   515
colas@0
   516
---++ ObjectMethod *getRevisionAtTime* <tt>($web,$topic,$time) -> $rev</tt>
colas@0
   517
colas@0
   518
   * =$web= - web for topic
colas@0
   519
   * =$topic= - topic
colas@0
   520
   * =$time= - time (in epoch secs) for the rev
colas@0
   521
colas@0
   522
Get the revision number of a topic at a specific time.
colas@0
   523
Returns a single-digit rev number or undef if it couldn't be determined
colas@0
   524
(either because the topic isn't that old, or there was a problem)
colas@0
   525
colas@0
   526
colas@0
   527
colas@0
   528
---++ ObjectMethod *getLease* <tt>($web,$topic) -> $lease</tt>
colas@0
   529
colas@0
   530
   * =$web= - web for topic
colas@0
   531
   * =$topic= - topic
colas@0
   532
colas@0
   533
If there is an lease on the topic, return the lease, otherwise undef.
colas@0
   534
A lease is a block of meta-information about a topic that can be
colas@0
   535
recovered (this is a hash containing =user=, =taken= and =expires=).
colas@0
   536
Leases are taken out when a topic is edited. Only one lease
colas@0
   537
can be active on a topic at a time. Leases are used to warn if
colas@0
   538
another user is already editing a topic.
colas@0
   539
colas@0
   540
colas@0
   541
colas@0
   542
---++ ObjectMethod *setLease* <tt>($web,$topic,$user,$length)</tt>
colas@0
   543
colas@0
   544
Take out an lease on the given topic for this user for $length seconds.
colas@0
   545
colas@0
   546
See =getLease= for more details about Leases.
colas@0
   547
colas@0
   548
colas@0
   549
colas@0
   550
---++ ObjectMethod *clearLease* <tt>($web,$topic)</tt>
colas@0
   551
colas@0
   552
Cancel the current lease.
colas@0
   553
colas@0
   554
See =getLease= for more details about Leases.
colas@0
   555
colas@0
   556
colas@0
   557
colas@0
   558
---++ ObjectMethod *removeSpuriousLeases* <tt>($web)</tt>
colas@0
   559
colas@0
   560
Remove leases that are not related to a topic. These can get left behind in
colas@0
   561
some store implementations when a topic is created, but never saved.
colas@0
   562
colas@0
   563