shared.vim 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
data/README.md ADDED
@@ -0,0 +1,175 @@
1
+ # shared.vim
2
+
3
+ > **AI disclaimer:** This code was created with the assistance of AI. But I
4
+ > get what the code does and why it does it. I maybe will not remember it as
5
+ > long as if I had done it all manually, spending many moons learning
6
+ > Vimscript and how to interact with Vim internals. Anyway. Its a passion
7
+ > project. Use at your own discretion.
8
+
9
+ Automatic live co-editing for Vim on one machine. Everybody who opens the same
10
+ file (same resolved path) edits one shared text; there is nothing to configure
11
+ or start.
12
+
13
+ * A single Ruby server on the Unix socket `/tmp/shared-vim/sock`, shared by all
14
+ local users. The first Vim that needs it starts it detached; it exits 60 s
15
+ after the last Vim has disconnected.
16
+ * Every real file buffer joins automatically. Names are `$USERNAME` (else
17
+ `$USER`) + a number per user per file: `alice1`, `bob1`, `alice2` (same
18
+ user twice is fine). Set `USERNAME` when several people share an account.
19
+ * All participants are shown in the status line, each in their color, your own
20
+ name first.
21
+ * Unsaved text is shown in its author's color. Any `:w` clears all colors in
22
+ everybody's Vim, since the file now holds all the text.
23
+ * Per-user undo: `u` and `CTRL-R` (with counts) take back only your own
24
+ changes, even after others edited around them.
25
+
26
+ ## Why this one
27
+
28
+ Most collaborative-editing plugins are built for working over a network: one
29
+ person starts or hosts a session, the others join it by address. shared.vim is
30
+ for the other case: you, or you and your friends, on the same computer, for
31
+ example several ssh logins to one server.
32
+
33
+ * **Nothing to set up or start.** No session, no host, no port, no join
34
+ command. Open a file, and if somebody else has it open, you edit together.
35
+ * **No network.** Everything goes through a Unix domain socket on the local
36
+ machine; nothing is exposed to other hosts.
37
+ * **You see who is there.** Everybody who has the file open is in the status
38
+ line, unsaved text is in its author's color, and the same person may have a
39
+ file open multiple times.
40
+ * **Per-user undo.** `u` takes back only your own changes, and never revives
41
+ text that somebody else has deleted in the meantime.
42
+ * **Plain Vim.** Most current projects are Neovim only.
43
+
44
+ ## Requirements
45
+
46
+ Vim 9.2 with `+ruby`, `+channel`, `+textprop` (`listener_add()`
47
+ with the `text` option); Ruby with `json`.
48
+
49
+ Neovim is not supported at this point: it lacks `listener_add()`, text
50
+ properties, Vim channels and the built-in `:ruby`.
51
+
52
+ A and I would need to port the whole affair to LUA to share
53
+ max code between vim and neovim. Lets do that when people want it.
54
+
55
+ ## Install
56
+
57
+ ```sh
58
+ gem install shared.vim
59
+ shared-vim-install
60
+ ```
61
+
62
+ `shared-vim-install` writes a small stub plugin to
63
+ `~/.vim/pack/shared/start/shared.vim/plugin/shared.vim` (another Vim directory
64
+ can be given as argument). At each start the stub asks RubyGems for the newest
65
+ installed `shared.vim` gem and loads the plugin from there, so nothing has to be
66
+ added to the vimrc and gem updates need no reinstall. Vim's Ruby must see the
67
+ gems, i.e. be the same Ruby that `gem` installs for. To uninstall, delete the
68
+ stub and `gem uninstall shared.vim`.
69
+
70
+ From a checkout instead:
71
+
72
+ ```vim
73
+ set rtp+=~/Projects/shared.vim
74
+ ```
75
+
76
+ Options:
77
+
78
+ ```vim
79
+ let g:shared_vim_socket = '/other/path/sock' " max ~100 chars
80
+ let g:shared_vim_max_size = 10000000 " bytes; bigger files are not shared
81
+ ```
82
+
83
+ ## Files
84
+
85
+ | file | role |
86
+ |---|---|
87
+ | `tools/shared-vim-server` | the server (`IO.select` loop, one JSON object per line) |
88
+ | `tools/shared-vim-install` | installs the stub plugin that loads the gem |
89
+ | `lib/shared_vim_core.rb` | line model, ops, transform, client state, undo stacks |
90
+ | `lib/shared_vim.rb` | Vim side in Ruby: listener, buffer patching, colors, status |
91
+ | `plugin/shared.vim` | autocmds, channel, mappings, swap/timestamp handling |
92
+ | `test/selftest.rb` | random tests incl. convergence and undo: `rake test` |
93
+
94
+ `rake` builds the gem into `pkg/`, `rake install` installs it.
95
+
96
+ ## How it works
97
+
98
+ Operational transformation on character positions, with a dumb server:
99
+
100
+ * **Server:** holds each open document in memory, as lines plus, per line, the
101
+ authors of unsaved text as runs (slot, length). It applies an op only if it is based on its current revision, then
102
+ acks the sender and forwards it; otherwise it answers `nack`. No transform,
103
+ no history.
104
+ * **Client:** one op in flight, the rest queued. Incoming ops are transformed
105
+ against the queue. On `nack` the op in flight is simply sent again: the ops
106
+ it missed arrived before the `nack` and have already transformed it.
107
+ * **Vim:** `listener_add()` reports each change with its resulting lines; it is
108
+ replayed onto the model, so the cost depends on the change, not on the file.
109
+ This also catches changes to buffers that are not current (`:diffput`, and
110
+ presumably edits by LSP plugins, untested). Remote ops patch only the changed lines, hidden from the listener.
111
+ * **Undo:** inverses of your own changes, grouped by Vim's undo step, form a
112
+ stack that every foreign op is transformed through. If another user deleted
113
+ the text around something your undo would restore, that part is dropped,
114
+ so undo never revives text inside a deleted section. An undo step that
115
+ came to nothing (someone removed that text) is skipped with a message, and
116
+ the same keypress goes on to your previous change.
117
+
118
+ Messages (`t` field): `join`/`joined`, `op`/`ack`/`nack`, `saved`, `leave`,
119
+ `peers`.
120
+
121
+ Vim integration details:
122
+
123
+ * A swap file of another *running* Vim on this host is ignored (edit anyway);
124
+ a dead one still gets the recovery prompt.
125
+ * When a peer writes, the other Vims reload the file quietly and put the shared
126
+ text back on top, so Vim's "changed since reading" checks stay quiet and
127
+ unsaved edits survive. Changes by other programs still warn as usual. A file
128
+ that did not exist when editing started is reloaded with `:edit!` instead
129
+ (Vim's W13 warning has no hook), once it is visible and not in insert mode.
130
+ * If the server dies, Vims reconnect after 0.5 s. The first to rejoin brings
131
+ its text; the others take over the server's text, so their edits not yet
132
+ sent are lost.
133
+ * Colors use text properties with priority 1000, meant to stay above semantic
134
+ highlighting of LSP plugins (untested).
135
+
136
+ ## Cost
137
+
138
+ Per edit, measured in Vim: 0.1 ms in a 100 KB file, 0.3–0.9 ms in a 1 MB file
139
+ (position dependent). Joining sends the whole file once.
140
+
141
+ Memory: the server and every Vim that has the file open each keep a model of
142
+ it, about twice the file size (1 MB file: 2 MB, 10 MB file: 23 MB).
143
+
144
+ ## Related projects
145
+
146
+ If you need editing over a network, or Neovim, one of these may fit better:
147
+
148
+ * [CoVim](https://github.com/FredKSchott/CoVim): Vim, Python/Twisted, a
149
+ server you start and connect to.
150
+ * [instant.nvim](https://github.com/jbyuki/instant.nvim): Neovim, Lua, built-in
151
+ server, virtual cursors; no longer maintained.
152
+ * [livecode.nvim](https://github.com/jxm35/livecode.nvim): Neovim, Lua,
153
+ operational transformation, local or LAN server.
154
+ * [live-share.nvim](https://github.com/azratul/live-share.nvim): Neovim, Lua,
155
+ session sharing.
156
+ * [Floobits](https://github.com/Floobits/vim-plugin): Vim/Neovim, hosted
157
+ service.
158
+ * [tandem](https://github.com/typeintandem/vim): Vim and other editors,
159
+ peer-to-peer.
160
+ * [Ethersync](https://github.com/ethersync/ethersync): editor-independent
161
+ sync tool with plugins for several editors.
162
+
163
+ ## Limits (by design, to stay simple)
164
+
165
+ * Only `u` and `CTRL-R` are per-user; `U`, `g-`, `g+` and `:undo` are Vim's
166
+ own and also take back other people's changes (which is then shared).
167
+ * After undoing back to the saved text, the buffer still shows `[+]`.
168
+ * Unsaved shared state lives only while somebody has the file open, and colors
169
+ of unsaved text are lost when the server restarts.
170
+ * No authentication: any local user can connect to the socket.
171
+ * The size limit (`g:shared_vim_max_size`) is checked only by each Vim; the
172
+ server accepts files of any size.
173
+ * Edits that LSP plugins or other scripts make are shared like your own; text
174
+ props of other plugins on a line a peer just changed may be lost until that
175
+ plugin refreshes them.
data/Rakefile ADDED
@@ -0,0 +1,26 @@
1
+ require 'rake'
2
+ require 'rubygems/package_task'
3
+ require 'fileutils'
4
+
5
+ spec = eval(File.read('shared.vim.gemspec'))
6
+ Gem::PackageTask.new(spec) do |pkg|
7
+ pkg.need_zip = true
8
+ pkg.need_tar = true
9
+ FileUtils.mkdir 'pkg' rescue nil
10
+ FileUtils.rm_rf Dir.glob('pkg/*')
11
+ FileUtils.ln_sf "#{pkg.name}.gem", "pkg/#{spec.name}.gem"
12
+ end
13
+
14
+ task :default => :gem
15
+
16
+ task :test do
17
+ ruby 'test/selftest.rb'
18
+ end
19
+
20
+ task :push => :gem do |r|
21
+ `gem push pkg/#{spec.name}.gem`
22
+ end
23
+
24
+ task :install => :gem do |r|
25
+ `gem install pkg/#{spec.name}.gem`
26
+ end
data/lib/shared_vim.rb ADDED
@@ -0,0 +1,279 @@
1
+ # Vim side of shared.vim, loaded with :rubyfile from plugin/shared.vim.
2
+ # The model of a buffer is its lines plus a final "" (the last newline).
3
+ # Local changes come from listener_add() and are replayed onto the model;
4
+ # remote ops are patched into the changed lines, hidden from the listener.
5
+ require 'json'
6
+ require File.join(VIM.evaluate('g:shared_vim_root'), 'lib', 'shared_vim_core')
7
+
8
+ module SharedVim
9
+ Core = SharedVimCore
10
+ OT = Core::OT
11
+ TYPES = (0..7).map { |i| "shared_slot#{i}" }
12
+
13
+ Buf = Struct.new(:nr, :path, :doc, :name, :peers, :listener, :ignore)
14
+
15
+ @bufs = {} # bufnr => Buf
16
+ @paths = {} # path => bufnr
17
+
18
+ class << self
19
+ def u(s) = s.to_s.dup.force_encoding('UTF-8')
20
+ def vs(s) = "'" + s.to_s.gsub("'", "''") + "'"
21
+ def vl(a) = '[' + a.map { |x| vs(x) }.join(',') + ']'
22
+ def cmd(c) = VIM.command(c)
23
+ def ev(e) = VIM.evaluate(e)
24
+ def lines(b) = ev("getbufline(#{b}, 1, '$')").map { |l| u(l) }
25
+ def tx(h) = cmd("call ch_sendraw(g:shared_vim_ch, #{vs(JSON.generate(h))} .. \"\\n\")")
26
+
27
+ def safely
28
+ yield
29
+ rescue StandardError => e
30
+ VIM.message("shared.vim: #{e.class}: #{e.message}")
31
+ end
32
+
33
+ # --- called from plugin/shared.vim ------------------------------------
34
+
35
+ def join(b, path, user)
36
+ return if @bufs[b]
37
+ s = @bufs[b] = Buf.new(b, u(path), nil, nil, [], nil, false)
38
+ @paths[s.path] = b
39
+ tx(t: 'join', path: s.path, user: u(user), lines: lines(b) + [''])
40
+ end
41
+
42
+ def leave(b)
43
+ s = @bufs.delete(b) or return
44
+ @paths.delete(s.path)
45
+ unhook(s)
46
+ tx(t: 'leave', path: s.path)
47
+ end
48
+
49
+ def reset
50
+ @bufs.each_value { |s| unhook(s) }
51
+ @bufs.clear
52
+ @paths.clear
53
+ end
54
+
55
+ # listener_add() callback.
56
+ def changed(b, first, last, added, changes)
57
+ s = @bufs[b] or return
58
+ return if s.ignore || !s.doc
59
+ key = ev("undotree(#{b}).seq_cur")
60
+ begin
61
+ changes.each do |c|
62
+ nl = c['text'].map { |l| u(l) }
63
+ raise 'listener text does not fit' unless nl.size == c['end'] + c['added'] - c['lnum']
64
+ own(s, s.doc.text.replace_op(c['lnum'] - 1, c['end'] - 1, nl), key)
65
+ end
66
+ rescue StandardError
67
+ resync(s)
68
+ end
69
+ render(s, first, last - 1 + added)
70
+ end
71
+
72
+ def saved(b)
73
+ s = @bufs[b] or return
74
+ return unless s.doc
75
+ flush(s)
76
+ tx(t: 'saved', path: s.path)
77
+ clear(s)
78
+ end
79
+
80
+ # Vim reloads after a peer's write: hide that from the listener until
81
+ # restore() has put the shared text back.
82
+ def before_reload(b)
83
+ s = @bufs[b] or return
84
+ flush(s)
85
+ s.ignore = true
86
+ end
87
+
88
+ def restore(b)
89
+ s = @bufs[b] or return
90
+ flush(s)
91
+ write_all(s)
92
+ flush(s)
93
+ ensure
94
+ s.ignore = false if s
95
+ end
96
+
97
+ # Per-user undo, redo with forward = true.
98
+ def undo(b, count, forward)
99
+ s = @bufs[b] or return
100
+ return unless s.doc
101
+ flush(s)
102
+ skipped = 0
103
+ count.times do
104
+ idle = s.doc.pending.empty?
105
+ done, n = s.doc.undo!(forward)
106
+ skipped += n
107
+ unless done
108
+ VIM.message(forward ? 'Already at newest change' : 'Already at oldest change')
109
+ break
110
+ end
111
+ send_op(s) if idle && !s.doc.pending.empty?
112
+ quietly(s) { done.each { |_, region, size| patch(s, size, region) } }
113
+ set_cursor(s, OT.first_change(done[0][0]))
114
+ end
115
+ VIM.message("shared.vim: skipped #{skipped} change#{'s' if skipped > 1} removed by someone else") if skipped > 0
116
+ end
117
+
118
+ def recv(line)
119
+ m = JSON.parse(u(line))
120
+ b = @paths[m['path']] or return
121
+ s = @bufs[b]
122
+ case m['t']
123
+ when 'joined' then joined(s, m)
124
+ when 'ack' then send_op(s) if s.doc.ack
125
+ when 'nack' then send_op(s) if s.doc.nack
126
+ when 'op' then remote(s, m['op'], m['slot'])
127
+ when 'saved'
128
+ clear(s)
129
+ cmd("call setbufvar(#{b}, 'shared_vim_peer_saved', 1)")
130
+ cmd("call SharedVimSyncTime(#{b})")
131
+ when 'peers' then s.peers = m['peers']
132
+ end
133
+ status(s)
134
+ end
135
+
136
+ # --- internals ----------------------------------------------------------
137
+
138
+ def joined(s, m)
139
+ text = Core::Text.new(m['lines'], m['authors'])
140
+ s.doc = Core::Doc.new(text, m['rev'], m['slot'])
141
+ s.name = m['name']
142
+ if m['created'] then resync(s) # typing between join and reply
143
+ else write_all(s)
144
+ end
145
+ own(s, text.normalize_op)
146
+ s.listener = ev("listener_add('SharedVimListener', #{s.nr}, {'text': v:true})")
147
+ cmd("call setbufvar(#{s.nr}, 'shared_vim_on', 1)")
148
+ render(s, 1, text.lines.size - 1)
149
+ end
150
+
151
+ def unhook(s)
152
+ cmd("call listener_remove(#{s.listener})") if s.listener
153
+ cmd("call setbufvar(#{s.nr}, 'shared_vim_on', 0)")
154
+ cmd("call setbufvar(#{s.nr}, 'shared_vim_status', '')")
155
+ end
156
+
157
+ def send_op(s) = tx(t: 'op', path: s.path, rev: s.doc.rev, op: s.doc.pending.first)
158
+
159
+ # Own op that the buffer already shows (key: undo group). Sends it.
160
+ def own(s, op, key = nil)
161
+ region = s.doc.own(op, key)
162
+ send_op(s) if region && s.doc.pending.size == 1
163
+ region
164
+ end
165
+
166
+ def remote(s, op, slot)
167
+ flush(s) # unreported local changes must be in the model first
168
+ cur = cursor_offset(s)
169
+ old_size = s.doc.text.lines.size
170
+ op, region = s.doc.remote(op, slot)
171
+ region = Core::Region.merge(region, own(s, s.doc.text.normalize_op))
172
+ quietly(s) { patch(s, old_size, region) }
173
+ set_cursor(s, OT.xform_index(op, cur)) if cur
174
+ end
175
+
176
+ def flush(s) = cmd("call listener_flush(#{s.nr})")
177
+
178
+ # Change the buffer without the listener reporting it.
179
+ def quietly(s)
180
+ flush(s)
181
+ s.ignore = true
182
+ yield
183
+ flush(s)
184
+ ensure
185
+ s.ignore = false
186
+ end
187
+
188
+ # Model lines [lo, lo+old) became [lo, lo+new); the buffer is the model
189
+ # without its final "".
190
+ def patch(s, old_size, region)
191
+ return unless region
192
+ lo, oc, nc = region
193
+ t = s.doc.text
194
+ ob = [lo + oc, old_size - 1].min - lo
195
+ nb = [lo + nc, t.lines.size - 1].min - lo
196
+ nl = t.lines[lo, nb]
197
+ c = [ob, nb].min
198
+ cmd("call setbufline(#{s.nr}, #{lo + 1}, #{vl(nl[0, c])})") if c > 0
199
+ cmd("call appendbufline(#{s.nr}, #{lo + c}, #{vl(nl[c..])})") if nb > ob
200
+ cmd("silent call deletebufline(#{s.nr}, #{lo + c + 1}, #{lo + ob})") if ob > nb
201
+ render(s, lo + 1, lo + nb)
202
+ end
203
+
204
+ # Differing middle part of buffer and model: [buffer lines, pre, suf].
205
+ def compare(s)
206
+ bl = lines(s.nr)
207
+ ml = s.doc.text.lines[0..-2]
208
+ pre, suf = 0, 0
209
+ pre += 1 while pre < bl.size && pre < ml.size && bl[pre] == ml[pre]
210
+ suf += 1 while suf < bl.size - pre && suf < ml.size - pre && bl[-1 - suf] == ml[-1 - suf]
211
+ [bl, pre, suf]
212
+ end
213
+
214
+ # Make the buffer show the model, touching only differing lines.
215
+ def write_all(s)
216
+ bl, pre, suf = compare(s)
217
+ patch(s, bl.size + 1, [pre, bl.size - pre - suf, s.doc.text.lines.size - 1 - pre - suf])
218
+ end
219
+
220
+ # Buffer and model differ in an unknown way: send the difference.
221
+ def resync(s)
222
+ bl, pre, suf = compare(s)
223
+ own(s, s.doc.text.replace_op(pre, s.doc.text.lines.size - 1 - suf, bl[pre, bl.size - pre - suf]))
224
+ render(s, pre + 1, bl.size - suf)
225
+ end
226
+
227
+ def cursor_offset(s)
228
+ return nil unless ev('bufnr()') == s.nr
229
+ ln = ev("line('.')")
230
+ line = s.doc.text.lines[ln - 1] or return nil
231
+ s.doc.text.offset(ln - 1) + u(line.b.byteslice(0, ev("col('.')") - 1)).scrub.length
232
+ end
233
+
234
+ def set_cursor(s, off)
235
+ return unless ev('bufnr()') == s.nr
236
+ t = s.doc.text
237
+ l, c = t.locate([off, t.length].min)
238
+ l = [l, t.lines.size - 2].min
239
+ cmd("call cursor(#{l + 1}, #{t.lines[l][0, c].to_s.bytesize + 1})")
240
+ end
241
+
242
+ # Color lines first..last by author, one prop_add_list() per color.
243
+ def render(s, first, last)
244
+ t = s.doc.text
245
+ first = [first, 1].max
246
+ last = [last, t.lines.size - 1].min
247
+ return if last < first
248
+ cmd("call prop_remove({'bufnr': #{s.nr}, 'types': #{vl(TYPES)}, 'all': 1}, #{first}, #{last})")
249
+ items = Hash.new { |h, k| h[k] = [] }
250
+ (first..last).each do |ln|
251
+ line = t.lines[ln - 1]
252
+ col = 1 # byte column
253
+ i = 0
254
+ t.authors[ln - 1].each do |slot, n|
255
+ b = line[i, n].bytesize
256
+ items[slot % 8] << [ln, col, ln, col + b] if slot
257
+ col += b
258
+ i += n
259
+ end
260
+ end
261
+ items.each do |k, v|
262
+ cmd("call prop_add_list({'bufnr': #{s.nr}, 'type': '#{TYPES[k]}'}, #{v})")
263
+ end
264
+ end
265
+
266
+ def clear(s)
267
+ s.doc.text.saved!
268
+ cmd("call prop_remove({'bufnr': #{s.nr}, 'types': #{vl(TYPES)}, 'all': 1})")
269
+ cmd("call setbufvar(#{s.nr}, '&modified', 0)")
270
+ end
271
+
272
+ def status(s)
273
+ peers = (s.peers || []).sort_by { |n, _| n == s.name ? 0 : 1 }
274
+ str = peers.map { |n, slot| "%#SharedStat#{slot % 8}# #{n} %*" }.join(' ')
275
+ cmd("call setbufvar(#{s.nr}, 'shared_vim_status', #{vs(str)})")
276
+ cmd('redrawstatus!')
277
+ end
278
+ end
279
+ end