load.txt    Utility used for loading other plugins
=============================================================================
CONTENTS                                                     load-contents
    1. Intro                                      load-intro
    2. Functionality provided                     load-functionality
        2.1. Commands                             load-commands
        2.2. Functions                            load-functions
        2.3. `Autocommands'                       load-autocommands
    3. Plugin registration                        load-reg
    4. Sessions                                   load-sessions
    5. Options                                    load-options
=============================================================================
1. Intro                                                        load-intro
This plugin provides the ability to autoload other plugins on demand, create 
global functions and commands and share plugin's functionality.
Features:
    ∙ Autoloading plugins on FuncUndefined event.
    ∙ Autoloading plugins when their command is called.
    ∙ Autoloading plugins when their mapping is used.
    ∙ Autoloading plugins when their functionality is required.
    ∙ Displaying plugins' status.
    ∙ Unloading and reloading plugins.
    ∙ Searching for a function number through registered plugins.
This plugin requires chk plugin.
=============================================================================
2. Functionality provided                               load-functionality
This plugin provides one command and one function. Both command and function 
names start with Load, but this prefix can be altered by _fprefix and _cprefix 
options in g:loadOptions dictionary (Note that it is a very bad idea).
-----------------------------------------------------------------------------
2.1. Commands                                                load-commands
                                                              load-actions
:LoadCommand {action} ...                     load-:Command :LoadCommand
            The only command provided by this plugin. If variable 
            g:loadOptions exists and has key _cprefix, then prefix Load is 
            altered.
:LoadCommand unload {plugin}                            load-action-unload
            Unload plugin named {plugin} and all plugins that depend on it.
            Unloading is done in the following order:
            0. If plugin is not already loaded it is first loaded and only 
               then unloaded.
            1. Plugin is unregistered. See load-func-unreg.
            2. load-reg-F.main.destruct function is called. See load-reg-F 
               for details.
            3. load-reg-g and load-reg-F variables are unlocked.
            4. All keys in load-reg-g and load-reg-F are deleted.
            In order to be able to be unloaded correctly your plugin must 
            follow the following rules:
            1. Put all functions into s:F dictionary and use it as 
               load-reg-F. If some function cannot be put into dictionary 
               (for example, because you cannot use script variables in 
               mappings), then this function should be deleted in 
               s:F.main.destruct function.
            2. Put all script variables into s:g dictionary and use it as 
               load-reg-g. Use dictionary where keys are buffer numbers 
               instead of buffer variables. If you still require to modify 
               external variables, then they should be reset in 
               s:F.main.destruct function.
            3. Do other cleanup (like deleting completion function created by 
               comp.vim plugin) inside s:F.main.destruct.
            4. Last three lines of s:F.main.destruct must be >
                    unlet s:g
                    unlet s:F
                    return 1
:LoadCommand reload {plugin}                            load-action-reload
            Reload plugin named {plugin}. Just like load-action-unload, but 
            after unloading load-reg-files are sourced. Note that reloading 
            some widely used plugins like vimargumentchec (chk) or even this 
            (load) plugin itself may render other plugins useless.
:LoadCommand show                                         load-action-show
            Show load-reg-scriptidload-reg-nameload-reg-file and 
            status for all plugins. Possible statuses: registered and loaded. 
            See load-reg for details.
:LoadCommand findnr {nr}                                load-action-findnr
            Find a function with number {nr}. Function is searched through
            load-reg-F variables of plugins.
:LoadCommand nrof {fname}                                 load-action-nrof
            Display a number of function {fname}{fname} must have the 
            following structure: /{plugname}/{pathToFunction}.
:LoadCommand autocmd {event} {plugin} {command}        load-action-autocmd
            Create an `autocommand', see load-autocommands. For 
            a description of arguments see load-func-autocmdNote that you 
            need to escape a backslash in {command}.
