store must be an object of type Wiki::Toolkit::Store::* and search if supplied must be of type Wiki::Toolkit::Search::* (though this isn't checked yet - FIXME). If formatter isn't supplied, it defaults to an object of class Wiki::Toolkit::Formatter::Default.

formatter can be any object that behaves in the right way; this essentially means that it needs to provide a format method which takes in raw text and returns the formatted version. See Wiki::Toolkit::Formatter::Default for a simple example. Note that you can create a suitable object from a sub very quickly by using Test::MockObject like so:

The node parameter is mandatory. The version parameter is optional and defaults to the newest version. If the node hasn't been created yet, it is considered to exist but be empty (this behaviour might change).

Note on metadata - each hash value is returned as an array ref, even if that type of metadata only has one value.

Uses the internal_links table to identify the nodes that link to this one, and re-writes any wiki links in these to point to the new name. If required, it can mark these updates to other pages as a new version.

Sees whether your checksum is current for the given node. Returns true if so, false if not.

NOTE: Be aware that when called directly and without locking, this might not be accurate, since there is a small window between the checking and the returning where the node might be changed, so don't rely on it for safe commits; use write_node for that. It can however be useful when previewing edits, for example.

Returns a list containing the name of every node whose caller-supplied metadata matches the criteria given in the parameters.

By default, the case-sensitivity of both metadata_type and metadata_value depends on your database - if it will return rows with an attribute value of "Pubs" when you asked for "pubs", or not. If you supply a true value to the ignore_case parameter, then you can be sure of its being case-insensitive. This is recommended.

If you don't supply any criteria then you'll get an empty list.

This is a really really really simple way of finding things; if you want to be more complicated then you'll need to call the method multiple times and combine the results yourself, or write a plugin.

my @nodes = $wiki->list_unmoderated_nodes();
my @nodes = $wiki->list_unmoderated_nodes(
only_where_latest => 1
);
$nodes[0]->{'name'} # The name of the node
$nodes[0]->{'node_id'} # The id of the node
$nodes[0]->{'version'} # The version in need of moderation
$nodes[0]->{'moderated_version'} # The newest moderated version
Fetches details of all the node versions that require moderation (id,
name, version, and latest moderated version).
If only_where_latest is set, then only the latest version of nodes where
the latest version needs moderating are returned.
Otherwise, all node versions (including old ones, and possibly multiple
per node) are returned.

Returns true if the node has ever been created (even if it is currently empty), and false otherwise.

By default, the case-sensitivity of node_exists depends on your store backend. If you supply a true value to the ignore_case parameter, then you can be sure of its being case-insensitive. This is recommended.

Returns a (possibly empty) hash whose keys are the node names and whose values are the scores in some kind of relevance-scoring system I haven't entirely come up with yet. For OR searches, this could initially be the number of terms that appear in the node, perhaps.

Defaults to AND searches (if $and_or is not supplied, or is anything other than OR or or).

Registers the plugin with the wiki as one that needs to be informed when we write a node.

If the plugin isaWiki::Toolkit::Plugin, calls the methods set up by that parent class to let it know about the backend store, search and formatter objects.

Finally, calls the plugin class's on_register method, which should be used to check tables are set up etc. Note that because of the order these things are done in, on_register for Wiki::Toolkit::Plugin subclasses can use the datastore, indexer and formatter methods as it needs to.

Writes the specified content into the specified node in the backend storage; and indexes/reindexes the node in the search indexes (if a search is set up); calls post_write on any registered plugins.

Note that you can blank out a node without deleting it by passing the empty string as $content, if you want to.

If you expect the node to already exist, you must supply a checksum, and the node is write-locked until either your checksum has been proved old, or your checksum has been accepted and your change committed. If no checksum is supplied, and the node is found to already exist and be nonempty, a conflict will be raised.

The first two parameters are mandatory, the others optional. If you want to supply metadata but have no checksum (for a newly-created node), supply a checksum of undef.

The final parameter, $requires_moderation (which defaults to false), is ignored except on new nodes. For existing nodes, use $wiki->toggle_node_moderation to change the node moderation flag.

Returns the version of the updated node on success, 0 on conflict, croaks on error.

Note on the metadata hashref: Any data in here that you wish to access directly later must be a key-value pair in which the value is either a scalar or a reference to an array of scalars. For example:

For more advanced usage (passing data through to registered plugins) you may if you wish pass key-value pairs in which the value is a hashref or an array of hashrefs. The data in the hashrefs will not be stored as metadata; it will be checksummed and the checksum will be stored instead. Such data can only be accessed via plugins.

Passed straight through to your chosen formatter object. You do not have to supply the $metadata hashref, but if your formatter allows node metadata to affect the rendering of the node then you will want to.

Versions between 0.75 and 0.79 inclusive contain a bug which prevents Recent Changes routines from working correctly if minor changes are excluded <http://www.wiki-toolkit.org/ticket/41>. You may wish to avoid upgrading to this version until it is fixed if this is important to you; the fix is however not trivial so noone has been able to step up yet.

blair christensen sent patches and gave me some good ideas. chromatic continues to patiently apply my patches to Text::WikiFormat and help me get it working in just the way I need. Paul Makepeace helped me add support for connecting to non-local databases. Shevek has been prodding me a lot lately. The OpenGuides team keep me well-supplied with encouragement and bug reports.

Nick Burch has been leading the way with development leading up to the release under the Wiki::Toolkit name.