Skip to content

API Documentation

Jump to bottom
Mike Iversen edited this page Feb 26, 2023 · 49 revisions

Source can be found here
The "API" of Netman consists of 4 parts. Those parts are

API (Redundant I know but 🤷‍♂️)

Providers

Consumers

Options

TLDR

The api is the main abstraction point within Netman. This component is what sits between the end user, the providers and consumers. This abstraction layer allows users to not have to worry about how to interact with the underlying providers, it allows providers to not have to worry about how users will interact with the data, it allows consumers to not have to worry about how to interface with providers, etc. Everything comes and goes through the api.

Notable functions within the api are

The Provider is the bridge between the api and external data sources. Examples of providers are

Notable functions within a provider are

The Consumer is the bridge between the api and external file browsers.

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 Developer 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), or be a member of an internal attribute (so for example, internal.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:
  • Updated :
  • 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

The api is the core of Netman and all processing of remote data is done through the api. It is worth noting that the api itself does not do much processing of the data, relegating that to the relevant provider to do. Instead, api acts as a sort of middle man between the user and the provider. API is designed with the following core concepts in mind

  • The api should be strict
  • The api should be consistent
  • The api should make as few decisions as possible
  • The api should not manipulate data

With these concepts in mind, the api is able to ensure a stable contract between the user and provider without either having to interface much with the other.

Most communication with the api will revolve around "uris". A uri is the string representation of the remote data that the user wishes to interface with. A uri is traditionally represented in the following manner protocol://host_authentication_information/path and api makes this assumption when dealing with any uris from the user.

The process of interfacing with the api is outlined more in the Developer Guide

init()

  • Version Added: 0.1
  • Updated : 1.01
  • 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

unload_buffer(buffer_index)

  • Version Added: 0.1
  • Updated : 1.01
  • uri
    • Type: String
    • Details: The string URI associated with the unloaded buffer
  • Returns: nil
  • Throws: nil
  • Notes
    • unload_buffer 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_buffer will cleanup the local file used for a remote file pull if the provider performed a remote file pull
    • Unload_buffer 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

read(uri, opts)

  • Version Added: 0.1
  • Updated : 1.01
  • uri
    • Type: String
    • Details: The uri to open. This is passed directly to the associated provider for this uri
  • opts
    • Type: Table
    • Details: Table containing read options. Valid options are
      • force: boolean
        • If provided, we will remove any cached version of the uri and call the provider to re-read the uri
  • Returns
    • read returns a table that will have the following key/value pairs (some are optional)
      • success: boolean
        • A boolean to indicate if the provider successfully read the uri
      • error: table (optional)
        • If provided, a message to be relayed to the user, usually given by the provider. Should be a table that has a single attribute (message) within. An example

          {error = { message = "Something bad happened!"}}

      • type: String
        • Will be one of the following strings
          • STREAM, EXPLORE, FILE These are enums found in netman.options.api.READ_TYPE
      • data: table (optional)
        • If provided, the data that was read. This will be a table, though the contents will be based on what type is returned
        • Type EXPLORE:
          • A 1 dimensional array where each item in the array contains the following keys
            • ABSOLUTE_PATH: table
              • A piece by piece break down of the path to follow to reach the item in question. As an example, for sftp://myhost///my/dir/, this would return > { name = 'my', uri = "sftp://myhost///my" }, { name = "dir", uri = "sftp://myhost///my/dir" } <
            • FIELD_TYPE: string
              • This will be either LINK or DESTINATION For a traditional filesystem, accept LINK as a "directory" and DESTINATION as a "file"
            • METADATA: table
              • Whatever (stat compatible) metadata the provider felt like providing with the item in question
            • NAME: string
              • The "relative" name of the item. As an example: sftp://myhost///my/dir would have a name of dir
            • URI: string
              • The "absolute" uri that can be followed to reach the item in question. This is more useful for LINK navigation (tree walking) as directories may be linked or nonexistent at times and this URI should ensure access to the same node at all times
      • Type FILE:
        • A table containing the following key/value pairs (or nil)
          • data: table
            • remote_path: string
              • The remote absolute path to follow for this URI
            • local_path: string
              • The local absolute path to follow for this URI
          • error: table (Optional)
            • TODO
      • Type STREAM:
        • A 1 dimensional table with text (each item should be considered a line) to display to the buffer Notes
    • read is accessible 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 interface with netman.api.read, instead preferring to let vim handle that via the above listed events.

delete(uri)

  • Version Added: 0.1
  • Updated : 1.01
  • uri
    • 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 uri
    • 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
    • delete is available to be called via the :Nmdelete vim command
    • 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, uri, opts)

  • Version Added: 0.1
  • Updated : 1.01
  • buffer_index (optional)
    • Type: Integer
    • Details: The buffer index associated with the write path. If provided, we will use the index to pull the buffer content and provide that to the provider. Otherwise, the provider will be given an empty array to write out to the file NOTE: this will almost certainly be destructive, be sure you know what you are doing if you are sending an empty write!
  • uri
    • Type: String
    • Details: The string URI to create
  • opts
    • Type: Table
    • Details: Reserved for later use
  • Returns: Table
    • A table that contains the following key/value pairs - success: boolean A boolean indicating if the provider was successful in its write - uri: string A string of the path to the uri
  • Throws
  • Notes
    • write is available to be called via the :Nmwrite vim command

rename(old_uri, new_uri)

  • Version Added: 1.01
  • old_uri
    • Type: String
    • Details: The (current) uri path to rename
  • new_uri
    • Type: String
    • Details: The (new) uri path. The path to rename to Returns: Table Returns a table that contains the following key/value pairs
      • success: boolean A boolean indicating if the provider was successful in its write
      • error: table (Optional)
        • If provided, a message to be relayed to the user, usually given by the provider. Should be a table that has a single attribute (message) within. An example

          {error = { message = "Something bad happened!"}} Notes

    • The api will prevent rename from "functioning" if the old_uri and new_uri do not share the same provider.

copy(uris, target_uri, opts)

  • Version Added: 1.01
  • uris
    • Type: table
    • Details: The table of string URIs to copy
  • target_uri
    • Type: String
    • Details: The string location to move the URIs to. Consider this a "parent" location to copy into
  • opts
    • Type: table
    • Details: A table of options that can be provided to the provider. Valid options are
      • cleanup: boolean If provided, indicates to the provider that they should "clean" (remove) the originating file after copy is complete. Consider this the "move" option
  • Returns: table
    • Details
      • A table should be returned with the following key/value pairs (some are optional)
        • success: boolean
          • This should be a true or false to indicate if the copy was successful or not
        • error: table (optional)
          • This should be provided in the event that you have an error to pass to the caller. The contents of this should be a table with a single message attribute (which houses a string) EG: error = { message = "SOMETHING CATASTROPHIC HAPPENED!" }

move(uris, target_uri, opts)

Version Added: 1.01 See copy as this definition is the exact same (with the exception being that it tells copy to clean up after its complete)

get_metadata(uri, metadata_keys)

  • Version Added: 0.95
  • Updated : 1.01
  • uri
    • Type: String
    • Details: The uri to request metadata for
  • metadata_keys
  • Returns
    • key, value pairs table where the key is each item in metadata_keys and the value is what was returned by the provider

version

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

unload_provider(provider_path, justification)

  • Version Added: 0.95
  • Updated : 1.01
  • provider_path
    • Type: String
    • Details: The string path for the provider to unload
  • justification
    • Type: table (optional)
      • Details: If provided, this table should indicate why the provider is being unloaded from netman. Required keys (if the table is provided) are
        • reason: string
        • name: string The "require" path of the provider
        • protocol: string A comma delimited list of the protocols the provider supported
        • version: string The version of the provider
  • Returns: nil
  • Throws: nil
  • Notes
    • This function is provided strictly for development use and is not required to be called in the lifecycle of a provider.
    • Use cases for this function are mostly when working on a new provider. By calling this function, you will remove the provider **both from Netman's memory as well as lua as a whole
    • Targeted use is live development of a provider without having to restart Neovim.

reload_provider(provider_path)

  • Version Added: 0.95
  • provider_path
    • Type: String
    • Details: The string path for the provider to reload
  • Returns: nil
  • Throws
  • Notes

get_provider_logger()

  • Version Added: 1.01
  • Returns logger - Type: table - Details: Returns a logger object that will log out to the provider logs (located at $XDG_DATA_HOME/netman/logs/provider)

