~lsp-mode~ exposes a simple API for connecting and communicating with other
language clients. It also allows the user to add custom handlers for
non-standard notifications from the server.

* Functions
** Defining LSP clients
*** lsp-define-stdio-client /name language-id get-root command &rest args/
   Define a LSP client that uses stdio to communicate with the language server.

~name~ is the symbol to use for the name of the client.

~language-id~ is the language id to be used when communication with the Language Server.

~command~ is the command to run.  It may either be a string containing the path of
the command, or a list wherein the ~car~ is a string containing the path of the
command, and the ~cdr~ are arguments to that command.

Optional arguments:

~:docstring~ is an optional docstring used for the entrypoint function created by
`lsp-define-stdio-client'.

~:ignore-regexps~ is a list of regexps which when matched will be ignored by the
 output parser.

~:command-fn~ is a function that returns the command string/list to be used to
 launch the language server. If non-nil, COMMAND is ignored.

~:language-id-fn~ is a function that returns the language-id string to be used
 while opening a new file. If non-nil, LANGUAGE-ID is ignored.

~:extra-init-params~ is a plist that specifies any (optional)
 initializeOptions parameters required by the LSP server. A function taking
 a single argument (LSP workspace) and returning a plist is also accepted.

~:initialize~ is a function called when the client is initialized. It takes a
 single argument, the newly created client.

** Communication with the language server
*** lsp-client-on-notification /client method callback/
   Add a handler for when Emacs receives a notification from the language server.


~client~ is the client object, received by the ~:initialize~ callback in
~lsp-define-*-client~.

~method~ should be a string with the method name.

~callback~ should be a lisp function taking two arguments, the workspace and the
parameters passed with the notification as a hash table. The return value of the
callback is ignored.

*** lsp-client-on-request /client method callback/
    Add a handler for when Emacs receives a request from the language server.

~client~ is the client object, received by the ~:initialize~ callback in
~lsp-define-*-client~.

~method~ should be a string with the method name.

~callback~ should be a lisp function taking a single argument, the parameters
passed with the request as a hash table. The return value of the callback should
be JSON friendly, as it will be sent to the server as a response.


/The following functions require ~lsp-mode~ >= 4.1/:

*** lsp-make-notification /method &optional params/
    Create a notification body.

~method~ should be a string with the notification method name.

~params~ should be a Lisp value that can be encoded using ~json-encode~.

*** lsp-send-notification /body/
    Send a notification to the language server. The response from the language
    server is unmarshalled to a hash table.

~body~ should be a notification body, returned by ~lsp-make-notification~.

*** lsp-make-request /method &optional params/
    Create request body.

~method~ should be a string with the request method name.

~params~ should be a Lisp value that can be encoded using ~json-encode~.

*** lsp-send-request /body/
    Send a request to the language server and get the response synchronously.
    The response from the language server is unmarshalled to a hash table.

~body~ should be a request body, returned by ~lsp-make-request~.

*** lsp-send-request-async /body callback/
    Send a request to the language server, and call the provided callback with
    the response asynchronously.

~body~ should be a request body, returned by ~lsp-make-request~.

~callback~ should be a function taking two arguments: the LSP workspace object,
and the response received from the server, as a hash table.

** Other
*** lsp-make-traverser /name/
   Return a closure that walks up the current directory until NAME is found.

NAME can either be a string or a predicate used for ~locate-dominating-file~.
The value returned by the function will be the directory name for NAME.

If no such directory could be found, log a warning and return ~default-directory~ instead.
Example for `lsp-python`:
#+BEGIN_SRC emacs-lisp
(lsp-define-stdio-client lsp-python "python"
			 (lsp-make-traverser #'(lambda (dir)
						 (directory-files
						  dir
						  nil
						  "\\(__init__\\|setup\\)\\.py")))
			 '("pyls"))
#+END_SRC
* Hooks
** lsp-before-initialize-hook
   List of functions to be called before a Language Server has been initialized
   for a new workspace.
** lsp-after-initialize-hook
   A list of functions to be called after a Language Server has been initialized
   for a new workspace.
** lsp-after-diagnostics-hook
   A list of functions to be called after the Language Server publishes
   diagnostics for a file.
** lsp-before-open-hook
   List of functions to be called before a new file with LSP support is opened.
** lsp-after-open-hook
   List of functions to be called after a new file with LSP support is opened.
