-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathtanka.txt
150 lines (113 loc) · 6.35 KB
/
tanka.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
*tanka.txt*
Author: Daniel Sabsay <https://github.com/dsabsay>
License: MIT
================================================================================
CONTENTS *tanka-contents*
1. Introduction .............................. |tanka-introduction|
2. Usage ..................................... |tanka-usage|
3. Commands .................................. |tanka-commands|
4. Configuration ............................. |tanka-configuration|
5. Common Problems ........................... |tanka-common-problems|
6. How It Works .............................. |tanka-how-it-works|
7. Related ................................... |tanka-related|
================================================================================
INTRODUCTION *tanka-introduction*
This plugin makes working with Tanka projects easier. Primarily, it aims to
ease navigation of Jsonnet libraries. If you don't know what Tanka is, this
plugin is probably not for you.
https://tanka.dev/
================================================================================
USAGE *tanka-usage*
You start by opening your entrypoint `main.jsonnet` file: >
:edit example/prom-grafana/environments/default/main.jsonnet
<
Then run: >
:TankaSetEnv
<
This command stores the Tanka environment in a global variable. From this
point on, everything the plugin does is in relation to this environment.
Move the cursor over the filename of a Jsonnet import statement and type |gf|
to open the referenced file. This is fully aware of Tanka's search paths and
precedence rules and works in all Jsonnet buffers. You can also use |:find|: >
:find 'prometheus-mixin/mixin-libsonnet'
<
The 'makeprg' and 'errorformat' options are also set in each Jsonnet buffer
when a Tanka environment is active so you can use Vim's built-in
compile/quickfix features: >
:make
<
The quickfix window will show the error reported by Tanka, if any. The cursor
will jump to the file, line, and column of the error. You can run `:make` from
any Jsonnet buffer; the active Tanka environment will always be used.
To check which Tanka environment is currently active: >
:TankaEnv
<
Finally, to disable the plugin's features: >
:TankaOff
<
================================================================================
COMMANDS *tanka-commands*
:TankaEnv *:TankaEnv*
Prints the currently active Tanka environment.
:TankaSetEnv *:TankaSetEnv*
Assuming this command is run while in a `main.jsonnet` buffer, that
environment will be set as the plugin's "active environment".
:TankaOff *:TankaOff*
Turns off the plugin's features, restoring the global 'statusline' and the
local 'path', 'makeprg', and 'errorformat' of all Jsonnet buffers.
================================================================================
CONFIGURATION *tanka-configuration*
By default, the global 'statusline' is modified to show the name of the
currently active Tanka environment. If you don't want this, add the following
to your .vimrc: >
let g:vim_tanka_statusline_enabled = v:false
<
If you have existing 'makeprg' and 'errorformat' settings for Tanka/Jsonnet,
you can put this in your .vimrc to prevent this plugin from modifying them: >
let g:vim_tanka_compile_enabled = v:false
<
================================================================================
COMMON PROBLEMS *tanka-common-problems*
If |:TankaSetEnv| fails, check to see that you can run `tk tool jpath <env>`
successfully. Also check that the Vim process can see the Tanka executable: >
:echo system('tk --version')
If not, it's probably because the shell used by |system()| to launch the
process does not have Tanka on its PATH. You can check what shell is being
used with: >
:set shell?
================================================================================
HOW IT WORKS *tanka-how-it-works*
Vim has an option, 'path', which determines the directories in which to search
for include files. See `help 22.3`. Though this was probably originally
designed only with C include files in mind, it can easily be re-purposed for
other languages. Commands like |:find:| and |gf| and others reference 'path'.
Tanka has its own import precedence rules that determine where a Jsonnet
import statement resolves too (see https://tanka.dev/libraries/import-paths).
These import paths are relative to a specific Tanka environment, which is why
you must explicitly choose the environment.
When the environment is chosen with |:TankaSetEnv|, the plugin gets the
corresponding Jsonnet "path" by running: >
tk tool jpath <environment>
<
The output of that command is in the format that most Jsonnet tools expect,
but isn't quite right for Vim's 'path'. For example, by default Jsonnet will
resolve an import relative to the directory of the file making the import
first, before searching any directories in the $JSONNET_PATH environment
variable. Tanka adopts the same behavior, so ".," is prepended to 'path',
which tells Vim to look relative to the directory of the current file as the
first option. The plugin does some other reformatting to get the proper
'path'.
The plugin also displays the short name of the active Tanka environment in the
statusline.
The rest of the plugin is concerned with properly applying and un-applying
these settings to all relevant buffers (i.e. all buffers with `jsonnet`
filetype). This logic is tricky and may not be perfect. If you see weird
errors, restarting Vim will fix any state issues.
================================================================================
RELATED *tanka-related*
- Tanka: https://tanka.dev/
- vim-jsonnet (basic syntax support): https://github.com/google/vim-jsonnet
- vim-apathy (path-searching options for various file types) -
https://github.com/tpope/vim-apathy
- https://teukka.tech/vimcandothat.html
vim:tw=78:et:ft=help:norl: