Skip to content

API Documentation

Jump to bottom
Mike Iversen edited this page Apr 26, 2022 · 49 revisions

The "API" of Netman consists of 3 parts. Those parts are

Each of these 3 pieces have their own specification which is laid out below. For more details on how these parts interact, as well as how Netman as whole works, please checkout the Dev Guide

What to expect from this documentation

Each of the above parts will have their "public facing" items documented here. "Private" functions/variables will not be documented in this documentation as they are not meant to be used.

Private functions/variables will usually have a _ leading them (so for example, _my_private_variable or _my_private_function).

Note, the specification for each function below is laid out in the follow example format

function_name(param1, param2, paramX)
  • Version Added:
  • Param1
    • Type: Expected Type
    • Details: (Optional)
  • Param2
    • Type: Expected Type
    • Details: (Optional)
  • ParamX
    • Type: Expected Type
    • Details: (Optional)
  • Returns
    • Type: Expected Return Type
    • Details: (Optional)
  • Throws
    • Details about potential errors that are thrown in this function
  • Notes (Optional)

API

init(core_providers)

  • Version Added: 0.1
  • core_providers
    • Type: Array
    • Details: core_providers is an optional array that can be provided on API initialization. If not provided, this will default to netman.providers
  • Returns: nil
  • Throws
    • Errors thrown by load_provider will be thrown from this as well
  • Notes
    • init is called automatically on import of netman.api and has a lock in place to prevent side effects of multiple imports of api.
    • This function does not need to be called when importing netman.api

dump_info(output_path)

  • Version Added: 0.1
  • output_path
    • Type: String
    • Details: output_path is optional and defaults to $HOME/*random string* where *random string* is a randomly generated 10 character string
  • Returns: nil
  • Throws: nil
  • Notes
    • dump_info can be called via the :Nmlogs vim command and will do the following 2 things
      • Dump session related logs into the file created at output_path (Note: if a file exists in output_path, it will be overwritten with the dump)
      • Open this file in a new NetmanLogs filetype buffer for viewing

unload(buffer_index)

  • Version Added: 0.1
  • buffer_index
    • Type: Integer
    • Details: buffer_index is the index of the buffer to be unloaded from the api's current state.
  • Returns: nil
  • Throws: nil
  • Notes
    • unload will be called automatically when a Netman managed buffer is closed by vim (due to the an autocommand that is registered to BufUnload for the specific protocol that the buffer was opened with)
    • Unload will cleanup the local file used for a remote file pull if the provider performed a remote file pull
    • Unload will call close_connection on the associated provider if the provider implemented close_connection

load_provider(provider_path)

  • Version Added: 0.1
  • provider_path
  • Returns: nil
  • Throws
    • "Failed to initialize provider: " error
      • This is thrown when an attempt to import the provider fails or the provider has no contents (IE, its an empty file)
      • This is also thrown (with different sub details) if the provider is missing one of the required attributes. For more details on required attributes for a provider, please consult the Developer Guide
  • Notes
    • load_provider is the expected function to call when you are registering a new provider to handle a protocol, or registering an explorer to handle tree browsing. The function does a handful of things, which are laid out below
      • Attempts to import the provider. If there is a failure in the initial import, the above error(s) are thrown
      • Validates the provider has the required attributes as laid out in the developer guide
      • Calls the provider's init function if it has one
      • Ensures that core providers do not override 3rd party providers. This means that Netman will never attempt to override an existing provider for a protocol that netman supports.
        • NOTE: Netman does not prevent overriding of 3rd party providers by other 3rd party providers. Netman operates providers on "most recent provider" basis. This means that the most recent provider to register as the provider for a protocol will be used
      • Register autocommands that link the providers protocols to Netman to be handled by the API

load_explorer(explorer_path, force)

  • Version Added: 0.9
  • explorer_path
  • force
    • Type: Boolean
    • Details: force is used to indicate if we should force use of this explorer path
  • Returns: nil
  • Throws:
    • "Failed to initialize explorer" error
      • This is thrown when the explorer is missing a required attribute. For more details on required explorer attributes, please consult the developer guide
  • Notes

read(buffer_index, path)

  • Version Added: 0.1
  • buffer_index
    • Type: Integer
    • Details: Required Index of the buffer to associate the uri with, stored within api and used as the key to access state objects associated with the buffer. If nil (but provided), api delays association until the URI is claimed later. For more details on this process, please consult the developer guide
  • path
    • Type: String
    • Details: The URI to open. This is passed directly to the associated provider for this URI
  • Returns
    • read returns 1 of the following 2 items, depending on what the provider declares the return type should be on read
      • nil
        • This is usually returned if the provider determined that it needs to interface with a File Manager, though it can also be returned if read throws an error (see below)
      • command
        • This is a command that is generated by api to be used by vim to display the contents for the user to interface with.
  • Throws
    • Any errors that the provider may throw during its read operation
    • "Unable to figure out how to display: " error
      • An invalid return type was provided to read from the provider's read operation
    • "No tree explorer loaded" error
      • The provider attempted to load an explorer when one wasn't available to load
  • Notes
    • read is accesible via the :Nmread command which is made available by netman.init. It is also automatically called on FileReadCmd and BufReadCmd vim events. The end user should not have to directly iterface with netman.api.read, instead prefering to let vim handle that via the above listed events.
    • Read operates on a generate-and-reserve model where it generates buffer details (via calls to the assocaited provider) and then depending on results from the provider it will either claim the buffer details immediately or wait for the provider to inform it that it is safe to do so. This is especially useful when opening multiple files via different providers as api will not conflict with itself trying to organize buffers to buffer objects while juggling the various (potentially asychronous) providers
    • read expects a return of 1 of 3 well defined types from the providers read function, which are detailed more below. These types are

delete(delete_path)

  • Version Added: 0.1
  • delete_path
    • Type: String
    • Details: The string URI to delete.
  • Returns: nil
  • Throws
    • "Unable to delete: " error
      • Thrown if a viable provider was unable to be found for delete_path
    • Any errors that the provider throws during the delete process
  • Notes
    • delete does not require the URI to be a loaded buffer, however it does require a provider be loaded (via load_provider) that can handle the protocol of the URI that is being requested to delete

write(buffer_index, write_path)

  • Version Added: 0.1
  • buffer_index
    • Type: Integer
    • Details: The buffer index associated with the write path
  • write_path
  • Returns: nil
  • Throws
  • Notes
    • write does an asychronous call to the provider's write method and then immediately returns back so the user can continue working. DO NOT EXPECT THIS TO BLOCK

version

  • Version Added: 0.1
  • Notes
    • It's a version tag, what notes do you need?

Glossary

File Manager:

A program that is used to visualize a directory tree

Protocol:

Term used to indicate method of network communication to use. EG: `ssh`, `rsync`, `ftp`, etc

Provider:

Program that integrates with `Netman` to provide a bridge between a program that supports a [protocol](#protocol) and `vim`

URI:

A string representation of a path to a stream/file. EG: `sftp://host/file` or `ftp://ip_address/file`

Shim:

A program that acts as a "wedge" or "shim" between 2 programs. Usually used to modify the input/output between the 2 programs

Clone this wiki locally