Vim documentation: vital/System/Cache/File

vital/System/Cache/File.txt   A file based cache system

Maintainer: Alisue <lambdalisue@hashnote.net>


==============================================================================
CONTENTS                        Vital.System.Cache.File-contents

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


==============================================================================
INTRODUCTIONS                           Vital.System.Cache.File-intro

Vital.System.Cache.File is a file based unified cache system.
It stores a value into a file in a cache directory, mean that individual files
have one particular Vim object.
If you prefer to store keys and values into a single file, use
Vital.System.Cache.SingleFile instead.


==============================================================================
USAGE                                   Vital.System.Cache.File-usage

Vital.System.Cache.File have all required API of unified cache system and
store cache in a filesystem.
In the following example, Vital.System.Cache.File is used for memorize the
calculated values.

        let s:V = vital#{plugin-name}#new()
        let s:C = s:V.import('System.Cache.File')

        let s:factorial_cache = s:C.new({'cache_dir': '.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.File-functions

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

        Create a new instance of System.Cache.File.
        It requires 'cache_dir' option in {options}. If no 'cache_dir' is
        specified, it will throw an exception.
        The 'cache_dir' will automatically be created if missing.

hash({cache_dir}, {str})                Vital.System.Cache.File.hash()

        Return a hash string of {str} in {cache_dir}.
        It is used internally to distinguish.

load({filename}[, {default}])           Vital.System.Cache.File.load()

        Load a vim object from a {filename}. It uses sandbox and eval internally
        to build a vim object dumped by Vital.System.Cache.File.dump().
        If the {filename} is unreadable or the content of {filename} is empty,
        an empty dictionary or {default} (when specified) will be returned.

dump({filename}, {obj})                 Vital.System.Cache.File.dump()

        Dump a vim object ({obj}) into a {filename}.
        Use Vital.System.Cache.File.load() to restore the dumped vim object.


==============================================================================
METHODS                                 Vital.System.Cache.File-methods

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

        See Vital.System.Cache.Base-instance.cache_key()

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

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

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

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

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

        {name} (required)
        A name of the cache. An actual cache key will be created via
        Vital.System.Cache.File-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.File-instance.set()

        Save {value} into a cache directory as {name}.

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

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

keys()                  Vital.System.Cache.File-instance.keys()

        Return a list of cache keys

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

        Remove {name} from a cache directory. 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.File-instance.cache_key() method thus {name} is not
        required to be String.

clear()                 Vital.System.Cache.File-instance.clear()

        Clear all files in the cache directory without prompts.

        CAUTION
        It removes all files in the directory. Make sure the correct cache
        directory is specified in the instance.

on_changed()            Vital.System.Cache.File-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.File-instance.set()
        - Vital.System.Cache.File-instance.remove()
        - Vital.System.Cache.File-instance.clear()


==============================================================================
PROPERTIES                              Vital.System.Cache.File-properties

cache_dir               Vital.System.Cache.File-instance.cache_dir

        A directory path where cache files (keys) are saved.
        The directory need to be exists if users re-define this property after
        the Vital.System.Cache.File.new() function call.


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