Provided by: libwiki-toolkit-perl_0.85-1_all bug

NAME

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

SYNOPSIS

       This is probably only useful for Wiki::Toolkit developers.

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

METHODS

       new
             my $store = Wiki::Toolkit::Store::MySQL->new( dbname  => "wiki",
                                   dbuser  => "wiki",
                                   dbpass  => "wiki",
                                   dbhost  => "db.example.com",
                                   dbport  => 1234,
                                   charset => "iso-8859-1" );
           or

             my $store = Wiki::Toolkit::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.

           If you do not provide an active database handle in "dbh", then "dbname" is mandatory.
           "dbpass", "dbuser", "dbhost" and "dbport" are optional, but you'll want to supply them
           unless your database's connection method doesn't require them.

           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:

           •   "RaiseError" = 1

           •   "PrintError" = 0

           •   "AutoCommit" = 1

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

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

       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" );

       list_dangling_links
             # 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.

       write_node_post_locking
             $store->write_node_post_locking( node     => $node,
                                              content  => $content,
                                              links_to => \@links_to,
                                              metadata => \%metadata,
                                              requires_moderation => $requires_moderation,
                                              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".

           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 the version number of
           the update just made.  A return value of -1 indicates that the change was not applied.
           This may be because the plugins voted against the change, or because the content and
           metadata in the proposed new version were identical to the current version (a "null"
           change).

           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, as is requires_moderation.

           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.

       rename_node
             $store->rename_node(
                                    old_name  => $node,
                                    new_name  => $new_node,
                                    wiki      => $wiki,
                                    create_new_versions => $create_new_versions,
                                  );

           Renames a node, updating any references to it as required (assuming your chosen
           formatter supports rename, that is).

           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.

       moderate_node
             $store->moderate_node(
                                    name    => $node,
                                    version => $version
                                  );

           Marks the given version of the node as moderated. If this is the highest moderated
           version, then update the node's contents to hold this version.

       set_node_moderation
             $store->set_node_moderation(
                                    name     => $node,
                                    required => $required
                                  );

           Sets if new node versions will require moderation or not

       delete_node
             $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.

           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.

       list_recent_changes
             # Nodes changed in last 7 days - each node listed only once.
             my @nodes = $store->list_recent_changes( days => 7 );

             # Nodes added in the last 7 days.
             my @nodes = $store->list_recent_changes(
                                                      days     => 7,
                                                      new_only => 1,
                                                    );

             # 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 => 10,
                 metadata_wasnt  => { edit_type => "Minor tidying" }
             );

           You must supply one of the following constraints: "days" (integer), "since" (epoch),
           "last_n_changes" (integer).

           You may also supply moderation => 1 if you only want to see versions that are
           moderated.

           Another optional parameter is "new_only", which if set to 1 will only return newly
           added nodes.

           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" 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.  Don't mix "is" with "was" - there's no check for this, but the
           results are undefined.

           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 version number of the node

           •   last_modified: timestamp showing when this version was written

           •   metadata: a ref to a hash containing any metadata attached to this 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.

           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.

       list_all_nodes
             my @nodes = $store->list_all_nodes();
             print "First node is $nodes[0]\n";

             my @nodes = $store->list_all_nodes( with_details=> 1 );
             print "First node is ".$nodes[0]->{'name'}." at version ".$nodes[0]->{'version'}."\n";

           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.

           Optionally also returns the id, version and moderation flag.

       list_node_all_versions
             my @all_versions = $store->list_node_all_versions(
                 name => 'HomePage',
                 with_content => 1,
                 with_metadata => 0
             );

           Returns all the versions of a node, optionally including the content and metadata, as
           an array of hashes (newest versions first).

       list_nodes_by_metadata
             # 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.

           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.

       list_nodes_by_missing_metadata Returns nodes where either the metadata doesn't exist, or
       is blank
           Unlike list_nodes_by_metadata(), the metadata value is optional.

             # All nodes missing documentation
             my @nodes = $store->list_nodes_by_missing_metadata(
                 metadata_type  => "category",
                 metadata_value => "documentation",
                 ignore_case    => 1,   # optional but recommended (see below)
             );

             # All nodes which don't have a latitude defined
             my @nodes = $store->list_nodes_by_missing_metadata(
                 metadata_type  => "latitude"
             );

       _get_list_by_metadata_sql
           Return the SQL to do a match by metadata. Should expect the metadata type as the first
           SQL parameter, and the metadata value as the second.

           If possible, should take account of $args{ignore_case}

       _get_list_by_missing_metadata_sql
           Return the SQL to do a match by missing metadata. Should expect the metadata type as
           the first SQL parameter.

           If possible, should take account of $args{ignore_case}

       list_unmoderated_nodes
             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

             With only_where_latest set, return the id, name and version of all the
              nodes where the most recent version needs moderation.
             Otherwise, returns the id, name and version of all node versions that need
              to be moderated.

       list_last_version_before
               List the last version of every node before a given date.
               If no version existed before that date, will return undef for version.
               Returns a hash of id, name, version and date

               my @nv = $wiki->list_last_version_before('2007-01-02 10:34:11')
               foreach my $data (@nv) {

               }

       list_metadata_by_type
               List all the currently defined values of the given type of metadata.

               Will only return data from the latest moderated version of each node

               # List all of the different metadata values with the type 'category'
               my @categories = $wiki->list_metadata_by_type('category');

       list_metadata_names
               List all the currently defined kinds of metadata, eg Locale, Postcode

               Will only return data from the latest moderated version of each node

               # List all of the different kinds of metadata
               my @metadata_types = $wiki->list_metadata_names()

       schema_current
             my ($code_version, $db_version) = $store->schema_current;
             if ($code_version == $db_version)
                 # Do stuff
             } else {
                 # Bail
             }

       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.

       dbhost
             my $dbhost = $store->dbhost;

           Returns the optional host used to connect to the database used for backend storage.