/ 
DDC-Concordance-0.39
River stage one • 1 direct dependent • 2 total dependents
/ DDC::Client

NAME

DDC::Client - Client socket utilities for DDC::Concordance

SYNOPSIS

use DDC::Client;

##---------------------------------------------------------------------
## Constructors, etc.

$dc = DDC::Client->new(PeerAddr=>'localhost',PeerPort=>50000);

##---------------------------------------------------------------------
## open, close

$io_socket = $dc->open();
undef      = $dc->close();

##---------------------------------------------------------------------
## Common Requests

$rsp  = $dc->request($request);
$data = $dc->requestJson($request);

$version = $dc->version();
$status  = $dc->status();
$vstatus = $dc->vstatus();
$info    = $dc->info();

$rsp     = $dc->expand_terms(\@pipeline, \@terms);
@terms   = $dc->expand(\@pipeline, \@terms);

##---------------------------------------------------------------------
## Low-level Communications

$dc->send(@command);               ##-- send a command (prepends size)
$dc->sendfh($fh,@command);         ##-- ... to specified filehandle

$size = $dc->readSize();           ##-- get size of return message from client socket
$size = $dc->readSize($fh);        ##-- ... or from a given filehandle

$buf  = $dc->readBytes($size);     ##-- read a sized return buffer from client socket
$buf  = $dc->readBytes($size,$fh); ##-- ... or from a given filehandle

$buf  = $dc->readData();           ##-- same as $dc->readBytes($dc->readSize())
$buf  = $dc->readData($fh);        ##-- ... same as $dc->readBytes($dc->readSize($fh),$fh)

$hits = $dc->parseData($buf);      ##-- parse a return buffer
$hits = $dc->parseJsonData($buf);  ##-- parse a return buffer in 'json' mode
$hits = $dc->parseTextData($buf);  ##-- parse a return buffer in 'text' mode
$hits = $dc->parseTableData($buf); ##-- parse a return buffer in 'table' mode
$hits = $dc->parseHtmlData($buf);  ##-- parse a return buffer in 'html' mode

@terms = $dc->parseExpandTermsResponse($buf);  ##-- parse an expand_terms response buffer

DESCRIPTION

Globals

Variable: $ifmt

pack()-format to use for integer sizes passed to and from a DDC server. The default value ('V') should be right for ddc-2.x (always 32-bit unsigned little endian). For ddc-1.x, the machine word size and endian-ness should match the those native to the machine running the DDC server.

Variable: $ilen

Length of message size integer used for DDC protocol in bytes. If you change $ifmt, you should make sure to change $ilen appropriately, e.g. by setting:

$ilen = length(pack($ifmt,0));

Constructors etc

new
$dc = $CLASS_OR_OBJ->new(%args);
accepted %args:
(
 optFile  =>$filename,       ##-- parse meta names, separators from DDC *.opt file
 connect  =>\%connectArgs,   ##-- passed to IO::Socket::INET->new()
 linger   =>\@linger,        ##-- SO_LINGER socket option (default=[1,0]: immediate termination)
 mode     =>$mode,           ##-- query mode; one of qw(json table text html raw); default='json'
 parseMeta=>$bool,           ##-- if true, hit metadata will be parsed to $hit->{_meta} (default=1)
 parseContext=>$bool,        ##-- if true, hit context data will be parsed to $hit->{_ctx} (default=1)
 keepRaw  =>$bool,           ##-- if false, raw context buffer $hit->{_raw} will be deleted after parsing context data (default=false)
 encoding =>$enc,            ##-- DDC server encoding (default='UTF-8')
 fieldSeparator => $str,     ##-- intra-token field separator (default="\x{1f}": ASCII unit separator); 'text' and 'table' modes only
 tokenSeparator => $str,     ##-- inter-token separator       (default="\x{1e}": ASCII record separator); 'text' and 'table' modes only
 metaNames      => \@names,  ##-- metadata names for 'text' and 'html' modes; default=none

 textHighlight => [$l0,$r0,$l1,$r1],  ##-- highlighting strings, text mode (default=[qw(&& && _& &_)])
 htmlHighlight => [$l0,$r0,$l1,$r1],  ##-- highlighting strings, html mode (default=[('<STRONG><FONT COLOR=red>','</FONT></STRONG>') x 2])
 tableHighlight => [$l0,$r0,$l1,$r1], ##-- highlighting strings, table mode (default=[qw(&& && _& &_)])
)
default \%connectArgs:
PeerAddr=>localhost
PeerPort=>50000,
Proto=>'tcp',
Type=>SOCK_STREAM,
Blocking=>1,

