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-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.

SEE ALSO

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