Introduce runserver function

runserver will attempt to pick a reasonable environment to run the
language server against.

Closes #748.

We still need to address running the language server against a project
with no Manifest.

README.md

@@ -21,17 +21,22 @@ make use of the Julia Language Server for various code editing features:
 ## Installation and Usage
 **Documentation**: [![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://www.julia-vscode.org/LanguageServer.jl/dev)
 
+To install LanguageServer.jl into the current environment:
+
 ```julia
 using Pkg
 Pkg.add("LanguageServer")
 ```
 
-Instantiate an instance of the language server with
-`LanguageServerInstance` and `run` it:
-
-```julia
-using LanguageServer
+To run an instance of LanguageServer.jl on `env_path`, you can run
+Julia as follows:
 
-server = LanguageServerInstance(stdin, stdout, "/path/to/environment")
-run(server)
+```sh
+julia --project=/path/to/LanguageServer.jl/environment \
+  -e "using LanguageServer, LanguageServer.SymbolServer; runserver()" \
+  <env_path>
 ```
+
+If `env_path` is not specified, the language server will run on the
+parent project of `pwd` or on the default `.julia/environments/v#.#`
+if there is no parent project.

src/LanguageServer.jl

@@ -6,13 +6,15 @@ using StaticLint: refof, scopeof, bindingof
 using UUIDs
 import JSONRPC
 using JSONRPC: Outbound, @dict_readable
-export LanguageServerInstance
+
+export LanguageServerInstance, runserver
 
 include("exception_types.jl")
 include("uri2.jl")
 include("protocol/protocol.jl")
 include("document.jl")
 include("languageserverinstance.jl")
+include("runserver.jl")
 include("staticlint.jl")
 
 include("requests/init.jl")

src/runserver.jl

@@ -0,0 +1,51 @@
+"""
+    runserver(pipe_in=stdin, pipe_out=stdout[, env_path])
+
+Run a `LanguageServerInstance` reading from `pipe_in` and writing to `pipe_out`.
+
+The same options can be passed to `runserver` as to
+[`LanguageServerInstance`](@ref). If `env_path` is not specified,
+attempt to pick an environment by considering in order of priority:
+
+1. [`ARGS`[1]](@ref): the first command-line argument passed to the
+   invocation of `julia`.
+2. The Julia project containing [`pwd()`](@ref).
+3. The default Julia environment withing `.julia/environments/v#.#`.
+
+# Examples
+
+The following invocation of Julia would set `env_path` to
+`/home/example/repos/Example.jl`:
+
+```sh
+julia --project=/path/to/LanguageServer.jl \\
+  -e "using LanguageServer, SymbolServer; runserver()" \\
+  /home/example/repos/Example.jl
+```
+
+!!! note
+    Due to [a current
+    bug](https://github.com/julia-vscode/LanguageServer.jl/issues/750),
+    `SymbolServer` must be imported into `Main`.
+
+If there was a `Project.toml` or `JuliaProject.toml` in
+`/home/example/repos/Example.jl/`, the following invocation would set
+`env_path` to `/home/example/repos/Example.jl/`; otherwise it would be
+set to `.julia/environments/v#.#` where `v#.#` is the major/minor
+version of Julia being invoked.
+
+```sh
+julia --project=/path/to/LanguageServer.jl \\
+  -e "using LanguageServer, SymbolServer; runserver()"
+```
+"""
+function runserver(pipe_in=stdin, pipe_out=stdout, env_path=choose_env(),
+                   depot_path="", err_handler=nothing, symserver_store_path=nothing)
+    server = LanguageServerInstance(pipe_in, pipe_out, env_path, depot_path,
+                                    err_handler, symserver_store_path)
+    run(server)
+end
+
+choose_env() = something(get(ARGS, 1, nothing),         # 1. path passed explicitly
+                         Base.current_project(pwd()),   # 2. parent project of pwd()
+                         Base.load_path_expand("@#.#")) # 3. default "global" env

test/test_communication.jl

@@ -107,8 +107,7 @@ end
     try
         sock = accept(server)
         try
-            ls = LanguageServerInstance(sock, sock, dirname(Pkg.Types.Context().env.project_file), first(Base.DEPOT_PATH))
-            run(ls)
+            runserver(sock, sock, Pkg.Types.Context().env.project_file, first(DEPOT_PATH))
         finally
             close(sock)
         end