# NAME
Cache::KyotoTycoon - KyotoTycoon client library
# SYNOPSIS
    use Cache::KyotoTycoon;
    my $kt = Cache::KyotoTycoon->new(host => '127.0.0.1', port => 1978);
    $kt->set('foo' => bar');
    $kt->get('foo'); # => 'bar'
# DESCRIPTION
KyotoTycoon.pm is [KyotoTycoon](http://fallabs.com/kyototycoon/) client library for Perl5.
__THIS MODULE IS IN ITS BETA QUALITY. THE API MAY CHANGE IN THE FUTURE__.
# ERROR HANDLING POLICY
This module throws exception if got __Server Error__.
# CONSTRUCTOR OPTIONS
- `timeout`
    Timeout value for each request in seconds.
    _Default_: 1 second
- `host`
    Host name of server machine.
    _Default_: '127.0.0.1'
- `port`
    Port number of server process. 
    _Default_: 1978 
- `db`
    DB name or id.
    _Default_: 0
# METHODS
- `$kt->db()`
    Getter/Setter of DB name/id.
- `my $cursor: Cache::KyotoTycoon::Cursor = $kt->make_cursor($cursor_number: Int);`
    Create new cursor object. This method returns instance of [Cache::KyotoTycoon::Cursor](http://search.cpan.org/perldoc?Cache::KyotoTycoon::Cursor).
- `my $res = $kt->echo($args)`
    The server returns $args. This method is useful for testing server.
    $args is hashref.
    _Return_: the copy of $args.
- `$kt->report()`
    Get server report.
    _Return_: server status information in hashref.
- `my $output = $kt->play_script($name[, \%input]);`
    Call a procedure of the script language extension.
    _$name_: the name of the procedure to call.
    _\\%input_: (optional): arbitrary records.
    _Return_: response of the script in hashref.
- `my $info = $kt->status()`
    Get database status information.
    _Return_: database status information in hashref.
- `$kt->clear()`
    Remove all elements for the storage.
    _Return_: Not a useful value.
- `$kt->synchronize($hard:Bool, $command);`
    Synchronize database with file system.
    _$hard_: call fsync() or not.
    _$command_: call $command in synchronization state.
    _Return_: 1 if succeeded, 0 if $command returns false.
- `$kt->set($key, $value, $xt);`
    Store _$value_ to _$key_.
    _$xt_: expiration time. If $xt>0, expiration time in seconds from now. If $xt<0, the epoch time. It is never remove if missing $xt.
    _Return_: not a useful value.
- `my $ret = $kt->add($key, $value, $xt);`
    Store record. This method is not store if the _$key_ is already in the database.
    _$xt_: expiration time. If $xt>0, expiration time in seconds from now. If $xt<0, the epoch time. It is never remove if missing $xt.
    _Return_: 1 if succeeded. 0 if $key is already in the db.
- `my $ret = $kt->replace($key, $value, $xt);`
    Store the record, ignore if the record is not exists in the database.
    _$xt_: expiration time. If $xt>0, expiration time in seconds from now. If $xt<0, the epoch time. It is never remove if missing $xt.
    _Return_: 1 if succeeded. 0 if $key is not exists in the database.
- `my $ret = $kt->append($key, $value, $xt);`
    Store the record, append the $value to existent record if already exists entry.
    _$xt_: expiration time. If $xt>0, expiration time in seconds from now. If $xt<0, the epoch time. It is never remove if missing $xt.
    _Return_: not useful value. 
- `my $ret = $kt->increment($key, $num, $xt);`
    _$num_: incremental
    _Return_: value after increment. 
- `my $ret = $kt->increment_double($key, $num, $xt);`
    _$num_: incremental
    _Return_: value after increment. 
- `my $ret = $kt->cas($key, $oval, $nval, $xt);`
    compare and swap.
    _$oval_: old value
    _$nval_: new value
    _Return_: 1 if succeeded, 0 if failed.
- `$kt->remove($key);`
    Remove _$key_ from database.
    _Return_ 1 if removed, 0 if record does not exists.
- `my $val = $kt->get($key);`
    Get _$key_ from database.
    _Return_: the value from database in scalar context. ($value, $xt) in list context. _undef_ or empty list  if not exists in database.
- `$kt->set_bulk(\%values);`
    Store multiple values in one time.
    _Return_: not useful value.
- `$kt->remove_bulk(\@keys);`
    Remove multiple keys in one time.
    _Return_: not useful value.
- `my $hashref = $kt->get_bulk(\@keys);`
    Get multiple values in one time.
    _Return_: records in hashref.
- `$kt->vacuum([$step]);`
    Scan the database and eliminate regions of expired records.
    _input_: step: (optional): the number of steps. If it is omitted or not more than 0, the whole region is scanned.
    _Return_: not useful.
- `my $hashref = $kt->match_prefix($prefix, $max);`
    Get list of matching keys.
    _Return_: records in hashref.
- `my $hashref = $kt->match_regex($regex, $max);`
    Get list of matching keys.
    _Return_: records in hashref.
- `my $hashref = $kt->match_similar($origin, $range, $utf8, $max);`
    Get list of matching keys.
    _Return_: records in hashref.
# AUTHOR
Tokuhiro Matsuno <tokuhirom AAJKLFJEF@ GMAIL COM>
# SEE ALSO
- `[KyotoTycoon](http://fallabs.com/kyototycoon/)`
- `http://fallabs.com/mikio/tech/promenade.cgi?id=99`
# LICENSE
Copyright (C) Tokuhiro Matsuno
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.