##========================================================================
## POD DOCUMENTATION, auto-generated by podextract.perl

##========================================================================
## NAME
=pod

=head1 NAME

DiaColloDB::Relation::TDF::Query - collocation db, profiling relation: PDL: query hacks

=cut

##========================================================================
## SYNOPSIS
=pod

=head1 SYNOPSIS

 ##========================================================================
 ## PRELIMINARIES
 
 use DiaColloDB::Relation::TDF::Query;
 
 ##========================================================================
 ## Constructors etc.
 
 $vq = CLASS_OR_OBJECT->new(%args);
 
 ##========================================================================
 ## API: compilation
 
 $vq_or_undef = $vq->compile(%opts);
 $vq_or_undef = $vq->compileLocal(%opts);
 $vq_or_undef = $vq->compileOptions(%opts);
 
 ##========================================================================
 ## Utils: set operations
 
 $vq = $vq->_intersect($vq2);
 $vq = $vq->_union($vq2);
 
 ##========================================================================
 ## Wrappers: DDC::XS::Object
 
 $vq = $DDC_XS_OBJECT->__dcvs_compile($vq,%opts);

=cut

##========================================================================
## DESCRIPTION
=pod

=head1 DESCRIPTION

DiaColloDB::Relation::TDF::Query
provides an object-oriented interface for parsing and evaluating
queries in DDC syntax with respect to
a sparse (term x document) frequency index as represented by a
L<DiaColloDB::Relation::TDF|DiaColloDB::Relation::TDF> object.

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Relation::TDF::Query: Globals & Constants
=pod

=head2 Globals & Constants

=over 4

=item Variable: @ISA

DiaColloDB::Relation::TDF::Query inherits from
L<DiaColloDB::Logger|DiaColloDB::Logger>.

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Relation::TDF::Query: Constructors etc.
=pod

=head2 Constructors etc.

=over 4

=item new

 $vq = CLASS_OR_OBJECT->new(%args);
 $vq = CLASS_OR_OBJECT->new($cquery);

Create and return a new tdf-query object from a
parsed L<DDC::XS::CQuery|DDC::XS::CQuery> object.
%args, %$vq:

 cq => $cquery,      ##-- underlying DDC::XS::CQuery object
 ti => $ti_pdl,      ##-- pdl ($NTi) : selected term-indices (undef: all)
 ci => $ci_pdl,      ##-- pdl ($NCi) : selected cat-indices (undef: all)

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Relation::TDF::Query: API: compilation
=pod

=head2 API: compilation

=over 4

=item compile

 $vq_or_undef = $vq->compile(%opts);

Wraps L<$vq-E<gt>compileLocal()|/compileLocal>.
%opts: as for DiaColloDB::profile(), also

 coldb => $coldb,   ##-- DiaColloDB context (for enums)
 tdf   => $tdf,     ##-- DiaColloDB::Relation::TDF context (for meta-enums)

=item compileLocal

 $vq_or_undef = $vq->compileLocal(%opts);

Calls L<$vq-E<gt>{cq}-E<gt>__dcvs_compile($vq,%opts)|/DDC::XS::Object::__dcvs_compile>
to compile the query conditions into $vq-E<gt>{ti} and $vq-E<gt>{ci},
followed by L<$vq-E<gt>compileOptions()|/compileOptions>.
%opts: as for L<DiaColloDB::profile()|DiaColloDB/profile>, also:

 coldb => $coldb,   ##-- DiaColloDB context (for enums)
 tdf  => $tdf,      ##-- DiaColloDB::Relation::TDF context (for meta-enums)

=item compileOptions

 $vq_or_undef = $vq->compileOptions(%opts);

merges underlying L<DDC::XS::CQueryOptions|DDC::XS::CQueryOptions> restrictions into $vq piddles.
%opts: as for the L<compile()|/compile> method.

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Relation::TDF::Query: Utils: set operations
=pod

=head2 Utils: set operations

=over 4

=item _intersect

 $vq = $vq->_intersect($vq2);

destructive intersection on component piddles.

=item _union

 $vq = $vq->_union($vq2);

destructive union on component piddles.

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Relation::TDF::Query: Wrappers: DDC::XS::Object
=pod

=head2 Wrappers: DDC::XS::Object

The DiaColloDB::Relation::TDF::Query package extends the
L<DDC::XS::Object> subclasses
with additional methods for compiling
DiaColloDB::Relation::TDF::Query objects from
L<DDC::XS::CQuery> and/or L<DDC::XS::CQFilter> objects
representing a fully parsed DDC query.

=over 4

=item DDC::XS::Object::__dcvs_compile

 $vq = $DDC_XS_OBJECT->__dcvs_compile($vq,%opts);

Compiles $DDC_XS_OBJECT (a L<DDC::XS::Object|DDC::XS::Object>)
into a DiaColloDB::Relation::TDF::Query object $vq.
Returns $vq on success, or undef on failure.
%opts: as for L<DiaColloDB::Relation::TDF::Query::compile()|/compile>.

Supported subclasses:

=over 4

=item DDC::XS::Object

Fallback method to report errors.

=item DDC::XS::CQTokAny

Dummy method for universal wildcard queries.

=item DDC::XS::CQTokExact

=item DDC::XS::CQTokInfl

Used for bareword queries,
doesn't really support DDC-style re-inflection or term-expansion.

=item DDC::XS::CQTokSet

=item DDC::XS::CQTokSetInfl

Used for set-valued bareword queries,
doesn't really support DDC-style re-inflection or term-expansion.

=item DDC::XS::CQTokRegex

=item DDC::XS::CQTokPrefix

=item DDC::XS::CQTokSuffix

=item DDC::XS::CQTokInfix

=item DDC::XS::CQTokPrefixSet

=item DDC::XS::CQTokSuffixSet

=item DDC::XS::CQTokInfixSet

=item DDC::XS::CQTokLemma

Used for %LEMMA lemma queries,
doesn't really support DDC-style re-inflection or term-expansion.

=item DDC::XS::CQWith

=item DDC::XS::CQWithout

=item DDC::XS::CQAnd

Boolean conjunction operator evaluates to union of sub-query term-targets
and the intersection of the sub-query category-targets, restricted to the
corresponding term-teargets, so a query (A && B)
behaves as a sparse matrix mapping each document C<d> in any category C<c> containing
both C<A> and C<B> to C<f(A,d)+f(B,d)>.

TODO: make this restriction actually work on document (signature) level rather than
category level, for better resolution.

=item DDC::XS::CQOr

=item DDC::XS::CQFHasFieldValue

=item DDC::XS::CQFHasFieldRegex

=item DDC::XS::CQueryOptions

Dispatch methods compiles filters.

=back

=back

=cut


##========================================================================
## END POD DOCUMENTATION, auto-generated by podextract.perl

##======================================================================
## Footer
##======================================================================
=pod

=head1 AUTHOR

Bryan Jurish E<lt>moocow@cpan.orgE<gt>

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2015-2016 by Bryan Jurish

This package is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.14.2 or,
at your option, any later version of Perl 5 you may have available.

=head1 SEE ALSO

L<DDC::XS::CQuery(3pm)|DDC::XS::CQuery>,
L<DiaColloDB::Relation::TDF(3pm)|DiaColloDB::Relation::TDF>,
L<DiaColloDB(3pm)|DiaColloDB>,
L<perl(1)|perl>,
...



=cut
