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

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

=head1 NAME

DiaColloDB::Client - diachronic collocation db, top-level client API

=cut

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

=head1 SYNOPSIS

 ##========================================================================
 ## PRELIMINARIES
 
 use DiaColloDB::Client;
 
 ##========================================================================
 ## Constructors etc.
 
 $cli = CLASS_OR_OBJECT->new(%args);
 %defaults = $CLASS_OR_OBJ->defaults();
 $cli_or_undef = $cli->promote($class,%opts);
 undef = $obj->DESTROY;
 
 ##========================================================================
 ## I/O: open/close
 
 $cli_or_undef = $cli->open($url,%opts);
 $cli_or_undef = $cli->open_file($file_url,%opts);
 $cli_or_undef = $cli->open_http($http_url,%opts);
 $cli_or_undef = $cli->open_list($list_url,%opts);
 $cli_or_undef = $cli->close();
 $bool = $cli->opened();
 
 ##========================================================================
 ## db-info
 
 \%info = $cli->dbinfo();
 
 ##========================================================================
 ## Profiling: Wrappers
 
 $mprf = $cli->query($rel,%opts);
 $mprf = $cli->profile1(%opts);
 $mprf = $cli->profile2(%opts);
 $mprf = $cli->compare1(%opts);
 $mprf = $cli->compare2(%opts);
 
 ##========================================================================
 ## Profiling: Generic
 
 $mprf = $cli->profile($relation, %opts);


=cut

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

=head1 DESCRIPTION

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Client: Globals & Constants
=pod

=head2 Globals & Constants

=over 4

=item Variable: @ISA

DiaColloDB::Client inherits from
L<DiaColloDB::Persistent|DiaColloDB::Persistent>.

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Client: Constructors etc.
=pod

=head2 Constructors etc.

=over 4

=item new

 $cli = CLASS_OR_OBJECT->new(%args);
 $cli = CLASS_OR_OBJECT->new($url, %args);

%args, object structure:

 url  => $url,       ##-- db url


=item defaults

 %defaults = $CLASS_OR_OBJ->defaults();

called by L<new()|/new> and L<promote()|/promote> to provide default options on a subclass basis.

=item promote

 $cli_or_undef = $cli->promote($class,%opts);

Promotes $cli to (a subclass of) $class.
Ensures $class-E<gt>L<defaults()|/defaults> keys are set for C<$cli>.
Client options are clobbered with C<%opts>.

=item DESTROY

 undef = $obj->DESTROY;

destructor calls L<close()|/close> if necessary.

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Client: I/O: open/close
=pod

=head2 I/O: open/close

=over 4

=item open

 $cli_or_undef = $cli->open($url,%opts);
 $cli_or_undef = $cli->open();

calls L<open_list()|/open_list>, L<open_file()|/open_file>, or L<open_http()|/open_http> as appropriate
depending on the datatype or scheme of C<$url>;
may re-bless() $cli into an appropriate package.
If C<$url> is passed as a string, its query string
will be parsed by the <URI::query_form()|URI/uri-query_form> method
and used to pass options to the (promoted) client subclass.


=item open_file

 $cli_or_undef = $cli->open_file($file_url,%opts);
 $cli_or_undef = $cli->open_file()

opens a local file url;
may re-bless() $cli into an appropriate package.
Called by L<open()|/open> for URLs with a C<file://> scheme or without an explicit URL scheme.

B<OVERRIDE> in subclasses supporting file urls;
see L<DiaColloDB::Client::file> for the default implementation.

=item open_http

 $cli_or_undef = $cli->open_http($http_url,%opts);
 $cli_or_undef = $cli->open_http()

opens an http url;
may re-bless() $cli into an appropriate package.
Called by L<open()|/open> for URLs with an C<http://> or C<https://> scheme.

B<OVERRIDE> in subclasses supporting http urls,
see L<DiaColloDB::Client::http> for the default implementation.

=item open_list

 $cli_or_undef = $cli->open_list($list_url,%opts);
 $cli_or_undef = $cli->open_list(\@urls,   %opts)
 $cli_or_undef = $cli->open_list()

opens a list url;
may re-bless() $cli into an appropriate package.
Called by L<open()|/open> for ARRAY-ref URLs or string URLs with a C<list://> scheme.

B<OVERRIDE> in subclasses supporting list urls,
see L<DiaColloDB::Client::list> for the default implementation.

=item close

 $cli_or_undef = $cli->close();

Close the client connection (if any); default just returns $cli.

=item opened

 $bool = $cli->opened();

Return true iff client is currently open.
Default implementation just checks for $cli-E<gt>{url}.

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Client: db-info
=pod

=head2 db-info

=over 4

=item dbinfo

 \%info = $cli->dbinfo();

Abstract method; should return db info hash for underlying db(s).

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Client: Profiling: Wrappers
=pod

=head2 Profiling: Wrappers

=over 4

=item query

 $mprf = $cli->query($rel,%opts);

Get a generic L<DiaColloDB::Profile::Multi|DiaColloDB::Profile::Multi> object for relation $rel.
Calls $cli-E<gt>profile() or $cli-E<gt>compare() as appropriate.

=item profile1

 $mprf = $cli->profile1(%opts);

Get unigram frequency profile for selected items as a L<DiaColloDB::Profile::Multi|DiaColloDB::Profile::Multi> object.
Really just wraps $cli-E<gt>profile('xf', %opts).
%opts: see profile() method

=item profile2

 $mprf = $cli->profile2(%opts);

Get native co-frequency profile for selected items as a L<DiaColloDB::Profile::Multi|DiaColloDB::Profile::Multi> object.
Really just wraps $cli-E<gt>profile('cof', %opts).
%opts: see profile() method.

=item compare1

 $mprf = $cli->compare1(%opts);

Get unigram comparison profile for selected items as a L<DiaColloDB::Profile::MultiDiff|DiaColloDB::Profile::MultiDiff> object.
Really just wraps $cli-E<gt>compare('xf', %opts).
%opts: see compare() method.

=item compare2

 $mprf = $cli->compare2(%opts);

Get co-frequency comparison profile for selected items as a L<DiaColloDB::Profile::MultiDiff|DiaColloDB::Profile::MultiDiff> object.
Really just wraps $cli-E<gt>profile('cof', %opts).
%opts: see compare() method.

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Client: Profiling: Generic
=pod

=head2 Profiling: Generic

=over 4

=item profile

 $mprf = $cli->profile($relation, %opts);

Get a relation profile for selected items as a L<DiaColloDB::Profile::Multi|DiaColloDB::Profile::Multi> object
%opts: as for L<DiaColloDB::profile()|DiaColloDB/profile>.
Sets $cli-E<gt>{error} on error.

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Client: Profiling: Comparison (diff)
=pod

=head2 Profiling: Comparison (diff)

=over 4

=item diff

 $mprf = $cli->diff($relation, %opts);

Wrapper for compare().

=item compare

 $mprf = $cli->compare($relation, %opts);

Get a relation comparison profile for selected items as a L<DiaColloDB::Profile::MultiDiff|DiaColloDB::Profile::MultiDiff> object.
%opts: as for L<DiaColloDB::compare()|DiaColloDB/compare>.
Sets $cli->{error} on error.

=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<DiaColloDB::Client::file(3pm)|DiaColloDB::Client::file>,
L<DiaColloDB::Client::http(3pm)|DiaColloDB::Client::http>,
L<DiaColloDB::Client::list(3pm)|DiaColloDB::Client::list>,
L<DiaColloDB(3pm)|DiaColloDB>,
L<perl(1)|perl>,
...

=cut