:LoadCommand autocmd! {event}{plugin}{command}]]  load-action-autocmd!
            Delete an `autocommand', see load-autocommands. For 
            a description of arguments see load-func-delautocmdNote that 
            you need to escape a backslash in {command}.
:LoadCommand mksession {filename}                    load-action-mksession
            Creates a session: two files, {filename} and {root}x.vim, where 
            {root} is {filename} with extension removed, see :mkssession for 
            information about filenames and load-sessions about how to 
            implement session support in your plugin. This command always 
            overwrites existing files.
-----------------------------------------------------------------------------
2.2. Functions                                              load-functions
                                   load-func-LoadFuncdict LoadFuncdict()
This plugin provides only one global function: LoadFuncdict (prefix Load may 
be altered, but this is a very bad idea). You can also use load#LoadFuncdict() 
which loads the plugin and then calls LoadFuncdict(). This function returns 
a dictionary with the following keys (each value is a function reference):
                                                  load-func-registerplugin
registerplugin({regdict})
            Register plugin. For the meaning of the argument see load-reg
            Returns a dictionary with following keys:
            Key        Value
            name       Name of the plugin, see load-reg-name for information 
                       about how it is constructed.
            type       Type of the plugin, see load-reg-name for information 
                       about how it is obtained.
            functions  Some useful functions:
                       eerror({srcname}{etype}{arg1}, ...)
                            Display the error message with pattern
                                {plugtype}/{plugname}/{srcname}:{etypestr}({msgs})
                            Here {plugtype} stands for plugin type, {plugname} 
                            for plugin name (see the `name' and `type' keys 
                            above), {srcname} is a string provided as the 
                            first argument, {etypestr} is a string obtained 
                            from load-reg-g.etype[{etype}] (or empty string 
                            if it does not exist) and {argN} are handled in 
                            following way:
                            1. If {arg1} (only {arg1}, not {argN}) is 
                               a non-zero number then throw error message 
                               after echoing it.
                            2. If {argN} is a list, its first value is 
                               a string and load-reg-g.emsg[{argN}[0]] 
                               exists, then add 
                               printf(load-reg-g.emsg[{argN}[0]], {argN}[1], 
                               {argN}[2], ...) to {msgs}.
                            3. In other cases add {argN} to {msgs}.
                            String {msgs} is a list of strings separated by
                            ": ".
                        option({optname})
                            Try getting option named {optname} first from 
                            b:{optionPrefix}Options, then from 
                            g:{optionPrefix}Options and finally from 
                            load-reg-g.defaultOptions. Throw an exception on 
                            failure. If exists 
                            load-reg-g.c.options[{optname}], then use it to 
                            check obtained option by function 
                            chk-func-checkargument. Throw an exception if 
                            check failed. Note that all option names starting 
                            with underscore are reserved.
unregister({plugname}[, {plugtype}])                  load-func-unregister
        Unregister plugin. For {plugname} and {plugtype} arguments see 
        load-reg-name. “Unregister” means:
        1. delete all global functions;
        2. delete all commands;
        3. remove plugin dictionary.
getfunctions({plugname}[, {plugtype}])             load-func-getfunctions
        Get the dictionary functions listed in load-reg-dictfunctions 
        argument provided when plugin {plugname} was registered. For 
        {plugname} and {plugtype} arguments see load-reg-name.
                                               load-func-lazygetfunctions
lazygetfunctions({plugname}[, {plugtype}])
        Get the dictionary which will be populated with plugin's dictionary 
        functions when this plugin will be loaded. Can be used to resolve 
        cyclic dependencies. See load-func-run for information about how to 
        run functions from this dictionary.
run({dict}{funcname}[, {arg1}[, ...]])                    load-func-run
        Run function {funcname} from dictionary {dict} with arguments 
        {arg1}..{argN} (N may be 0). If {dict} was obtained by 
        load-func-lazygetfunctions and was not modified then first load the 
        plugin and then run the function. Trows an exception, if function is 
        not found in dictionary.
autocmd({event}{plugin}{command})                   load-func-autocmd
        Register an autocommand. For a description of {event} see 
        load-autocommands{plugin} is any string of a form 
        {plugtype}/{plugname}{command} is either a string which will be 
        executed (see :execute) or a function reference which will be called 
        with two arguments: {event} and {plugin}.
