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