denops.txt

*denops.txt*		An Ecosystem for Writing Vim/Neovim Plugins in Deno

=============================================================================
CONTENTS					*denops-contents*

INTRODUCTION				|denops-introduction|
USAGE					|denops-usage|
  SHARED SERVER				|denops-shared-server|
INTERFACE				|denops-interface|
  VARIABLE				|denops-variable|
  FUNCTION				|denops-function|
  AUTOCMD				|denops-autocmd|


=============================================================================
INTRODUCTION					*denops-introduction*

*denops.vim* (denops) is an ecosystem for writing plugins for Vim or Neovim
using Deno.

Visit the Denops Document or Wiki for guidance on creating denops plugins.

Denops Document: https://vim-denops.github.io/denops-documentation/
Wiki: https://github.com/vim-denops/denops.vim/wiki
API Reference: https://deno.land/x/denops_std/mod.ts


=============================================================================
USAGE							*denops-usage*

-----------------------------------------------------------------------------
SHARED SERVER					*denops-shared-server*

Typically, a Denops server starts for each Vim/Neovim instance, but there are
scenarios where the process startup becomes a bottleneck, affecting usability.

To address this, launching a "Shared server" and connecting to it allows all
Vim/Neovim instances to utilize a shared server, eliminating the process
launch bottleneck and potentially improving usability.

To start the shared server, execute the following command in the denops.vim
repository's top directory:
>
	deno run -A --no-lock ./denops/@denops-private/cli.ts
<

Then specify the server address in |g:denops_server_addr| as follows:
>
	let g:denops_server_addr = '127.0.0.1:32123'
<

If you want to specify a hostname and port, use the "--hostname" and "--port"
command arguments as follows:
>
	deno run -A --no-lock \
		./denops/@denops-private/cli.ts \
		--hostname=0.0.0.0 \
		--port 12345
<
Note that there is a plugin that install startup scripts of the shared server
for each platform. See the following repository for details:

https://github.com/vim-denops/denops-shared-server.vim


=============================================================================
INTERFACE						*denops-interface*

-----------------------------------------------------------------------------
VARIABLE						*denops-variable*

*g:denops_disable_version_check*
	Disables version check on startup. Use it to forcibly enable denops on
	unsupported versions of Vim/Neovim. Do not report any errors/issues
	on non-supported versions.
	Default: 0

*g:denops_server_addr*
	Global denops server address in "{hostname}:{port}" format.
	If the value is not specified or invalid, denops starts a local denops
	server for each Vim/Neovim instance.
	Default: 0

*g:denops#disabled*
	Set to 1 to disable denops.
	Default: 0

*g:denops#deno*
	Executable program of Deno. Use it to specify the executable program
	of Deno if "deno" is not in PATH.
	Default: "deno"

*g:denops#deno_dir*
	Cache directory of Deno. If unspecified, the cache directory is
	determined by the DENO_DIR environment variable or internally by
	"deno".
	Default: |v:null|

*g:denops#debug*
	Set to 1 to enable debug mode. In debug mode, additional debug
	messages of denops itself will be shown.
	This variable must be configured prior to denops initialization.
	Default: 0

*g:denops#disable_deprecation_warning_message*
	Set to 1 to disable deprecation warning messages.
	Default: 0

*g:denops#server#deno*
	Executable program of Deno for starting a server.
	Default: |g:denops#deno|

*g:denops#server#deno_args*
	Program arguments of Deno for starting a server.
	Default: ['-q', '--no-lock', '-A']

*g:denops#server#restart_delay*
	Restart delay in milliseconds to avoid #136.
	https://github.com/vim-denops/denops.vim/issues/136
	Default: 100

*g:denops#server#restart_interval*
	Interval in milliseconds to avoid infinite errors. Denops will reset
	internal counter when the process keeps running more than this
	interval.
	Default: 10000

*g:denops#server#restart_threshold*
        The number of restart counts within
        |g:denops#server#restart_interval|.
	Default: 3

*g:denops#server#reconnect_interval*
	Interval in milliseconds before retrying connection to the server.
	Default: 100

*g:denops#server#reconnect_threshold*
	The number of reconnect counts on connection failure.
	Default: 3

*g:denops#server#wait_interval*
	Interval in milliseconds for |denops#server#wait()|.
	Default: 10

*g:denops#server#wait_timeout*
	Timeout in milliseconds for |denops#server#wait()|.
	Default: 30000

*g:denops#plugin#wait_interval*
	Interval in milliseconds for |denops#plugin#wait()|.
	Default: 10

*g:denops#plugin#wait_timeout*
	Timeout in milliseconds for |denops#plugin#wait()|.
	Default: 30000

-----------------------------------------------------------------------------
FUNCTION						*denops-function*

						*denops#notify()*
