load.txt Utility used for loading other plugins
=============================================================================
=============================================================================
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.
=============================================================================
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).
-----------------------------------------------------------------------------
The only command provided by this plugin. If variable
g:loadOptions exists and has key _cprefix, then prefix Load is
altered.
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.
for details.
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
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.
status for all plugins. Possible statuses: registered and loaded.
Find a function with number {nr}. Function is searched through
Display a number of function {fname}. {fname} must have the
following structure: /{plugname}/{pathToFunction}.
need to escape a backslash in {command}.
you need to escape a backslash in {command}.
Creates a session: two files, {filename} and {root}x.vim, where
{root} is {filename} with extension removed, see :mkssession for
implement session support in your plugin. This command always
overwrites existing files.
-----------------------------------------------------------------------------
This plugin provides only one global function: LoadFuncdict (prefix Load may
which loads the plugin and then calls LoadFuncdict(). This function returns
a dictionary with the following keys (each value is a function reference):
registerplugin({regdict})
Register plugin. For the meaning of the argument see load-reg.
Returns a dictionary with following keys:
Key Value
about how it is constructed.
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
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
exists, then add
{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
failure. If exists
check obtained option by function
check failed. Note that all option names starting
with underscore are reserved.
Unregister plugin. For {plugname} and {plugtype} arguments see
1. delete all global functions;
2. delete all commands;
3. remove plugin dictionary.
argument provided when plugin {plugname} was registered. For
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 function {funcname} from dictionary {dict} with arguments
{arg1}..{argN} (N may be 0). If {dict} was obtained by
plugin and then run the function. Trows an exception, if function is
not found in dictionary.
Register an autocommand. For a description of {event} see
{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}.
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}.
Restore additional session information stored by
by yourself, it should be used from session file only.
There are also some convenience functions in autoload/load.vim file:
optional {plugname} argument is provided, then it calls
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.
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)")
-----------------------------------------------------------------------------
This plugin provides a way to run custom hooks on the following events:
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.
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.
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.
key) then this event occures just after
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.
key) then this event never occures.
Just before unloading the plugin.
Just after unloading the plugin.
=============================================================================
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:
dictfunctions :: [({dictname}, {internalname}, {check})]
List of lists of three items:
{dictname} any string, which will be the function name in the
{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
more details.
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.
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.
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
Dictionary with plugin functions. The load plugin assumes that all
functions are declared as dictionary functions inside this
dictionary.
Dictionary with global script variables. The load plugin assumes that
this dictionary is the only s: variable declared in the plugin.
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.
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
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.
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.
Defines the mapping leader.
The script id obtained by s:SID function called in the plugin. See
<SID> for more details.
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.
Defines whether plugin needs to be autoloaded (defines whether plugin
file needs to be sourced twice before plugin is actually ready to
work).
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.
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
{PlugType} is not given it is assumed to be equal to `plugin'.
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.
=============================================================================
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.
=============================================================================
options:
Global. This options override command and function prefixes provided
This option provides a way to override default values given in
{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
that `{-...-}' is stripped before checking for `+'. Empty string
disables mapping.
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:
loading of plugins that use it. On by default, should be turned off by
plugin developers.
vim: ft=help:tw=78