Chirpy::DataManager - Chirpy! 0.3 API Documentation

Chirpy! 0.3 API Documentation

<<
Chirpy::DataManager

NAME

Chirpy::DataManager - Abstract data manager class

IMPLEMENTATION

This section should tell you just about everything you need to know if you want to write your own Chirpy! data manager.

First of all, it must be a class that extends this abstract class, and it must have something along the lines of

  use vars qw($VERSION @ISA);
  $VERSION = '';
  @ISA = qw(Chirpy::DataManager);

All you need to do then, really, is implement this class's abstract methods. Unfortunately, there are quite a few of them. However, a lot of them are fairly trivial, as you will quickly learn. All of them are object methods.

Compatibility

get_target_version(): The return value of this function is compared to Chirpy!'s version. If the version numbers do not match, execution will be aborted. Hence, it needs to be exactly the same as the version of Chirpy! the data manager was built for.

Parameters

get_parameter($name): Gets the value of a persistent parameter.
set_parameter($name, $value): Sets the value of a persistent parameter.

Installation & Removal

set_up($accounts, $news, $quotes)

Called at installation time, this method should create all necessary resources to use the data manager. For instance, if the module uses a database, this method should create the necessary tables in it.

In addition, the method takes 3 arguments, each either an array reference or undef. They represent the initial data to be stored in the installation. $accounts holds instances of Chirpy::Account, $news instances of Chirpy::NewsItem and $quotes instances of Chirpy::Quote.

remove()

The exact opposite of the set_up() method. Removes all applicable data.

Quotes

get_quotes($options)

Accepts $options, a reference to a hash containing parameters defining the output, or undef.

In a scalar context, returns a reference to an array of matching quotes (as instances of Chirpy::Quote), or undef if there are no matches. Otherwise, returns that array, along with 2 boolean values. The first is true if there are quotes before the start of the results, the second is true if there are quotes after the end of the results.

The option hash may contain any of the keys below. If multiple keys are present, the properties they imply must all apply to the resulting quotes.

id

ID of the quote to retrieve.

contains

Reference to an array of strings to find in either the quote body or notes. May contain wildcard characters: an asterisk (*) may represent any character sequence, including an empty one; a question mark (?) represents a single character. To search for the wildcard characters themselves, they may be prefixed with a backslash (\). Consequently, backslashes themselves must also be prefixed with a backslash.

tags

Reference to an array of tags, any of which must be a tag of the quote.

approved

Boolean value indicating the approved status of the quote. Note that a false value implies that the quotes must not be approved, while undef cannot affect the results.

flagged

Boolean value indicating the flagged status of the quote. Note that a false value implies that the quotes must not be flagged, while undef cannot affect the results.

since

UNIX timestamp representing the earliest date allowed for the date when quotes were submitted.

sort

Properties of the quote to sort on, represented as a two-dimensional array reference. Here is an example:

 [ [ 'score', 0 ], [ 'id', 1 ] ]

The boolean value is true if the results should be in descending order. Hence, the sorting instruction above means the data manager should sort by score first, in ascending order. If the ratings are equal, then it should sort by ID, in descending order.

The possible properties to sort on are id, rating, approved, score, and flagged. It is assumed that sorting on the date when the quote was submitted has the same effect as sorting on quote ID.

Sorting on score was introduced in Chirpy! 0.3 and is used to determine the top and bottom quotes. Quotes' scores are calculated as follows:

                                   votes + rating
                                  ---------------- + 1
           positive votes + 1             2
  score = -------------------- = ----------------------
           negative votes + 1      votes - rating
                                  ---------------- + 1
                                          2

Data managers may prefer to cache this value for performance purposes.

random

Boolean value indicating if results should be randomly selected. Overrides the "sort" option.

first

The number of the first result to return, 0 being the first in the result list.

count

The number of quotes to maximally return.

quote_count($options)

Returns the number of quotes in the database, either approved, unapproved, or both. Optionally accepts $options, a reference to a hash of parameters defining which quotes are to be counted. Currently, $options may contain only one parameter, namely approved. If approved is undefined, all quotes are included in the count; if it is a true value, only approved quotes are included, and vice versa.

add_quote($quote)

Adds the Chirpy::Quote $quote to the collection. Assigns an ID to the quote and updates the object with it. Returns a true value upon success.

The properties to be saved by this method are body, notes, approved and tags.

modify_quote($quote)

Updates the Chirpy::Quote $quote in the collection. Returns a true value on success.

The properties to be saved by this method are body and notes.

remove_quote($quote)

