API Documentation

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

• API (Redundant I know but 🤷‍♂️)
• Provider
• Shim

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

function 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

function 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

function unload(buffer_index)

• Version Added: 0.1
• buffer_index
  • Type: Integer
  • Details: buffer_index is the index of the buffer to be unloaded from netman.api's current state.
• Returns: nil
• Throws: nil
• Notes
  • This 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

function load_provider(provider_path)

• Version Added: 0.1
• provider_path
  • Type: String
  • Details: provider_path should be the string path to import a provider. For example netman.provider.ssh
• 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

function load_explorer(explorer_path, force)

function read(buffer_index, path)

function delete(delete_path)

function write(buffer_index, write_path)

version