-
Notifications
You must be signed in to change notification settings - Fork 3
Developer Guide
Here you will find a breakdown of the following items
The "Netman Buffer Object" is the object that api creates to help keep track of data associated with a neovim buffer. This is automatically created by the api when neovim creates a buffer (via the FileReadCmd, or BufReadCmd). This object is only created for buffers where the file uri being opened is associated with a provider.
But how does
apiassociate auriwith a provider?
Netman is a clever little program, it only pays attention to buffer open events based on the file name (as neovim considers it). Netman selectively creates event listeners specifically for protocols as registered by providers. This means that if you have a provider loaded for ssh
spoiler alert
you do if you are usingNetmanNetman will only listen to files opened that start with ssh related protocols (as defined by the ssh provider). These events listeners (called autocommands in vim speak) are all cleanly housed in the Netman command group (called augroup in vim speak).
Netman will use this object to track internal metadata about the uri (its provider, if it has a local file stored somewhere, what buffer its on, a provider cache, etc). This is to help prevent Netman from having to redo logic when seeing a uri that is has already processed. Additionally, this buffer object contains a provider specific cache that is passed to the provider on most function calls so the provider can safely store "relevant" information to the uri.
Ok thats cool but what about when the user is done with the file?
Netman has its greedy little hooks into a handful of places in neovim's event system, one of those places being the BufUnload event. When neovim fires this event on a buffer that Netman is watching, Netman will receive the event and proceed to clear out the object from its memory. Additionally, if the provider associated with the buffer has implemented the close_connection function, Netman will call out to it to inform it that the buffer for the uri was closed.
Sounds pretty cool, but
The api is the main "guts" of Netman. It sits between neovim (and therefore the end user) and the provider. Both of them communicate with it via a standard set of functions, and this allows the api to communicate "between" them in an abstract way (so the end user doesn't have to care how to interface with a protocol and the provider doesn't have to care about how to interface with a user).
Sounds cool but why would a user talk to Netman instead of neovim?
The best part of all of this is that Netman's api cleanly integrates itself into neovim and thus the user (and neovim) don't have to care about how to talk to it. The user will simply utilize neovim as they would regularly do, except Netman provides additional functionality to interface with remote data via the provider structure. When a user opens a remote location (via uri), Netman will take over and ensure a clean experience between the user and the provider.
How does Netman do that?
Netman has the following events set for providers that are registered with it
-
FileReadCmd- This
autocommandis used to capture whenneovimis opening a file with a protocol that Netman supports.
- This
-
BufReadCmd- This
autocommandis used to capture whenneovimis opening a buffer with a protocol that Netman supports.
- This
-
FileWriteCmd- This
autocommandis used to capture when the user is writing out to a file (before the write occurs) for a buffer that Netman is watching.
- This
-
BufWriteCmd- This
autocommandis used to capture when the user is writing out their buffer (before the write occurs), when the buffer is one that Netman is watching
- This
-
BufUnload- This
autocommandis used to capture when a relevant buffer is being closed by the user. Netman will reach out to the associated provider to inform it that the buffer is being closed
- This
When a ReadCmd event is fired, Netman forwards the associated uri to its read command, where the api establishes which provider should handle the read, and then provides the results from the provider to the user. This is laid out more in the api documentation
Additionally, Netman does expose a vim command :Nmread which directs to the read api. This can be used by the user but is more meant for you the developer.
When a WriteCmd event is fired, Netman forwards the associated uri to its write command, where the api grabs the cached provider and informs it that the user wishes to write out their buffer to this uri. More details on how write works is explained in the api documentation
Additionally, Netman does expose a vim command :Nmwrite which directs to the write api. This can be used by the user but is more meant for you the developer.
There is alot of talk about providers