NAME

CGI::Wiki::Store::Database - parent class for database storage backends for CGI::Wiki

SYNOPSIS

Can't see yet why you'd want to use the backends directly, but:

# See below for parameter details.
my $store = CGI::Wiki::Store::MySQL->new( %config );

METHODS

new

  my $store = CGI::Wiki::Store::MySQL->new( dbname => "wiki",
					    dbuser => "wiki",
					    dbpass => "wiki" );

dbname is mandatory. dbpass and dbuser are optional, but you'll want to supply them unless your database's authentication method doesn't require it.

retrieve_node

  my $content = $store->retrieve_node($node);

  # Or get additional meta-data too.
  my %node = $store->retrieve_node("HomePage");
  print "Current Version: " . $node{version};

  # Maybe we stored some metadata too.
  my $categories = $node{metadata}{category};
  print "Categories: " . join(", ", @$categories);
  print "Postcode: $node{metadata}{postcode}[0]";

  # Or get an earlier version:
  my %node = $store->retrieve_node(name    => "HomePage",
			             version => 2 );
  print $node{content};

In scalar context, returns the current (raw Wiki language) contents of the specified node. In list context, returns a hash containing the contents of the node plus additional data:

last_modified

version

checksum

metadata - a reference to a hash containing any caller-supplied metadata sent along the last time the node was written

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 an array ref, even if that type of metadata only has one value.

retrieve_node_and_checksum

my ($content, $cksum) = $store->retrieve_node_and_checksum($node);

Works just like retrieve_node would in scalar context, but also gives you a checksum that you must send back when you want to commit changes, so you can check that no other changes have been committed while you were editing.

NOTE: This is a convenience method supplied for backwards compatibility with 0.03, and will probably disappear at some point. Use retrieve_node in list context, instead.

node_exists

if ( $store->node_exists( "Wombat Defenestration" ) {
    # do something about the weird people infesting your wiki
} else {
    # ah, safe, no weirdos here
}

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

verify_checksum

my $ok = $store->verify_checksum($node, $checksum);

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.

list_backlinks

# List all nodes that link to the Home Page.
my @links = $store->list_backlinks( node => "Home Page" );

write_node_after_locking

Deprecated, use write_node_post_locking instead. This is still here for now as a wrapper but it will go away soon.

write_node_post_locking

$store->write_node_post_locking( node     => $node,
                                 content  => $content,
                                 links_to => \@links_to,
                                 metadata => \%metadata  )
    or handle_error();

Writes the specified content into the specified node. Making sure that locking/unlocking/transactions happen is left up to you (or your chosen subclass). This method shouldn't really be used directly as it might overwrite someone else's changes. Croaks on error but otherwise returns true.

Supplying a ref to an array of nodes that this ones links to is optional, but if you do supply it then this node will be returned when calling list_backlinks on the nodes in @links_to. Note that if you don't supply the ref then the store will assume that this node doesn't link to any others, and update itself accordingly.

The metadata hashref is also optional, but if it is supplied then each of its keys must be either a scalar or a reference to an array of scalars.

delete_node

$store->delete_node($node);

Deletes the node (whether it exists or not), croaks on error. Again, doesn't do any kind of locking. You probably don't want to let anyone except Wiki admins call this. Removes all the node's history as well.

list_recent_changes

# Changes in last 7 days.
my @nodes = $store->list_recent_changes( days => 7 );

# Changes since a given time.
my @nodes = $store->list_recent_changes( since => 1036235131 );

# Most recent change and its details.
my @nodes = $store->list_recent_changes( last_n_changes => 1 );
print "Node:          $nodes[0]{name}";
print "Last modified: $nodes[0]{last_modified}";
print "Comment:       $nodes[0]{metadata}{comment}";

Returns results as an array, in reverse chronological order. Each element of the array is a reference to a hash with the following entries:

• name: the name of the node

• version: the latest version number

• last_modified: the timestamp of when it was last modified

• metadata: a ref to a hash containing any metadata attached to the current version of the node

Each node will only be returned once, regardless of how many times it has been changed recently.

Note: interface change between CGI::Wiki 0.23 and 0.24 - this method used to pretend to return a comment, which was always the blank string. It now returns the metadata hashref, so you can put your comments in that.

list_all_nodes

my @nodes = $store->list_all_nodes();

Returns a list containing the name of every existing node. The list won't be in any kind of order; do any sorting in your calling script.

list_nodes_by_metadata

# All nodes that Kake's watching.
my @nodes = $store->list_nodes_by_metadata(
    metadata_type  => "watched_by",
    metadata_value => "Kake"              );

# All pubs in Hammersmith.
my @pubs = $store->list_nodes_by_metadata(
    metadata_type  => "category",
    metadata_value => "Pub"              );
my @hsm  = $store->list_nodes_by_metadata(
    metadata_type  => "category",
    metadata_value  => "Hammersmith"     );
my @results = my_l33t_method_for_ANDing_arrays( \@pubs, \@hsm );

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

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, when I get around to adding support for that.

dbh

my $dbh = $store->dbh;

Returns the database handle belonging to this storage backend instance.

dbname

my $dbname = $store->dbname;

Returns the name of the database used for backend storage.

dbuser

my $dbuser = $store->dbuser;

Returns the username used to connect to the database used for backend storage.

dbpass

my $dbpass = $store->dbpass;

Returns the password used to connect to the database used for backend storage.