denops#notify({name}, {method}, {params})
	Calls API {method} of {name} plugin with {params} and returns
	immediately without waiting for a result.
	Use |denops#request()| instead if you need a result.
        Note: It does not redraw in the Vim environment. Manually execute
        |:redraw| if needed.

						*denops#request()*
denops#request({name}, {method}, {params})
	Calls API {method} of {name} plugin with {params} and waits for a
	result, then returns it.
	Use |denops#notify()| instead if you don't need a result.
	Use |denops#request_async()| instead if you need a result
	asynchronously.

						*denops#request_async()*
denops#request_async({name}, {method}, {params}, {success}, {failure})
	Calls API {method} of {name} plugin with {params} and returns
	immediately. Once the call succeeds, the {success} callback is called
	with a result.
	Otherwise, the {failure} callback is called with an error.
	Use |denops#notify()| instead if you don't need a result.
	Use |denops#request()| instead if you need a result synchronously.

	Note that it uses |denops#callback#register()| with "once" options to
	register {success} and {failure} internally. So developers MUST
	use |lambda| expressions to always create new fresh unnamed functions.
>
	" DO NOT
	call denops#request_async(
	      \ 'foo', 'bar', [],
	      \ funcref('s:success'),
	      \ funcref('s:failure'),
	      \)

	" DO
	call denops#request_async(
	      \ 'foo', 'bar', [],
	      \ { v -> s:success(v) },
	      \ { e -> s:failure(e) },
	      \)
<
						*denops#cache#update()*
denops#cache#update([{options}])
	Update Deno module cache of denops itself and denops plugins in
	|runtimepath|.

	The following {options} is available

	"reload"	|v:true| to force update ("--reload" flag of "deno
			cache") command.

						*denops#server#start()*
denops#server#start()
	Starts a denops server process and connects to the channel. It does
	nothing when the server is already started.

	It is automatically called 1) on |VimEnter| autocmd when denops is
	in 'runtimepath' during Vim startup, 2) immediately when denops is
	added to 'runtimepath' after Vim startup.

	Note that the server is automatically restarted when the process is
	stopped unexpectedly.

						*denops#server#stop()*
denops#server#stop()
	Stops a denops server. It does nothing when the server is not started
	yet.

						*denops#server#restart()*
denops#server#restart()
	Restarts a denops server.

						*denops#server#connect()*
denops#server#connect()
	Connects to a |denops-shared-server| channel. It does nothing when the
	channel is already established.

	It is automatically called 1) on |VimEnter| autocmd when denops is
	in 'runtimepath' during Vim startup, 2) immediately when denops is
	added to 'runtimepath' after Vim startup when |g:denops_server_addr|
	is specified. Otherwise, it echoes errors.

	Note that the channel is automatically re-established when the channel
	is closed unexpectedly.

						*denops#server#close()*
denops#server#close()
	Closes the channel. It does nothing when the channel is not
	established yet.

						*denops#server#reconnect()*
denops#server#reconnect()
	Reconnects to a denops shared server.

						*denops#server#status()*
denops#server#status()
	Returns the current server status, which can be one of the following:

	Status		Description~
	"stopped"	Server is stopped.
	"starting"	Server is starting.
	"preparing"	Server is preparing (initializing).
	"running"	Server is running (ready).

	Note that "starting" is never returned when a |denops-shared-server|
	is used.

						*denops#server#wait()*
denops#server#wait([{options}])
	Waits synchronously until a |DenopsReady| autocmd is fired. It returns
	immediately when the autocmd is already fired.
	It returns -1 if it times out, -2 if the server is not started or
	interrupted.
	Developers need to consider this return value to decide whether to
	continue with the subsequent process.
	The following attributes are available on {options}.

        "interval"	Interval in milliseconds for |:sleep| in internal
        		loop.
			Default: |g:denops#server#wait_interval|
	"timeout"	Timeout in milliseconds to block.
			Default: |g:denops#server#wait_timeout|
	"silent"	1 to silence error messages.
			Default: 0

						*denops#server#wait_async()*
denops#server#wait_async({callback})
	Waits asynchronously until a |DenopsReady| autocmd is fired and
	invokes a {callback}. It invokes the {callback} immediately when the
	autocmd is already fired. If this function is called multiple times,
	callbacks registered are called in order of registration.

						*denops#plugin#is_loaded()*
denops#plugin#is_loaded({name})
	Returns 1 if a {name} plugin is already loaded. Otherwise, returns
	0.

						*denops#plugin#wait()*
denops#plugin#wait({name}[, {options}])
	Waits synchronously until a {name} plugin is loaded. It returns
	immediately when the {name} plugin is already loaded.
	It returns -1 if it times out, -2 if the server is not yet ready or
	interrupted, or -3 if the plugin initialization failed.
	Developers need to consider this return value to decide whether to
	continue with the subsequent process.
	The following attributes are available on {options}.

        "interval"	Interval in milliseconds for |:sleep| in internal
        		loop.
			Default: |g:denops#plugin#wait_interval|
	"timeout"	Timeout in milliseconds to block.
			Default: |g:denops#plugin#wait_timeout|
	"silent"	1 to silence error messages.
			Default: 0

						*denops#plugin#wait_async()*
