:h format.txt

format.txt Convert current file to colored HTML, BBCode or whateverLINK

==============================================================================

CONTENTS format-contentsLINK

1. Intro format-intro

2. Functionality provided format-functionality

2.1. Commands format-commands

2.2. Features format-features

3. Options format-options

3.1. HTML specification options format-options-html

3.2. vimorg-tagged specification options format-options-vo-tagged

4. Format specification description format-spec

4.1. Dictionary keys format-spec-keys

4.2. String descriptions format-spec-description

5. List of built-in format specifications format-formats

==============================================================================

1. Intro format-introLINK

This plugin provides the ability to convert current file to colored HTML,

BBcode, (in future) LaTeX or whatever you have written specification for.

Features:

∙ Flexible format specifications.

∙ Ability to create abstract stylesheets.

∙ 'list' and 'listchars' options support (only tab, trail, eol and conceal

for now).

∙ Side-by-side diffs support. format-side-by-side-diff

∙ Support for creating numbered lines.

∙ Dynamic folds support. g:format_AllFolds

Differencies with built-in :TOhtml:

∙ For large files formatting using my plugin is faster.

∙ 'list' and 'listchars' options support.

∙ Background color for the whole line with differencies, not just for text

(for g:html_no_pre=1) and without trailing spaces (for

g:html_no_pre=0).

∙ Signs support. signs

∙ Tags linked to their definition. Implemented for 2html in

vimscript #2252. g:format_IgnoreTags

∙ (HTML) Anchors in tags definition location: for copying links.

g:format_HTMLAddLinkAtTagLine

∙ Side-by-side diff based on tables (2html relies on lines having the same

height which is generally false).

∙ Full conceal support: with g:format_FormatConcealed set to 2

formats-format-html generates both concealed and shown.

∙ Non-copyable signs, fold columns and numbers by default. 2html requires

setting g:html_prevent_copy.

∙ 'fillchars' vert suboption support (2html supports only diff and fold

suboptions).

∙ Matches and 'hlsearch' support. g:format_FormatMatches

∙ More correct highlighting in some cases.

∙ Support for formats other then HTML/XHTML (format-formats). Makes it

relatively easy to add new format to the list of supported formats

(format-f-format.add).

∙ 2html still has more options for HTML formatting though.

∙ Full 'foldcolumn' support: 2html sets foldcolumn to either 'foldcolumn'

value or maximum fold level, whichever is greater, formatvim uses

'foldcolumn' value, fully emulating what vim shows.

∙ 'spell' checking support. g:format_IgnoreSpell

Plugin requires some additional plugins:

∙ frawor (https://bitbucket.org/ZyX_I/frawor)

Note: formatvim supports VAM (https://github.com/MarcWeber/vim-addon-manager).

It is prefered that you use it for formatvim installation.

==============================================================================

2. Functionality provided format-functionalityLINK

------------------------------------------------------------------------------

2.1. Commands format-commandsLINK

format-actionsLINK

:Format {action} ... format-:Command :FormatCommandLINK

The only command provided by this plugin.

format-action-formatLINK

:{range}Format format [{formatName} [{option1} {value1}]]

Create a new buffer which contains lines formatted using the

specification named {formatName} ("html" by default). If {range}

is not given, format the whole file. For list of built-in formats

see format-formats. Possible options:

Option Value and description

columns Unsigned integer greater then zero or -1. This

option is used to specify number of columns (screen

width). Overrides format-o-MinColumns.

to Defines file where result should be saved. If no

file was specified, new buffer will be created.

cursor Bool (`cursor' or `nocursor').

Overrides format-o-IgnoreCursor, does the

opposite to it.

number Bool (`number' or `nonumber').

Overrides format-o-NoLineNR, does the opposite to

it.

relativenumber Bool (`relativenumber' or `norelativenumber').

Overrides format-o-RelativeNumber.

list Bool (`list' or `nolist').

Overrides format-o-IgnoreList.

Does the opposite to the IgnoreList option.

diff Bool (`diff' or `nodiff').

Overrides format-o-IgnoreDiff.

Does the opposite to the IgnoreDiff option.

starttagreg Regex (in very nomagic mode: /\V).

Overrides format-o-StartTagReg.

endtagreg Regex (in very nomagic mode: /\V).

Overrides format-o-EndTagReg.

tags False (`notags'), `local' or `all'.

Overrides format-o-IgnoreTags.

foldcolumn `nofoldcolumn', unsigned integer or -1.

Overrides format-o-FoldColumn.

folds Bool (`folds' or `nofolds').

Overrides format-o-IgnoreFolds, does the opposite

to it.

signs Bool (`signs' or `nosigns').

Overrides format-o-IgnoreSigns, does the opposite

to it.

spell Bool (`spell' or `nospell').

Overrides format-o-IgnoreSpell, does the opposite

to it.

concealed False (`noconcealed'), `show' or `both'.

Overrides format-o-FormatConcealed.

progress False (`noprogress'), `lines' or `percent'.

Overrides format-o-ShowProgress.

collapsfiller `nocollapsfiller' or unsigned integer.

Overrides format-o-CollapsFiller.

allfolds Bool (`allfolds' or `noallfolds').

Overrides format-o-AllFolds.

matches False (`nomatches'), `search', `matches' or `all'.

Determines whether patterns searched for and

patterns returned by getmatches() should be taken

into account: with `search' and `all' arguments it

formats search pattern as if 'hlsearch' were on

(actual value is ignored), with `matches' or `all'

it formats getmatches() output.

Overrides format-o-FormatMatches.

links Bool (`links' or `nolinks').

Overrides format-o-FormatLinks.

format-side-by-side-diffLINK

format-action-diffformatLINK

:{range}Format diffformat [{formatName} [{option1} {value1}]]

Like format-action-format, but create a side-by-side diff file.

In side-by-side diff format-o-CollapsFiller and

format-o-AllFolds are ignored and set to false, you also cannot

specify this options on the command line. If in one of the diffed

windows 'foldmethod' is not equal to "diff" then

format-o-IgnoreFolds is also overriden and set to true.

Note that in side-by-side diff document in first column is the

document where the command were called from.

Note that if there is only one or no windows where 'diff' is set

then empty buffer will be created and nothing will be generated.

:Format list format-action-listLINK

Print a list of format specifications.

------------------------------------------------------------------------------

2.2. Features format-featuresLINK

format.add : function ({formatName}, {specification}) format-f-format.addLINK

+ unload

Add {specification} to the list of specifications and name it

{formatName}. If specification named {formatName} already exists then

it throws an exception. For the description of {specification} see

format-spec.

==============================================================================

3. Options format-optionsLINK

b:formatOptions g:formatOptionsLINK

All options are located either in b:formatOptions and g:formatOptions

dictionaries or in [gb]:format_{option} variables (see frawor-f-getoption).

g:format_DefaultFormatLINK

DefaultFormat :: String format-o-DefaultFormatLINK

Default format specification's name. Default: html.

g:format_IgnoreFoldsLINK

IgnoreFolds :: Bool format-o-IgnoreFoldsLINK

If IgnoreFolds is true, then act as if there were no text folds. See

fold.txt for more information about folding. Default: 0.

Note that if format specification does not provide "fold" key then

closed folds will be ignored even if IgnoreFolds is set to 0.

g:format_AllFoldsLINK

AllFolds :: Bool format-o-AllFoldsLINK

If IgnoreFolds is not true and current format has either foldstart or

foldend keys (or both), then collect all possible folds and call

foldstart at each fold start and foldend at each foldend. Default: 0.

Note that this option will overwrite your 'foldminlines' option, so

you will have to restore it manually if you terminate formatting

process.

g:format_FoldColumnLINK

FoldColumn :: -1 | 0 | Natural format-o-FoldColumnLINK

If FoldColumn is set to -1 (default) and IgnoreFolds is not true, then

foldcolumn is added to the resulting format if 'foldcolumn' is greater

then zero. Other values override 'foldcolumn' option. Note that this

option will overwrite your 'foldminlines' option, so you will have to

restore it manually if you terminate formatting process.

g:format_IgnoreListLINK

IgnoreList :: Bool format-o-IgnoreListLINK

If IgnoreList is true, then ignore 'list' and 'listchars' options.

Now plugin supports only tab, trail, eol and conceal 'listchars'

specifications. Default: 0.

g:format_IgnoreSignsLINK

IgnoreSigns :: Bool format-o-IgnoreSignsLINK

If IgnoreSigns is true, then placed signs are ignored (see :sign).

Default: 0.

g:format_IgnoreDiffLINK

IgnoreDiff :: Bool format-o-IgnoreDiffLINK

If IgnoreDiff is true, then ignore 'diff' option.

Default: 0.

g:format_StartTagRegLINK

StartTagReg :: Regex format-o-StartTagRegLINK

Defines regular expression that must match before the start of the tag

text. Regex must be in magic mode (/\m) and you must use zero-width

look-aheads/look-behinds if you need to match something that is the

part of the tag. Regex is wrapped into /\%( and is suffixed by

/\zs to exclude it from match.

g:format_EndTagRegLINK

EndTagReg :: Regex format-o-EndTagRegLINK

Like format-o-StartTagReg, but defines regex that must be matched

after end of the tag text. Like above it is wrapped into /\%( and

prefixed by /\ze.

g:format_IgnoreTagsLINK

IgnoreTags :: 0 | 1 | 2 format-o-IgnoreTagsLINK

Defines whether tags are ignored, see taglist()

0: do not ignore any tags. In HTML format it produces the following

tags:

(if tag links to the current buffer) and

(if tag links to other file). Here {path} is a path to the file

with tag definition relative to the current directory (if

possible). Note that HTML formatter escapes all `<' and `>'

characters, so it is safe to use regular expressions to change the

tags.

1: ignore tags that are not in current file (default)

2: ignore all tags

Note: it is highly recommended that you use vim-7.3.627 and higher

when formatting tags.

g:format_AddTagCmdEscapesLINK

AddTagCmdEscapes :: [ Char ] format-o-AddTagCmdEscapesLINK

String, defines a list of characters that should be escaped if `cmd'

key in tag description returned by taglist() is an vim pattern.

Default: '[]*.~'.

g:format_MaxDupTagsLINK

MaxDupTags :: UInt format-o-MaxDupTagsLINK

Defines a maximum number of tag entries with one name. If actual

number of tag entries that share the same name exceeds this value,

then this tag is ignored. You can set this option to 0 in order to

prevent filtering. Default: 5.

g:format_IgnoreSpellLINK

IgnoreSpell :: Bool format-o-IgnoreSpellLINK

Determines whether spell checker highlighting should be ignored.

Default: 0.

g:format_RelativeNumberLINK

RelativeNumber :: -1 | Bool format-o-RelativeNumberLINK

If it is true, then it adds relative line numbers, just like when

'relativenumber' is set ('relativenumber' was introduced in vim 7.3,

but this option will also work in vim 7.2). -1 (default) means that

this option will be enabled if 'relativenumber' option is set.

Overrides format-o-NoLineNR.

g:format_NoLineNRLINK

NoLineNR :: -1 | Bool format-o-NoLineNRLINK

If it is true then do not add the line numbers, -1 (default) means

"preserve 'number' option" (plugin acts as if NoLineNR were true if

'number' is not set and as if it were false otherwise). It does the

following:

1. Sets @_donr@ to 0

2. Makes "%#" and "%_" return blank strings

3. Forces skipping applying "linenr" specification

It has the same effect as removing "linenr" key from specification.

g:format_CollapsFillerLINK

CollapsFiller :: UnsignedInteger format-o-CollapsFillerLINK

If this value is not zero, number of deleted lines is equal or greater

than CollapsFiller and there is "collapsedfiller" key in format

specification then this key is used instead of repeating "difffiller"

for every deleted line. If "difffiller" key is absent, then this

option is ignored and plugin will act as if this option was set to 1.

g:format_IgnoreCursorLINK

IgnoreCursor :: Bool format-o-IgnoreCursorLINK

If this option is true (default) then cursor position is ignored

(cursor line does not get highlighted when 'cursorline' is on, line

number in cursor line does not use hl-CursorLineNr (unless

'relativenumber' is set), concealed characters are concealed

regardless of 'concealcursor' setting).

g:format_FormatConcealedLINK

FormatConcealed :: 0, 1 or 2 format-o-FormatConcealedLINK

If both this option and 'conceallevel' have non-zero values, then only

actually shown text will be formatted. Difference between values

1 (default) and 2 is that if FormatConcealed value is 1 then

format-spec-key-line will be used with specification derived from

hl-Concealed higlight group, thus losing information about what

characters are actually hidden. And if FormatConcealed value is 2 then

format-spec-key-concealed is used, so information about concealed

characters can be possibly saved.

g:format_FormatMatchesLINK

FormatMatches :: none, search, matches or all format-o-FormatMatchesLINK

Determines whether patterns searched for and patterns returned by

getmatches() should be taken into account: with `search' and `all'

arguments it formats search pattern as if 'hlsearch' were on (actual

value is ignored), with `matches' or `all' it formats getmatches()

output.

Default: `all' if 'hlsearch' is on and v:hlsearch is 1 and `matches'

if it is not.

If v:hlsearch is not present it is `all' once 'hlsearch' is

on. If vim was compiled without +extra_search it is

`matches' by default regardless of other settings.

g:format_FormatLinksLINK

FormatLinks :: Bool format-o-FormatLinksLINK

Determines whether links should be detected and formatted using

format-spec-key-linkstart and/or format-spec-key-linkend. If true

linkstart is added before links described by format-o-LinkRegexes

and linkend is added after.

Default: 1.

b:format_LinkRegexes g:format_LinkRegexesLINK

LinkRegexes :: [(regexp, expr)] format-o-LinkRegexesLINK

Determines what the link is and what it links to. Is a list of pairs

where first value is a regular expression (in /\m and /\C mode)

and second value is a sub-replace-expression.

Note: if you define both g:format_LinkRegexes and b:format_LinkRegexes

they will be merged together. g:format_LinkRegexes will override

default value, b:format_LinkRegexes will be merged with it.

Note 2: you must define regexes so that they will not overlap.

g:format_ShowProgressLINK

ShowProgress :: 0, 1 or 2 format-o-ShowProgressLINK

If this option is not zero then show progress bar. Differencies

between 1 and 2:

Value Bar

1 [=> ] 10% (bar and per cent count)

2 [=> ] 1/9 10% (bar, currentline/lastline, per cent count)

Note that it is currentline/lastline, not

linesformatted/linestoformat

Default: 0.

Note that in terminal it is impossible (at least in version 7.2) to

determine actual window size if you resize vim while script is

running, so doing that may render progress bar useless. This does not

apply to gvim.

g:format_ColorFileLINK

ColorFile :: 0 or filename (file must be readable) format-o-ColorFileLINK

If this option is not zero, then read colors from file {ColorFile}

instead of {rtp}/config/formatvim/colors-default-'t_Co'.yaml. Relevant

only for vim running in color terminal or when using

format-format-csi (in the latter case

{rtp}/config/formatvim/colors-default.yaml is used by default which

has only 16 colors). It is allowed to skip {rtp}/config/formatvim

part: if no path separators or forward slashes appear in the option

value then it is searched there.

Format of the file must be the following (it is a very limited subset

of YAML):

# Comment

--- # Document start (may be omitted)

# Default color

- "#000000" # Color 0

- "#abcdef" # Color 1

# Yet another comment

- "#dead00" # Color 2

... # Document end (may be omitted)

# Note the following: each non-comment line must start with `- '

# (a dash and a space, exactly at the start of line) followed by

# an opening quote (either «'» or «"»), a hash, six hexadecimal

# digits and a closing quote («'» or «"» depending on what you

# have chosen before).

Note that this option must be set before format.vim is loaded. All

changes made to this option will be ignored if plugin is already

loaded (though you may use frawor#Reload()).

In the tools/ directory there is a script which helps you with

creating color table: tools/getcolors.pl. It requires perl bindings to

imagemagick, imagemagick shell commands and xdotool (to get focused

window) installed, latter is optional. Usage is the following:

# If you have N-colored terminal

./tools/getcolors.pl colors.yaml N

# If you created a screenshot with color table by yourself and

# want getcolors.pl to parse it (lines and columns are arguments

# to SetupTable function in colortable.vim)

./tools/getcolors.pl image.png lines columns > colors.yaml

Note: you can’t use the script in first form with less then four

colors.

g:format_UseStyleNamesLINK

UseStyleNames :: Bool format-o-UseStyleNamesLINK

If true, format-spec-%S uses name attributes in place of styleid.

Default: false.

Note: unlike style IDs, style names are not guaranteed to be unique,

though conflict is unlikely to occur.

g:format_MinColumnsLINK

MinColumns :: UnsignedInteger format-o-MinColumnsLINK

Determines minimal number of columns text must occupy. If there is a line

that is wider then MinColumns then value of this option is ignored. Useful

for format-spec-%.-, format-spec-%-, format-spec-%+.

Default: 40.

------------------------------------------------------------------------------

3.1. HTML specification options format-options-htmlLINK

g:format_HTMLAnchorFileNameExprLINK

HTMLAnchorFileNameExpr :: expr format-o-HTMLAnchorFileNameExprLINK

Expression used to generate filename in anchor out of filename attached to

the tag. Defaults to a:tag.tfname.".html".

In the expression you can use the a:tag variable which is a dictionary

with the following keys in addition to keys defined by taglist() and by

formatvim (see format-tag-keys):

Key Description

__ename String, tag name escaped for use in anchor (wikipedia-style

escaping). See http://www.w3.org/TR/html4/types.html#type-name

for the description why this is needed. Example of such escaping:

tag 'ls' is escaped to .27ls.27.

g:format_HTMLUseTagNameInAnchorLINK

HTMLUseTagNameInAnchor :: Bool format-o-HTMLUseTagNameInAnchorLINK

Determines whether anchor should contain tag name or line number.

Defaults to false.

g:format_HTMLAddLinkAtTagLineLINK

HTMLAddLinkAtTagLine :: Bool format-o-HTMLAddLinkAtTagLineLINK

Determines whether line that contains tag definition should also contain

tag link. This link is to be used for copy-pasting. Defaults to true.

g:format_HTMLTitleExprLINK

HTMLTitleExpr :: expr format-o-HTMLAddLinkAtTagLine

Determines what file name should go into title.

Default: expand('%:p:~').

g:format_HTMLFontFamilyLINK

HTMLFontFamily :: string format-o-HTMLFontFamilyLINK

Determins font-family property in embedded CSS.

Default: `"Bitstream Vera Sans Mono","DejaVu Sans Mono",Monaco,monospace`.

g:format_HTMLAdditionalCSSLINK

HTMLAdditionalCSS :: string format-o-HTMLAdditionalCSSLINK

Determines CSS string that will be added at the very end of <style> tag

contents. Default is empty.

Useful information about possible selectors:

Line selectors:

Selector Description

.Line Attached to the outer container of the regular line. If

side-by-side diff is active outer container is wrapped

into table line.

.Fold Same as above, but for folded lines.

See format-o-IgnoreFolds.

.DiffFiller Same as above, but for diff filler lines.

.CollapsedFiller Same as above, but for collapsed diff fillers.

See format-o-CollapsFiller.

.TrailLine Same as above, but for trailing ~ lines. Can only be

seen in side-by-side diff in some rare cases (e.g. when

diffing against an empty file).

See format-side-by-side-diff.

#line{n}-{b} Outer container for line number {n}. {b} is 0 unless

side-by-side diff is being generated, otherwise it is

number of the buffer.

Fold selectors, see format-o-IgnoreFolds and format-o-AllFolds:

Selector Description

.Fold > .Text Text inside collapsed fold.

.Fold > .FoldFiller Fold filler inside collapsed fold.

format-side-by-side-diff selectors:

Selector Description

.SbSDLine Outer container for some line in all buffers in

a side-by-side diff.

.SbSD{n} Outer container for a buffer in a side-by-side diff.

.SbSDSep Container for 'fillchars'/vert that separates two diffed

buffers.

.SbSDSep{n} Same as above, but only for separator between (n-1)’th diffed

buffer and n’th.

#sbsd{n} Outer container for a line {n}. Note that due to diff fillers

and folds this may have nothing to do with actual line number

in any of the diffed buffers.

format-o-FormatConcealed==2 selectors:

Selector Description

.Concealed Container for both concealed and shown text.

.Concealed > .Shown Container for the :syn-cchar.

.Concealed > .Present Container for the text actually present in the

buffer.

Tags and links, see format-o-IgnoreTags and format-o-FormatLinks:

Selector Description

.Tag Link to some tag definition.

.TagLink Container for quick link near tag definition. Applicable

only if format-o-HTMLAddLinkAtTagLine is true.

.TagLink > a Like above, but selects the link itself.

.Link Link to some location

Selectors for various columns:

Selector Description

.LineNR Container for line number, see format-o-NoLineNR, 'number'

and 'relativenumber' options.

.FoldColumn Container for fold column, see format-o-IgnoreFolds,

format-o-FoldColumn and 'foldcolumn' options.

.Sign Container for signs, see format-o-IgnoreSigns.

.SignImage Same as above, but selects only signs that use icons.

.SignText Same as above, but selects only signs that do not use icons.

.SignAbsent Same as above, but selects only sign columns in lines where

no sign is defined.

------------------------------------------------------------------------------

3.2. vimorg-tagged specification options format-options-vo-taggedLINK

g:format_VOHelpPrefix g:format_VOHelpSuffix g:format_VOHelpAnchorExprLINK

VOHelpPrefix :: string format-o-VOHelpPrefixLINK

VOHelpSuffix :: string format-o-VOHelpSuffixLINK

VOHelpAnchorExpr :: expr format-o-VOHelpAnchorExprLINK

All these options determine how links at the bottom should look like: they

are used as below:

[1] {VOHelpPrefix}{filename}{VOHelpSuffix}#{eval(VOHelpAnchorExpr)}

Defaults are the following:

[1] http://vimpluginloader.sourceforge.net/doc/format.txt.html#line220-0 (g:format_IgnoreTags)

1111111111111111111111111111111111111111111222222222233333 4444444444444444444444444444444

[1] http://vimpluginloader.sourceforge.net/doc/options.txt.html#.27list.27

11111111111111111111111111111111111111111112222222222233333 4444444444

where

1 is VOHelpPrefix (note: includes the trailing slash).

Default is "http://vimpluginloader.sourceforge.net/doc/".

2 is help file name.

3 is VOHelpSuffix. Default is ".html".

4 is a result of eval()uating VOHelpAnchorExpr.

Default is "tag.__ename=~#':'?('line'.tag._linenr.'-0 ('.tag.name.')'):(tag.__ename)".

Note: here it uses tag variable which is a dictionary described at

format-tag-keys. In addition to those keys __ename key is

available which is the same as described at

format-o-HTMLAnchorFileNameExpr.

==============================================================================

4. Format specification description format-specLINK

Document is constructed in the following way:

[begin]?

(

[foldend]?

[foldstart]?

[linestart][foldcolumn][sign][linenr]{line}[lineend]

[end]?

where

[begin] is described by the format-spec-key-begin,

[end] is described by format-spec-key-end,

[linestart] by format-spec-key-linestart,

[foldcolumn] by format-spec-key-foldcolumn,

[sign] by format-spec-key-sign,

[linenr] by format-spec-key-linenr,

[lineend] by format-spec-key-lineend,

[foldend] by format-spec-key-foldend,

[foldstart] by format-spec-key-foldstart,

while {line} may be

- a sequence of items described by format-spec-key-line (for regular

lines),

- a difffiller described by format-spec-key-difffiller,

- collapsed sequence of difffillers described by

format-spec-key-collapsedfiller,

- or a folded text described by format-spec-key-fold.

In the first case there may be additional tokens:

[tagstart][concealedstart]([tagstart][line][tagend])*[concealedend][tagend]

where

[tagstart] is described by format-spec-key-tagstart,

[concealedstart] by format-spec-key-concealedstart,

[line] by format-spec-key-line,

[concealedend] by format-spec-key-concealedend,

[tagend] by format-spec-key-tagend.

Actual position of [tagstart] and [tagend] depends on the place where tag was

matched. It is a bug to have nested [tagstart] .. [tagend] pairs.

For side-by-side diff generation first all lines of first document are being

generated, then all lines of second document are being generated (both without

beginning and ending, format-spec-key-haslf and format-spec-key-nolf are

ignored) and then generated lines are merged like that:

[sbsdstart]{lineOfFirstDocument}[sbsdsep]{lineOfSecondDocument}[sbsdend]

where

[sbsdstart] is described by the format-spec-key-sbsdstart,

[sbsdsep] by format-spec-key-sbsdsep,

[sbsdend] by format-spec-key-sbsdend.

format-spec-key-begin, format-spec-key-end, format-spec-key-haslf and

format-spec-key-nolf are being processed only after line merge.

Everything is defined in the format specification which is the dictionary with

the following keys (only `line' key is required):

------------------------------------------------------------------------------

4.1. Dictionary keys format-spec-keysLINK

begin format-spec-key-beginLINK

String, describes the beginning of the document. Arguments (see

format-spec-description) (listed only arguments with non-standart

values):

Argument Value

@@@ Empty string

@.@ 0 (zero)

@-@ 0 (zero)

@{stspec}@ Specification derived from hl-Normal highlight group

sbsdstart format-spec-key-sbsdstartLINK

String, describes the start of side-by-side diff line. Arguments (see

format-spec-description) (listed only arguments with non-standart

values):

Argument Value

@@@ Empty string

@.@ 0 (zero)

@-@ Index of the current line (Note that index is not current

line number)

@{stspec}@ Specification derived from hl-Normal highlight group

sbsdsep format-spec-key-sbsdsepLINK

String, describes the document separator of side-by-side diff line.

Arguments (see format-spec-description) (listed only arguments with

non-standart values):

Argument Value

@@@ Empty string

@.@ Number of document on the right site of the separator

@-@ Index of the current line (Note that index is not current

line number)

@{stspec}@ Specification derived from hl-VertSplit highlight group

foldstart format-spec-key-foldstartLINK

String, describes start of each possible fold. Used only if

format-o-AllFolds is true. Arguments (see format-spec-description)

(listed only arguments with non-standart values):

Argument Value

@@@ Value returned by foldtextresult() concatenated with

fold, sign and column number contents

@.@ Fold level

@{stspec}@ Specification derived from hl-Folded highlight group

linestart format-spec-key-linestartLINK

String, describes each start of line. Arguments (see

format-spec-description) (listed only arguments with non-standart

values):

Argument Value

@@@ 0 for regular lines,

1 for folded lines,

2 for difffiller,

3 for collapsedfiller,

4 for trailing ~ filler lines

@.@ 0 (zero)

@{stspec}@ Specification derived from hl-Normal highlight group,

possibly joined with sign linehl group, hl-CursorLine

and/or hl-DiffAdd /hl-DiffChange. For folded lines

specification changes to hl-Folded highlight group, for

difffiller and collapsedfiller lines specification changes

to hl-DiffDelete highlight group.

foldcolumn format-spec-key-foldcolumnLINK

String, describes foldcolumn at the start of each line. Arguments (see

format-spec-description) (listed only arguments with non-standart

values):

Argument Value

@@@ String that is supposed to be displayed in the real

foldcolumn

@.@ Folding level

@{stspec}@ Specification derived from hl-FoldColumn highlight group

sign format-spec-key-signLINK

String, describes sign at the start of each line. Arguments (see

format-spec-description) (listed only arguments with non-standart

values):

Argument Value

@@@ String that is supposed to be displayed in the real

sign column or path to the icon

@.@ 0 if no sign is placed on this line,

1 for text sign,

2 for icon sign

@{stspec}@ Specification derived from hl-SignColumn highlight group

or whatever is defined in texthl property of the current

sign (see :sign-define).

linenr format-spec-key-linenrLINK

String, describes line number at the start of each line without folds.

Arguments (see format-spec-description) (listed only arguments with

non-standart values):

Argument Value

@@@ Same as @-@ for normal lines or an empty string for

difffillers and collapsedfillers

@.@ 0 (zero)

@{stspec}@ Specification derived from hl-LineNr highlight group,

from both hl-Normal and hl-CursorLine highlight groups

if 'cursorline' is true and format-o-IgnoreCursor is

false or from hl-Folded highlight group for folded text

tagstart format-spec-key-tagstartLINK

String, describes the start of each tag. Arguments (see

format-spec-description) (listed only arguments with non-standart

values):

Argument Value

@@@ Tag name.

@{stspec}@ Undefined (it may be anything)

line format-spec-key-lineLINK

String, describes each differently highlighted group of characters.

Arguments take only standart values (see format-spec-description).

Note that this the only required key.

format-spec-key-concealed...LINK

concealedstart format-spec-key-concealedstartLINK

String, describes the start of concealed character. Arguments (see

format-spec-description) (listed only arguments with non-standart

values):

Argument Value

@@@ :syn-cchar.

@{stspec}@ Specification derived from hl-Concealed highlight group

concealedend format-spec-key-concealedendLINK

String, describes the end of concealed character. Arguments (see

format-spec-description) (listed only arguments with non-standart

values):

Argument Value

@@@ :syn-cchar.

@{stspec}@ Specification derived from hl-Concealed highlight group

tagend format-spec-key-tagendLINK

String, describes the end of each tag. Arguments (see

format-spec-description) (listed only arguments with non-standart

values):

Argument Value

@@@ Tag name.

@{stspec}@ Undefined (it may be anything)

fold format-spec-key-foldLINK

String, describes each fold. Arguments (see format-spec-description)

(listed only arguments with non-standart values):

Argument Value

@@@ Value returned by foldtextresult()

@.@ 0 (zero)

@{stspec}@ Specification derived from hl-Folded highlight group

difffiller format-spec-key-difffillerLINK

String, describes difffiller. Arguments (see

format-spec-description) (listed only arguments with non-standart

values):

Argument Value

@@@ @_difffillchar@

@.@ (Total number of filler lines)-(Number of filler lines

already created)

@{stspec}@ Specification derived from hl-DiffDelete highlight group

collapsedfiller format-spec-key-collapsedfillerLINK

String, describes collapsed filler. Arguments (see

format-spec-description) (listed only arguments with non-standart

values):

Argument Value

@@@ Number of deleted lines

@.@ 0 (zero)

@{stspec}@ Specification derived from hl-DiffDelete highlight group

lineend format-spec-key-lineendLINK

String, describes each line end. Arguments (see

format-spec-description) (listed only arguments with non-standart

values):

Argument Value

@@@ 0 for regular lines,

1 for folded lines

2 for difffiller,

3 for collapsedfiller

4 for trailing ~ filler lines

@{stspec}@ Specification derived from hl-Normal highlight group,

possibly joined with sign linehl group, hl-CursorLine

and/or hl-DiffAdd /hl-DiffChange. For folded lines

specification changes to hl-Folded highlight group, for

difffiller and collapsedfiller lines specification changes

to hl-DiffDelete highlight group.

foldend format-spec-key-foldendLINK

String, describes end of each possible fold. Used only if

format-o-AllFolds is true. Arguments (see format-spec-description)

(listed only arguments with non-standart values):

Argument Value

@@@ Value returned by foldtextresult() concatenated with

fold, sign and column number contents

@.@ Fold level

@{stspec}@ Specification derived from hl-Folded highlight group

sbsdend format-spec-key-sbsdendLINK

String, describes the end of side-by-side diff line. Arguments (see

format-spec-description) (listed only arguments with non-standart

values):

Argument Value

@@@ Empty string

@.@ Number of documents formatted

@-@ Index of the current line (Note that index is not current

line number)

@{stspec}@ Specification derived from hl-Normal highlight group

end format-spec-key-endLINK

String, describes the end of the document. Arguments (see

format-spec-description) (listed only arguments with non-standart

values):

Argument Value

@@@ Empty string

@.@ 0 (zero)

@-@ Number of last formatted line

@{stspec}@ Specification derived from hl-Normal highlight group

style format-spec-key-styleLINK

String, describes the style of the given highlight group, this style

is appended to @:@. Used only once for each highlight group. Arguments

(see format-spec-description) (listed only arguments with

non-standart values):

Argument Value

@@@ Style id

@.@ 0 (zero)

@-@ 0 (zero)

@{stspec}@ Specification derived from current style

strescape format-spec-key-strescapeLINK

String, specifies expression that should be used to obtain escaped

string for current format. In expression `@@@' should represent

escaped value. Should not depend on anything except

format-spec-@_key@, format-spec-@__key@ or format-spec-@___key@

and format-spec-@@@.

strlen format-spec-key-strlenLINK

Function reference, specifies the function that counts length of line

for "%_" and "%-" formats and "@=@" argument. Can be accessed inside

%=...=% via @_strlen@. Default: strdisplaywidth().

tagproc format-spec-tagprocLINK

Function reference. If present this function will be called for every

tag found with two arguments: options dictionary (see

format-spec-@_key@, format-spec-@__key@ and format-spec-@___key@

for a list of keys you may find in this dictionary) and the tag

dictionary. Tag dictionary contains all keys found in taglist()

output and additionally the following keys: format-tag-keysLINK

Key Description

_incurf Boolean, true if tag is located in the current file.

Note: will be false if tag is located in the current file,

but outside of the formatted region.

_found Boolean, true if tag is referenced at least once in the

current file.

_tfname String, filename relative to the current working directory.

_linenr Number, number of line that contains tag definition.

This function may add some keys to tags dictionary in order to speed

up tags processing.

Note: all keys that do not start with the underscore are reserved for

taglist(), all keys that start with one underscore are

reserved for formatvim. Use keys that start with two

underscores.

nolf format-spec-key-nolfLINK

Bool. Normally, new item in list returned by format-func-format

starts after each lineend, difffiller, collapsedfiller, fold,

foldstart and foldend, but if this option is present and not zero then

all items are joined and the list of one item is returned. Makes the

script halt for some time at 100% progress (~30s on 1 MiB file), so be

patient. Default: 0.

haslf format-spec-haslfLINK

Bool. Causes script to additionaly split each item in list returned by

format-func-format on "\n" character. It is the only way to include

line breaks inside format items. This option is applied after nolf, so

set both nolf and haslf to 1 if you want to have line breaks defined

only by your format specification. Default: 0.

addopts format-spec-addoptsLINK

Dictionary. All keys from this dictionary are copied (deepcopy())

and accessible as format-spec-@__key@. Only keys containing latin

letters, digits and underscores are allowed. Keys must not start with

underscores.

addoptsfun format-spec-addoptsfunLINK

Function that returns dictionary. All keys from this dictionary are

copied (deepcopy()) and accessible as format-spec-@___key@. Only

keys containing latin letters, digits and underscores are allowed.

Keys must not start with underscores.

This function is called each time format is used. Before it is called

keys defined in previous run are wiped out.

state format-spec-stateLINK

sbsdstate format-spec-sbsdstateLINK

Dictionary that contains mutable state and Dictionary-functions that

manipulate it, receiving this dictionary as self variable.

Difference between state and sbsdstate keys is that the former is

regererated (deepcopy()) before each next processed buffer and the

latter is regenerated once per :Format call.

If these dictionaries contain `init' key then it will be called with

a single opts (see format-spec-@_key@) dictionary as an argument

once after each regeneration. It will as well receive newly generated

dictionary as self variable.

See also format-spec-@!key@: this is how you should use it.

Note that after each lineend, foldstart and foldend a newline will be added

unless nolf option is present: using "{range}FormatCommand format

{formatName}" is equivalent to:

let Format=LoadFuncdict().getfunctions("format").format

let lines=call(Format, [{formatName}, {rangeStart}, {rangeEnd}], {})

new ++enc=utf-8

call setline(1, lines)

------------------------------------------------------------------------------

4.2. String descriptions format-spec-descriptionLINK

Most specification keys use the following format to describe what plugin

should actually have in the returned value. It uses %C to describe some common

strings and format-spec-expression to describe more complex structures. Here

are the characters that are used in the %C expression. All characters not

listed here are reserved and throw an error.

%%, %@ format-spec-%% format-spec-%@LINK

Percent sign and `at' symbol.

%f, %b format-spec-%f format-spec-%bLINK

Foreground and background colors (string with format "#RRGGBB"), same

as @fgcolor@ and @bgcolor@ inside %=...=%.

%S format-spec-%SLINK

Style id ("N", "N_N", "N_N_N", …: numbers are added for signs, diff

highlighting, 'cursorline' highlighting and so on), same as

%=@styleid@=%. See also format-o-UseStyleNames.

%N format-spec-%NLINK

Current line number, same as %=@-@=%.

%C format-spec-%CLINK

Column number of the end of string, same as %=@.@=%.

%s format-spec-%sLINK

String being formatted. Escaped using format-spec-key-strescape.

%: format-spec-%:LINK

All styles in format-spec-key-begin and format-spec-key-end,

current style only in other specification keys, same as

%=@:@=%.

%# format-spec-%#LINK

Either line number padded to the right with @_leadingspace@ (for

normal lines) or a sequence of @_leadingspace@s (for difffiller and

collapsedfiller lines) if @_donr@ is true or an empty string

otherwise.

%_ format-spec-%_LINK

@_leadingspace@ repeated @_linenumlen@ times if @_donr@ is true or an

empty string otherwise.

%<SPACE> format-spec-%SPACELINK

A single @_leadingspace@. Just the same as %=@_leadingspace@=%, but

computed only once.

%+ format-spec-%+LINK

@_leadingspace@ repeated enough times for the line length to be less

or equal to @_columns@ (`less' case can appear only if length of

@_leadingspace@, computed by format-spec-key-strlen, is greater

then 1).

%^ format-spec-%^LINK

A single @_leadingspace@ if @_donr@ is true or an empty string

otherwise. Just the same as %=((@_donr@)?(@_leadingspace@):(''))=%,

but computed only once.

%- format-spec-%-LINK

@_difffillchar@ repeated enough times for the line length to be less

or equal to @_columns@ (`less' case can appear only if length of

@_difffillchar@, computed by format-spec-key-strlen, is greater

then 1).

%~ format-spec-%~LINK

A single @_difffillchar@. Just the same as %=@_difffillchar@=%.

%.- format-spec-%.-LINK

@_foldfillchar@ repeated enough times for the line length to be less

or equal to @_columns@ (`less' case can appear only if length of

@_foldfillchar@, computed by format-spec-key-strlen, is greater

then 1).

%.~ format-spec-%.~LINK

A single @_foldfillchar@. Just the same as %=@_foldfillchar@=%.

%| format-spec-%|

A single @_vertseparator@. Just the same as %=@_vertseparator@=%.

------------------------------------------------------------------------------

4.2.1. Expressions in string description format-spec-%=LINK

format-spec-%' format-spec-%>LINK

format-spec-expressionLINK

Inside string descriptions can be used complex expressions:

"%={expression}=%", "%'{expression}'%" and "%>{expression}". In the first form

all '%' and '\' characters need to be escaped, in the second form you must not

allow the string "'%" to appear inside expression, and the third form just

grabs the whole string after "%>".

format-spec-%!LINK

There is also a special form of expression, valid only at the start of the

string: "%!{commands}!%", where {commands} is a newline-separated list of

commands. It can be used to declare variables. Note that you must omit having

"!%" inside {commands} string.

Inside the expressions you can use the following sequences (use them in place

of ordinary variables):

@@@ format-spec-@@@LINK

String being formatted.

@-@ format-spec-@-@LINK

Current line number.

@.@ format-spec-@.@LINK

Column number of the end of the string.

@:@ format-spec-@:@LINK

String with all styles in format-spec-key-begin and

format-spec-key-end, string with current style in other

specification keys.

format-spec-@$@LINK

@=@ format-spec-@=@LINK

Length of the string of the current line before expression. You must

split format with @$@ at the very top level of expr before using it to

get valid values. Example:

Some text<span class="Filler">%''@$@repeat(@_foldfillchar@),@_columns@-@=@)''%</span>

You do not have to use it if your filler is not followed by any text.

@{stspec}@ format-spec-@key@LINK

Value of the style specification. Possible {stspec}s:

{stspec} Value

styleid ID of the current highlight group. For normal lines it is

a single number, for lines with differencies it is equal to

{hlID}_{diffhighID}. Signs and 'cursorline' may add

additional _{hlID} group.

name Like above, but uses names in place of numbers.

fgcolor Foreground color transformed to "#RRGGBB" notation.

bgcolor Background color transformed to "#RRGGBB" notation.

bold Bold syntax attribute.

italic Italic syntax attribute.

inverse Inverse syntax attribute.

underline Underline syntax attribute.

@~@ format-spec-@~@LINK

Dictionary with style specification. For a list of its keys, see

format-spec-@key@.

@S@ format-spec-@S@LINK

Same as format-spec-%S.

@_{option}@ format-spec-@_key@LINK

Value of the specified option. Possible {option}s:

{option} Value

leadingspace Space escaped using format-spec-key-strescape

expression.

fillchars Dictionary containing values from 'fillchars' options.

Not escaped.

difffillchar Value of the diff item in 'fillchars' option if it is

present, "-" otherwise. Escaped.

foldfillchar Value of the fold item in 'fillchars' option if it is

present, "-" otherwise. Escaped.

vertseparator Value of the vert item in 'fillchars' option if it is

present, "|" otherwise. Escaped.

columns Actual number of columns that will be used for the

formats like `%-'.

fgcolor Foreground color of "Normal" highlight group. If this

color is an empty string then it is either "#000000" or

"#ffffff" depending on 'background' option.

bgcolor Background color of "Normal" highlight group. If this

color is an empty string then it is either "#000000" or

"#ffffff" depending on 'background' option.

linenumlen Length of the number of the last line.

ignorefolds 1 if folds are ignored, 0 otherwise.

donr 1 if lines will be numbered normally, 0 otherwise.

dornr 1 if lines will be numbered relatively, 0 otherwise.

allfolds 1 if AllFolds is on, 0 otherwise

foldcolumn 0 if foldcolumn is not formatted, width of foldcolumn in

characters otherwise

ignorecursor 0 if IgnoreCursor is off and either 'cursorcolumn' is

set or cursor is within formatted line range,

1 otherwise.

sbsd 0 if side-by-side diff is not being generated, 1 if

begin, end and sbsd* format specification keys are being

processed, 1+N, where N>0 if N'th document is being

generated

formatconcealed 0 if concealed text is ignored, 1 or 2 otherwise, see

format-o-FormatConcealed.

formatmatches, formatsearch, formatsomematch

0 if related match will not be formatted, 1 if they are.