/ 
Games-Lacuna-Client-0.003
River stage zero No dependents
/ Games::Lacuna::Cache

NAME

Games::Lacuna::Cache - a caching mechanism for Games::Lacuna::Client

SYNOPSIS

use Games::Lacuna::Cache;
my $lacuna = Games::Lacuna::Cache->new(
                                       'cfg_file' => "/path/to/lacuna.yml",
                                       'cache_file' => "/path/to/lac_cache.dat",
                                       'cache_debug' => 1,
                                       'refresh' => 0
                                      );

my $empire_data = $lacuna->empire_data();
my $planet_data = $lacuna->planet_data($planet_id, $refresh);

DESCRIPTION

This module provides a caching mechanism for the Games::Lacuna::Client package.

METHODS

new

my $lacuna = Games::Lacuna::Cache->new( $refresh );

If $refresh is defined, the Cache will force a refresh of the data.

empire_data([$refresh])

Returns top level empire data

planet_data([$planet_id], [$refresh])

Returns planet data for $planet_id, or all bodies if you leave off the id. At the moment,

body_data([$body_id], [$refresh])

Ditto.

These should work pretty much as you expect. Cache stores partial information if it has it, and full information if you request it. That's because a lot of high level calls return a bit of data about the next level down (Empire gives planets, Body gives buildings, etc). So we store the partial to avoid hitting up a full call when all you want is the id. So empire_data will give you full empire data and partial planets (just ID and name). Planet_data will give you full data on the planet and partial (though fairly good) data on the buildings. building_data will give you full info on the building.

building_data([$building_id], [$refresh])

This might not work as you expect. By default, when we call body_data, we store partial info on buildings from a body->get_buildings() request. That's generally enough for pending build, recycling, etc. Calling building data with the refresh flag set will give you full info on that building.

The data structure returned from a full request consists of the main hash returned by the object->view() call, *and* other top level structures in the response. So if you call

my $spaceport = $lacuna->building_data($spaceport),

you'll get $spaceport->{'id'}, $spaceport->{'waste_hour'}, etc, but you'll also get $spaceport->{'docked_ships'}. Similarly, $recycler->{'recycle'} if it's in the middle of one.

NB REFRESH FLAG

The "refresh" flag may not work quite as you expect. It doesn't guarantee fresh info. It guarantees full data less than 25 minutes old (or whatever you set CACHE_TIME to). That's somewhat counterintuitive, and I should probably call it the "full" flag, but for the moment, this is what you get. The resource extrapolation works pretty well, so if you call "refresh" on a building for which we already have full info, you'll get that full info, with extrapolated resource values, but it might be a little old. If you absolutely must have up to the second data, there are convenience methods to call:

view_planet($planet_id)

view_building($building_id)

These are wrappers around the body->view_buildings (because that gives building info and full planet info) and building->view() client methods. These guarantee you up-to-the-second information about a planet or building, and they also cache the info.

list_buildings_on_planet($planet, [$array_ref])

my @filters = ("spaceport");
my @buildings = $lacuna->list_buildings_on_planet($planet, \@filters);

$planet will be a planet id. foreach my $planet (keys %$planet_data) from above will do.

@filters needs to contain valid building types of the kind found in a building url - "wasterecycling" or "spaceport". Feel free to implement a look up table for "Space Port" and "Trash Compactor" :)

The method returns a list of building ids, but it also creates client objects in the Cache OBJECT structure. So then you could say

foreach $building (@recyclers){
    my $object = $lacuna{'OBJECTS'}->{'buildings'}->{$building};
    $object->recycle();

or any similar client method. Don't use the object for view methods, though - use the helper methods above so data is cached (and actually just use cached data where you can)

Note objects do not persist between script calls, and are not shared between scripts.

DATA

OBJECTS

$lacuna->{'OBJECTS'}->{'buildings'} and $lacuna->{'OBJECTS'}->{'bodies'}

Stored by id. This just means you don't have to toss around the objects all the time.

$lacuna->{'OBJECTS'}->{$type}->{$id}->method(); should always work.

I think that's about it.

CAVEATS

It may stomp on disk data, but scripts should play friendly with each other. See how it goes.

You know the drill. Don't use it to run Fusion Power plants. Oh, wait....

AUTHOR

Jai Cornes, <solitaire@tygger.net>

COPYRIGHT AND LICENSE

Copyright (C) 2010 by Jai Cornes

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.0 or, at your option, any later version of Perl 5 you may have available.