-
Notifications
You must be signed in to change notification settings - Fork 6
/
filetype_formatter.txt
151 lines (112 loc) · 5.92 KB
/
filetype_formatter.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
*filetype_formatter.txt* A general Neovim/Vim "code formatter" utility
Author: Samuel Roeca
Table of Contents
1. Introduction ... |filetype_formatter_intro|
2. Configuration .. |filetype_formatter_configuration|
3. Commands ....... |filetype_formatter_commands|
4. Mappings ....... |filetype_formatter_mappings|
5. Credits ........ |filetype_formatter_credits|
==============================================================================
*filetype_formatter_intro*
1. INTRODUCTION~
This plugin plugin simply applies command line code formatters to your Vim
buffer. It assumes:
1. Your Vim buffer has a filetype
2. You have associated a qualifying system command with your filetype
Code formatters are provided as system commands. A system command is
compatible with this plugin if it:
1. Takes its formatter input from standard input
2. Writes its formatted output to standard output
3. Is in your PATH. Vim-filetype-formatter uses code formatters; it does not
install them.
Most code formatters will be compatible with this plugin. If they are not, you
should submit a PR to the formatter's project; any well-designed code
formatter should be able to meet these minimal requirements.
This plugin assumes you have Bash installed and available at /bin/bash.
==============================================================================
*filetype_formatter_configuration*
2. CONFIGURATION~
*g:vim_filetype_formatter_commands*
Type: Dictionary[String, Union[String, F]]
F:
Function(Integer, Integer) -> String |
Function() -> String
Default: defined in plugin/filetype_formatter.vim
Assume you have several theoretical filetypes: 'dog', 'cat', 'bat', and 'rat'.
With these theoretical filetypes, you have some command line code formatting
programs: 'dog-fmt', 'cat-fmt', 'bat-fmt', and 'rat-fmt'. To enable the
relevant code formatters to run on each filetype, you might configure this
option as follows: >
let g:vim_filetype_formatter_commands = {
\ 'dog': 'dog-fmt --stdout -',
\ 'cat': 'cat-fmt --standard-out --std-in',
\ 'bat': {start, end -> printf('bat-fmt --lines=%d-%d', start, end)},
\ 'rat': {-> printf('rat-fmt --stdin-file=%s', expand('%:p'))},
\ }
If your Dictionary value is a String, it is assumed to operate over an entire
file / buffer.
If your Dictionary value is a Function that takes 0 arguments, it may require
some runtime functionality to format your string command, but it's assumed
that the formatter is not aware of visually-selected ranges.
If your Dictionary value is a Function that takes two arguments, these should
be the starting line and the ending line from your range selection. In this
case, the formatter itself will operate over the entire file but only format
from "start line" to "end line". This is good because only running the
formatter on selected text can be breakable without the text's broader
context. If a formatter provides a range interface, it's a good idea to use
it!
*g:vim_filetype_formatter_verbose*
Type: Boolean (or Integer, Vim doesn't care)
Default: 0 (for False)
This plugin follows the "Rule of Silence" from "The Art of Unix Programming".
This means that unsurprising messages are not given to the user. This mode
echos a confirmation the user that a command ran successfully. To enable it,
set this option to anything other than Zero: >
let g:vim_filetype_formatter_verbose = 1
*g:vim_filetype_formatter_ft_maps*
Type: Dictionary[String, String]
Default: {}
Maps a filetype to a top-level filetype. Values on the left should be
available as keys in vim_filetype_formatter_commands.
This default is provided purely as a courtesy. If you choose to override, you
will need to provide the above mappings again in your own vimrc if you would
like to retain them. >
let g:vim_filetype_formatter_ft_maps = {'sql.postgres', 'sql'}
*g:vim_filetype_formatter_ft_no_defaults*
Type: List[String]
Default: []
Contains a list of filetype strings for which the user wants no default values
configured. This is useful if you don't like the default formatter but don't
have an alternative formatter in mind.
If you specify values in this list, they are only removed from the defaults.
Any filetypes configured in g:vim_filetype_formatter_commands will NOT be
overridden by this configuration. >
let g:vim_filetype_formatter_ft_no_defaults = ['markdown', 'javascript']
==============================================================================
*filetype_formatter_commands*
3. COMMANDS~
*:FiletypeFormat*
Format the entire current buffer using a configured formatter. If the
buffer's filetype has not been associated with this plugin, it will save an
error message accessible through :ErrorFiletypeFormat.
NOTE: this command works on both the entire file and visually selected
ranges. As described elsewhere in this document, for visually selected
ranges, behavior depends on whether a filetype's formatter is a "String", a
"Function[] -> String", or a "Function[Integer, Integer] -> String".
*:LogFiletypeFormat*
Show output from a buffer's most recent formatter function attempt in a Vim
preview window.
*:DebugFiletypeFormat*
Show configuration variables and settings in a Vim preview window.
==============================================================================
*filetype_formatter_mappings*
4. MAPPINGS~
This plugin does not provide key mappings; please add your own! Recommended
mappings: >
nnoremap <silent> <leader>f <Cmd>FiletypeFormat<CR>
xnoremap <silent> <leader>f :FiletypeFormat<CR>
==============================================================================
*filetype_formatter_credits*
5. CREDITS~
filetype_formatter was originally inspired by the design of vim-autoformat.
vim:tw=78:ts=8:ft=help:norl: