View source for Cache Library

= Creating a cache instance =
'''object Cache()'''

'''object Cache(string driver)'''

'''object Cache(string driver, table config)'''

The cache library is optional and the module must be required before use. Next, the cache class must be instantiated:
<source lang="lua">
require('cache/cache');

cache = Cache();
</source>

You may optionally specify which driver you want to use and a table of configuration options (see driver details for more info).

= Drivers =
Various drivers may be used which determine how cached data will be handled. Each driver may have its own set of pros and cons. For instance the 'memory' driver should give great speed, but may consume a lot of memory, will not be saved to disk (the data disappears once the script terminates), and will not share data between instances. By default, the DB driver is used.


== DB Driver ==
This will use SQLite internally to handle data. It should give good speed, but the primary benefit is that it will continually save to disk and all data will be shared across multiple instances. Using this driver will result in data being saved to 'cache.db' in the executing script's directory. You can explicitly create an instance of the DB driver by instantiating with the 'db' driver name:
<source lang="lua">
cache = Cache('db');
-- OR: --
local settings = {
  file = 'mycachefile.db',
  table = 'cachetable',
};
cache = Cache('db', settings);
</source>


Optional configurations:
{| class="wikitable" style="padding: 8px;"
|-
| style="width: 150px;" | file
| The filename (and optionally path) of the file to use for storing the database; by default this is 'cache.db'
|-
| table
| The name of the table to use for storing cache data; by default this is 'cache'
|-
|}

== Memory Driver ==
This will store cached data directly into the Lua engine's memory space. Speed should be great, but storing lots of cached data will require more memory. Cached information should be considered volatile; any cached data will be immediately lost as soon as the script terminates. Additionally, multiple instances of your script will not share data between them. You can explicitly create an instance of the memory driver by instantiating with the 'memory' driver name:
<source lang="lua">
cache = Cache('memory');
</source>



= Example usage =
<source lang="lua">
require('cache/cache');

function macro.init()
  cache = Cache(); -- Use the default cache driver
end

function macro.main()
  -- Returns the existing value, or generates and returns a new one
  local value = cache:remember('testValue', 1, function() return string.random('alnum', 16) end);

  print("Cached value:", value);
end
</source>



= Supported methods =

== Cache:driverName ==
'''string Cache:driverName()'''

Returns the 'name' of a driver for descriptive use only.


== Cache:get ==
'''value Cache:get(string itemName, defaultValue)'''

Returns a value from the cache if the item exists and is not expired, otherwise returns defaultValue or nil. In most cases you will probably want to either grab a cached value or set and return a new value, and so it is recommended to use [[Cache_Library#Cache:remember|Cache:remember()]] instead.


== Cache:has ==
'''boolean Cache:has(string itemName)'''

Returns true if an item exists and is not expired, otherwise returns false.


== Cache:set ==
'''Cache:set(string itemName, value, minutes)'''
'''Cache:set(string itemName, value)'''

Sets an item in the cache that will expire in the number of minutes denoted by 'minutes'. If 'minutes' is not given, a value of 1 is assumed. If the item should never expire, pass a negative number for 'minutes.'


== Cache:remember ==
'''value Cache:remember(string itemName, number minutes, function callback)'''

If the item exists and is not expired, the cached value is returned. Otherwise, the callback function will be called (which should return the value you want to be set) and used as the item's new value which expires in 'minutes' from now; again a negative 'minutes' value indicates it should never expire (or use [[Cache_Library#Cache:rememberForever|Cache:rememberForever()]]). If the callback is used to generate a new value, that value is the one returned by this function.


== Cache:rememberForever ==
'''value Cache:rememberForever(string itemName, function callback)'''

Exactly like [[Cache_Library#Cache:remember|Cache:remember()]], only the item is set to never expire.


== cache:renew ==
'''Cache:renew(string itemName, number minutes)'''

Updates the expires_at timestamp for an item so that it will expire in 'minutes' from now. If 'minutes' is nil, the item is set to never expire.


== Cache:forget ==
'''Cache:forget(string itemName)'''

Removes an item from the cache, regardless of whether it is still valid, expired, or set to never expire.


== Cache:flush ==
'''Cache:flush()'''

Removes all items from the cache.