open, close

open
$io_socket = $dc->open();

Open the underlying socket; returns undef on failure.

close
undef = $dc->close();

Closes the underlying socket if currently open.

Common Requests

request
$rsp = $dc->request($request_string);

Send a raw DDC request and return the server's response as a raw byte-string.

requestJson
$data = $dc->requestJson($request_string);

Send a raw DDC request and decode the server's response as JSON data.

version
$server_version = $dc->version();

Request the current running version of the selected server, wraps $dc->request("version").

status
$status = $dc->status();
$status = $dc->status($timeout);

Get basic server status; wraps $dc->requestJson("status $timeout").

vstatus
$vstatus = $dc->vstatus();
$vstatus = $dc->vstatus($timeout);

Get verbose server status; wraps $dc->requestJson("vstatus $timeout").

info
$info = $dc->info();
$info = $dc->info($timeout);

Get verbose server information; wraps $dc->requestJson("info $timeout").

expand_terms
$expandRaw = $dc->expand_terms($pipeline, $term);
$expandRaw = $dc->expand_terms($pipeline, $term, $timeout);
$expandRaw = $dc->expand_terms($pipeline, $term, $timeout, $subcorpus);

Perform server-side term-expansion for the term $term via pipeline $pipeline. Both $term and $pipeline may be specified as ARRAY-refs or bare strings. Returns the raw response data string.

expand
@terms = $dc->expand($pipeline, $term);
@terms = $dc->expand($pipeline, $term, $timeout);
@terms = $dc->expand($pipeline, $term, $timeout, $subcorpus);

Perform server-side term-expansion for the term $term via pipeline $pipeline and parses the response with parseExpandTermsResponse. Returns an array @terms of server expansions in list-context; in scalar context returns the reference \@terms to such an array.

Low-level Communications

send
undef = $dc->send(@message_strings);

  • Sends @message_strings to the underlying socket as a single message.

sendfh
undef = $dc->sendfh($fh,@message_strings);

  • Sends @message_strings to filehandle $fh, prepending total length.

readSize
$size = $dc->readSize();
$size = $dc->readSize($fh)

Reads message size from $fh (default=underlying socket).

readBytes
$data = $dc->readBytes($nbytes);
$data = $dc->readBytes($nbytes,$fh)

Reads fixed number of bytes from $fh (default=underlying socket).

readData
$data = $dc->readData();
$data = $dc->readData($fh)

Reads pending data from $fh (default=underlying socket); calls readSize() and readBytes().

Hit Parsing

parseTableData
parseTextData
parseJsonData
\@hits = $dc->parseTableData($buf);
\@hits = $dc->parseTextData($buf);
\@hits = $dc->parseJsonData($buf);

Parses raw DDC data buffer in $buf. Returns an array-ref of DDC::Hit objects representing the individual hits.

JSON parsing requires the JSON module.

parseExpandTermsResponse
\@terms = $dc->parseExpandTermsResponse($buf);
 @terms = $dc->parseExpandTermsResponse($buf);

Parses a DDC server expand_terms response buffer. Returns an array @terms of server expansions in list-context; in scalar context returns the reference \@terms to such an array.

AUTHOR

Bryan Jurish <moocow@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2006-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.