*vital/System/Cache/SingleFile.txt*	A single file based cache system

Maintainer: Alisue <lambdalisue@hashnote.net>


==============================================================================
CONTENTS			*Vital.System.Cache.SingleFile-contents*

Introductions		|Vital.System.Cache.SingleFile-intro|
Usage			|Vital.System.Cache.SingleFile-usage|
Functions		|Vital.System.Cache.SingleFile-functions|
Methods			|Vital.System.Cache.SingleFile-methods|
Properties		|Vital.System.Cache.SingleFile-properties|


==============================================================================
INTRODUCTIONS				*Vital.System.Cache.SingleFile-intro*

*Vital.System.Cache.SingleFile* is a single file based cache system.
It stores a cache dictionary into a single cache file, mean that it is similar
to |Vital.System.Cache.Memory| but the cache is persistent.
If you prefer to store key and value into individual files, use
|Vital.System.Cache.File| instead.


==============================================================================
USAGE					*Vital.System.Cache.SingleFile-usage*

|Vital.System.Cache.SingleFile| have all required API of unified cache system and
values are stored in a |Dictionary| instance.
In the following example, |Vital.System.Cache.SingleFile| is used for memorize
the calculated values.
>
	let s:V = vital#{plugin-name}#new()
	let s:C = s:V.import('System.Cache.SingleFile')

	let s:factorial_cache = s:C.new({'cache_file': '.cache'})

	function! s:factorial(n)
	  if a:n == 0
	    return 1
	  elseif s:factorial_cache.has(a:n)
	    return s:factorial_cache.get(a:n)
	  else
	    let x = s:factorial(a:n - 1) * a:n
	    call s:factorial_cache.set(a:n, x)
	    return x
	  endif
	endfunction

	echo s:factorial(10)
<

==============================================================================
FUNCTIONS				*Vital.System.Cache.SingleFile-functions*

new([{options}])			*Vital.System.Cache.SingleFile.new()*

	Create a new instance of System.Cache.SingleFile.
	It requires 'cache_file' option in {options}. If no 'cache_file' is
	specified, it will throw an exception.
	The parent directory of 'cache_file' will automatically be created if
	missing.
	Users can use a 'autodump' option in {options} to set the initial value
	of |Vital.System.Cache.SingleFile-instance.autodump|.


==============================================================================
METHODS					*Vital.System.Cache.SingleFile-methods*

dump()			*Vital.System.Cache.SingleFile-instance.dump()*

	Dump a cache content into the 'cache_file'.
	It will be automatically called when the cache content is changed if
	|Vital.System.Cache.SingleFile-instance.autodump| is 1. Otherwise users
	need to call this method to dump the cache content into a cache file.

load()			*Vital.System.Cache.SingleFile-instance.load()*

	Load a cache content from the 'cache_file'.
	It will be automatically called when the cache instance is created (in
	|Vital.System.Cache.SingleFile.new()|.
	Users can call this method to load the cache content manually.
	Note that this method call may trigger to call
	|Vital.System.Cache.SingleFile-instance.on_changed()| hook.

cache_key({obj})	*Vital.System.Cache.SingleFile-instance.cache_key()*

	See |Vital.System.Cache.Base.cache_key()|

has({name})		*Vital.System.Cache.SingleFile-instance.has()*

	Return 1 if the cache instance has {name} in its cache dictionary.
	Otherwise 0.

	{name} (required)
	A name of the cache. An actual cache key will be created via
	|Vital.System.Cache.SingleFile-instance.cache_key()| method thus {name}
	is not required to be |String|.

                        *Vital.System.Cache.SingleFile-instance.get()*
get({name}[, {default}])

	Return a cached value of {name} in a cache dictionary. It return
	{default} if no value is found.

	{name} (required)
	A name of the cache. An actual cache key will be created via
	|Vital.System.Cache.SingleFile-instance.cache_key()| method thus {name}
	is not required to be |String|.

	{default} (optional)
	A default value. It will be returned when no value is found in the
	cache dictionary.

set({name}, {value})	*Vital.System.Cache.SingleFile-instance.set()*

	Save {value} into a cache dictionary as {name} and dump the cache
	dictionary into 'cache_file'.

	{name} (required)
	A name of the cache. An actual cache key will be created via
	|Vital.System.Cache.SingleFile-instance.cache_key()| method thus {name}
	is not required to be |String|.

	{value} (required)
	A value of the cache.

keys()			*Vital.System.Cache.SingleFile-instance.keys()*

	Return a list of cache keys

remove({name})		*Vital.System.Cache.SingleFile-instance.remove()*

	Remove {name} from a cache dictionary and dump the cache dictionary
	into 'cache_file'. It does nothing when the specified {name} is not
	found in the cache.

	{name} (required)
	A name of the cache. An actual cache key will be created via
	|Vital.System.Cache.SingleFile-instance.cache_key()| method thus {name}
	is not required to be |String|.

clear()			*Vital.System.Cache.SingleFile-instance.clear()*

	Clear a cache dictionary and dump the cache dictionary into
	'cache_file'.

on_changed()		*Vital.System.Cache.SingleFile-instance.on_changed()*

	A user defined hook method. This method is called when the content of
	the cache is changed, namely after the following methods:
	- |Vital.System.Cache.SingleFile-instance.set()|
	- |Vital.System.Cache.SingleFile-instance.remove()|
	- |Vital.System.Cache.SingleFile-instance.clear()|
	- |Vital.System.Cache.SingleFile-instance.load()|


==============================================================================
PROPERTIES			*Vital.System.Cache.SingleFile-properties*

cache_file		*Vital.System.Cache.SingleFile-instance.cache_file*

	A file path where the cache content is saved.
	The directory of this file need to be exists if users re-define this
	property after the |Vital.System.Cache.SingleFile.new()| function call.

autodump		*Vital.System.Cache.SingleFile-instance.autodump*

	A boolean to enable/disable autodump feature.
	If the value is 1, |Vital.System.Cache.SingleFile-instance.dump()|
	will be automatically calledn when the cache content is changed.
	Otherwise users need to call the method manually to dump the cache
	content into a cache file.


vim:tw=78:fo=tcq2mM:ts=8:ft=help:norl