get_consumer_logger()

  • Version Added: 1.01
  • Returns logger - Type: table - Details: Returns a logger object that will log out to the provider logs (located at $XDG_DATA_HOME/netman/logs/consumer)

get_system_logger()

  • Version Added: 1.01
  • Returns logger - Type: table - Details: Returns a logger object that will log out to the provider logs (located at $XDG_DATA_HOME/netman/logs/system)

clear_unused_configs(assume_yes)

  • Version Added: 1.01
  • assume_yes
    • Type: boolean
    • Default: false
    • Details: If provided, no questions are asked to the end user and we will just remove purge any unused configurations. If not provided, we will prompt for each configuration that needs to be removed
  • Returns: nil

generate_log(output_path)

  • Version Added: 1.01
  • output_path
    • Type: string
    • Default: nil
    • Details: If provided, the session logs that are "generated" (more like gathered but whatever) will be saved into this file.
  • Returns: nil
  • Note
    • This is one of the only functions in the api that interacts with vim's buffers. It will open a new buffer and set the contents of the buffer to the log gathered for the current session. This is very useful if you are trying to track down an odd event as the in memory logs are not filtered out

register_event_callback(event, callback)

  • Version Added: 1.01
  • event
    • Type: string
    • Details: An event to listen for
  • callback
    • Type: function
    • Details: The callback to be called when the event is emitted. When this function is called by the API, it will be provided with a table that contains the following key/value pairs - event: string - The event that was fired - source: string (optional) - The source that emitted the event. This is not required by emit_event and thus may be nil
  • Returns: id
    • An id that is used to associated the provided callback with the event Throws
    • INVALID_EVENT_ERROR
      • An error that is thrown if the requested event is nil
    • INVALID_EVENT_CALLBACK_ERROR
      • An error that is thrown if there is no callback provided

unregister_event_callback(id)

  • Version Added: 1.01
  • id
    • Type: string
    • Details: The id of the callback to unregister. This id is provided by |netman.api.register_event_callback| Returns: nil Throws
    • INVALID_ID_ERROR
      • An error that is thrown if the id is nil

emit_event(event, source)

  • Version Added: 1.01
  • event
    • Type: string
    • Details: The event to emit (I know, super clever!)
  • source
    • Type: string (optional)
    • Details: The name of the caller. Usually this would be the require path of the caller but you can technically use whatever you want here Returns: nil Note:
    • This is (currently) a synchronous call, so your callback needs to process the event quickly as it will hold up the rest of neovim

Providers

A provider is a program (Neovim plugin in the case of Netman) that acts as a middle man between api and external programs. The providers job is to communicate with said external programs and return consistently formatted data to the api so it can be returned to the user to be handled.

An example of a provider is netman.providers.ssh When creating a provider, there are several key things to keep in mind. api chooses which provider to use for a given uri based on the provider protocol_patterns. These patterns are extracted and analyzed when a provider registers itself with the api on its load_provider call (which is required in order to have your provider be made available to consume uris from the user)

There are several required attributes a provider must implement, those being

There are additional optional functions that if implemented, will be called during the lifecycle of the provider and buffers associated with it. Those being

There are 2 key variables that are provided with most calls to a provider by the api. Those are

The uri is the string representation of the remote data that the user wishes to interface with. A uri is traditionally represented in the following manner protocol://host_authentication_information/path and api uses this assumption to determine if a provider should handle that uri or not.

The cache object is a table that is created (as an empty table) by api after calling the provider's init function. This is a safe place for the provider to store state as it is not manipulated by anything else (including the api, other providers, etc) and stores any changes made to it by the provider. This is especially useful when establishing the initial details from the uri so the provider doesn't have to continually re-parse a uri

Details on how to implement a provider can be found within the Developer Guide