denops#plugin#wait_async({name}, {callback})
	Waits asynchronously until a {name} plugin is loaded and invokes a
	{callback}. It invokes the {callback} immediately when the {name}
	plugin is already loaded. If this function is called multiple times
	for the same {name} plugin, callbacks registered for the plugin are
	called in order of registration.

						*denops#plugin#register()*
denops#plugin#register({name}[, {script}[, {options}]])
	DEPRECATED: Use |denops#plugin#load()| instead.

	Developers who would like to support previous denops versions should
	fallback to this function like
>
	try
	  call denops#plugin#load(
	        \ "denops-hello",
	        \ "/path/to/denops-hello/main.ts",
	        \)
	catch /^Vim\%((\a\+)\)\=:E117:/
	  " Fallback to `register` for backward compatibility
	  call denops#plugin#register(
	        \ "denops-hello",
	        \ "/path/to/denops-hello/main.ts",
	        \ {"mode": "skip"},
	        \)
	endtry
<
	Note that the {options} are ignored and always treated as skip mode.

						*denops#plugin#discover()*
denops#plugin#discover()
	Discovers denops plugins from 'runtimepath' and loads them.
	It gathers "main.ts" under "denops/*" directories under 'runtimepath'
	if the middle directory does not start with "@".
        This is automatically called on |User| |DenopsReady| autocmd invoked
        by |denops#server#start()|.

						*denops#plugin#load()*
denops#plugin#load({name}, {script})
	Loads a denops plugin. Use this function to load denops plugins that
	are not discovered by |denops#plugin#discover()|.
	It invokes |User| |DenopsPluginPre|:{plugin} just before denops
	executes a "main" function of the plugin and |User|
	|DenopsPluginPost|:{plugin} just after denops executes a "main"
	function of the plugin.

						*denops#plugin#reload()*
denops#plugin#reload({name})
	Reloads a denops plugin.

						*denops#plugin#check_type()*
denops#plugin#check_type([{name}])
	Runs Deno's type check feature for {name} or all registered plugins.
	The result of the check will be displayed in |message-history|.

						*denops#callback#register()*
denops#callback#register({callback}[, {options}])
	Registers {callback} to the internal callback map as an anonymous
	function and returns a unique {id} to call the {callback} later.
	The following attributes are available on {options}.

	"once"		|v:true| to register the callback as a one-time
			anonymous function that will be removed when the
			callback has been called.
			Default: |v:false|
>
	" Persistent callback
	let id = denops#callback#register({ a, b -> a + b })
	let ret1 = denops#callback#call(id, 1, 2)
	let ret2 = denops#callback#call(id, 2, 3)

	" One-time callback
	let id = denops#callback#register(
	      \ { a, b -> a + b },
	      \ { 'once': v:true }
	      \)
	let ret1 = denops#callback#call(id, 1, 2)
<

						*denops#callback#unregister()*
denops#callback#unregister({id})
	Unregisters a callback of {id} from the internal callback map. It does
	nothing when no {id} callback exists.

						*denops#callback#call()*
denops#callback#call({id}[, {args}...])
	Finds a callback of {id} from the internal callback map and calls it
	with given {args}, then returns a result. It throws an error when no
	{id} callback exists.
	Note that the callback called is automatically removed from the
	internal callback map if the "once" option had been specified.

						*denops#callback#clear()*
denops#callback#clear()
	Clears the internal callback map.


-----------------------------------------------------------------------------
AUTOCMD						*denops-autocmd*

DenopsReady						*DenopsReady*
	Fired when a connection (channel) with Denops is established.
	Note that this is not when all plugins are available.

DenopsClosed						*DenopsClosed*
	Fired when the connection (channel) with Denops is broken.
	It is assumed to be used to release resources such as cache.

DenopsPluginPre:{plugin}				*DenopsPluginPre*
	Fired before the "main" function of each plugin is called.
	{plugin} is the name of the target plugin.

DenopsPluginPost:{plugin}				*DenopsPluginPost*
	Fired after the "main" function of each plugin is called.
	{plugin} is the name of the target plugin.

DenopsProcessStarted					*DenopsProcessStarted*
	Fires when the Denops local server process is started.
	It is never fired in shared server mode.

DenopsProcessStopped:{exitcode}				*DenopsProcessStopped*
	Fired when the Denops local server process is stopped.
	It is never fired in shared server mode.

=============================================================================
vim:tw=78:fo=tcq2mM:ts=8:ft=help:norl