Sublime Forum

How does View.set_reference_document() work?

#1

Can anyone explain to me how View.set_reference_document() works. Thanks.

0 Likes
#2 
def update_ref():
    reference_content = "my new content to use as base for mini diff"
    view.set_reference_document(reference_content)

It simply passes a string to be used as reference for the incremental diff.

The string can be read from any file (e.g.: of an older revision from a vcs).

2 Likes
#3

IMO the name set_reference_document is misleading, I supposed it takes a filename (document) to compare the view against.

0 Likes
#4

Keep in mind that any method in the API that accepts a filename include the word file in the method name or parameter. Also, document in development generally refers to the actual document, whereas a file or filename refers to a reference to a document.

2 Likes
#5

What if I want to make the reference of the incremental diff the contents of a file (that may be modified) that isn’t open in sublime ?

0 Likes
#6

To do that, you would need to monitor the external file yourself to notice when it’s changing and then call the method again to update it.

Note that even Sublime doesn’t update the reference document when the disk file changes (except for files tracked by git). When you open an untracked file, that content remains as the reference document no matter how often you save the file; in order to reset it you need to either call the this API method manually or close and re-open the file.

0 Likes
#7

You just open the file on disk, read its content and pass it to the API.

You should just make sure to read the file with the correct encoding. GitGutter does it by reading the view’s actual encoding and passing it to the open() function.

with open(the_filename_on_disc, mode='r',
          encoding=self.view_cache.python_friendly_encoding()) as file:
    self.view.set_reference_document(file.read())
0 Likes
#8

I thought of that, but how to watch the file for changes ?

0 Likes
#9

I was playing around with the watchdog library in the past, but with all the edge cases and issues I’ve read about file change notifications, you should use it with care.

1 Like
#10

@wbond, i’m just curious, how hard is it for ST to expose some utilities for resource monitoring in the API ?
It can help solve https://github.com/tomv564/LSP/issues/516.

0 Likes
#11

We’ve discussed it. The blocker on lots of issues is performance. Right now we sometimes run into issues where monitoring filesystem notifications in C++ can cause high CPU usage, especially if the user decides to “open” their whole home directory, or a directory that has constant churn.

Adding it to the API would require additionally:

  • serializing all filesystem notifications
  • sending the data over shared memory to both plugin hosts
  • converting the data into Python data structures
  • having each handler loop through and process each event

For users with reasonable size projects, this would be no problem. However, for users with large projects, it would cause severe performance issues.

I think for us to implement something like that, we’d have to find a way to flip it on its head and have plugins only listen to the bare minimum instead of getting a firehose of events.

BTW, I believe this is the canonical issue for the topic: https://github.com/sublimehq/sublime_text/issues/2669.

2 Likes