NAME

Rubric::Entry::Query - construct and execute a complex query

VERSION

version 0.157

DESCRIPTION

Rubric::Entry::Query builds a query based on a simple hash of parameters, performs that query, and returns the rendered report on the results.

PERL VERSION

This code is effectively abandonware. Although releases will sometimes be made to update contact info or to fix packaging flaws, bug reports will mostly be ignored. Feature requests are even more likely to be ignored. (If someone takes up maintenance of this code, they will presumably remove this notice.) This means that whatever version of perl is currently required is unlikely to change -- but also that it might change at any new maintainer's whim.

METHODS

query(\%arg, \%context)

This is the only interface to this module. Given a hashref of named arguments, it returns the entries that match constraints built from the arguments. It generates these constraints with get_constraint and its helpers. If any constraint is invalid, an empty set of results is returned.

The second hashref passed to the method provides context for generating implicit query parameters; for example, if the querying user is indicated in the context, private entries for that user will be returned.

get_constraint($param => $value)

Given a name/value pair describing a constraint, this method will attempt to generate part of an SQL WHERE clause enforcing the constraint. To do this, it looks for and calls a method called "constraint_for_NAME" where NAME is the passed value of $param. If no clause can be generated, it returns undef.

get_entries(\@constraints)

Given a set of SQL constraints, this method builds the WHERE and ORDER BY clauses and performs a query with Class::DBI's retrieve_from_sql.

constraint_for_NAME

These methods are called to produce SQL for the named parameter, and are passed a scalar argument. If the argument is not valid, they return undef, which will cause query to produce an empty set of records.

constraint_for_user($user)

Given a Rubric::User object, this returns SQL to limit results to entries by the user.

constraint_for_tags($tags)

constraint_for_exact_tags($tags)

Given a set of tags, this returns SQL to limit results to entries marked with the given tags.

The exact version of this constraint returns SQL for entries with only the given tags.

constraint_for_desc_like($value)

constraint_for_body_like($value)

constraint_for_like($value)

constraint_for_has_body($bool)

This returns SQL to limit the results to entries with bodies.

constraint_for_has_link($bool)

This returns SQL to limit the results to entries with links.

constraint_for_first_only($bool)

This returns SQL to limit the results to the first entry posted for any given link.

constraint_for_urimd5($md5)

This returns SQL to limit the results to entries whose link has the given md5sum.

constraint_for_{timefield}_{preposition}($datetime)

This set of six methods return SQL to limit the results based on its timestamps.

The passed value is a complete or partial datetime in the form:

YYYY[-MM[-DD[ HH[:MM]]]]  # space may be replaced with 'T'

The timefield may be "created" or "modified".

The prepositions are as follows:

after  - after the latest part of the given unit of time
before - before the earliest part of the given unit of time
on     - after (or at) the earliest part and before (or at) the latest part

AUTHOR

Ricardo SIGNES <rjbs@semiotic.systems>

COPYRIGHT AND LICENSE

This software is copyright (c) 2004 by Ricardo SIGNES.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.