1 # <a name="TWiki Source Code Packages"></a><a name=" TWiki Source Code Packages"></a> TWiki Source Code Packages
3 %X% This documentation is automatically generated from the `pod`, so it always matches the running code
7 <li><a href="#"> </a></li>
8 <li><a href="#"> </a></li>
9 <li><a href="#"> </a></li>
10 <li><a href="#"> </a></li>
11 <li><a href="#"> </a></li>
12 <li><a href="#"> </a></li>
13 <li><a href="#"> </a></li>
14 <li><a href="#"> </a></li>
15 <li><a href="#"> </a></li>
16 <li><a href="#"> </a></li>
17 <li><a href="#"> </a></li>
18 <li><a href="#"> </a></li>
19 <li><a href="#"> </a></li>
20 <li><a href="#"> </a></li>
21 <li><a href="#"> </a></li>
22 <li><a href="#"> </a></li>
23 <li><a href="#"> </a></li>
24 <li><a href="#"> </a></li>
25 <li><a href="#TWiki::_AccessControlException"> TWiki::AccessControlException </a></li>
26 <li><a href="#TWiki::Access"> TWiki::Access </a></li>
27 <li><a href="#TWiki::_AggregateIterator"> TWiki::AggregateIterator </a></li>
28 <li><a href="#TWiki::Attach"> TWiki::Attach </a></li>
29 <li><a href="#TWiki::Attrs"> TWiki::Attrs </a></li>
30 <li><a href="#TWiki::Compatibility"> TWiki::Compatibility </a></li>
31 <li><a href="#TWiki::Configure::Load"> TWiki::Configure::Load </a></li>
32 <li><a href="#Purpose"> Purpose</a></li>
33 <li><a href="#"> </a></li>
34 <li><a href="#TWiki"> TWiki </a></li>
35 <li><a href="#Public Data members"> Public Data members</a></li>
36 <li><a href="#TWiki::Form"> TWiki::Form </a></li>
37 <li><a href="#TWiki::Form::_FieldDefinition"> TWiki::Form::FieldDefinition </a></li>
38 <li><a href="#TWiki::Form::_ListFieldDefinitio"> TWiki::Form::ListFieldDefinition </a></li>
39 <li><a href="#"> </a></li>
40 <li><a href="#TWiki::Func"> TWiki::Func </a></li>
41 <li><a href="#TWiki::_I18N"> TWiki::I18N </a></li>
42 <li><a href="#TWiki::_I18N::Extract"> TWiki::I18N::Extract </a></li>
43 <li><a href="#TWiki::If::Node"> TWiki::If::Node </a></li>
44 <li><a href="#TWiki::If::OP_isweb"> TWiki::If::OP_isweb </a></li>
45 <li><a href="#TWiki::If::Parser"> TWiki::If::Parser </a></li>
46 <li><a href="#TWiki::Infix::Error"> TWiki::Infix::Error </a></li>
47 <li><a href="#TWiki::Infix::Node"> TWiki::Infix::Node </a></li>
48 <li><a href="#TWiki::Infix::Parser"> TWiki::Infix::Parser </a></li>
49 <li><a href="#TWiki::_LineIterator"> TWiki::LineIterator </a></li>
50 <li><a href="#TWiki::_ListIterator"> TWiki::ListIterator </a></li>
51 <li><a href="#TWiki::_LoginManager::_ApacheLog"> TWiki::LoginManager::ApacheLogin </a></li>
52 <li><a href="#TWiki::_LoginManager"> TWiki::LoginManager </a></li>
53 <li><a href="#ObjectData =twiki="> ObjectData twiki</a></li>
54 <li><a href="#TWiki::_LoginManager::_TemplateL"> TWiki::LoginManager::TemplateLogin </a></li>
55 <li><a href="#TWiki::Merge"> TWiki::Merge </a></li>
56 <li><a href="#TWiki::Meta"> TWiki::Meta </a></li>
57 <li><a href="#TWiki::Net"> TWiki::Net </a></li>
58 <li><a href="#TWiki::Net::HTTPResponse"> TWiki::Net::HTTPResponse </a></li>
59 <li><a href="#TWiki::_OopsException"> TWiki::OopsException </a></li>
63 ## <> \[[CGISessionDotPm]\[]]
65 This package doesn't smell
67 ## <> \[[CGISessionDriverDBIDotPm]\[]]
69 This package doesn't smell
71 ## <> \[[CGISessionDriverDb\_fileDotPm]\[]]
73 This package doesn't smell
75 ## <> \[[CGISessionDriverDotPm]\[]]
77 This package doesn't smell
79 ## <> \[[CGISessionDriverFileDotPm]\[]]
81 This package doesn't smell
83 ## <> \[[CGISessionDriverMysqlDotPm]\[]]
85 This package doesn't smell
87 ## <> \[[CGISessionDriverPostgresqlDotPm]\[]]
89 This package doesn't smell
91 ## <> \[[CGISessionDriverSqliteDotPm]\[]]
93 This package doesn't smell
95 ## <> \[[CGISessionErrorHandlerDotPm]\[]]
97 This package doesn't smell
99 ## <> \[[CGISessionIDIncrDotPm]\[]]
101 This package doesn't smell
103 ## <> \[[CGISessionIDMd5DotPm]\[]]
105 This package doesn't smell
107 ## <> \[[CGISessionSerializeDefaultDotPm]\[]]
109 This package doesn't smell
111 ## <> \[[CGISessionSerializeFreezethawDotPm]\[]]
113 This package doesn't smell
115 ## <> \[[CGISessionSerializeJsonDotPm]\[]]
117 This package doesn't smell
119 ## <> \[[CGISessionSerializeStorableDotPm]\[]]
121 This package doesn't smell
123 ## <> \[[CGISessionSerializeYamlDotPm]\[]]
125 This package doesn't smell
127 ## <> \[[CGISessionTutorialDotPm]\[]]
129 This package doesn't smell
131 ## <> \[[MonitorDotPm]\[]]
133 This package doesn't smell
135 ## <a name="TWiki::_AccessControlException"></a> [[TWiki::AccessControlException|Main/TWikiAccessControlExceptionDotPm]]
137 Exception used raise an access control violation. This exception has the following fields:
139 - `web` - the web which was being accessed
140 - `topic` - the topic being accessed (if any)
141 - `user` - canonical username of the person doing the accessing. Use the methods of the TWiki::Users class to get more information about the user.
142 - `mode` - the access mode e.g. CHANGE, VIEW etc
143 - `reason` a text string giving the reason for the refusal.
145 The exception may be thrown by plugins. If a plugin throws the exception, it will normally be caught and the browser redirected to a login screen (if the user is not logged in) or reported (if they are and just don't have access).
147 This package doesn't smell
149 ## <a name="TWiki::Access"></a> [[TWiki::Access|Main/TWikiAccessDotPm]]
151 A singleton object of this class manages the access control database.
153 This package doesn't smell
155 ## <a name="TWiki::_AggregateIterator"></a> [[TWiki::AggregateIterator|Main/TWikiAggregateIteratorDotPm]]
157 combine multiple iterators
159 This package doesn't smell
161 ## <a name="TWiki::Attach"></a> [[TWiki::Attach|Main/TWikiAttachDotPm]]
163 A singleton object of this class is used to deal with attachments to topics.
165 This package doesn't smell
167 ## <a name="TWiki::Attrs"></a> [[TWiki::Attrs|Main/TWikiAttrsDotPm]]
169 Class of attribute sets, designed for parsing and storing attribute values from a TWiki tag e.g. `%TAG{"joe" fred="bad" joe="mad"}%`
171 An attribute set is a hash containing an entry for each parameter. The default parameter (unnamed quoted string) is named `_DEFAULT` in the hash.
173 Attributes declared later in the string will override those of the same name defined earlier. The one exception to this is the \_DEFAULT key, where the _first_ instance is always taken.
175 As well as the default TWiki syntax (parameter values double-quoted) this class also parses single-quoted values, unquoted spaceless values, spaces around the =, and commas as well as spaces separating values. The extended syntax has to be enabled by passing the `$friendly` parameter to `new`.
177 This package doesn't smell
179 ## <a name="TWiki::Compatibility"></a> [[TWiki::Compatibility|Main/TWikiCompatibilityDotPm]]
181 Support for compatibility with old TWiki versions. Packaged separately because 99.999999% of the time this won't be needed.
183 This package has smell factor of **2**
185 ## <a name="TWiki::Configure::Load"></a> [[TWiki::Configure::Load|Main/TWikiConfigureLoadDotPm]]
187 ## <a name="Purpose"></a> Purpose
189 This module consists of just a single subroutine `readConfig`. It allows to safely modify configuration variables _for one single run_ without affecting normal TWiki operation.
191 This package doesn't smell
193 ## <> \[[TWikiConfigureUIsEXTENDDotPm]\[]]
195 This package has smell factor of **2**
197 ## <a name="TWiki"></a> [[TWiki|Main/TWikiDotPm]]
199 TWiki operates by creating a singleton object (known as the Session object) that acts as a point of reference for all the different modules in the system. This package is the class for this singleton, and also contains the vast bulk of the basic constants and the per- site configuration mechanisms.
201 Global variables are avoided wherever possible to avoid problems with CGI accelerators such as mod\_perl.
203 ## <a name="Public Data members"></a> Public Data members
205 - `cgiQuery` Pointer to the CGI::
206 - `context` Hash of context ids
207 - moved: `loginManager` TWiki::LoginManager singleton (moved to TWiki::Users)
208 - `plugins` TWiki::Plugins singleton
209 - `prefs` TWiki::Prefs singleton
210 - `remoteUser` Login ID when using [[ApacheLogin]]. Maintained for compatibility only, do not use.
211 - `requestedWebName` Name of web found in URL path or `web` URL parameter
212 - `sandbox` TWiki::Sandbox singleton
213 - `scriptUrlPath` URL path to the current script. May be dynamically extracted from the URL path if \{GetScriptUrlFromCgi\}. Only required to support \{GetScriptUrlFromCgi\} and not consistently used. Avoid.
214 - `security` TWiki::Access singleton
215 - `SESSION_TAGS` Hash of TWiki variables whose value is specific to the current CGI request.
216 - `store` TWiki::Store singleton
217 - `topicName` Name of topic found in URL path or `topic` URL parameter
218 - `urlHost` Host part of the URL (including the protocol) determined during intialisation and defaulting to \{DefaultUrlHost\}
219 - `user` Unique user ID of logged-in user
220 - `users` TWiki::Users singleton
221 - `webName` Name of web found in URL path, or `web` URL parameter, or \{UsersWebName\}
223 This package has smell factor of **35**
225 ## <a name="TWiki::Form"></a> [[TWiki::Form|Main/TWikiFormDotPm]]
227 Object representing a single form definition.
229 Form definitions are mainly used to control rendering of a form for editing, though there is some application login there that handles transferring values between edits and saves.
231 A form definition consists of a TWiki::Form object, which has a list of field definitions. Each field definition is an object of a type derived from TWiki::Form::FieldDefinition. These objects are responsible for the actual syntax and semantics of the field type. Form definitions are parsed from TWiki tables, and the types are mapped by name to a class declared in TWiki::Form::\* - for example, the `text` type is mapped to `TWiki::Form::Text` and the `checkbox` type to `TWiki::Form::Checkbox`.
233 The `TWiki::Form::FieldDefinition` class declares default behaviours for types that accept a single value in their definitions. The `TWiki::Form::ListFieldDefinition` extends this for types that have lists of possible values.
235 This package has smell factor of **4**
237 ## <a name="TWiki::Form::_FieldDefinition"></a> [[TWiki::Form::FieldDefinition|Main/TWikiFormFieldDefinitionDotPm]]
239 Base class of all field definition classes.
241 Type-specific classes are derived from this class to define specific per-type behaviours. This class also provides default behaviours for when a specific type cannot be loaded.
243 This package doesn't smell
245 ## <a name="TWiki::Form::_ListFieldDefinitio"></a> [[TWiki::Form::ListFieldDefinition|Main/TWikiFormListFieldDefinitionDotPm]]
247 Form field definitions that accept lists of values in the field definition. This is different to being multi-valued, which means the field type can **store** multiple values.
249 This package has smell factor of **1**
251 ## <> \[[TWikiFormSelectDotPm]\[]]
253 This package doesn't smell
255 ## <a name="TWiki::Func"></a> [[TWiki::Func|Main/TWikiFuncDotPm]]
257 _Official list of stable TWiki functions for Plugin developers_
259 This module defines official functions that [[Plugins|SYSTEMWEB/TWikiPlugins]] can use to interact with the TWiki engine and content.
261 Refer to [[EmptyPlugin]] and lib/TWiki/Plugins/EmptyPlugin.pm for a template Plugin and documentation on how to write a Plugin.
263 Plugins should **only** use functions published in this module. If you use functions in other TWiki libraries you might create a security hole and you will probably need to change your Plugin when you upgrade TWiki.
265 Deprecated functions will still work in older code, though they should _not_ be called in new Plugins and should be replaced in older Plugins as soon as possible.
267 The version of the TWiki::Func module is defined by the VERSION number of the TWiki::Plugins module, currently 1.11. This can be shown by the `%PLUGINVERSION%` TWiki variable, and accessed in code using `$TWiki::Plugins::VERSION`. The 'Since' field in the function documentation refers to `$TWiki::Plugins::VERSION`.
269 Notes on use of `$TWiki::Plugins::VERSION` (from 1.2 forwards):
271 - If the **major** version (e.g. `1.`) is the same then any plugin coded to use any **earlier** revision of the `1.` API will still work. No function has been removed from the interface, nor has any API published in that version changed in such a way as to **require** plugins to be recoded.
272 - If the **minor** version (e.g. 1.1) is incremented there may be changes in the API that may help improve the coding of some plugins - for example, new interfaces giving access to previously hidden core functions. In addition, **deprecation** of functions in the interface trigger a minor version increment. Note that deprecated functions are not _removed_, they are merely frozen, and plugin authors are recommended to stop using them.
273 - Any additional digits in the version number relate to minor changes, such as the addition of parameters to the existing functions, or addition of utility functions that are unlikely to require significant changes to existing plugins.
274 - `TWiki::Plugins::VERSION` also applies to the plugin handlers. The handlers are documented in the EmptyPlugin, and that module indicates what version of `TWiki::Plugins::VERSION` it relates to.
276 A full history of the changes to this API can be found at the end of this topic.
278 This package has smell factor of **1**
280 ## <a name="TWiki::_I18N"></a> [[TWiki::I18N|Main/TWikiI18NDotPm]]
282 Support for strings translation and language detection.
284 This package has smell factor of **2**
286 ## <a name="TWiki::_I18N::Extract"></a> [[TWiki::I18N::Extract|Main/TWikiI18NExtractDotPm]]
288 Support translatable strings extraction from TWiki topics and templates. Depends on Locale::Maketext::Extract (part of CPAN::Locale::Maketext::Lexicon).
290 This package has smell factor of **1**
292 ## <a name="TWiki::If::Node"></a> [[TWiki::If::Node|Main/TWikiIfNodeDotPm]]
294 Node class for the result of an If statement parse
296 This package doesn't smell
298 ## <a name="TWiki::If::OP_isweb"></a> [[TWiki::If::OP_isweb|Main/TWikiIfOP_iswebDotPm]]
300 This package doesn't smell
302 ## <a name="TWiki::If::Parser"></a> [[TWiki::If::Parser|Main/TWikiIfParserDotPm]]
304 Support for the conditions in %IF\{\} statements.
306 This package doesn't smell
308 ## <a name="TWiki::Infix::Error"></a> [[TWiki::Infix::Error|Main/TWikiInfixErrorDotPm]]
310 Class of errors used with TWiki::Infix::Parser
312 This package doesn't smell
314 ## <a name="TWiki::Infix::Node"></a> [[TWiki::Infix::Node|Main/TWikiInfixNodeDotPm]]
316 Base class for node types generated by Infix::Parser. You don't **have** to use it, but it may be useful.
318 This package doesn't smell
320 ## <a name="TWiki::Infix::Parser"></a> [[TWiki::Infix::Parser|Main/TWikiInfixParserDotPm]]
322 A simple stack-based parser that parses infix expressions with nonary, unary and binary operators specified using an operator table.
324 Escapes are supported in strings, using backslash.
326 This package doesn't smell
328 ## <a name="TWiki::_LineIterator"></a> [[TWiki::LineIterator|Main/TWikiLineIteratorDotPm]]
330 Iterator over the lines in a file
332 This package doesn't smell
334 ## <a name="TWiki::_ListIterator"></a> [[TWiki::ListIterator|Main/TWikiListIteratorDotPm]]
338 This package doesn't smell
340 ## <a name="TWiki::_LoginManager::_ApacheLog"></a> [[TWiki::LoginManager::ApacheLogin|Main/TWikiLoginManagerApacheLoginDotPm]]
342 This is login manager that you can specify in the security setup section of [configure](http://www.dementia.org/twiki/configure). It instructs TWiki to cooperate with your web server (typically Apache) to require authentication information (username & password) from users. It requires that you configure your web server to demand authentication for scripts named "login" and anything ending in "auth". The latter should be symlinks to existing scripts; e.g., `viewauth -> view`, `editauth -> edit`, and so on.
344 See also [[TWikiUserAuthentication]].
346 Subclass of TWiki::LoginManager; see that class for documentation of the methods of this class.
348 This package has smell factor of **1**
350 ## <a name="TWiki::_LoginManager"></a> [[TWiki::LoginManager|Main/TWikiLoginManagerDotPm]]
352 The package is also a Factory for login managers and also the base class for all login managers.
354 On it's own, an object of this class is used when you specify 'none' in the security setup section of [configure](http://www.dementia.org/twiki/configure). When it is used, logins are not supported. If you want to authenticate users then you should consider [[TemplateLogin]] or [[ApacheLogin]], which are subclasses of this class.
356 If you are building a new login manager, then you should write a new subclass of this class, implementing the methods marked as **VIRTUAL**. There are already examples in the `lib/TWiki/LoginManager` directory.
358 The class has extensive tracing, which is enabled by $TWiki::cfg\{Trace\}\{LoginManager.pm\}. The tracing is done in such a way as to let the perl optimiser optimise out the trace function as a no-op if tracing is disabled.
360 Here's an overview of how it works:
362 Early in TWiki::new, the login manager is created. The creation of the login manager does two things:
364 1. If sessions are in use, it loads CGI::Session but doesn't initialise the session yet.
365 2. Creates the login manager object
367 Slightly later in TWiki::new, loginManager->loadSession is called.
369 1. Calls loginManager->getUser to get the username **before** the session is created
370 - TWiki::LoginManager::ApacheLogin looks at REMOTE\_USER (only for authenticated scripts)
371 - TWiki::LoginManager::TemplateLogin just returns undef
372 2. reads the TWIKISID cookie to get the SID (or the TWIKISID parameters in the CGI query if cookies aren't available, or [[IP2SID]] mapping if that's enabled).
373 3. Creates the CGI::Session object, and the session is thereby read.
374 4. If the username still isn't known, reads it from the cookie. Thus TWiki::LoginManager::ApacheLogin overrides the cookie using REMOTE\_USER, and TWiki::LoginManager::TemplateLogin **always** uses the session.
376 Later again in TWiki::new, plugins are given a chance to **override** the username found from the loginManager.
378 The last step in TWiki::new is to find the user, using whatever user mapping manager is in place.
380 ## <a name="ObjectData <code>twiki="></a> [[ObjectData]] =twiki
382 The TWiki object this login manager is attached to.
384 This package has smell factor of **7**
386 ## <a name="TWiki::_LoginManager::_TemplateL"></a> [[TWiki::LoginManager::TemplateLogin|Main/TWikiLoginManagerTemplateLoginDotPm]]
388 This is a login manager that you can specify in the security setup section of [configure](http://www.dementia.org/twiki/configure). It provides users with a template-based form to enter usernames and passwords, and works with the [[PasswordManager]] that you specify to verify those passwords.
390 Subclass of TWiki::LoginManager; see that class for documentation of the methods of this class.
392 This package has smell factor of **2**
394 ## <a name="TWiki::Merge"></a> [[TWiki::Merge|Main/TWikiMergeDotPm]]
396 Support for merging strings
398 This package has smell factor of **1**
400 ## <a name="TWiki::Meta"></a> [[TWiki::Meta|Main/TWikiMetaDotPm]]
402 All TWiki topics have **data** (text) and **meta-data** (information about the topic). Meta-data includes information such as file attachments, form fields, topic parentage etc. When TWiki loads a topic from the store, it represents the meta-data in the topic using an object of this class.
404 A meta-data object is a hash of different types of meta-data (keyed on the type, such as 'FIELD' and 'TOPICINFO').
406 Each entry in the hash is an array, where each entry in the array contains another hash of the key=value pairs, corresponding to a single meta-datum.
408 If there may be multiple entries of the same top-level type (i.e. for FIELD and FILEATTACHMENT) then the array has multiple entries. These types are referred to as "keyed" types. The array entries are keyed with the attribute 'name' which must be in each entry in the array.
410 For unkeyed types, the array has only one entry.
419 - [0] -> \{ name => '...' ... \}
420 - [1] -> \{ name => '...' ... \}
422 - [0] -> \{ name => '...' ... \}
423 - [1] -> \{ name => '...' ... \}
425 As well as the meta-data, the object also stores the web name, topic name and remaining text after meta-data extraction.
427 This package has smell factor of **2**
429 ## <a name="TWiki::Net"></a> [[TWiki::Net|Main/TWikiNetDotPm]]
431 Object that brokers access to network resources.
433 This package has smell factor of **3**
435 ## <a name="TWiki::Net::HTTPResponse"></a> [[TWiki::Net::HTTPResponse|Main/TWikiNetHTTPResponseDotPm]]
437 Fakeup of HTTP::Response for use when LWP is not available. Only implements a small subset of the HTTP::Response methods:
439 <table border="1" cellpadding="0" cellspacing="0">
441 <td><code>code()</code></td>
444 <td><code>message()</code></td>
447 <td><code>header($field)</code></td>
450 <td><code>content()</code></td>
453 <td><code>is_error()</code></td>
456 <td><code>is_redirect()</code></td>
460 See the documentation of HTTP::Response for information about the methods.
462 This package doesn't smell
464 ## <a name="TWiki::_OopsException"></a> [[TWiki::OopsException|Main/TWikiOopsExceptionDotPm]]
466 Exception used to raise a request to redirect to an Oops URL.
468 An [[OopsException]] thrown anywhere in the code will redirect the browser to a url based on the `oops` script. `oops` requires the name of an oops template file from the `templates` directory. This file will be expanded and the parameter values passed to the exception instantiated. The result will be shown in the browser.
470 Plugins may throw TWiki::OopsException. For example:
476 throw TWiki::OopsException( 'bathplugin',
480 params => [ 'bigtoe', 'hot tap' ] );
482 This package doesn't smell
484 ---++ [[TWikiPluginDotPm][]]
486 This package has smell factor of *2*
488 ---++ [[TWikiPluginsDotPm][TWiki::Plugins]]
490 This module defines the singleton object that handles Plugins
491 loading, initialization and execution.
493 This class uses Chain of Responsibility (GOF) pattern to dispatch
494 handler calls to registered plugins.
496 This package doesn't smell
498 ---++ [[TWikiPluralsDotPm][TWiki::Plurals]]
500 Handle conversion of plural topic names to singular form.
502 This package doesn't smell
504 ---++ [[TWikiPrefsDotPm][TWiki::Prefs]]
506 The Prefs class is a singleton that implements management of preferences.
507 It uses a stack of TWiki::Prefs::PrefsCache objects to store the
508 preferences for global, web, user and topic contexts, and provides
509 the means to look up preferences in these.
511 Preferences from different places stack on top of each other, so there
512 are global preferences, then site, then web (and subweb and subsubweb),
513 then topic, included topic and so on. Each level of the stack is tagged with
516 The module also maintains a separate of the preferences found in every topic
517 and web it reads. This supports the lookup of preferences for webs and topics
518 that are not on the stack, and must not be chained in (you can't allow
519 a user to override protections from their home topic!)
521 This package doesn't smell
523 ---++ [[TWikiPrefsParserDotPm][TWiki::Prefs::Parser]]
525 This Prefs-internal class is used to parse * Set and * Local statements
526 from arbitrary text, and extract settings from meta objects. It is used
527 by TopicPrefs to parse preference settings from topics.
529 This class does no validation or duplicate-checking on the settings; it
530 simply returns the recognized settings in the order it sees them in.
532 This package has smell factor of *1*
534 ---++ [[TWikiPrefsPrefsCacheDotPm][TWiki::Prefs::PrefsCache]]
536 The PrefsCache package holds a cache of topics that have been read in, using
537 the TopicPrefs class. These functions manage that cache.
539 We maintain 2 hashes of values:
540 * {locals} Contains all locals at this level. Locals are values that
541 only apply when the current topic is the topic where the local is
542 defined. The variable names are decorated with the locality where
544 * {values} contains all sets, locals, and all values inherited from
547 As each cache level is built, the values are copied down from the parent
548 cache level. This sounds monstrously inefficient, but in fact perl does
549 this a lot better than doing a multi-level lookup when a value is referenced.
550 This is especially important when many prefs lookups may be done in a
551 session, for example when searching.
553 This package doesn't smell
555 ---++ [[TWikiQueryHoistREsDotPm][TWiki::Query::HoistREs]]
557 Static functions to extract regular expressions from queries. The REs can
558 be used in caching stores that use the TWiki standard inline meta-data
559 representation to pre-filter topic lists for more efficient query matching.
561 See =Store/RcsFile.pm= for an example of usage.
563 This package doesn't smell
565 ---++ [[TWikiQueryNodeDotPm][TWiki::Query]]
567 A Query object is a representation of a query over the TWiki database.
569 Fields are given by name, and values by strings or numbers. Strings should always be surrounded by 'single-quotes'. Numbers can be signed integers or decimals. Single quotes in values may be escaped using backslash (\).
571 See TWiki.QuerySearch for details of the query language. At the time of writing
572 only a subset of the entire query language is supported, for use in searching.
574 A query object implements the =evaluate= method as its general
575 contract with the rest of the world. This method does a "hard work" evaluation
576 of the parser tree. Of course, smarter Store implementations should be
577 able to do it better....
579 This package has smell factor of *2*
581 ---++ [[TWikiQueryParserDotPm][TWiki::Query::Parser]]
585 This package doesn't smell
587 ---++ [[TWikiRenderDotPm][TWiki::Render]]
589 This module provides most of the actual HTML rendering code in TWiki.
591 This package has smell factor of *22*
593 ---++ [[TWikiSandboxDotPm][TWiki::Sandbox]]
595 This object provides an interface to the outside world. All calls to
596 system functions, or handling of file names, should be brokered by
599 NOTE: TWiki creates a singleton sandbox that is *shared* by all TWiki
600 runs under a single mod_perl instance. If any TWiki run modifies the
601 sandbox, that modification will carry over in to subsequent runs.
602 Be very, very careful!
604 This package has smell factor of *4*
606 ---++ [[TWikiSearchDotPm][TWiki::Search]]
608 This module implements all the search functionality.
610 This package has smell factor of *13*
612 ---++ [[TWikiStoreDotPm][TWiki::Store]]
614 This module hosts the generic storage backend. This module provides
615 the interface layer between the "real" store provider - which is hidden
616 behind a handler - and the rest of the system. it is responsible for
617 checking for topic existance, access permissions, and all the other
618 general admin tasks that are common to all store implementations.
620 This module knows nothing about how the data is actually _stored_ -
621 that knowledge is entirely encapsulated in the handlers.
623 The general contract for methods in the class requires that errors
624 are signalled using exceptions. TWiki::AccessControlException is
625 used for access control exceptions, and Error::Simple for all other
628 This package has smell factor of *14*
630 ---++ [[TWikiStoreQueryAlgorithmsBruteForceDotPm][TWiki::Store::QueryAlgorithms::BruteForce]]
632 Default brute-force query algorithm
634 Has some basic optimisation: it hoists regular expressions out of the
635 query to use with grep, so we can narrow down the set of topics that we
636 have to evaluate the query on.
638 Not sure exactly where the breakpoint is between the
639 costs of hoisting and the advantages of hoisting. Benchmarks suggest
640 that it's around 6 topics, though this may vary depending on disk
641 speed and memory size. It also depends on the complexity of the query.
643 This package doesn't smell
645 ---++ [[TWikiStoreRcsFileDotPm][TWiki::Store::RcsFile]]
647 This class is PACKAGE PRIVATE to Store, and should never be
648 used from anywhere else. It is the base class of implementations of stores
649 that manipulate RCS format files.
651 The general contract of the methods on this class and its subclasses
652 calls for errors to be signalled by Error::Simple exceptions.
654 Refer to Store.pm for models of usage.
656 This package has smell factor of *11*
658 ---++ [[TWikiStoreRcsLiteDotPm][TWiki::Store::RcsLite]]
660 This package does not publish any methods. It implements the virtual
661 methods of the [[TWikiStoreRcsFileDotPm][TWiki::Store::RcsFile]] superclass.
663 Simple replacement for RCS. Doesn't support:
666 Neither of which are used (or needed) by TWiki.
668 This module doesn't know anything about the content of the topic
670 There is one of these object for each file stored under RCSLite.
672 This object is PACKAGE PRIVATE to Store, and should NEVER be
673 used from anywhere else.
676 * need to tidy up dealing with \n for differences
677 * still have difficulty on line ending at end of sequences, consequence of doing a line based diff
682 rcstext ::= admin {delta}* desc {deltatext}*
683 admin ::= head {num};
686 symbols {sym : num}*;
687 locks {id : num}*; {strict ;}
688 { comment {string}; }
704 digit ::= 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
705 id ::= {num} idchar {idchar | num }*
706 sym ::= {digit}* idchar {idchar | digit }*
707 idchar ::= any visible graphic character except special
708 special ::= $ | , | . | : | ; | @
709 string ::= @{any character, with @ doubled}*@
710 newphrase ::= id word* ;
711 word ::= id | num | string | :
713 Identifiers are case sensitive. Keywords are in lower case only. The
714 sets of keywords and identifiers can overlap. In most environments RCS
715 uses the ISO 8859/1 encoding: visible graphic characters are codes
716 041-176 and 240-377, and white space characters are codes 010-015 and 040.
718 Dates, which appear after the date keyword, are of the form Y.mm.dd.hh.mm.ss,
719 where Y is the year, mm the month (01-12), dd the day (01-31), hh the hour
720 (00-23), mm the minute (00-59), and ss the second (00-60). Y contains just
721 the last two digits of the year for years from 1900 through 1999, and all
722 the digits of years thereafter. Dates use the Gregorian calendar; times
725 The newphrase productions in the grammar are reserved for future extensions
726 to the format of RCS files. No newphrase will begin with any keyword already
729 Revisions consist of a sequence of 'a' and 'd' edits that need to be
730 applied to rev N+1 to get rev N. Each edit has an offset (number of lines
731 from start) and length (number of lines). For 'a', the edit is followed by
732 length lines (the lines to be inserted in the text). For example:
734 d1 3 means "delete three lines starting with line 1
735 a4 2 means "insert two lines at line 4'
736 xxxxxx is the new line 4
737 yyyyyy is the new line 5
739 This package has smell factor of *2*
741 ---++ [[TWikiStoreRcsWrapDotPm][TWiki::Store::RcsWrap]]
743 This package does not publish any methods. It implements the
744 virtual methods of the [[TWikiStoreRcsFileDotPm][TWiki::Store::RcsFile]] superclass.
746 Wrapper around the RCS commands required by TWiki.
747 There is one of these object for each file stored under RCS.
749 This package has smell factor of *3*
751 ---++ [[TWikiStoreSearchAlgorithmsForkingDotPm][TWiki::Store::SearchAlgorithms::Forking]]
753 Forking implementation of the RCS cache search.
755 ---++ search($searchString, $topics, $options, $sDir) -> \%seen
756 Search .txt files in $dir for $searchString. See RcsFile::searchInWebContent
759 This package has smell factor of *3*
761 ---++ [[TWikiStoreSearchAlgorithmsPurePerlDotPm][TWiki::Store::SearchAlgorithms::PurePerl]]
763 Pure perl implementation of the RCS cache search.
765 ---++ search($searchString, $topics, $options, $sDir) -> \%seen
766 Search .txt files in $dir for $string. See RcsFile::searchInWebContent
769 This package doesn't smell
771 ---++ [[TWikiTemplatesDotPm][TWiki::Templates]]
773 Support for the TWiki template language.
775 This package has smell factor of *2*
777 ---++ [[TWikiTimeDotPm][TWiki::Time]]
779 Time handling functions.
781 This package has smell factor of *7*
783 ---++ [[TWikiUIChangeFormDotPm][TWiki::UI::ChangeForm]]
785 Service functions used by the UI packages
787 This package doesn't smell
789 ---++ [[TWikiUIDotPm][TWiki::UI]]
791 Service functions used by the UI packages
793 This package doesn't smell
795 ---++ [[TWikiUIEditDotPm][TWiki::UI::Edit]]
799 This package has smell factor of *1*
801 ---++ [[TWikiUIManageDotPm][TWiki::UI::Manage]]
803 UI functions for web, topic and user management
805 This package has smell factor of *4*
807 ---++ [[TWikiUIOopsDotPm][TWiki::UI::Oops]]
809 UI delegate for oops function
811 This package doesn't smell
813 ---++ [[TWikiUIRDiffDotPm][TWiki::UI::RDiff]]
815 UI functions for diffing.
817 This package has smell factor of *12*
819 ---++ [[TWikiUIRegisterDotPm][TWiki::UI::Register]]
821 User registration handling.
823 This package has smell factor of *8*
825 ---++ [[TWikiUISaveDotPm][TWiki::UI::Save]]
827 UI delegate for save function
829 This package has smell factor of *1*
831 ---++ [[TWikiUISearchDotPm][TWiki::UI::Search]]
833 UI functions for searching.
835 This package has smell factor of *2*
837 ---++ [[TWikiUIStatisticsDotPm][TWiki::UI::Statistics]]
839 Statistics extraction and presentation
841 This package has smell factor of *4*
843 ---++ [[TWikiUIUploadDotPm][TWiki::UI::Upload]]
845 UI delegate for attachment management functions
847 This package has smell factor of *3*
849 ---++ [[TWikiUIViewDotPm][TWiki::UI::View]]
851 UI delegate for view function
853 This package has smell factor of *2*
855 ---++ [[TWikiUserMappingDotPm][TWiki::UserMapping]]
857 This is a virtual base class (a.k.a an interface) for all user mappers. It is
858 *not* useable as a mapping in TWiki - use the BaseUserMapping for default
861 User mapping is the process by which TWiki maps from a username (a login name)
862 to a display name and back. It is also where groups are maintained.
864 See TWiki::Users::BaseUserMapping and TWiki::Users::TWikiUserMapping for
865 the default implementations of this interface.
867 If you want to write a user mapper, you will need to implement the methods
868 described in this class.
870 User mappings work by mapping both login names and display names to a
871 _canonical user id_. This user id is composed from a prefix that defines
872 the mapper in use (something like 'BaseUserMapping_' or 'LdapUserMapping_')
873 and a unique user id that the mapper uses to identify the user.
875 The null prefix is reserver for the TWikiUserMapping for compatibility
876 with old TWiki releases.
878 __Note:__ in all the following documentation, =$cUID= refers to a
881 This package has smell factor of *1*
883 ---++ [[TWikiUsersApacheHtpasswdUserDotPm][TWiki::Users::ApacheHtpasswdUser]]
885 Password manager that uses Apache::HtPasswd to manage users and passwords.
887 Subclass of [[TWikiUsersPasswordDotPm][ =TWiki::Users::Password= ]].
888 See documentation of that class for descriptions of the methods of this class.
890 Duplicates functionality of
891 [[TWikiUsersHtPasswdUserDotPm][ =TWiki::Users::HtPasswdUser=]];
892 provided mainly as an example of how to write a new password manager.
894 This package has smell factor of *1*
896 ---++ [[TWikiUsersBaseUserMappingDotPm][TWiki::Users::BaseUserMapping]]
898 User mapping is the process by which TWiki maps from a username (a login name)
899 to a display name and back. It is also where groups are maintained.
901 The BaseMapper provides support for a small number of predefined users.
902 No registration - this is a read only usermapper. It uses the mapper
903 prefix 'BaseUserMapping_'.
906 * TWikiAdmin - uses the password that was set in Configure (IF its not null)
909 * TWikiContributor - 1 Jan 2005
910 * TWikiRegistrationAgent - 1 Jan 2005
913 * $TWiki::cfg{SuperAdminGroup}
916 This package has smell factor of *2*
918 ---++ [[TWikiUsersDotPm][TWiki::Users]]
919 This package provides services for the lookup and manipulation of login and
920 wiki names of users, and their authentication.
922 It is a Facade that presents a common interface to the User Mapping
923 and Password modules. The rest of the core should *only* use the methods
924 of this package, and should *never* call the mapping or password managers
927 TWiki uses the concept of a _login name_ which is used to authenticate a
928 user. A login name maps to a _wiki name_ that is used to identify the user
929 for display. Each login name is unique to a single user, though several
930 login names may map to the same wiki name.
932 Using this module (and the associated plug-in user mapper) TWiki supports
933 the concept of _groups_. Groups are sets of login names that are treated
934 equally for the purposes of access control. Group names do not have to be
935 wiki names, though it is helpful for display if they are.
937 Internally in the code TWiki uses something referred to as a _canonical user
938 id_ or just _user id_. The user id is also used externally to uniquely identify
939 the user when (for example) recording topic histories. The user id is *usually*
940 just the login name, but it doesn't need to be. It just has to be a unique
941 7-bit alphanumeric and underscore string that can be mapped to/from login
942 and wiki names by the user mapper.
944 The canonical user id should *never* be seen by a user. On the other hand,
945 core code should never use anything *but* a canonical user id to refer
949 * A *login name* is the name used to log in to TWiki. Each login name is
950 assumed to be unique to a human. The Password module is responsible for
951 authenticating and manipulating login names.
952 * A *canonical user id* is an internal TWiki representation of a user. Each
953 canonical user id maps 1:1 to a login name.
954 * A *wikiname* is how a user is displayed. Many user ids may map to a
955 single wikiname. The user mapping module is responsible for mapping
956 the user id to a wikiname.
957 * A *group id* represents a group of users and other groups.
958 The user mapping module is responsible for mapping from a group id to
959 a list of canonical user ids for the users in that group.
960 * An *email* is an email address asscoiated with a *login name*. A single
961 login name may have many emails.
964 * wherever the code references $cUID, its a canonical_id
965 * wherever the code references $group, its a group_name
966 * $name may be a group or a cUID
968 This package has smell factor of *5*
970 ---++ [[TWikiUsersHtPasswdUserDotPm][TWiki::Users::HtPasswdUser]]
972 Support for htpasswd and htdigest format password files.
974 Subclass of [[TWikiUsersPasswordDotPm][ =TWiki::Users::Password= ]].
975 See documentation of that class for descriptions of the methods of this class.
977 This package has smell factor of *3*
979 ---++ [[TWikiUsersPasswordDotPm][TWiki::Users::Password]]
981 Base class of all password handlers. Default behaviour is no passwords,
982 so anyone can be anyone they like.
984 The methods of this class should be overridded by subclasses that want
985 to implement other password handling methods.
987 This package doesn't smell
989 There were a total of *199* smells