frawor.txt Vim frameworkLINK


CONTENTS frawor-contentsLINK

1. Intro frawor-intro

2. Functionality provided frawor-functionality

2.1. Functions frawor-functions

2.2. Commands frawor-commands

3. Features frawor-features

3.1. Features defined in @frawor frawor-f-@frawor

3.2. @/functions features frawor-f-@/functions

3.3. @/decorators features frawor-f-@/decorators

3.4. @/decorators/altervars features frawor-f-@/decorators/altervars

3.5. @/options features frawor-f-@/options

3.6. @/checks features frawor-f-@/checks

3.7. @/fwc features frawor-f-@/fwc

3.8. @/mappings features frawor-f-@/mappings

3.9. @/autocommands features frawor-f-@/autocommands

3.10. @/commands features frawor-f-@/commands

3.11. @/resources features frawor-f-@/resources

3.12. @/python features frawor-f-@/python

3.13. @/perl features frawor-f-@/perl

3.14. @/lua features frawor-f-@/lua

3.15. @/ruby features frawor-f-@/ruby

3.16. @/tcl features frawor-f-@/tcl

3.17. @/signs features frawor-f-@/signs

4. Resources frawor-resources

4.1. map resource frawor-r-map

4.2. os resource frawor-r-os

4.3. printtable resource frawor-r-printtable

4.4. base64 resource frawor-r-base64

4.5. sign resource frawor-r-sign

4.6. history resource frawor-r-history

4.7. new_constructor resource frawor-r-new_constructor

5. Options frawor-options

5.1. Mapping options frawor-mapoptions

6. Type definitions frawor-types

7. Variables index frawor-variables

8. Changelog frawor-changelog


1. Intro frawor-introLINK

This plugin provides extensible vim framework.


2. Functionality provided frawor-functionalityLINK


2.1. Functions frawor-functionsLINK


FraworRegister({version}, {sid}, {file}, {dependencies}, {g})

Registers plugin sourced from {file} that has given {version} (see

frawor-t-version; {version} must have at least two components).

{dependencies} argument is a dictionary that contains pairs

{{depplid}: {depversion}} where each {depversion} must have at least

one component. {g} argument must contain dictionary with script-local

variable (s:, see internal-variables, a paragraph just after a list

of name spaces). This function sets s:_frawor to the dictionary with

the following keys:

Key Description

id Plugin identifier string. Normally it contains a list of

path components of script file separated by `/' with

leading runtimepath and extension removed. If plugin with

such id already exists, trailing `/' is added.

runtimepath Runtimepath of your plugin (empty if frawor failed to

detect it).

type First component of plugin file path that is not part of

runtimepath (or `/unknown' if frawor failed to detect


It sets s:_pluginloaded to 1.


If some key in {dependencies} dictionary starts with `@', then it is


Origin Transformed

@/ autoload/frawor/

@: ftplugin/

@% autoload/

@@ @

@ plugin/

There two special cases: `^' gets expanded to plugin id without one

component (but with trailing slash) and `@.' gets expanded to plugin

id (both only for {dependencies} dictionary and frawor-f-require).


You may specify 0 instead of {version}. In this case plugin type will

be `/anonymous', plugin id will be equal to `file' argument (possibly

with some trailing `/' added), runtimepath will be empty. In this case

you may use s:_sfile variable to tell frawor what should be sourced to

load plugin.

frawor#Setup({version}, {dependencies}) frawor#Setup()LINK

If :executed, does some common setup:

1. If {version} or some value in {dependencies} is a dot-separated

list of numbers, then it is transformed into List of Numbers.

Example: "1.0.4" → [1, 0, 4].

2. It creates s:Eval function which is just a wrapper to eval().

Useful inside mappings because they have no direct access to script

variables and for obtaining <SID> value.

3. It creates s:F variable containing a dictionary, s:_functions list

containng string "s:Eval".

4. Creates s:_sid variable containing your plugin script id.

5. If s:_sfile variable does not exist, sets it to plugin filename.

6. Calls FraworRegister(), passing it transformed {version}, s:_sid,

s:_sfile, transformed {dependencies} and s:.


execute frawor#Setup([0, 0], {"@frawor": [0, 0]})

You may replace [0, 0] here with "0.0", but remember that it is

frawor#Setup extension, it won't work with FraworRegister.

Note: you must :execute frawor#Setup, not :call it.

FraworLoad({plugin}) FraworLoad()LINK

Load {plugin}. {plugin} argument may be either a plugin ID

(transformed using frawor-plid-expansion) or plugin dictionary.

Returns 0 if it failed to load plugin, 1 if plugin was successfully

loaded and 2 if plugin is being loaded now.

FraworUnload({plugin}) FraworUnload()LINK

Unload {plugin}. {plugin} argument may be either a plugin ID

(transformed using frawor-plid-expansion) or plugin dictionary.

Return list of files in order they must be sourced to load unloaded

plugins back. Unload is done in the following sequence:

0. Collect all plugins that depend on given plugin and order them so

that plugins that are less depended on come first.

1. Launch `unloadpre' feature key for all collected plugins.

2. Iterate over collected plugins and do the following:

2.1. Launch `unload' feature key for given plugin. Note that some

plugins that define this key may be unloaded at this point, thus

undefining their feature.

2.2. If {g} dictionary contains _unload key with a function reference,

then this function is launched. Note that you should use

s:._unload to define such function, not s:_unload.

2.3. Set plugdict status to 0, then remove plugin dictionary from

plugin dictionaries list.

2.4. Purge all {g} keys (normally this is equal to purging all s:


frawor#Reload({plugin}) frawor#Reload()LINK

Wrapper around FraworUnload that will unload {plugin} and immediately

load it back.


2.2. Commands frawor-commandsLINK


3. Features frawor-featuresLINK


3.1. Features defined in @frawor frawor-f-@fraworLINK

warn : function ({msgid}, ...) + s:_messages → {message} frawor-f-warnLINK

Echoes message `Frawor:{plid}:{msgid}:{message}' where {message} is

obtained by getting {msgid} out of `s:_messages'. If more then one

argument is present, then {message} and that arguments will be passed

to printf(). Warn function returns the whole message echoed. {plid}

is an id of a plugin that uses this function. Semicolon and backslash

in {plid} and {msgid} will be escaped.

throw : function ({msgid}, ...) → exception frawor-f-throwLINK

Calls frawor-f-warn and throws an exception with text

`Frawor:{plid}:{msgid}:{message}' where {message} is a value returned

by frawor-f-warn. Semicolon and backslash in {plid} and {msgid} will

be escaped.


require : function ({plid}, {dversion}, {throw}[, {plidreturn}]) → 0..2 | plid

Loads plugin {plid} and makes it dependency of the caller, also

running all its features. {throw} argument determines what should be

done if frawor failed to load requested plugin: if it is 1, then

`Frawor:plugin/frawor:reqfailed' exception will be thrown, otherwise

0 will be returned. 2 is returned when requested dependency was

already added and 1 indicates that dependency was successfully loaded.

If {plidreturn} is present and is 1 then.

newfeature : function ({fid}, {fopts}) frawor-f-newfeatureLINK

+ unload

Registers plugin feature with id {fid} ({fid} must contain only

digits, latin letters and underscores). {fopts} is a dictionary with

the following keys (all are optional, but feature without any keys is


Key Description


cons Reference to a function that will take frawor-t-plugdict

as its first argument, feature dictionary as its second

argument and, possibly, some additional arguments. It is

just a normal function that can do anything related to the

plugin that uses frawor. Function that is a wrapper to this

function will be added to s:_f dictionary under the

same conditions for which `load' function is called (except

that `ignoredeps' option has no effect).

Instead of function reference you can use a dictionary that

contains function references (that should accept the same

arguments) or dictionaries (with same restrictions on

contained keys and values). Dictionary keys should consist

only of latin letters, digits and underscores.


register Reference to a function that will take frawor-t-plugdict

as its first argument and feature dictionary as its second

(it will be empty). This function will be called once after

plugin is registered for each plugin that depends on the

feature definer.


init A dictionary. Feature dictionary (second argument to all

feature functions) will be obtained by deep copying

(deepcopy()) of this value. Copying is done just before

assignement, so if you record a pointer to a List or

Dictionary that is a value of `init' key somewhere,

modifications done to these structures will take effect on

init value recorded in the next plugin.


load Reference to a function that will take frawor-t-plugdict

as its first argument and feature dictionary as its second.

This function will be called only once for each plugin that

depends on the feature definer.

Function will be called under following circumstances:

1. If feature definer (plugin that registered feature) was

loaded before plugin that requires it, then it will be

called just before plugin will be loaded.

2. If feature definer was loaded after plugin that requires

it, then it will be called just after feature definer is



unload Reference to a function that will take frawor-t-plugdict

as its first argument and feature dictionary as its second.

This function will be called only once for each plugin that

depends on the plugin that registers this feature. Function

will be called when dependent plugin is unloaded.


unloadpre Just like unload, but function will be called when plugin

is queued for unloading, but nothing was yet unloaded.


depadd Reference to a function that will be called when dependency

was added using frawor-f-require feature. Receives

frawor-t-plugdict, feature dictionary and plugin id of

the added dependency as its arguments.


ignoredeps If this key is present, then register, load, unload and

unloadpre keys will be called for all plugins even if they

do not specify feature definer in dependencies. Key `cons'

will be ignored for plugins that do not specify feature

definer in dependencies.

Sequence in which feature keys are used:

0. Loading all dependencies.

1. (In case using frawor-f-require) running frawor-fk-depadd.

2. Populating feature dictionary using frawor-fk-init.

3. Running frawor-fk-register.

4. Constructing functions from frawor-fk-cons.

5. Running frawor-fk-load.

6. (While unloading) running frawor-fk-unloadpre.

7. (While unloading) unloading dependencies and the plugin itself,

frawor-fk-unload is called just before unloading of each plugin,

s:_unload just after frawor-fk-unload.


3.2. @/functions features frawor-f-@/functionsLINK

delfunctions : unloadpre + s:_functions frawor-f-delfunctionsLINK

+ register + s:_functions

Deletes all non-anonymous functions in s:_functions list before plugin

is unloaded. It is frawor-fk-ignoredeps feature, so you don't need

specify @/functions in your dependencies.

Usage (assuming that you executed frawor#Setup()):

function Foo()

" some code here


let s:_functions+=['Foo']


addextfunctions : function ({ {funcname}: {funcdescr} })

+ unload

Adds external functions. Each {funcname} must be a valid function name

(names that start with s: are also supported, though it is probably

better to just use `let s:_functions+=['s:Func']' after each

plugin-local function definition). This feature will throw an error if