read(uri, cache)

  • Version Added: 0.1
  • Updated : 1.01
  • uri
    • Type: String
    • Details: The string URI to read
  • cache
    • Type: Table
    • Details: The table object that is stored and managed by the api. The api gets this object from the provider's init. For more details on how the cache works, consult the Developer Guide
  • Returns
    • table
      • read must return a table with the following key/value pairs
        • success: boolean
          • A true/false to indicate if the read was successful or not
        • type: string
        • error: table (optional)
          • If there were any encountered errors, place the error here in a table where the error is attached to the message attribute. EG error = {message = "SOMETHING CATASTROPHIC HAPPENED!"}
        • data: table
          • A table that contains the data to consume. This data should be formed in one of the 3 following ways, depending on the type that is returned along side the data.
            • TYPE == 'STREAM'
              • For a STREAM type, simply put your data into a 1 dimensional table (where each item in the table is a "line" of output)
            • TYPE == 'EXPLORE'
              • For a EXPLORE type, the returned table should be a 1 dimensional table of complex tables. Each "child" table should contain the following key/value pairs
                • URI: string
                  • The URI to follow to resolve this child object
                • FIELD_TYPE: string
                  • The type of item being returned. See options for valid field types
                • NAME: string
                  • The name of the item to be presented to the user
                • ABSOLUTE_PATH: table
                  • Another complex table that is a "path" of URIs to follow to reach this URI. An example would better demonstrate this { { name = 'my', uri = "sftp://myhost///my" }, { name = "dir", uri = "sftp://myhost///my/dir" } }
                • METADATA: table (optional)
                  • Stat compliant metadata for the item. If provided, the flags must match what are found in the options
            • TYPE == 'FILE'
              • For a FILE type, the returned table must include the following 2 key/value pairs
                • local_path: string
                  • The "local" path of the item. Useful for rendering a "local" representation of the "remote" system
                • origin_path
                  • The uri that was followed for this item
          • For more information on how the read process works, please consult the Developer Guide
  • Throws: nil
  • Notes
    • IT IS NO LONGER ACCEPTABLE FOR READ TO THROW ERRORS. INSTEAD, RETURN THOSE ERRORS ALONG WITH A success = false

write(uri, cache, data, opts)

  • Version Added: 0.1
  • Updated : 1.01
  • uri
    • Type: String
    • Details: The string URI to create
  • cache
    • Type: Table
    • Details: The table object that is stored and managed by the api. The api gets this object from the provider's init. For more details on how the cache works, consult the Developer Guide
  • data
    • Type: Table
    • Details: A table of "lines" to write to the backing store
  • opts
    • Type: Table
    • Details: Reserved for future use
  • Returns: Table
    • A table with the following key/value pairs is returned
      • uri: string (optional)
        • The URI of the written item. Useful if a new item was generated and needs to be returned, or if the provided URI is a shortcut URI (IE, not absolute)
      • success: boolean
      • error: table (optional)
        • If there were any encountered errors, place the error here in a table where the error is attached to the message attribute. EG error = {message = "SOMETHING CATASTROPHIC HAPPENED!"}
  • Notes
    • api does not currently provide any tools for dealing with oddities in the write process (permission error, network failure, etc), and those errors and validations are left up to the provider to handle.

delete(uri, cache)

  • Version Added: 0.1
  • Updated : 1.01
  • uri
    • Type: String
    • Details: The string URI to delete
  • cache
    • Type: Table
    • Details: The table object that is stored and managed by the api. The api gets this object from the provider's init. For more details on how the cache works, consult the Developer Guide
  • Returns: Table
    • A table with the following key/value pairs is returned
      • success: boolean
      • error: table (optional)
        • If there were any encountered errors, place the error here in a table where the error is attached to the message attribute. EG error = {message = "SOMETHING CATASTROPHIC HAPPENED!"}
  • Notes
    • api does not currently provide any tools for dealing with oddities in the delete process (user verification, permission error, network failure, etc), and those errors and validations are left up to the provider to handle.

move(uris, target_uri, cache)

  • Version Added: 0.2
  • Updated : 1.01
  • uris
    • Type: Table
    • Details: The table of string URIs to move
  • target_uri
    • Type: String
    • Details: The string location to move the URIs to. Consider this a "parent" location to move into. Note, if a single uri is provided, it is expected that that the uri is "renamed" to the target_uri (as opposed to moving into that location)
  • cache
    • Type: Table
    • Details: The provider cache as provided by the api
  • Returns: Table
    • Details
      • A table should be returned with the following key/value pairs (some are optional)
        • success: boolean
          • This should be a true or false to indicate if the move was successful or not
        • error: table (optional)
          • This should be provided in the event that you have an error to pass to the caller. The contents of this should be a table with a single message attribute (which houses a string) EG: error = { message = "SOMETHING CATASTROPHIC HAPPENED!" }