delautocmd({event}[, {plugin}[, {command}]])         load-func-delautocmd
        Delete `autocommand(s)': if only {event} is given, then all 
        `autocommands' attached to this event are cleared. If {plugin} is 
        given, then it deletes all `autocommands' associated with the given 
        event and given plugin (if any). If both {plugin} and {command} 
        arguments are given, then it filters out all autocommands that match 
        all of {event}{plugin} and {command}.
restoresession({filename})                        load-func-restoresession
        Restore additional session information stored by 
        load-action-mksessionNote that you should not call this function 
        by yourself, it should be used from session file only.
There are also some convenience functions in autoload/load.vim file:
load#LoadFuncdict([{plugname}[, {plugtype}]])          load#LoadFuncdict()
        Calls LoadFuncdict(), loads the plugin if it is not defined. If the 
        optional {plugname} argument is provided, then it calls 
        load-func-getfunctions.
load#Setoption({dictname}{key}{value}[, {extend}])    load#Setoption()
        Sets the value of {key} in dictionary with name {dictname} to {value} 
        if it is possible. If {extend} is given and is 1, then try to extend 
        existing option instead of overwriting it. Some notes:
        1. If variable {dictname} does not exist it will be created.
        2. If variable {dictname} does not contain a dictionary, it will be 
           reset to an empty dictionary without notice.
        3. If {key} is locked, it will be unlocked without notice and will not 
           be locked again.
        4. If {extend} is given, but {key} cannot be extended with {value}
           then it will be overwritten without notice.
        5. If setting an option failed, then function will return 0, otherwise 
           it will return a dictionary. No error will be echoed anyway.
load#CreateDictFunction({arguments}{body})     load#CreateDictFunction()
        Creates a dictionary function with given arguments and body. The 
        advantage of creating a dictionary function using this function is 
        that created function will be unable to get access to script 
        variables. For example, to create an eval() function that does not 
        have access to script variables you should do the following call: >
            let s:F.safeeval=load#CreateDictFunction("s", "return eval(a:s)")
-----------------------------------------------------------------------------
2.3. `Autocommands'                                      load-autocommands
This plugin provides a way to run custom hooks on the following events:
RegisterPluginPre                                load-au-RegisterPluginPre
        Before plugin registration. Note that there is no way to catch this 
        event for a load plugin as it must be loaded before you are able to 
        define any autocommand.
RegisterPluginPost                              load-au-RegisterPluginPost
        After plugin registration. Note that there is no way to catch this 
        event for a load plugin as it must be loaded before you are able to 
        define any autocommand.
LoadPluginPre                                        load-au-LoadPluginPre
        After plugin registration, before plugin is sourced second time.
        Some note's:
        1. There is no way to catch this event for a load plugin as it must be 
           loaded before you are able to define any autocommand.
        2. If plugin is sourced only once (if it defines load-reg-oneload 
           key) then this event occures just after 
           load-au-RegisterPluginPre.
LoadPluginPost                                      load-au-LoadPluginPost
        After plugin is sourced second time.
        Some note's:
        1. There is no way to catch this event for a load plugin as it must be 
           loaded before you are able to define any autocommand.
        2. If plugin is sourced only once (if it defines load-reg-oneload 
           key) then this event never occures.
UnloadPluginPre                                    load-au-UnloadPluginPre
        Just before unloading the plugin.
UnloadPluginPost                                  load-au-UnloadPluginPost
        Just after unloading the plugin.
=============================================================================
3. Plugin registration                                            load-reg
Registration is done via calling load-func-register function with a single 
dictionary as an argument. The following keys are required: oprefix, funcdict, 
globdict, sid, scriptfile, apiversion. Possible keys:
                                                    load-reg-dictfunctions
dictfunctions :: [({dictname}{internalname}{check})]
        List of lists of three items:
        {dictname}     any string, which will be the function name in the
                       dictionary returned by load-func-getfunctions.
        {internalname} string, which consist of alphanumeric characters,
                       underscores and dots, where dot does neither start nor 
                       end the string. Dictionary function with name 
                       load-reg-F.{internalname} must exist. Value returned 
                       by this function will be returned by {dictname} 
                       dictionary function.
        {check}        Argument check for a function or an empty dictionary if
                       no check is required. See chk-func-checkarguments for 
                       more details.
fprefix :: String                                         load-reg-fprefix
        String which starts either with g: or with uppercase latin letter and 
        contains any number of latin letters, digits and underscores. It is 
        the default function prefix for plugin being registered. You must not 
        use this key unless `functions' key is present.
cprefix :: String                                         load-reg-cprefix
        String which starts with uppercase latin letter and contains any 
        number of latin letters, digits and underscores. It is the default 
        command prefix for plugin being registered. You must not use this key 
        unless `commands' key is present.