function is already defined. {funcdescr} is described in


Note that if plugin is not loaded yet then instead of creating

function it will define FuncUndefined event that will load the

plugin and create requested function.


wrapfunc : function ({funcdescr})

+ load + s:_aufunctions

+ unload

Creates a function out of given {funcdescr} (see

frawor-t-funcdescr). Is useful to wrap some function with

savers/setters without making it accessible outside of plugin.


3.3. @/decorators features frawor-f-@/decoratorsLINK


adddecorator : function ({decid}, {decfunc})

+ unload

Adds a decorator named {decid} for constructed function. Decorator

function ({decfunc}) must accept plugin dictionary, function name (it

must only be used to make error messages more verbose) and an argument

(value of `@{decid}' key) and return a tuple of five values:

1. priority (any number). Decorators with higher priority will be put

less close to return statement, if priority is equal decorators'

names are taken into account;

2. arguments variable name (return `@@@' to leave it unchanged);

3. private decorator variable (0 if not used);

4. a list of lines that are to be put before :return statement

(leading spaces in all lines of the list are ignored);

5. a list of lines that are to be put after :return statement (it is

rather useless unless you use :try in the first list and

:finally in this one) (leading spaces in all lines of the list

are ignored);

6. boolean that determines whether block after :return needs access

to function return value. Note that in this case you don't need to

use :try .. :finally to get block after :return executed.

String {decid} should consist only of digits, latin letters and

underscores and must not be equal to a single underscore.

There are some special substrings that can be used inside returned

lists of strings and arguments variable name:

@@@ is replaced by argument list variable name (note that it may be

locked a:000 variable).

@%@ is replaced with the private variable name (you may also use it as

arguments variable name - second item in a returned tuple).

@$@ is replaced with the identifier unique to decorator. Use it when

you need a local variable.

@=@ is replaced with name of variable where function return value is

stored. Note that without sixth value in returned list set to true

this sequence won't work.

@*@ is replaced with name of variable containing function which will

be called. You may alter it if you want.

@.@ is replaced with dictionary which will be used as self in called


There are some predefined decorators:

Decorator Description


@altervars Uses :try .. :finally to alter variables/options and

restore them afterwards. Accepts a list as an argument,

see frawor-t-altervars. Priority: 192.

Defined in @/decorators/altervars.


@checker Checks function arguments before running the function

itself. See frawor-t-checker for description of an

argument. Priority: 128. Defined in @/checks.


@filter Filters function arguments before running the function

itself. See frawor-t-filter for description of an

argument. Priority: 64. Defined in @/checks.


@FWC Accepts tuple with two elements: FWC string and type.

Depending on type, acts like @checker (if type is "check")

or @filter (if type is "filter"). Unlike @checker and

@filter does not create additional function.

Priority: 128. Defined in @/fwc.


3.4. @/decorators/altervars features frawor-f-@/decorators/altervarsLINK


addaltspecial : function ({id}, {saver}, {setter}[, {opts}])

+ unload

Adds saver and setter functions for `+{intname}' (see

frawor-t-altervars). {id} must be a string that starts with a letter

and contains only letters, digits and underscores. {opts} is

a dictionary with the following keys:

Key Description

requiresarg If it is present, then {saver} and {setter} functions are

marked as functions that require additional argument, see

frawor-t-altervars. This additional argument will be

the only argument to saver and the second argument to

setter functions. Overrides `acceptsarg'.

acceptsarg Like `requiresarg', but does not force argument to be


checker Checker for additional argument, see frawor-t-checker.

Checker must accept list with a single item: additional



3.5. @/options features frawor-f-@/optionsLINK


getoption : function ({optname}[, {scopes}]) + s:_options, s:_oprefix

Obtains option with the given name. For the value of an option it will

first search dictionary {oprefix}Options, then variable

{oprefix}_{optname}, then it will use `default' key of

s:_options.{optname} option description (see frawor-t-option).

{oprefix} is either a value of s:_oprefix (it must be a valid

variable name!) or second component of plugin id (so if plugin id is

plugin/foo/bar, then {oprefix} will be foo). {oprefix} is determined

on first getoption call. If {scopes} is given it overrides



3.6. @/checks features frawor-f-@/checksLINK

conschecker : function ({checker}[, {gdict}]) frawor-f-conscheckerLINK

Creates a checker function. Constructed function takes exactly one

argument: List containing checked arguments. For {checker}

description see frawor-t-checker. {gdict} is only used for creating

checker with frawor-f-fwc.compile

let s:F.checker=s:_f.conschecker(s:F.checker)


" Check value contained in args variable

if !s:F.checker(args)

" check failed


consfilter : function ({filter}[, {gdict}]) frawor-f-consfilterLINK

Like frawor-f-conschecker, but for filters, see frawor-t-filter.


3.7. @/fwc features frawor-f-@/fwcLINK


fwc.compile : function ({FWCstring}, {type}[, {gdict}])

+ unload

Create a function out of {FWCstring} code. This function takes a list

of values (unless fwc-o-only is enabled) and returns either

(possibly modified) its argument (or 0) when {type} is "filter", or

a boolean value when {type} is "check". {gdict} overrides value of

script-local dictionary.

Returns a tuple with created function and its internal resources

identifier which can be then passed to frawor-f-fwc.del.

Note that created function will be anonymous dictionary function, so

you will need to supply a dictionary when you call it even though it

does not use this dictionary. See Dictionary-function and

description of the third argument to call().

fwc.del : function ({FWCid}) frawor-f-fwc.delLINK

Delete resources used by function with given ID.


3.8. @/mappings features frawor-f-@/mappingsLINK


mapgroup.add : function ({mgid}, {mappings}[, {mgopts}])

+ unload

Add mapping group with id {mgid}. {mappings} is a dictionary which

contains mapping names (they should consist only of latin letters,

digits and underscores) as keys and frawor-t-mapping as values.

{mgid} is one of the following:

1. Unique string that starts with an uppercase latin letter and

contains only latin letters and digits.

2. Zero. In this case unique {mgid} will be generated and then

returned by function, you will have to use it to map/unmap/delete

mapping group. Note that {mgid}=0 enables `nouser' option (see


3. An existing {mgid} defined by caller plugin. In this case mappings

will be appended to the given mapping group.

{mgopts} is a dictionary with the following keys:

Key Description

leader String, determines map leader. Default value: empty (note that

empty frawor-mk-lhs with empty leader disables a mapping).

It must be either a string or zero (latter disables mapping

group unless overrided by user). Is overriden by


buffer If this key is present, then given mapping group will create

only buffer-local mappings.

Note that if plugin type is `ftplugin', then `buffer' is on by

default and you cannot switch it off.

dontmap If this key is present, then given mapping group won't be

mapped unless requested by If both

this and `buffer' keys are present then mapping group is

mappend only for current buffer.

nouser If this key is present, then neither frawor-mk-lhs of

mappings defined in the mapping group nor group leader are

overridable by user. If this option is enabled, then no

restrictions are put on mapping names.

Passing zero as {mgid} enables this option.

func If this key is present, then its value will be used as `func'

key for mappings with List frawor-mk-rhs.

type One of `map', `abbr' or `menu'. Overrides the default value

for frawor-mk-type.

mode If this key is present, then its value will be used as the

default mode.

silent, noremap, expr, operator

If these keys are present, then their value will override the

default values for group mappings. See frawor-mk-silent,

frawor-mk-noremap, frawor-mk-expr and


Note that if mapgroup.add is called for existing group, then `nouser',

`buffer' and `dontmap' options are ignored. : function ({mgid}[, {bufnr}]) frawor-f-mapgroup.mapLINK

Executes mapping commands described by given group. Throws an error if

called by plugin that does not have mgroup definer in its dependencies

and is not a mgroup definer itself. Optional {bufnr} argument must be

a buffer number, if it is present then group is mapped for the given

buffer only.

mapgroup.unmap : function ({mgid}[, {bufnr}]) frawor-f-mapgroup.unmapLINK

Does the opposite to

mapgroup.del : function ({mgid}} frawor-f-mapgroup.delLINK

Unmaps and deletes group with given ID. Forbidden for every plugin but

that one which defined this group.


3.9. @/autocommands features frawor-f-@/autocommandsLINK

augroup.add : function ({agid}, {events}) frawor-f-augroup.addLINK

+ unload

Creates an autocommand group with name FraworAugroup_{agid} containing

events defined in {events} list. Each item in {events} list must be

a list with three or four values: ({type}, {pattern}, {nested},

{command}). {type} is a list (either actual List or comma-separated

string) of event types (see autocmd-events), {pattern} is a string

described in autocmd-patterns, {nested} determines whether

autocommand is nested (see autocmd-nested) and {command} is one of

the following:

1. List with at least one item. First item must be either a dictionary

that describes a function (see frawor-t-funcdescr) or a function

reference. The following items are arguments that will be passed to

the first item.

If first item is a dictionary then plugin will be loaded before

running function described by it.

2. Function reference. Determines a function that will be called. In

this case no arguments are supplied.

3. Dictionary described in frawor-t-funcdescr. In this case plugin

will be loaded before running function described by it.

Note that you must depend on @/functions to use such {command}.

4. String. Determines actual command that should be called.

Note that <SID> in the command will be replaced by <SNR>{sid}_, but

you still cannot use script-local variables because autocommand

will be defined in @/autocommands scope. It is better to use

s:_augroups variable as described in frawor-f-delaugroups.

augroup.del : function ([{agid}]) frawor-f-augroup.delLINK

Deletes autocommand group with given {agid}. If no {agid} is given,

then deletes all autocommands that belong to plugin that calls this


delaugroups : unloadpre + s:_augroups frawor-f-delaugroupsLINK

register + s:_augroups

Deletes autocmd groups listed in s:_augroups. It is

frawor-fk-ignoredeps feature, so you don't need specify

@/autocommands in your dependencies.


augroup FooBar

autocmd BufAdd * call s:F.fooinit()

augroup END

" s:_augroups is set to an empty list when plugin is registered.

let s:_augroups+=['FooBar']


3.10. @/commands features frawor-f-@/commandsLINK

delcommands : unloadpre + s:_commands frawor-f-delcommandsLINK

register + s:_commands

Deletes commands listed in s:_commands. Usage:

command -nargs=? Foo echo "Bar"

let s:_commands+=["Foo"]

command.add : function( cid, cstr, copts ) frawor-f-command.addLINK

+ unload

Creates a command named {cid}. {cstr} describes replacement string and

is one of the following:

1. String. It will be added to the :command call directly. Note that

command will be defined in the context of @/commands module, so you

can't use script-local variables here.

2. Function reference.

3. Dictionary. This variant provides a way to delay loading of the

plugin until command is called: when defined command is called

frawor will load the plugin, use frawor-f-wrapfunc to create

a function out of the given dictionary (note: you must have

@/functions module in dependencies) and only then call given


{copts} is a dictinary that describes some additional options:

Key Description

nargs String or 0. Defines number of arguments, see

:command-nargs. Use 0 to skip this argument. Default: "0".

Ignored if `rsplitfunc' key is present and is not 0.

range 0, 1, "%" or Number written as string. Defines default

range, see :command-range. 1 means `add -range without

argument'. Default: 0. Adds <line1> and <line2> to argument


count 0, 1 or Number written as string. Just the same as range,

but for :command-count. Default: 0. Adds <count> to

argument list.

bang 0 or 1, see :command-bang. Default: 0. Adds <bang>0 to

argument list.

bar 0 or 1, see :command-bar. Default: 1.

register 0 or 1, see :command-register. Default: 0. Adds <q-reg> to

argument list.

buffer 0 or 1, see :command-buffer. Default: 0, 1 for ftplugins.

Note that if plugin type is `ftplugin', then `buffer' is on

by default and you cannot switch it off.

complete Defines completion for the command. Possible values:

1. String, see :command-complete.

2. Function reference. Anonymous and script-local functions

are also allowed. See :command-completion-customlist.

3. Dictionary. In this case plugin will be loaded when

completion is called and then this dictionary will be

passed to frawor-f-wrapfunc. You must have @/functions

module in dependencies. This variant enables you to delay

defining completion function until required.

4. List with one or two strings. In this case

frawor-f-fwc.compile will be used to compile completion

function. If list contains one string, then

FWC-o-onlystrings option will be enabled and "complete"

string will be added to list. If list contains two

strings, then it will be passed to fwc.compile

unmodified. Like with dictionary, compilation will be

done only after plugin is loaded.

splitfunc, rsplitfunc

Defines function that will split command-line into a list of

arguments. `splitfunc' is for completion (only valid if

completion defined by a list), `rsplitfunc' is for running

(valid only if {cstr} is not a string). You may use 0 to

keep default behavior.


If true, makes `splitfunc' key be also used for dictionary

completion definitions.

Order of additional arguments if any (only applicable if {cstr} is

a dictionary or a function reference):

<bang>0, <count>, <line1>, <line2>, <q-reg>

command.del : function( [ cid ] ) frawor-f-command.delLINK

Delete command named {cid} if it was defined by this plugin. If no

{cid} was specified, deletes all commands defined by caller.


3.11. @/resources features frawor-f-@/resourcesLINK


postresource : function ({rid}, {resource}[, {copyfunc}])

+ register, unload

Create resource (copy of {resource}) with given {rid}. This feature is

now used only to provide access to plugin functions that don't have to

know anything about a caller. Additional argument determines what

should be done when resource is requested:

1. If it is `0' (default), then resource is deepcopied (deepcopy())

for each plugin.

2. If it is a reference to a function, then {resource} is deepcopied

when resource is created and on each request {copyfunc}({resource})

is used to obtain value which will actually be added to plugin


3. If it is `1' then no copying is performed at all. Use this to save

space if you are sharing large structures or need to give access to

your plugin's state. Note that only Lists and Dictionaries are

passed by references, so it won't have any affect when you share

strings, numbers or function references.

addresource : load, depadd + s:_r frawor-f-addresourceLINK

Automatically adds resources that are defined by plugins listed in

dependencies to s:_r dictionary. It is frawor-fk-ignoredeps feature,

so you don't need anything to get it working.


3.12. @/python features frawor-f-@/pythonLINK

All @/python features are available only if vim is compiled with python


addpythonpath : register, unloadpre frawor-f-addpythonpathLINK

Automatically adds {rtp}/python or {rtp}/python3 directory to sys.path

if it exists, then removes it when plugin is unloaded.


3.13. @/perl features frawor-f-@/perlLINK

All @/perl features are available only if vim is compiled with perl support.

addperlpath : register, unloadpre frawor-f-addperlpathLINK

Automatically adds {rtp}/perl directory to @INC if it exists, then

removes it when plugin is unloaded.


3.14. @/lua features frawor-f-@/luaLINK

All @/lua features are available only if vim is compiled with lua support.

addluapath : register, unloadpre frawor-f-addluapathLINK

Automatically adds {rtp}/lua/?.lua and {rtp}/lua/?/init.lua to

package.path if directory {rtp}/lua exists, then removes them when

plugin is unloaded.


3.15. @/ruby features frawor-f-@/rubyLINK

All @/ruby features are available only if vim is compiled with ruby support.

addrubypath : register, unloadpre frawor-f-addrubypathLINK

Automatically adds {rtp}/ruby directory to $LOAD_PATH if it exists,

then removes it when plugin is unloaded.


3.16. @/tcl features frawor-f-@/tclLINK

All @/tcl features are available only if vim is compiled with tcl support.

addtclpath : register, unloadpre frawor-f-addtclpathLINK

Automatically adds {rtp}/tcl directory to auto_path if it exists, then

removes it when plugin is unloaded.


3.17. @/signs features frawor-f-@/signsLINK

delsigns : unloadpre + s:_signs frawor-f-delsignsLINK

register + s:_signs

Deletes signs listed in s:_signs. Usage:

sign define xxx text=EE texthl=Error

let s:_signs+=["xxx"] : function (sgid, sgopts) frawor-f-sign.newLINK

+ unload

Define a new sign with name {sgid} (0 if you don't care about

human-readable names). Returns sign name ({sgid} if it is not 0).

{sgopts} is a dictionary with the following keys (see sign-define):

Key Description

text One or two printable characters.

texthl Highlight group for text.

linehl Highlight group for line with sign.

icon Sign icon. Ignored unless has("gui_running") return 1.

At least one of these keys must be present. : function (sgid, bufnr, line) frawor-f-sign.placeLINK

Place sign defined using Use 0 for {bufnr} if you

want to place sign in current buffer.

sign.delete : function ([ sgid ]) frawor-f-sign.deleteLINK

Unplace and delete sign defined using If no

{sgid} given, delete all signs defined by this plugin.


4. Resources frawor-resourcesLINK

Resources are defined (posted) by frawor-f-postresource. Unlike functions

defined by features, all functions accessed from posted resources does not

check their arguments.


4.1. map resource frawor-r-mapLINK

Resource `map' is defined in @/mappings.


map.maparg :: {lhs}, {mode}::Char, {abbr}::Bool -> {mapdescr}

Given an {lhs} of the mapping ({abbr}=0) or abbreviation ({abbr}=1)

and {mode} (see maparg() description) returns a dictionary with the

following keys:

Key Description

lhs {lhs} of the mapping

rhs {rhs} of the mapping

silent 1 if mapping is silent (:map-<silent>), 0 if it is not

noremap 1 if {rhs} is not remappable, 0 otherwise

expr 1 for expr mappings (:map-<expr>), 0 otherwise

buffer 0 if mapping is global, buffer number for :map-<buffer>

mode Mode for which mapping is defined

sid SID of the script which defined this mapping (<SID>)

type "abbr" or "map" (depending on {abbr} argument)

Note that in <vim-7.3.32 `silent', `expr', and `sid' keys are

unconditionally set to 0 as there was no way to obtain their values. :: {mapdescr} -> _ + :map frawor-r-map.mapLINK

Given an {mapdescr} returned by frawor-r-map.maparg, constructs and

executes a command that will create the new mapping.

map.unmap :: {mapdescr} -> _ + :unmap frawor-r-map.unmapLINK

Given an {mapdescr} returned by frawor-r-map.maparg, constructs and

executes a command that will delete an existing mapping.


4.2. os resource frawor-r-osLINK

Resource `os' is defined in @/os.

os.fullname :: String frawor-r-os.fullnameLINK

One of unix, win*, mac, macunix, amiga, os2, qnx, beos, vms or

unknown. Describes the version of vim: has(os.fullname) is true unless

os.fullname is equal to "unknown", see feature-list. :: String frawor-r-os.nameLINK

Either "posix" (for *nix, mac*, qnx and vms versions of vim), "nt"

(for win* versions of vim except win32unix), "os2" (for os2 version of

vim) or "other".

os.sep :: Char frawor-r-os.sepLINK

Path separator. It is likely to be either "/", "\\" or ":".

os.linesep :: String frawor-r-os.linesepLINK

Line separator: "\r\n" for nt systems, "\r" for mac*, "\n" for other.

os.pathsep :: String frawor-r-os.pathsepLINK

Separator used in $PATH variable: ";" for nt and os2 systems and ":"

for other systems.

os.listdir :: path[, _] -> path frawor-r-os.listdirLINK

Lists directory contents. If optional argument is given, then list of

absolute file names is returned, otherwise only trailing components

are returned.

os.chdir :: path[, Bool] -> Bool + WD frawor-r-os.chdirLINK

Changes current directory, returns 1 on success and 0 on failure. If

optional argument is true, then only window current directory will be

changed (see :lcd).

os.mkdir :: path[, mode] -> Bool + FS frawor-r-os.mkdirLINK

Creates directory with given protection bits (default 0755). Returns

1 on success, 0 on failure. Not available on some systems (relies on

mkdir() function being available).

os.makedirs :: path[, mode] -> Bool + FS frawor-r-os.makedirsLINK

Like frawor-r-os.mkdir, but also creates intermediate directories if

they do not exist. Unlike built-in mkdir(), mode is applied to all

intermediate directories created, not just to last directory.

os.unlink :: path -> Bool + FS frawor-r-os.unlinkLINK

os.remove :: path -> Bool + FS frawor-r-os.removeLINK

Removes given file (not directory) returning 1 on success and 0 on


os.rmdir :: path -> Bool + FS frawor-r-os.rmdirLINK

Remove given directory if it is empty. Only available on posix and nt

systems with some tools installed (rmdir or rm for posix, rmdir or

deltree for nt). Returns 1 on success and 0 on failure.

Note that if is not working correctly then neither

will os.rmdir.

os.removedirs :: path -> UInt + FS frawor-r-os.removedirsLINK

Remove given directory and all empty intermediate ones (excluding

current directory). Returns number of components removed.

Note that if is not working correctly then neither

will os.removedirs.

os.removetree :: path -> Bool + FS frawor-r-os.removetreeLINK

Remove the given file or directory including all contained files or

directories (like `rm -r' on posix systems). Returns 1 on success and

0 on failure. Don't forget that removetree will first remove all files

and only then will try to remove directories using frawor-r-os.rmdir.

Note that if is not working correctly then neither

will os.removetree.


os.walk :: path + FS -> [(path, [ component ], [ component ])]

For each directory in the directory tree rooted at path including path

itself but excluding `.' and `..' generates a 3-tuple

({dirpath}, {dirnames}, {filenames})

where {dirpath} is path to a directory, {dirnames} is a list of

subdirectories' names and {filenames} is a list of regular file names.

Note that symbolic links to existing directories are considered to be

directories themselves. :: command[, path] -> shell_error|-1 frawor-r-os.runLINK

Runs command with given arguments and returns its exit code. “Command”

may be either a list of strings (in this case they will get

shellescaped() and joined with spaces) or a plain string (note that

you must use {special}=1 when using shellescape()). Optional path

argument designates working directory in which command should be run.

If path is not accessible it may return -1.

Note that depends on 'shell', 'shellquote', 'shellxquote' and

'shellcmdflag' options being set correctly.

os.readsystem :: command[, path] -> [ String ] | -1 frawor-r-os.readsystemLINK

Like, but returns command outputs instead in the

same format as readfile() does. Additionally depends on 'shellredir'

option being set correctly and tempname() returning writable file


os.path.abspath :: path + FS -> path frawor-r-os.path.abspathLINK

Returns an absolute path.

os.path.realpath :: path + FS -> path frawor-r-os.path.realpathLINK

Returns an absolute path with all symbolic links resolved.

os.path.relpath :: path[, path] -> path frawor-os.path.relpathLINK

Transforms its first argument so that it will be a path, relative to

the path given in the second argument (default: current directory).

Returns transformed version of path or 0 if it cannot be constructed

(for example, if paths are on different drives on windows).

os.path.normpath :: path -> path frawor-r-os.path.normpathLINK

Normalize path by removing duplicate path separators and simplifying

it (see simplify()). It also adds leading `./' to the relative


os.path.basename :: path -> component frawor-r-os.path.basenameLINK

Returns the final component of a path.

os.path.dirname :: path -> path frawor-r-os.path.dirnameLINK

Returns the directory component of a path.

os.path.join :: [ path ] -> path frawor-r-os.path.joinLINK

Joins path components into one path, removing duplicate path

separators. The following calls are equivalent:

let path=s:_r.os.path.join("foo", "bar")

let path=s:_r.os.path.join(["foo", "bar"])

os.path.split :: path -> [ component ] frawor-r-os.path.splitLINK

Returns a list of path components starting either from root (`/' on

posix systems, `{DriveCharacter}:' on nt systems) or from current

directory ('.').

os.path.samefile :: path, path + FS -> Bool frawor-r-os.path.samefileLINK

Returns 1 if both pathnames refer to the same actual file.

os.path.exists :: path + FS -> Bool frawor-r-os.path.existsLINK

Returns 1 if file or directory with given name exists, 0 otherwise.

os.path.isdir :: path + FS -> Bool frawor-r-os.path.isdirLINK

Returns 1 if given path is existing directory, 0 otherwise.

os.path.isfile :: path + FS -> Bool frawor-r-os.path.isfileLINK

Returns 1 if given path is existing file, 0 otherwise.


os.path.walk :: path, (arg, path, [ component ] -> _)[, arg] + FS -> _

Directory tree walk with callback function:

For each directory in the directory tree rooted at top (including top

itself, but excluding '.' and '..'), call func({arg}, {dirname},

{fnames}) (func is the second argument). {dirname} is the name of the

directory, and {fnames} is a list of the names of the files and

subdirectories in dirname (excluding '.' and '..'). Function may

modify the {fnames} list in-place (using add(), remove() and list

assignment), and walk() will only recurse into the subdirectories

whose names remain in {fnames}; this can be used to implement

a filter, or to impose a specific order of visiting. No semantics are

defined for, or required of, {arg}, beyond that {arg} is always passed

to func. It can be used, e.g., to pass a filename pattern, or

a mutable object designed to accumulate statistics. If additional

argument is not present, then 0 will be passed in place of {arg}.


4.3. printtable resource frawor-r-printtableLINK

Resource `printtable' is defined in @/table. It is a single function which is

used for outputting table data.

Usage: s:_r.printtable({lines}[, {opts}]), where {lines} is a list of lists of

strings each list representing a line and each string in a list representing

column contents:

:call s:_r.printtable([['foo', 'bar', 'baz'], ['f', 'b']])

foo bar baz

f b

{opts} is an optional dictionary with the following keys:

Key Description

header Defines a table header (it has just the same format as a single

line). It is highlighted by PreProc group by default:

:call s:_r.printtable([['a', 'b']], {'header': ['A', 'B']})


a b

vseparator Defines a vertical separator between columns:

:let lines=[['a', 'b', 'c'], ['d', 'e', 'f']]

:call s:_r.printtable(lines, {'vseparator': ' | '})

a | b | c

d | e | f

vseparators List of separators:

:call s:_r.printtable(lines, {'vseparators': [' : ', ' | ']})

a : b | c

d : e | f

Instead of specifing separator as a string you may specify

a two-tuple (String, hlgroup). In this case separator will be

highlighted. Separotor highlight group is discarded when printing

table header.

align Defines align for all columns (but not for header line). Possible

values: "left" (default), "center", "right":

:let lines2=[['abc', 'def', 'ghi'], ['a', 'b', 'c']]

:call s:_r.printtable(lines2, {'align': 'center'})

abc def ghi

a b c

aligns List of aligns:

:call s:_r.printtable(lines2,

\{'aligns': ['right', 'center', 'left']})

abc def ghi

a b c

halign, haligns

Like align and aligns, but for header.

hl, hls, hhl, hhls

Defines higlight groups for columns. `hl' defines one hl group

for all data in table, `hhl' overrides PreProc highlighting for

header. `hls' and `hhls' have the same relation to `hl' and `hhl'

as `aligns' has to `align'.


4.3.1. strdisplaywidth resource frawor-r-strdisplaywidthLINK

Resource `strdisplaywidth' is defined in @/table. It contains either

a reference to strdisplaywidth() function or emulation of this function for

older Vims.


4.4. base64 resource frawor-r-base64LINK

Resource `base64' is defined in @/base64. It is used for encoding/decoding

base64 data.


base64.decode :: b64str[, bytearray] -> str | bytearray

Decode base64 encoded string. If optional argument is 1, then function

will return a List of numbers, each number representing one byte.

Otherwise it will return a decoded string.

base64.encode :: str | bytearray -> b64str frawor-r-base64.encodeLINK

Encode string or a list of numbers each representing a single byte

(thus restricted to be between 0 and 255 inclusive).

base64.encodelines :: [ str ] -> b64str frawor-r-encodelinesLINK

base64.decodelines :: b64str -> [ str ] frawor-r-decodelinesLINK

Similar to above functions, but these work with a list of lines like

returned by readfile() or getline() with two arguments (see



4.5. sign resource frawor-r-signLINK

Resource `sign' is defined in @/signs. It is used for signs manipulation, see


sign.exists :: sgid -> Bool frawor-r-sign.existsLINK

Check whether sign with given name exists.

sign.delete :: sgid -> _ frawor-r-sign.deleteLINK

Unplace and delete sign with given id.

sign.getbuf :: bufnr -> [(line, id, name)] frawor-r-sign.getbufLINK

Get all signs placed in buffer with given number. Returns a list of

3-tuples ({line}, {id}, {name}) where {line} is line number, {id} is

placed id (see :sign-place) and {name} is sign id (see


sign.getdef :: sgid -> sgopts frawor-r-sign.getdefLINK

Get definition of sign named {sgid}. Returns a dictionary which may

contain keys `text', `texthl', `linehl' and `icon', see



4.6. history resource frawor-r-historyLINK

Resource `history' is defined in @/history. It is used for history list

manipulation (see histadd() and friends).

history.get :: htype + history -> [ String ] frawor-r-history.getLINK

Returns list of history lines for given history type (see


history.clear :: htype -> _ + history frawor-r-history.clearLINK

Clears given history (see hist-names).

history.set :: htype, histlines -> _ + history frawor-r-history.setLINK

Clears given history (see hist-names) and populates it with a list

of lines.


4.7. new_constructor resource frawor-r-new_constructorLINK

Resource “new_constructor” is defined in @/fwc/constructor. It is used to

create VimL code by creating a syntax tree:

new_constructor :: () -> tree

Tree object is described in FWC-constructor-plugin.


5. Options frawor-optionsLINK


All frawor options are defined into various modules.


5.1. Mapping options frawor-mapoptionsLINK

b:frawormap b:frawormapOptionsLINK

g:frawormap g:frawormapOptionsLINK

These options are defined in @/mappings. Unlike other frawor options the

following options should be prefixed with `frawormap' string, not with

`frawor'. Exact values of {mgid} and {mapname} are determined by plugin that

defined a mapping group (see frawor-f-mapgroup.add), frawor itself does not

define any mappings.

b:frawormap_mgid g:frawormap_mgidLINK

{mgid} frawor-mo-mgidLINK

Defines a leader for given mapping group. If you specify 0 instead of

a leader, then the whole mapping group will be disabled.

b:frawormap_mgid_mapname g:frawormap_mgid_mapnameLINK

{mgid}_{mapname} frawor-mo-mgid_mapnameLINK

Defines a suffix for given mapping ({lhs} of the mapping is

constructed out of the leader and this option). If you specify

0 instead of some string then you will disable target mapping. You can

also specify a list of strings instead of one string, in this case all

strings will be mapped. It will also merge option values if they are

defined both in frawormap_{mgid}_{mapname} and in {mgid}_{mapname} key

of frawormapOptions dictionary.


6. Type definitions frawor-typesLINK

version :: [ Integer ] frawor-t-versionLINK

List of integers, all integers must be nonnegative.

plugdict :: {} frawor-t-plugdictLINK

Dictionary which describes plugin. It has the following keys:

Key Description

type Plugin type (first path component after runtimepath if

there are at least two of them, string "/unknown" if

detection of runtimepath failed, string "/script" if

there were not more then one component after runtimepath

and string "/anonymous" if FraworRegister() got zero

instead of version).

id Plugin id.

runtimepath Plugin runtimepath, empty if detection of rtp failed or

FraworRegister() got zero instead of version.

version Plugin version, see frawor-t-version.

isfiletype Bool, true if plugin is devoted to some filetype

(determined by chekcing whether plugin id starts with

ftplugin/, syntax/ or indent/).

file Path to plugin file ({file} argument to

FraworRegister() for non-anonymous plugins, s:_sfile

or 0 for anonymous plugins).

sid Plugin script id, see <SID>. May be 0 if

FraworRegister() got zero instead of version.

dependencies Dictionary which contains pairs {plid} - {version}. When

dependency is loaded it is checked whether actual plugin

version is greater then requested plugin version

(excluding first component, it must be matched exactly).

status Number that describes status of the plugin:

0 - plugin is not loaded

1 - plugin is registered, but not loaded

2 - plugin is loaded

g Dictionary with global variables (last argument to


checker :: Function frawor-t-checkerLINK

If checker is a function reference, then in order to check arguments

this function will be called with an argument list as an only

argument. Check is considered passed when this function returns 1 and

failed when this function returns 0.

If checker is a string, then it is passed to frawor-f-fwc.compile

with "check" as a second argument, then generated function is

returned. Consider using FWC decorator (frawor-de-FWC) instead.

filter :: Function frawor-t-filterLINK

If filter is a function reference, then in order to filter arguments

this function will be called with an argument list as an only

argument. If function returns a List, then it will be used as a new

argument list. Function should return 0 if some error occured.

If filter is a string, then it is passed to frawor-f-fwc.compile

with "filter" as a second argument, then generated function is

returned. Consider using FWC decorator (frawor-de-FWC) instead.

option :: {} frawor-t-optionLINK

Dictionary which describes option. It has the following keys:

Key Description


default Determines default value of an option. Is neither checked

nor filtered.


scopes Scope of variables which can be searched for an option.

Must be a string which contains an ordered sequence of

characters: `wtbg', all of them are optional, order of

characters determines order of option search. Each letter

describes where option will be searched: `g' for global

variables, `b' for buffer, `t' for tabpage-local and `w'

for window-local. If this key is not present, it is

considered to be equal to `bg'.


checker Checker for an option, see frawor-t-checker. Will be

used only for options from enviroment, not for default

values. It is processed before `filter' if both are

present. Checker must accept a list with a singe item:

option being checked.

Note that this key is passed to frawor-f-conschecker

only once for each option, then returned value is saved

and reused.


filter Filter for an option, see frawor-t-filter. Will be used

only for options from enviroment, not for default values.

Filter must accept a list with a singe item: option being

filtered, and on success return a list with a single item:

filter results.

Note that this key is passed to frawor-f-consfilter only

once for each option, then returned value is saved and


Note 2: if filter key is present, option will be deep

copied before filtering, see deepcopy().


merger If this key is present and is a function reference, then

it will be used to merge options from different scopes

(arguments: old value, new value, option name, plugin id,

name of the variable from which option new value was

obtained ("default" for default option)). If it is not

present, then frawor-f-getoption will return first value

it finds. If this key is equal to "extend", then it will

use extend() with `keep' as a third argument to merge

Dictionaries, expr-+ for List, Float and Number

values, expr-. for Strings, throwing an error when types

do not match.

Note that values are checked and filtered before they are

passed to the merger.

Note 2: if merger key is present, first of merged options

is deep copied (see deepcopy()). Otherwise copying is

not performed.


override Determines values from which scopes should override

default value. Value is the same as frawor-od-scopes.

This option is ignored unless frawor-od-merger is


funcdescr : {} frawor-t-funcdescrLINK

Function description is a dictionary with the following keys (all

except `function' are optional):

Key Description


function Function reference or list. Determines function that will

be called. In case of function reference referenced

function will be called. List must have another syntax:

[{plid}, {version}, {key}], in this case when function is

created the following is done:

1. {plid} is loaded using frawor-f-require. It must

depend on @/functions.

2. Dictionary {key} from s:_aufunctions dictionary of

plugin with given {plid} is merged with the current

dictionary, overriding keys in the latter. Load event of

frawor-f-wrapfunc feature is responsible for this.

Nested loads are supported (i.e. when loaded function

description has similar 3-tuple).

Note about merges: plugdict for decorator is taken from

the plugin that defined the decorator, not from the

plugin that created function definition. Same for

dependencies: plugin that defined the decorator

must be specified as the dependency of the plugin

that requested the decorator.


redefine If this key is present, then it will try to redefine

function if it exists, if it is not and function with given

name exists or :delfunction threw E131 (function is in

use) error, then `fdef' exception is thrown. Makes some

difference only when used in funcdescr passed to


@{decorator} frawor-fd-@LINK

Apply decorator to the function, see

frawor-f-adddecorator. The last argument to a decorator

is the value of this key.

Note that you must specify plugin that defined {decorator}

as your plugin dependency.

altervars :: [({varname}[, {value}])] frawor-t-altervarsLINK

Tells altervars decorator which variables to save and, possibly, alter

(if {value} is not present, then variables will only be saved and then

restored, otherwise they will be set to {value}). {varname} may be the


1. `g:{varname}', `b:{varname}', `t:{varname}' and `w:{varname}'

variables for global, buffer-, tabpage- or window-local variables.

Note that it will unlet existing variables thus purging toplevel

locks (see :lockvar).

2. `&g:{optname}' and `&l:{optname}' for global and local option


3. `+{special}' or `+{special}({argument})' for special saver and

setter functions that are defined by frawor-f-addaltspecial.

Note that you must specify plugin that defines {special} as your

plugin dependency.

Each list in a list that is passed as `altervars' option is copied,

but no deepcopy() is performed, so you may alter variable {value}s

if they are Lists or Dictionaries.

List of special savers/setters. They are defined by

@/decorators/altervars unless listed otherwise:


Name Description

variables Saves and restores whole variables dictionary (by default,

saves global variables. You may override it by supplying

one of `b', `t' or `w' as an optional argument for buffer,

tabpage or window-local variables).

buffer Saves and restores current buffer number.

window Saves and restores current tab page and window.

folds Saves and restores folds state.

winview Saves and restores window view (using winsaveview() and


matches Saves and restores matches (using getmatches() and


qflist Saves and restores quickfix list (using getqflist() and


history Saves and restores history. Defined by @/history. Requires

additional argument: history type (see hist-names).

mapping :: {} frawor-t-mappingLINK

Dictionary which contains the following keys (at least rhs key is


Key Description


lhs String or 0. {lhs} of the mapping: sequence of keys which

is mapped to. If it is 0, then mapping is disabled by

default. Default value: empty (thus actual {lhs} will be

determined by leader). Is overriden by

frawor-mo-mgid_mapname unless `nouser' key was specified

when mapping group was defined.


rhs String, List, Function reference or Dictionary. Depending

of the type may have the following meanings:

1. String: {rhs} of the mapping. If frawor-mk-strfunc is

present then all occurences of "%str" will be replaced

with call to a function that will return requested


2. List: requires presence of `func' key. Function given in

the `func' key will be called with arguments given in

the `rhs' key and its result will be taken as an {rhs}

of the mapping (see map-<expr>). Each argument that is

a String equal to one of the following keys will be

replaced with corresponding values:

String Value

%str String obtained by using frawor-mkf-getstr.

Requires presence of frawor-mk-strfunc key.

%lhs Actual lhs of the mapping (with leader).

%mode Mode of the mapping (mode() will give more

precise results).

%mgid Mapping group id.

%mname Mapping name.

You can use dictionary instead of the function reference

for the `func' key.

3. Function reference: like 2. with `func' set to rhs and

`args' set to [].

3. Dictionary: requires presence of @/functions in

dependency list. When mapping is invoked for the first

time plugin will be loaded and then function will be

wrapped using frawor-f-wrapfunc with given dictionary

as an argument. Wrapped function will be used just as in

the previous clause, though instead of taking list of

arguments from the `rhs' key, it will be taken from the

`args' key.


silent Bool, determines whether mapping will be silent (see

map-<silent>). Default value: 0.


noremap Bool, determines whether mapping will be remappable (see

:noremap and others). Default value: 1.


expr Bool, determines whether mapping will be expression mapping

(see map-<expr>). Default value: 0. Ignored if

frawor-mk-rhs is not a String.


type String, one of `map' (default), `abbr' or `menu'.

Determines command that will be used to create a mapping.


mode String, determines for which modes mapping will be defined

(you may specify more then one mode). Default value:

<Space>. Other possible modes (note that only ` ', `c' and

`i' are accessible for abbreviations):

Key Modes

<Space> mapmode-n, mapmode-x, mapmode-s and

mapmode-o for mappings and menus; :iabbreviate

and :cabbreviate for abbreviations

! mapmode-i and mapmode-c, not for menus

v mapmode-x and mapmode-s

i mapmode-i or :iabbreviate

c mapmode-c or :cabbreviate

o mapmode-o

n mapmode-n

x mapmode-x

s mapmode-s

l mapmode-l, not for menus

a Only for menus, :amenu

Note that :menu, :vmenu, :map, :vmap, :map! and

:abbreviate commands will never be used, keys that

represent multiple modes are expanded by @/mappings and

then iterated over them, creating one mapping for each



strfunc Function reference, determines function that should be used

to obtain an additional string argument using getchar()

loop. This function must take one or more arguments where

first argument is character that was entered by user. It

must then return a tuple ({status}, {retvalue}, {addarg}).

Here {status} is one of the following numbers:

Number Meaning

0 character not accepted (reverts to previous key

that caused strfunc to return 2 and passes the

following keys back. If strfunc haven't returned 2,

then `strfail' exception is thrown);

-1 like 0, but instead of throwing an exception it

will use an empty string instead of {gotstring}.

{retvalue} in this case will be ignored unless it

is the first character processed;

1 character accepted, more characters needed;

2 character accepted, can accept more characters;

3 character accepted, no more characters needed.

{retvalue} is discarded if it is equal to 0 and ignored if

{status} is 0 or 1. In other cases it causes tuple

({gotstringa}, {retvalue}) to be passed to the mapping

instead of default {gotstring}.

{addarg} is the additional argument to itself that will be

used on next iteration (ignored if it is equal to zero).

You can use dictionary instead of a function reference. In

this case plugin will be loaded before strfunc will be

wrapped and called (only if `rhs' is a List or


Note: `passing some keys back' means using feedkeys() for

mappings where frawor-mk-rhs is a String and

frawor-mk-expr is 0 and appending result to {rhs} in

other cases. It means that in first case additional keys

will be remapped, but in second case they will be remapped

only if frawor-mk-noremap is set to 0.


operator Bool. If this key is present, is not 0 and frawor-mk-rhs

is not a String, then 'operatorfunc' will be set to

internal function which will call yours one with three

additional arguments: motion type, motion start position

(getpos("'[") or getpos("'<"), see getpos()), motion end

position (getpos("']") or getpos("'>")).

Note that your function will be called outside of <expr>

mapping and its return value will be ignored, see g@.

As g@ works only in Visual and Normal modes, in other

modes it will be preceded with key sequence that switches

to one of these modes either temporary or pernamently:

- <C-o> for Insert and langmap modes (switches temporary

to Normal mode),

- <C-o> for Select mode (switches temporary to Visual


- <Esc> for Cmdline and Operator-pending modes

(switches pernamently to Normal mode).


tip String, defines a tip for menu item. Ignored unless

frawor-mk-type is `menu'.


7. Variables index frawor-variablesLINK

Defined in/

Varname required for Description

s:_sid @%frawor Integer. Is set to current script id by LINK


s:_sfile @%frawor String. Is set to script filename by LINK


s:F @%frawor Dictionary that is intended to hold all LINK

plugin functions. Is initially set by

frawor#Setup(). It is not used by frawor

itself, but it is intended to be used by

plugins for internal purposes.

s:_pluginloaded @frawor Integer. Is set to 0 after plugin is LINK

registered and then to 1 after plugin is


s:_frawor @frawor Dictionary. Is set by FraworRegister().LINK

s:_messages @frawor Dictionary that contains strings as LINK

values. Required for frawor-f-warn and


s:_f @frawor Dictionary containing feature functions. LINK

Is set and populated by FraworRegister()

and frawor-f-newfeature.

s:_unload @frawor Reference to a function that will be LINK

called on plugin unloading


s:_options @/options Dictionary that contains option LINK

definitions. Required for


s:_oprefix @/options String that contains option prefix. Is LINK

used by frawor-f-getoption.

s:_augroups @/autocommands List of strings containing augroup names. LINK

Is used by frawor-f-delaugroups.

s:_commands @/commands List of strings containing command names. LINK

Is used by frawor-f-delcommands.

s:_signs @/signs List of strings containing sign names. Is LINK

used by frawor-f-delsigns.

s:_functions @/functions List containing references to global and LINK

script-local functions or their names. Is

used by frawor-f-delfunctions and set by


s:_aufunctions @/functions Dictionary containing functions that are LINK

required by another plugins, see

frawor-f-wrapfunc (feature using this

dictionary) and frawor-fd-function.

s:_r @/resources Dictionary containing resources posted by LINK

plugins listed in dependencies. Is set by



8. Changelog frawor-changelogLINK

Only API changes are listed here. See commit log in order to get other



0.1: Added frawor-f-require and frawor-fk-depadd.

0.2: Added s:_loading variable.

0.3: Added isftplugin key to frawor-t-plugdict,

adjusted the way plugin type is determined.

1.0: Removed twoload feature and s:_loading variable.

1.1: Added {plidreturn} argument to frawor-f-require.


0.1: Added possibility to specify dictionaries in `strfunc' and `func'



0.1: Posted frawor-r-strdisplaywidth.


0.1: (intfuncs-0.1) Added FWC-c-idof.

0.2: (intfuncs-0.2) Made FWC-f-path filter expand argument.

0.3: (intfuncs-0.3) Added -onlystrings support for FWC-c-range.

0.4: (intfuncs-0.4) Made FWC-f-isfunc transform argument to a function



0.1: Added more functions

1.0: Renamed some functions so that they now have “_” at the start of

their names

1.1: Made block compiling functions be located in self._comp now

2.0: Renamed self.tree and self.stack to self._tree and self._stack

3.0: Renamed self.l to self._l

3.1: Made self.continue and self.break go up one level.

4.0: Splitted self.addif(expr?) into self.addif(expr) and self.addelse()

4.1: Added self.endfor() and self.endwhile().

4.2: Made it possible to minimize code (currently only indent is removed

and command names are truncated).


0.1: Added frawor-r-os.path.relpath.

Made frawor-r-os.path.normpath also simplify its argument.

0.2: Added frawor-r-os.readsystem, made also accept

plain strings as the first argument.


0.1: Added folds frawor-av-special.


1.0: Removed resource, made it handle python and python3 separately.


0.1: Added ability to have [{plid}, {version}, {key}] in

frawor-fd-function and frawor-fd-thisplugin.


0.1: Added usedictcompsplitfunc option.


0.1: Added frawor-od-override.

vim: ft=help:tw=78