CGI::Wiki::Store::Database - parent class for database storage backends for CGI::Wiki
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 );
my $store = CGI::Wiki::Store::MySQL->new( dbname => "wiki", dbuser => "wiki", dbpass => "wiki", dbhost => "db.example.com", charset => "iso-8859-1" ); or my $store = CGI::Wiki::Store::MySQL->new( dbh => $dbh );
charset is optional, defaults to iso-8859-1, and does nothing unless you're using perl 5.8 or newer.
charset
iso-8859-1
If you do not provide an active database handle in dbh, then dbname is mandatory. dbpass, dbuser and dbhost are optional, but you'll want to supply them unless your database's authentication method doesn't require it.
dbh
dbname
dbpass
dbuser
dbhost
If you do provide database then it must have the following parameters set; otherwise you should just provide the connection information and let us create our own handle:
database
RaiseError = 1
RaiseError
PrintError = 0
PrintError
AutoCommit = 1
AutoCommit
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:
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.
my $ok = $store->node_exists( "Wombat Defenestration" ); # or ignore case - optional but recommended my $ok = $store->node_exists( name => "monkey brains", ignore_case => 1, );
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 database. If you supply a true value to the ignore_case parameter, then you can be sure of its being case-insensitive. This is recommended.
node_exists
ignore_case
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.
write_node
# List all nodes that link to the Home Page. my @links = $store->list_backlinks( node => "Home Page" );
# List all nodes that have been linked to from other nodes but don't # yet exist. my @links = $store->list_dangling_links;
Each node is returned once only, regardless of how many other nodes link to it.
$store->write_node_post_locking( node => $node, content => $content, links_to => \@links_to, metadata => \%metadata, plugins => \@plugins ) or handle_error();
Writes the specified content into the specified node, then calls post_write on all supplied plugins, with arguments node, version, content, metadata.
post_write
node
version
content
metadata
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.
list_backlinks
@links_to
The metadata hashref is also optional.
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:
$wiki->write_node( "Calthorpe Arms", "nice pub", $checksum, { category => [ "Pubs", "Bloomsbury" ], postcode => "WC1X 8JR" } ); # and later my @nodes = $wiki->list_nodes_by_metadata( metadata_type => "category", metadata_value => "Pubs" );
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 (as __metadatatypename__checksum). Such data can only be accessed via plugins.
__metadatatypename__checksum
$store->delete_node( name => $node, version => $version, wiki => $wiki );
version is optional. If it is supplied then only that version of the node will be deleted. Otherwise the node and all its history will be completely deleted.
wiki is also optional, but if you care about updating the backlinks you want to include it.
wiki
Again, doesn't do any locking. You probably don't want to let anyone except Wiki admins call this. You may not want to use it at all.
Croaks on error, silently does nothing if the node or version doesn't exist, returns true if no error.
# Nodes changed in last 7 days - each node listed only once. my @nodes = $store->list_recent_changes( days => 7 ); # All changes in last 7 days - nodes changed more than once will # be listed more than once. my @nodes = $store->list_recent_changes( days => 7, include_all_changes => 1, ); # Nodes changed between 1 and 7 days ago. my @nodes = $store->list_recent_changes( between_days => [ 1, 7 ] ); # Nodes changed 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}"; # Last 5 restaurant nodes edited. my @nodes = $store->list_recent_changes( last_n_changes => 5, metadata_is => { category => "Restaurants" } ); # Last 5 nodes edited by Kake. my @nodes = $store->list_recent_changes( last_n_changes => 5, metadata_was => { username => "Kake" } ); # All minor edits made by Earle in the last week. my @nodes = $store->list_recent_changes( days => 7, metadata_was => { username => "Earle", edit_type => "Minor tidying." } ); # Last 10 changes that weren't minor edits. my @nodes = $store->list_recent_changes( last_n_changes => 5, metadata_wasnt => { edit_type => "Minor tidying" } );
You must supply one of the following constraints: days (integer), since (epoch), last_n_changes (integer).
days
since
last_n_changes
You may also supply either metadata_is (and optionally metadata_isnt), or metadata_was (and optionally metadata_wasnt). Each of these should be a ref to a hash with scalar keys and values. If the hash has more than one entry, then only changes satisfying all criteria will be returned when using metadata_is or metadata_was, but all changes which fail to satisfy any one of the criteria will be returned when using metadata_isnt or metadata_is.
metadata_is
metadata_isnt
metadata_was
metadata_wasnt
metadata_is and metadata_isnt look only at the metadata that the node currently has. metadata_was and metadata_wasnt take into account the metadata of previous versions of a node.
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
Unless you supply include_all_changes, metadata_was or metadata_wasnt, each node will only be returned once regardless of how many times it has been changed recently.
include_all_changes
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.
metadata_type
metadata_value
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.
# All documentation nodes. my @nodes = $store->list_nodes_by_metadata( metadata_type => "category", metadata_value => "documentation", ignore_case => 1, # optional but recommended (see below) ); # 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.
my $dbh = $store->dbh;
Returns the database handle belonging to this storage backend instance.
my $dbname = $store->dbname;
Returns the name of the database used for backend storage.
my $dbuser = $store->dbuser;
Returns the username used to connect to the database used for backend storage.
my $dbpass = $store->dbpass;
Returns the password used to connect to the database used for backend storage.
my $dbhost = $store->dbhost;
Returns the optional host used to connect to the database used for backend storage.
2 POD Errors
The following errors were encountered while parsing the POD:
=over without closing =back
To install CGI::Wiki, copy and paste the appropriate command in to your terminal.
cpanm
cpanm CGI::Wiki
CPAN shell
perl -MCPAN -e shell install CGI::Wiki
For more information on module installation, please visit the detailed CPAN module installation guide.