oprefix :: String                                         load-reg-oprefix
        String, which contains any number of latin letters, digits and 
        underscores. It is used to construct option dictionary name 
        (g:{oprefix}Options), which is used to get custom command (from 
        g:{oprefix}Options._cpferix) and function (from 
        g:{oprefix}Options._fprefix) prefixes, and also to get options by an 
        option function (see load-func-registerplugin).
                                                                load-reg-F
funcdict :: Dictionary                                   load-reg-funcdict
        Dictionary with plugin functions. The load plugin assumes that all 
        functions are declared as dictionary functions inside this 
        dictionary.
                                                                load-reg-g
globdict :: Dictionary                                   load-reg-globdict
        Dictionary with global script variables. The load plugin assumes that 
        this dictionary is the only s: variable declared in the plugin.
commands :: Dictionary                                   load-reg-commands
        Dictionary {{CmdTail}{Arguments}}, where arguments is a dictionary 
        with the following keys:
        Key       Value
        func      string, which consist of alphanumeric characters,
                  underscores and dots, where dot does neither start nor end 
                  the string. Dictionary function with name 
                  load-reg-F.{internalname} must exist. This function is 
                  called when the command {cprefix}{CmdTail} is run. Arguments 
                  of the function (depending on other keys, some of them may 
                  not be present):
                  '<bang>', '<reg>', <LINE1><LINE2><count><f-args>.
        nargs     “+”, “?”, “*”, “0”, natural number or an empty string.
                  See :command-nargs. Adds <f-args> to the function 
                  arguments.
        range     “%”, non-negative number or an empty string.
                  See :command-range. Adds <LINE1> and <LINE2> to function 
                  arguments.
        count     Non-negative number or an empty string.
                  See :command-count. Adds <count> to function arguments.
        bang      Emty string. See :command-bang.
                  Adds '<bang>' to function arguments.
        bar       Emty string. See :command-bar.
        reg       Emty string. See :command-register.
                  Adds '<reg>' to function arguments.
        complete  Non-empty string. See :command-complete for possible
                  values. Note that for custom completion function it must be 
                  equal either to custom=s:{FunctionName} or 
                  customlist=s:{FunctionName}. In both cases 
                  load-reg-F.comp.{FunctionName} function must exist because 
                  it will be silently (see :silent) called instead of 
                  s:{FunctionName}.
        This key is used to construct plugin's commands. Note that existing 
        commands will not be redefined. Key `cprefix' must also be present.
                                                        load-reg-functions
functions :: [({functiontail}{internalname}{check})]
        List of lists of three items:
        {functiontail} string, which consist of any number of latin letters,
                       digits and underscores. It is used to construct plugin 
                       global function's name ({fprefix}{functiontail}).
        {internalname} string, which consist of alphanumeric characters, 
                       underscores and dots, where dot must not start or end 
                       the string or follow another dot. Dictionary function 
                       with name load-reg-F.{internalname} must exist. Value 
                       returned by this function will be returned by 
                       constructed function.
        {check}        Argument check for a function or an empty dictionary if
                       no check is required. See chk-func-checkarguments for 
                       more details.
        This key is used to construct plugin's global functions. Note that 
        existing functions will not be redefined. Key `fprefix' must also be 
        present.
