##========================================================================
## 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_rcfile($rcfile_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);
 $mprf = $cli->extend($relation, %opts);
 $mprf = $cli->compare($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_file()|/open_file>, L<open_rcfile()|/open_rcfile>, or L<open_http()|/open_http>, or L<open_list()|/open_list> as appropriate,
depending on the datatype or scheme of C<$url>;
may re-bless() C<$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_rcfile

 $cli_or_undef = $cli->open_rcfile($rcfile_url,%opts);
 $cli_or_undef = $cli->open_rcfile();

Opens a local configuration file URL.  Called by the default
L<open|/open>() implementation for the URLS using the C<rcfile://> scheme,
as well as for C<file://> schemes or scheme-less URLs which resolve to a
local non-directory path.  Configuration files accepted by this method
are expected to be in JSON format as accepted by
L<DiaColloDB::Persistent::readHeaderFile()|DiaColloDB::Persistent/readHeaderFile>,
and contain one or more of the following keys:

 class => $CLASS, ##-- bless() client into class $CLASS
 url   => $url,   ##-- open client url $url
 $key  => $val,   ##-- ... other keys passed to (promoted) $cli->open($url,%opts)

Client options specified in the query portion of C<$rcfile_url> will override
options read from the configuration file if there are any conflicts,
and the original URL of the configuration file will be placed in C<$cli-E<gt>{rcurl}>.

=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 method L<profile|/profile>(), L<extend|/extend>(), or L<compare|/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.

=item extend

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

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

=item compare

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

Get a comparison profile for selected items as a L<DiaColloDB::Profile::Multi|DiaColloDB::Profile::Multi> object.
%opts: as for L<DiaColloDB::compare()|DiaColloDB/compare>.
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-2020 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