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