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};

  # 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 metadata: last_modified, version, checksum.

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).

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

  $store->write_node_after_locking($node, $content, \@links_to)
      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.

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]{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

• last_modified: the timestamp of when it was last modified

• comment: the comment (if any) that was attached to the node last time it was modified

Note that adding comments isn't implemented properly yet, so those will always be the blank string at the moment.

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.

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.

dbh

  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.