.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.14)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "DlfQuery 3pm"
.TH DlfQuery 3pm "2006-07-23" "Lire 2.1.1" "LogReport's Lire Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Lire::DlfQuery \- Interface to specialized SQL wrappers used internally by
the Lire API.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Lire::DlfQuery;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
.ie n .SS "new( $stream_name )"
.el .SS "new( \f(CW$stream_name\fP )"
.IX Subsection "new( $stream_name )"
This is the constructor method for the Lire::DlfQuery class. It takes a
dlf stream name and a Lire::DlfStore object as parameters. Lire::DlfStore
is expected to contain the specified stream. Both parameters are
mandatory. This method returns an instance of Lire::DlfQuery.
.SS "\fIstream_name()\fP"
.IX Subsection "stream_name()"
Returns the \s-1DLF\s0 stream's name upon which this DlfQuery is defined.
.ie n .SS "join_stream( $stream_name )"
.el .SS "join_stream( \f(CW$stream_name\fP )"
.IX Subsection "join_stream( $stream_name )"
This method can be used to add an ExtendedSchema stream which will
be joined in the query.
.SS "\fIjoined_streams()\fP"
.IX Subsection "joined_streams()"
Returns as an array reference all the streams that are part of the
query.
.SS "\fIrelease()\fP"
.IX Subsection "release()"
Nested DlfQuery introduce a circular reference between the children
and the parent. Call \fIrelease()\fR on the top-level DlfQuery to remove the
circular when the DlfQuery object isn't needed anymore, so that perl
can garbage collect the objects.
.SS "\fIcreate_nested_query()\fP"
.IX Subsection "create_nested_query()"
This method will create and return an instance of Lire::DlfQuery nested
within the current query. The returned query will be modified later with
regular methods.
.SS "\fInested_queries()\fP"
.IX Subsection "nested_queries()"
This method returns a reference to an array containing all the nested
queries of the current query.
.ie n .SS "has_field( $field_name )"
.el .SS "has_field( \f(CW$field_name\fP )"
.IX Subsection "has_field( $field_name )"
Returns true if there is a field \f(CW$field_name\fR defined in the query.
.ie n .SS "field_def( $field_name )"
.el .SS "field_def( \f(CW$field_name\fP )"
.IX Subsection "field_def( $field_name )"
Returns the \s-1SQL\s0 expression that is associated with the field
\&\f(CW$field_name\fR in the query. This method will throw an exception if
there is no field \f(CW$field_name\fR defined in the query.
.SS "\fIfields()\fP"
.IX Subsection "fields()"
Returns the name of the fields defined as simple fields in an array
reference. These are fields added through the \fIadd_field()\fR method.
.SS "\fIgroup_fields()\fP"
.IX Subsection "group_fields()"
Returns the name of the fields defined as group fields in an array
reference. These are fields added through the \fIadd_group_field()\fR method.
.SS "\fIaggr_fields()\fP"
.IX Subsection "aggr_fields()"
Returns the name of the fields defined as aggregate fields in an array
reference. These are fields added through the \fIadd_aggr_field()\fR method.
.ie n .SS "add_field( $field_name, $expr )"
.el .SS "add_field( \f(CW$field_name\fP, \f(CW$expr\fP )"
.IX Subsection "add_field( $field_name, $expr )"
Add a simple field to the current query. The first parameter will be the
field name. The second represents an expression that will then be aliased
with the specified field name. Only the field name is mandatory.
.PP
Certain restrictions apply: simple fields cannot be added to queries
containing either subqueries or group fields.
.ie n .SS "add_aggr_field( $field_name, $aggregate )"
.el .SS "add_aggr_field( \f(CW$field_name\fP, \f(CW$aggregate\fP )"
.IX Subsection "add_aggr_field( $field_name, $aggregate )"
Add a group field to the current query. The first parameter will be the
field name. The second represents the aggregate expression that will then be
aliased with the specified field name. Both parameters are mandatory.
.PP
Aggregate field can only be added to queries which contain group fields.
.ie n .SS "add_group_field( $field_name, $expr )"
.el .SS "add_group_field( \f(CW$field_name\fP, \f(CW$expr\fP )"
.IX Subsection "add_group_field( $field_name, $expr )"
Add a group field to the current query. The first parameter will be the
field name. The second represents an expression that will then be aliased
with the specified field name. Only the field name is mandatory.
.PP
Certain restrictions apply: group fields cannot be added to queries
containing simple fields.
.ie n .SS "set_order_by_clause( $clause )"
.el .SS "set_order_by_clause( \f(CW$clause\fP )"
.IX Subsection "set_order_by_clause( $clause )"
Sets the order clause of the query, that is, what will appear in the
\&\*(L"\s-1ORDER\s0 \s-1BY\s0\*(R" clause of the \s-1SQL\s0 statement.
.SS "\fIorder_by_clause()\fP"
.IX Subsection "order_by_clause()"
Returns the current \s-1ORDER\s0 \s-1BY\s0 clause or undef when none was set.
.ie n .SS "set_sort_spec( $spec )"
.el .SS "set_sort_spec( \f(CW$spec\fP )"
.IX Subsection "set_sort_spec( $spec )"
.SS "\fIsort_spec()\fP"
.IX Subsection "sort_spec()"
Returns the sort specification that was set using \fIset_sort_spec()\fR. If
no sort specification was set (or it was set using the
\&\fIset_order_by_clause()\fR method), this will be undef.
.SS "\fIset_limit()\fP"
.IX Subsection "set_limit()"
Sets the limit clause of the query, that is, what will appear in the
\&\*(L"\s-1LIMIT\s0\*(R" clause of the \s-1SQL\s0 statement. This method will also have an impact
on the internal handling of the query.
.SS "\fIlimit()\fP"
.IX Subsection "limit()"
Returns the maximum number of records that should be returned by the
query. When no limit was set, it returns 0.
.ie n .SS "set_filter_clause( $clause, @params )"
.el .SS "set_filter_clause( \f(CW$clause\fP, \f(CW@params\fP )"
.IX Subsection "set_filter_clause( $clause, @params )"
Sets the filter clause of the query, the filter clause being the \s-1SQL\s0
restrictions on the results that will be return by the query, i.e. what
will appear in the \*(L"\s-1WHERE\s0\*(R" clause of the \s-1SQL\s0 statement.
.PP
It is compatible with the \s-1DBI\s0 handling of placeholders ('?'). Of course,
the amount of placeholders has to be the same of the amount of values and
variables that are passed in \f(CW@params\fR.
.PP
Only the clause parameter is mandatory, the number of elements in \f(CW@params\fR
being dependent on the amount of placeholders specified therein.
.SS "\fIfilter_clause()\fP"
.IX Subsection "filter_clause()"
Returns the current \s-1WHERE\s0 clause or undef when none was set.
.SS "\fIexecute()\fP"
.IX Subsection "execute()"
This method executes the query through the database interface and returns
an instance of Lire::DlfResult to obtain the data.
.SS "\fIexecute_summary()\fP"
.IX Subsection "execute_summary()"
Same as the \fIexecute()\fR except that the query is executed as a summary query.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fILire::DlfQuery\fR\|(3pm) \fILire::DlfStream\fR\|(3pm) \fILire::DlfStore\fR\|(3pm)
.SH "AUTHORS"
.IX Header "AUTHORS"
.Vb 2
\&  Francis J. Lacoste <flacoste@logreport.org>
\&  Wolfgang Sourdeau <Wolfgang.Sourdeau@Contre.COM>
.Ve
.SH "VERSION"
.IX Header "VERSION"
\&\f(CW$Id:\fR DlfQuery.pm,v 1.44 2006/07/23 13:16:28 vanbaal Exp $
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2003 Stichting LogReport Foundation LogReport@LogReport.org
.PP
This file is part of Lire.
.PP
Lire is free software; you can redistribute it and/or modify
it under the terms of the \s-1GNU\s0 General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
.PP
This program is distributed in the hope that it will be useful,
but \s-1WITHOUT\s0 \s-1ANY\s0 \s-1WARRANTY\s0; without even the implied warranty of
\&\s-1MERCHANTABILITY\s0 or \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0.  See the
\&\s-1GNU\s0 General Public License for more details.
.PP
You should have received a copy of the \s-1GNU\s0 General Public License
along with this program (see \s-1COPYING\s0); if not, check with
http://www.gnu.org/copyleft/gpl.html.