/ 
DiaColloDB-0.12.020
River stage one • 1 direct dependent • 1 total dependent
/ DiaColloDB::Client

NAME

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

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);

DESCRIPTION

Globals & Constants

Variable: @ISA

DiaColloDB::Client inherits from DiaColloDB::Persistent.

Constructors etc.

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

%args, object structure:

url  => $url,       ##-- db url
defaults
%defaults = $CLASS_OR_OBJ->defaults();

called by new() and promote() to provide default options on a subclass basis.

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

Promotes $cli to (a subclass of) $class. Ensures $class->defaults() keys are set for $cli. Client options are clobbered with %opts.

DESTROY
undef = $obj->DESTROY;

destructor calls close() if necessary.

I/O: open/close

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

calls open_file(), open_rcfile(), or open_http(), or open_list() as appropriate, depending on the datatype or scheme of $url; may re-bless() $cli into an appropriate package. If $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.

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 open() implementation for the URLS using the rcfile:// scheme, as well as for 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 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 $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 $cli->{rcurl}.

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 open() for URLs with a file:// scheme or without an explicit URL scheme.

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

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 open() for URLs with an http:// or https:// scheme.

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

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 open() for ARRAY-ref URLs or string URLs with a list:// scheme.

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

close
$cli_or_undef = $cli->close();

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

opened
$bool = $cli->opened();

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

db-info

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

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

Profiling: Wrappers

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

Get a generic DiaColloDB::Profile::Multi object for relation $rel. Calls $cli method profile(), extend(), or compare() as appropriate.

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

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

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

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

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

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

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

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

Profiling: Generic

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

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

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

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

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

Get a comparison profile for selected items as a DiaColloDB::Profile::Multi object. %opts: as for DiaColloDB::compare(). Sets $cli->{error} on error.

Profiling: Comparison (diff)

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

Wrapper for compare().

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

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

AUTHOR

Bryan Jurish <moocow@cpan.org>

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.

SEE ALSO

DiaColloDB::Client::file(3pm), DiaColloDB::Client::http(3pm), DiaColloDB::Client::list(3pm), DiaColloDB(3pm), perl(1), ...