Removes the Chirpy::Quote $quote from the collection. Returns a true value on success.

remove_quotes(@ids)

Removes all quotes whose ID is in @ids from the collection. Returns the number of removed quotes.

increase_quote_rating($id, $revert)

Increases the rating of quote number $id. If $revert is a true value, increases the rating by 2, as the user is reverting his vote; otherwise, increases it by 1. If the user is not reverting his vote, increases the number of votes for the quote by 1 as well. Returns a list containing the updated rating and vote count.

decrease_quote_rating($id, $revert)

Decreases the rating of quote number $id. If $revert is a true value, decreases the rating by 2, as the user is reverting his vote; otherwise, decreases it by 1. If the user is not reverting his vote, increases the number of votes for the quote by 1 as well. Returns a list containing the updated rating and vote count.

get_tag_use_counts()

Returns a reference to a hash, mapping tags to the number of times they were used. Only tags for approved quotes should be counted.

approve_quotes(@ids)

Sets the quotes associated with an ID in @ids to approved. Returns the number of affected quotes.

unflag_quotes(@ids)

Sets the quotes associated with an ID in @ids to unflagged. Returns the number of affected quotes.

News Items

get_news_items($options)

Retrieves news items, a lot like get_quotes() retrieves quotes. The possible options are now:

id: ID of the news item to retrieve.
count: Maximum number of news items returned.

Resulting news items are always sorted by date, newest first.

The function returns a reference to an array of instances of Chirpy::NewsItem, or undef if no matching news items were found.

add_news_item($news_item)

Adds the Chirpy::NewsItem $news_item to the collection. Assigns an ID to the news item and updates the object with it. Returns a true value upon success.

The properties to be saved by this method are body and poster. poster may be undef if the poster is unknown.

modify_news_item($news_item)

Updates the Chirpy::NewsItem $news_item in the collection. Returns a true value on success.

The properties to be saved by this method are body and poster. poster may be undef if the poster is unknown.

remove_news_item($news_item)

Removes the Chirpy::NewsItem $news_item from the collection. Returns a true value on success.

remove_news_items(@ids)

Removes all news items whose ID is in @ids from the collection. Returns the number of removed news items.

User Accounts

get_accounts($options)

Retrieves accounts, a lot like get_quotes() retrieves quotes and get_news_items() retrieves news items. The possible options are now:

id: ID of the account to retrieve.
username: User name of the account to retrieve.
levels: Reference to an array containing allowed user levels.

Resulting accounts are always sorted by user level, highest first, then by user name.

The function returns a reference to an array of instances of Chirpy::Account, or undef if no matching accounts were found.

add_account($account)

Adds the Chirpy::Account $account to the collection. Assigns an ID to the account and updates the object with it. Returns a true value upon success.

The properties to be saved by this method are username, password and level.

modify_account($account)

Updates the Chirpy::Account $account in the collection. Returns a true value on success.

The properties to be saved by this method are username, password and level.

remove_account($account)

Removes the Chirpy::Account $account from the collection. Returns a true value on success.

Note that upon removal of an account, news items associated with it must be kept, but their author becomes unknown.

remove_accounts(@ids)

Removes all accounts whose ID is in @ids from the collection. Returns the number of removed accounts.

Note that upon removal of an account, news items associated with it must be kept, but their author becomes unknown.

username_exists($username)

Returns a true value if the given username exists in the collection.

account_count($params)

Returns the current number of accounts. Takes an optional hash reference to retrieval options. For now, it can only contain the key levels, whose value is a reference to an array of user levels. If this key is set, the function returns the number of accounts with any of those levels.

Logging

get_events($options)

Retrieves log events, taking a hash reference like the other get_ functions. Returns results in the same fashion as get_quotes(), but always sorted chronologically. This time, the available options are:

code: Either a single event code or a reference to an array of codes to match. This option may be omitted.
user: Either a single user ID or a reference to an array of IDs to match. This option may be omitted. A user ID of 0 represents users who are not logged in.
first: The number of the first result to return, 0 being the first in the result list. If this option is omitted, the default value of 0 is assumed.
count: The number of events to maximally return. If this option is omitted, there is no limit on the number of results.
reverse: If this option has a true value, the order is reversed, so the events are in reverse chronological order.
data: May be set to a hash reference to filter the events on metadata. If any of the key-value pairs in the hash are equal to a metadata property of the event, it is considered a match. This option may be omitted.

log_event($event)

Logs the Chirpy::Event $event. Returns a true value on success.

The properties to be saved by this method are code, user and data.

Chirpy!

Chirpy! 0.3 API Documentation