mappings :: {{MapName}{MapOptions}}                    load-reg-mappings
        Dictionary where keys are map names (names that start with underscore 
        are reserved, they also must not start with `+') and values are 
        dictionaries with the following keys:
        Key       Description
        function  String, which consist of alphanumeric characters, 
                  underscores and dots, where dot must not start or end the 
                  string or follow another dot. Required Dictionary function 
                  with name load-reg-F.{function} must exist. Value returned 
                  by this function is used as {rhs} of the mapping, see 
                  :map-<expr>. This function must take four arguments: type 
                  of mapping (one character, see below), mapping name, 
                  sequence of keys which invoked it (mapping string) and 
                  buffer number, if it was mapping local to buffer or -1 if it 
                  was not.
        default   String, defines a default {lhs} of the mapping. May be 
                  overriden by g:{oprefix}Options._maps.
        type      Char, defines a type of the mapping. Possible types and 
                  corresponding commands:
                  Type        Command
                  " " (space) noremap
                   !          noremap!
                  n, v, x, s, o, i, l, c
                              {Type}noremap
        silent    Bool. If true, then <silent> argument is added to the map 
                  command.
        leader    Bool. If true, then either load-reg-leader or 
                  load-opt-_leader is prepended to the default mapping.
leader :: String                                           load-reg-leader
        Defines the mapping leader.
sid :: String                                            load-reg-scriptid
        The script id obtained by s:SID function called in the plugin. See 
        <SID> for more details.
                                                             load-reg-name
scriptfile :: String                                   load-reg-scriptfile
        The script filename. It is used to autoload plugin and also to get 
        a plugin name. Must end with `.vim'. Here is a way how plugin name is 
        constructed:
        0. Resolve given path to full path (using %:p path modifier).
        1. Get last path component without extension and remove it (see %:t 
           and %:r path modifiers description).
        2. Remove tail path components until last path component will not 
           match one of the following strings: `plugin', `autoload', 
           `ftplugin', `ftdetect', `syntax', `indent', `colors', `keymap' or 
           `compiler' (yes, they all are names of special folders in vim 
           runtime directory). If it is found, this component is remembered as 
           a script type. If it is not, then script type will be `/unknown'.
        3. Join all removed path components (except those with type) with `/'. 
           This will be a plugin name.
oneload :: Bool                                           load-reg-oneload
        Defines whether plugin needs to be autoloaded (defines whether plugin 
        file needs to be sourced twice before plugin is actually ready to 
        work).
apiversion :: String                                   load-reg-apiversion
        String, defines the api version. Must consist of a number (unsigned 
        integer) followed by a dot and another unsigned integer. Everything 
        after this is ignored.
                                                         load-reg-requires
requires :: [({PlugName}{APIVersion}[, {PlugType}])]
        List of lists of two or three items. Defines requirements for the 
        plugin. Requirements are considered satisfied if {PlugName} was 
        loaded, its major api version number is equal to the one specified in 
        {APIVersion} and minor api version number greater then or equal to the 
        one specified in {APIVersion}. Minor api version number may be 
        omitted. {APIVersion} has syntax equal to load-reg-apiversion. If 
        {PlugType} is not given it is assumed to be equal to `plugin'.
preload :: [({PlugName}[, {PlugType}])]                  load-reg-preload
        List of lists of one or two items. Defines requirements for the plugin 
        that do not use pluginloader. Requirements are considered satisfied if 
        {PlugType}/{PlugName} was sourced. Note that you must not disable 
        SourcePre events in order to get this work.
=============================================================================
4. Sessions                                                 load-sessions
All plugins that use vim plugin loader can easily implement a sessions 
support: all you need is to define load-reg-F.main.session function which 
will take either no or one argument. When session file is created using 
load-action-session, this function will be called with no arguments and its 
result will be stored in {root}x.vim file ({root} is a session file name with 
extension removed). When session is restored, this function will be called 
with the only argument: value stored on previous step.
=============================================================================
5. Options                                                   load-options
Plugin registered by load-func-registerplugin automatically gets some 
options:
_cprefix :: String                                      load-opt-_cprefix
_fprefix :: String                                      load-opt-_fprefix
        Global. This options override command and function prefixes provided 
        to load-func-registerplugin. They have the same restrictions as 
        load-reg-cprefix and load-reg-fprefix.
_maps :: {{MapName}: String}                               load-opt-_maps
        This option provides a way to override default values given in 
        load-reg-mappings either locally (local to buffer) or globally. If 
        {MapName} starts with `{-' and contains string `-}', then everything 
        between starting `{-' and first occurence of `-}' is stripped, 
        providing a way to map several strings to one {MapName}. If {MapName} 
        starts with `+' then `+' is stripped and plugin mapping leader is 
        prepended to the string (see load-opt-_leader for details). Note 
        that `{-...-}' is stripped before checking for `+'. Empty string 
        disables mapping.
_leader :: String                                        load-opt-_leader
        Overrides plugin mapping leader provided in load-reg-leader.
_disablemaps :: Bool                                load-opt-_disablemaps
        Global. If true then all plugin mappings are disabled. May be set to 
        1 in load-reg-g.defaultOptions in order to disable mappings by
        default.
This plugin also has its own options:
DisableLoadChecks :: Bool                      load-opt-DisableLoadChecks
        Disables checking of load-func-registerplugin argument, speeding up 
        loading of plugins that use it. On by default, should be turned off by 
        plugin developers.
vim: ft=help:tw=78