diff --git a/doc/apidoc.md b/doc/apidoc.md index 16da0c36..38e8a047 100644 --- a/doc/apidoc.md +++ b/doc/apidoc.md @@ -2,40 +2,39 @@ The "API" of Netman consists of 4 parts. Those parts are ## [API](#api) (Redundant I know but :man_shrugging:) ## [Providers](#providers-1) +## [Consumers](#consumers) ## [Options](#options-1) -## [Shims](#shimswip) ## TLDR -The [`api`](#api) is the main abstraction point within `Netman`. This component is what sits between the end user and the other components ([providers](#providers) and [shims](#shimswip)). This abstraction layer allows users to not have to worry about how to interact with the underlying [`providers`](#providers), it allows [`providers`](#providers) to not have to worry about how users will interact with the data, it allows [`shims`](#shimswip) to not have to worry about how to interface with [`providers`](#providers), etc. Everything comes and goes through the [`api`](#api). +The [`api`](#api) is the main abstraction point within `Netman`. This component is what sits between the end user, the [providers](#providers) and [consumers](#consumers). This abstraction layer allows users to not have to worry about how to interact with the underlying [`providers`](#providers), it allows [`providers`](#providers) to not have to worry about how users will interact with the data, it allows [`consumers`](#consumers) to not have to worry about how to interface with [`providers`](#providers), etc. Everything comes and goes through the [`api`](#api). Notable functions within the [`api`](#api) are - [`load_provider`](#loadproviderproviderpath) - [`read`](#readbufferindex-path) The [`Provider`](#providers) is the bridge between the [`api`](#api) and external data sources. Examples of providers are -- [`netman.providers.ssh`](#https://github.com/miversen33/netman.nvim/blob/main/lua/netman/providers/ssh.lua) +- [`netman.providers.ssh`](https://github.com/miversen33/netman.nvim/blob/main/lua/netman/providers/ssh.lua) +- [`netman.providers.docker`](https://github.com/miversen33/netman.nvim/blob/main/lua/netman/providers/docker.lua) Notable functions within a [`provider`](#providers) are - [`read`](#readuri-cache) - [`write`](#writebufferindex-uri-cache) -The [`Shim`](#shimswip) are the bridge between the [`api`](#api) and external file browsers. This concept is currently being explored and will likely change and grow as its experimented with. - -Notable functions within a [`shim`](#shimswip) are -- [`explore`](#exploredetails) +The [`Consumer`](#consumers) is the bridge between the [`api`](#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](https://github.com/miversen33/netman.nvim/wiki/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`). +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 ```lua function_name(param1, param2, paramX) ``` - Version Added: +- Updated : - Param1 - Type: Expected Type - Details: (Optional) @@ -62,49 +61,32 @@ The [`api`](#api) is the core of `Netman` and all processing of remote data is d With these concepts in mind, the [`api`](#api) is able to ensure a _stable_ contract between the user and [`provider`](#providers) without either having to interface much with the other. -There are 2 key variables that the [`api`](#api) revolves around, and these are -- `buffer_index` -- [`uri`](#uri) - -The `buffer_index` is the lua [integer](https://www.lua.org/pil/2.3.html) representation of the `vim` buffer id that is currently being interacted with. This is used as a sort of `key` within [`api`](#api) due to the nature of `buffer_index` never changing within `vim`. This fact (that `buffer_index` is unique) makes it a prime mechanic for being the `key` in various objects within [`api`](#api) - -The [`uri`](#uri) is the string representation of the remote data that the user wishes to interface with. A [`uri`](#uri) is traditionally represented in the following manner `protocol://host_authentication_information/path` and [`api`](#api) makes this assumption when dealing with [`uri`](#uri)s from the user. +Most communication with the api will revolve around "uris". A [`uri`](#uri) is the string representation of the remote data that the user wishes to interface with. A [`uri`](#uri) is traditionally represented in the following manner `protocol://host_authentication_information/path` and [`api`](#api) makes this assumption when dealing with any uris from the user. The process of interfacing with the [`api`](#api) is outlined more in the [Developer Guide](https://github.com/miversen33/netman.nvim/wiki/Developer-Guide) -## init(core_providers) +## init() - Version Added: 0.1 -- `core_providers` - - Type: [Array](https://www.lua.org/pil/11.1.html) - - Details: `core_providers` is an optional array that can be provided on API initialization. If not provided, this will default to [`netman.providers`](https://github.com/miversen33/netman.nvim/blob/main/lua/netman/providers/init.lua) +- Updated : 1.01 - Returns: nil - Throws - Errors thrown by [`load_provider`](#loadproviderproviderpath) will be thrown from this as well - Notes - - [`init`](#initcoreproviders) is called **automatically** on import of [`netman.api`](#api) and has a lock in place to prevent side effects of multiple imports of [`api`](#api). + - [`init`](#initcoreproviders) is called **automatically** on import of [`netman.api`](#api) and has a lock in place to prevent side effects of multiple imports of [`api`](#api). - **This function _does not_ need to be called when importing `netman.api`** -## dump_info(output_path) + +## unload_buffer(buffer_index) - Version Added: 0.1 -- `output_path` +- Updated : 1.01 +- `uri` - Type: [String](http://www.lua.org/pil/2.4.html) - - 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`](#dumpinfooutputpath) 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](https://www.lua.org/pil/2.3.html) - - Details: `buffer_index` is the index of the buffer to be unloaded from the [`api`](#api)'s current state. + - Details: The string URI associated with the unloaded buffer - Returns: nil - Throws: nil - Notes - - [`unload`](#unloadbufferindex) will be called automatically when a `Netman` managed buffer is closed by vim (due to the an autocommand that is registered to [`BufUnload`](https://neovim.io/doc/user/autocmd.html#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` + - [`unload_buffer`](#unload_bufferbuffer_index) will be called automatically when a `Netman` managed buffer is closed by vim (due to the an autocommand that is registered to [`BufUnload`](https://neovim.io/doc/user/autocmd.html#BufUnload) for the specific protocol that the buffer was opened with) + - [`unload_buffer`](#unload_bufferbuffer_index) 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`](#close_connectionbuffer_index-uri-cache) ## load_provider(provider_path) - Version Added: 0.1 - `provider_path` @@ -123,102 +105,215 @@ The process of interfacing with the [`api`](#api) is outlined more in the [Devel - 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`](#protocol) to `Netman` to be handled by the [`API`](#api) -## load_explorer(explorer_path, force) -- Version Added: 0.9 -- `explorer_path` - - Type: [String](http://www.lua.org/pil/2.4.html) - - Details: `explorer_path` should be the string path to import a explorer shim. For example [`netman.provider.explore_shim`](https://github.com/miversen33/netman.nvim/blob/main/lua/netman/providers/explore_shim.lua) -- `force` - - Type: [Boolean](https://www.lua.org/pil/2.2.html) - - 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](https://github.com/miversen33/netman.nvim/wiki/Developer-Guide) -- Notes - - [`load_explorer`](#loadexplorerexplorerpath-force) is a sub function that is called by [`load_provider`](#loadproviderproviderpath). It is advised that you call [`load_provider`](#loadproviderproviderpath) when loading _any provider_ in `Netman`, including an `explorer_shim`. -## read(buffer_index, path) + +## read(uri, opts) - Version Added: 0.1 -- `buffer_index` - - Type: [Integer](https://www.lua.org/pil/2.3.html) - - Details: **Required** Index of the buffer to associate the uri with, stored within [`api`](#api) and used as the key to access state objects associated with the buffer. If nil (but provided), [`api`](#api) delays association until the `URI` is claimed later. For more details on this process, please consult the [developer guide](https://github.com/miversen33/netman.nvim/wiki/Developer-Guide) -- `path` +- Updated : 1.01 +- `uri` - Type: [String](http://www.lua.org/pil/2.4.html) - - Details: The [`URI`](#uri) to open. This is passed directly to the associated provider for this [`URI`](#uri) + - 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`](#readbufferindex-path) returns 1 of the following 2 items, depending on what the [`provider`](#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`](#file-manager), though it can also be returned if [`read`](#readbufferindex-path) throws an error (see below) - - command - - This is a command that is generated by [`api`](#api) to be used by `vim` to display the contents for the user to interface with. -- Throws - - Any errors that the [`provider`](#provider) may throw during its `read` operation - - "Unable to figure out how to display: " error - - An invalid return type was provided to [`read`](#readbufferindex-path) from the [`provider`](#provider)'s `read` operation - - "No tree explorer loaded" error - - The [`provider`](#provider) attempted to load an explorer when one wasn't available to load -- Notes - - [`read`](#readbufferindex-path) is accessible via the `:Nmread` command which is made available by `netman.init`. It is also automatically called on [`FileReadCmd`](https://neovim.io/doc/user/autocmd.html#FileReadCmd) and [`BufReadCmd`](https://neovim.io/doc/user/autocmd.html#BufRead) `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. - - Read operates on a generate-and-reserve model where it generates buffer details (via calls to the associated [`provider`](#provider)) and then depending on results from the provider it will either claim the buffer details immediately or wait for the [`provider`](#provider) to inform it that it is safe to do so. This is especially useful when opening multiple files via different providers as [`api`](#api) will not conflict with itself trying to organize buffers to buffer objects while juggling the various (potentially asynchronous) providers - - [`read`](#readbufferindex-path) expects a return of 1 of 3 well defined types from the [`provider`](#provider)s [`read`](#readbufferindex-path) function, which are detailed more below. These types are - - [READ_TYPE.FILE](#read-type-file) - - If [`read`](#readbufferindex-path) is returned a [`READ_TYPE.FILE`](#read-type-file), it will assume that the information being read into the `vim` buffer is a local file. [`api`](#api) will document this and remember to clean up this local file after [`unload`](#unloadbufferindex) is called - - [READ_TYPE.STREAM](#read_type_stream) - - [READ_TYPE.EXPLORE](#read-type-explore) -## delete(delete_path) + - [`read`](#readuri-opts) 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](http://www.lua.org/pil/2.4.html) + - 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 -- `delete_path` - - Type: [String](http://www.lua.org/pil/2.4.html) - - Details: The string [`URI`](#uri) to delete. +- Updated : 1.01 +- `uri` + - Type: [String](http://www.lua.org/pil/2.4.html) + - Details: The string [`URI`](#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`](#provider) throws during the [`delete`](#deletedeletepath) process + - Thrown if a viable provider was unable to be found for `uri` + - Any errors that the [`provider`](#provider) throws during the [`delete`](#deleteuri) process - Notes - - [`delete`](#deletedeletepath) does **_not_** require the URI to be a loaded buffer, _however_ it does require a provider be loaded (via [`load_provider`](#loadproviderproviderpath)) that can handle the protocol of the [`URI`](#uri) that is being requested to delete - - [`delete`](#deletedeletepath) is available to be called via the `:Nmdelete` vim command -## write(buffer_index, write_path) + - [`delete`](#deleteuri) 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`](#deleteuri) is available to be called via the `:Nmdelete` vim command + - [`delete`](#deleteuri) does **_not_** require the URI to be a loaded buffer, _however_ it does require a provider be loaded (via [`load_provider`](#loadproviderproviderpath)) that can handle the protocol of the [`URI`](#uri) that is being requested to delete +## write(buffer_index, uri, opts) - Version Added: 0.1 -- `buffer_index` +- Updated : 1.01 +- `buffer_index` (optional) - Type: [Integer](https://www.lua.org/pil/2.3.html) - - Details: The buffer index associated with the write path -- `write_path` + - 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](http://www.lua.org/pil/2.4.html) - Details: The string [`URI`](#uri) to create -- Returns: nil +- `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 - Any errors that the [`provider`](#provider) throws during the [`write`](#writebufferindex-writepath) process - Notes - - [`write`](#writebufferindex-writepath) does an asynchronous call to the [`provider`](#provider)'s `write` method and then immediately returns back so the user can continue working. **DO NOT EXPECT THIS TO BLOCK** - [`write`](#writebufferindex-writepath) is available to be called via the `:Nmwrite` vim command -## get_metadata(requested_metadata) + +## rename(old_uri, new_uri) +- Version Added: 1.01 +- `old_uri` + - Type: [String](http://www.lua.org/pil/2.4.html) + - Details: The (current) uri path to rename +- `new_uri` + - Type: [String](http://www.lua.org/pil/2.4.html) + - 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`](#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](http://www.lua.org/pil/2.4.html) + - 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`](#copyuris-target_uri-cache---table) 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 -- `requested_metadata` - - Type: [Array](https://www.lua.org/pil/11.1.html) - - Details: `requested_metadata` should be an array of [valid METADATA](https://github.com/miversen33/netman.nvim/blob/main/lua/netman/options.lua) options +- Updated : 1.01 +- `uri` + - Type: [String](http://www.lua.org/pil/2.4.html) + - Details: The uri to request metadata for +- `metadata_keys` + - Type: Table + - Details: A 1 dimensional table of metadata keys as found in [netman.options.metadata](#options) - Returns - - `key`, `value` pairs table where the key is each item in `requested_metadata` and the `value` is what was returned by the provider -- Throws: nil -- Notes - - This will be called by the explorer shim whenever an explorer requests [`libuv`](https://github.com/luvit/luv/blob/master/docs.md#uvfs_statpath-callback) details about a remote location. `Netman` will reach down to the provider for the remote location and call the same named function ([`get_metadata`](#getmetadatauri-requestedmetadata)). + - `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) +## unload_provider(provider_path, justification) - Version Added: 0.95 +- Updated : 1.01 - `provider_path` - Type: [String](http://www.lua.org/pil/2.4.html) - 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. + - 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. - - See Also [reload_provider](#reloadproviderproviderpath) ## reload_provider(provider_path) - Version Added: 0.95 @@ -229,7 +324,107 @@ The process of interfacing with the [`api`](#api) is outlined more in the [Devel - Throws - Any errors that [load_provider](#loadproviderproviderpath) throws - Notes - - This is a helper function that simply calls [unload_provider](#unloadproviderproviderpath) followed immediately by [load_provider](#loadproviderproviderpath) + - This is a helper function that simply calls [unload_provider](#unloadproviderproviderpath) followed immediately by [load_provider](#load_providerprovider_path) + +## 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`](#emit_eventevent-source) 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`](#providers) is a program (`Neovim` plugin in the case of `Netman`) that acts as a middle man between [`api`](#api) and external programs. The [`providers`](#providers) job is to communicate with said external programs and return consistently formatted data to the [`api`](#api) so it can be returned to the user to be handled. @@ -241,16 +436,17 @@ There are several required attributes a provider must implement, those being - [`read`](#readuri-cache) - [`write`](#writebufferindex-uri-cache) - [`delete`](#deleteuri-cache) -- [`move`](#moveuris-target_uri-cache---table) -- [`copy`](#copyuris-target_uri-cache---table) - [`get_metadata`](#getmetadatarequestedmetadata) - [`name`](#name) - [`protocol_patterns`](#protocolpatterns) - [`version`](#version-1) -There are additional optional attributes that if implemented, will be called during the lifecycle of the provider and buffers associated with it. 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 - [`init`](#initconfigurationoptions) - [`close_connection`](#closeconnectionbufferindex-uri-cache) +- [`move`](#moveuris-target_uri-cache---table) +- [`copy`](#copyuris-target_uri-cache---table) +- [`archive`]() There are 2 key variables that are provided with most calls to a [`provider`](#providers) by the [`api`](#api). Those are - [`uri`](#uri) @@ -263,6 +459,7 @@ The `cache` object is a `table` that is created (as an empty table) by [`api`](# Details on how to implement a [`provider`](#providers) can be found within the [Developer Guide](https://github.com/miversen33/netman.nvim/wiki/Developer-Guide) ## read(uri, cache) - Version Added: 0.1 +- Updated : 1.01 - [`uri`](#uri) - Type: [String](http://www.lua.org/pil/2.4.html) - Details: The string [`URI`](#uri) to read @@ -270,55 +467,96 @@ Details on how to implement a [`provider`](#providers) can be found within the [ - Type: [Table](https://www.lua.org/pil/2.5.html) - Details: The `table` object that is stored and managed by the [`api`](#api). The `api` gets this object from the [`provider`](#provider)'s [`init`](). For more details on how the cache works, consult the [Developer Guide](https://github.com/miversen33/netman.nvim/wiki/Developer-Guide) - Returns - - [`read`](#readuri-cache) must return one of the 4 following items - - A table containing the following `key`, `value` pairs, and [`READ_TYPE.FILE`](#read-type-file) - - local_path: String to file path to load - - origin_path: String for the original URI of the file - - unique_name: (Optional) String to indicate what the "unique" name of this file is - - An array containing strings to be displayed in the buffer, and [`READ_TYPE.STREAM`](#read-type-stream) - - It is assumed that each entry in the array is 1 "line" to be displayed in the buffer. Conform to this assumption in order to use [`READ_TYPE.STREAM`](#read-type-stream) - - A table containing the following `key`, `value` pairs, and [`READ_TYPE.EXPLORE`](#read-type-explore) - - parent: Integer pointing to the location in `details` that is the parent object - - details: An array of table objects where each table contains the following `key`, `value` (at minimum) pairs - - `FIELD_TYPE`: String - - `NAME`: String - - `URI`: String - - nil + - table + - [`read`](#readuri-cache) 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 + - A valid type as found in [`api.read`](#readuri-opts) + - 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](#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](#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`](#readuri-cache) process works, please consult the [`Developer Guide`](https://github.com/miversen33/netman.nvim/wiki/Developer-Guide) -- Throws - - It is acceptable to throw any errors that are encountered in the process of opening the requested URI +- Throws: nil - Notes - - [`read`](#readuri-cache) is a `synchronous` operation, meaning [`api`](#api) will block and wait for _some_ result on read. This can be partially circumvented by returning `nil` and then calling `netman.api.read` at a later point with the same [`URI`](#uri) details as provided earlier. This is useful if the provider has to do some backend work before it can "read" the URI properly (IE, needs to get a password from the user, must register an endpoint, must create a container, etc). More details on the `read` process can be found in the [`Developer Guide`](https://github.com/miversen33/netman.nvim/wiki/Developer-Guide) -## write(buffer_index, uri, cache) + - **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 -- `buffer_index` - - Type: [Integer](https://www.lua.org/pil/2.3.html) - - Details: The buffer index associated with the write path +- Updated : 1.01 - `uri` - Type: [String](http://www.lua.org/pil/2.4.html) - Details: The string [`URI`](#uri) to create - `cache` - Type: [Table](https://www.lua.org/pil/2.5.html) - Details: The `table` object that is stored and managed by the [`api`](#api). The `api` gets this object from the [`provider`](#provider)'s [`init`](). For more details on how the cache works, consult the [Developer Guide](https://github.com/miversen33/netman.nvim/wiki/Developer-Guide) -- Returns: nil -- Throws - - It is acceptable to throw any errors that are encountered in the process of writing the requested [`URI`](#uri) +- `data` + - Type: [Table](https://www.lua.org/pil/2.5.html) + - Details: A table of "lines" to write to the backing store +- `opts` + - Type: [Table](https://www.lua.org/pil/2.5.html) + - 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`](#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. - - **NOTE: [`api`](#api) calls the [`write`](#writebufferindex-uri-cache) function asynchronously and thus the provider cannot expect the [`api`](#api) to block on it. The provider should get whatever details it will need for the write immediately before doing any long running tasks as those resources may change over time** -## delete(uri) +## delete(uri, cache) - Version Added: 0.1 +- Updated : 1.01 - `uri` - Type: [String](http://www.lua.org/pil/2.4.html) - Details: The string [`URI`](#uri) to delete -- Returns: nil -- Throws - - It is acceptable to throw any errors that are encountered in the process of delete the requested [`URI`](#uri) +- `cache` + - Type: [Table](https://www.lua.org/pil/2.5.html) + - Details: The `table` object that is stored and managed by the [`api`](#api). The `api` gets this object from the [`provider`](#provider)'s [`init`](). For more details on how the cache works, consult the [Developer Guide](https://github.com/miversen33/netman.nvim/wiki/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`](#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. - - **NOTE: [`api`](#api) calls the [`delete`](#deleteuri-cache) function asynchronously and thus the provider cannot expect the [`api`](#api) to block on it. The provider should get whatever details it will need for the delete immediately before doing any long running tasks as those resources may change over time** -## move(uris, target_uri, cache) -> Table +## move(uris, target_uri, cache) - Version Added: 0.2 +- Updated : 1.01 - `uris` - Type: [Table](https://www.lua.org/pil/2.5.html) - Details: The table of string [`URIs`](#uri) to move @@ -339,8 +577,9 @@ Details on how to implement a [`provider`](#providers) can be found within the [ 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) -> Table +## copy(uris, target_uri, cache) - Version Added: 0.2 +- Updated : 1.01 - `uris` - Type: [Table](https://www.lua.org/pil/2.5.html) - Details: The table of string [`URIs`](#uri) to copy @@ -385,11 +624,9 @@ Details on how to implement a [`provider`](#providers) can be found within the [ - Notes - **[`init`](#initconfigurationoptions) is an optional function that will be called immediately after import of the [`provider`](#providers) if it exists** - This function's intended purpose is to allow the [`provider`](#providers) to verify that the environment it is being ran in is capable of handling it (IE, the environment meets whatever requirements the [`provider`](#provider) has), though it can be used for whatever the [`provider`](#providers) need in order to ensure it is ready to run -## close_connection(buffer_index, uri, cache) +## close_connection(uri, cache) - Version Added: 0.1 -- `buffer_index` - - Type: [Integer](https://www.lua.org/pil/2.3.html) - - Details: The buffer index associated with the write path +- Updated : 1.01 - `uri` - Type: [String](http://www.lua.org/pil/2.4.html) - Details: The string [`URI`](#uri) to create @@ -416,13 +653,6 @@ Details on how to implement a [`provider`](#providers) can be found within the [ # 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`](https://github.com/miversen33/netman.nvim/wiki/API-Documentation) as well as the [`Developer Guide`](https://github.com/miversen33/netman.nvim/wiki/Developer-Guide) -- utils - - command - - IGNORE_WHITESPACE_ERROR_LINES - - IGNORE_WHITESPACE_OUTPUT_LINES - - STDOUT_JOIN - - STDERR_JOIN - - SHELL_ESCAPE - api - READ_TYPE - FILE @@ -432,46 +662,28 @@ Options can be found in `netman.options`. These "options" are a table which acts - FILE - DIRECTORY - LINK - - protocol - - EXPLORE - - 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 -# Shims(WIP) -## explore(details) -- Version Added: 0.9 -- `details` - - Type: [Table](https://www.lua.org/pil/2.5.html) - - Details: The explore object will contain the a table with the following `key`, `value` pairs - - parent: Integer pointing to the location in `details` that is the parent object - - details: An array of table objects where each table contains the following `key`, `value` pairs - - `FIELD_TYPE`: String - - `NAME`: String - - `URI`: String -- Returns: nil -- Throws: nil -- Notes - - [`explore`](#exploredetails) is the method that [`api`](#api) will call when it is reaching out to the explorer to feed it with contents to display. - - [`explore`](#exploredetails) should reach out to its associated [`File Manager`](#file-manager) and feed it the provided details in `details`.`details` in a way the [`File Manager`](#file-manager) understands +- 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 ## protocol_patterns - Version Added: 0.9 - Notes diff --git a/lua/netman/tools/options.lua b/lua/netman/tools/options.lua index 39c31841..6aa329f1 100644 --- a/lua/netman/tools/options.lua +++ b/lua/netman/tools/options.lua @@ -21,9 +21,6 @@ return { error = 'error' } } - ,protocol = { - EXPLORE = 'EXPLORE' - } ,explorer = { METADATA = { -- This should match what is available from libuv's fs_statpath https://github.com/luvit/luv/blob/master/docs.md#uvfs_statpath-callback