copy(uris, target_uri, cache)

  • Version Added: 0.2
  • Updated : 1.01
  • uris
    • Type: Table
    • Details: The table of string URIs to copy
  • target_uri
    • Type: String
    • Details: The string location to copy the URIs to. Consider this a "parent" location to copy into. Note, if a single uri is provided, it is expected that that the uri is named to the target_uri (as opposed to copied into that location)
  • cache
    • Type: Table
    • Details: The provider cache as provided by the api
  • Returns: Table
    • Details
      • A table should be returned with the following key/value pairs (some are optional)
        • success: boolean
          • This should be a true or false to indicate if the copy was successful or not
        • error: table (optional)
          • This should be provided in the event that you have an error to pass to the caller. The contents of this should be a table with a single message attribute (which houses a string) EG: error = { message = "SOMETHING CATASTROPHIC HAPPENED!" }

get_metadata(uri, requested_metadata)

  • Version Added: 0.95
  • uri
    • Type: String
    • Details: The string URI to get metadata for
  • requested_metadata
    • Type: Array
    • Details: requested_metadata an array of values where each value in the array can be located in the Netman METADATA Table.
  • Returns
    • Should return a Table where the key in each entry of the table should be from the input requested_metadata array
  • Throws: nil
  • Notes
    • This will be called by api whenever the user requests additional metadata about a link/destination. The keys are all valid stat flags and api will expect the data returned to conform to the datatypes that stat will return for those flags

init(configuration_options)

  • Version Added: 0.1
  • configuration_options
    • Type: Table
    • Details: WIP (currently unused)
  • Returns
    • Should return a true/false depending on if the provider was able to properly initialize itself
  • Throws: nil
  • Notes
    • init is an optional function that will be called immediately after import of the provider if it exists
    • This function's intended purpose is to allow the provider to verify that the environment it is being ran in is capable of handling it (IE, the environment meets whatever requirements the provider has), though it can be used for whatever the provider need in order to ensure it is ready to run

close_connection(uri, cache)

  • Version Added: 0.1
  • Updated : 1.01
  • uri
    • Type: String
    • Details: The string URI to create
  • cache
    • Type: Table
    • Details: The table object that is stored and managed by the api. The api gets this object from the provider's init. For more details on how the cache works, consult the Developer Guide
  • Returns: nil
  • Throws: nil
  • Notes
    • close_connection is an optional function that will be called immediately after a BufUnload event if called from vim, if close_connection exists on the provider
    • This function's intended purpose is to allow the provider to clean up after a buffer has been closed. The intent being to allow the provider a way to close out existing connections to remote locations, close files, etc

name

  • Version Added: 0.1
  • Notes: The string name of the provider

protocol_patterns

  • Version Added: 0.1
  • Notes

version

  • Version Added: 0.1
  • Notes
    • You've come far in the documentation. I am proud of you :)

Options

Options can be found in netman.options. These "options" are a table which acts as a sort of enum for the core of Netman. api relies on these options as a standard way of communicating "information" between itself and its providers. Below is a breakdown of each "option" that can be found here. These options will be referenced throughout various points in the API Documentation as well as the Developer Guide

  • api
    • READ_TYPE
      • FILE
      • STREAM
      • EXPLORE
    • ATTRIBUTES
      • FILE
      • DIRECTORY
      • LINK
  • explorer
    • METADATA
      • PERMISSIONS
      • OWNER_USER
      • OWNER_GROUP
      • SIZE_LABEL
      • SIZE
      • GROUP
      • PARENT
      • FIELD_TYPE
      • TYPE
      • INODE
      • LASTACCESS
      • FULLNAME
      • URI
      • NAME
      • LINK
      • DESTINATION
    • FIELDS
      • FIELD_TYPE
      • NAME
      • URI

version

  • Version Added: 0.9
  • Notes
    • I'm tired, I am running out of quirky things to say here

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 and vim

URI:

A string representation of a path to a stream/file. EG: sftp://host/file or ftp://ip_address/file. A more technical definition can be found on wikipedia

Clone this wiki locally