editing: add higher-precedence SPACK_EDITOR environment variable

Other tools like git support `GIT_EDITOR` which takes higher precedence than the
standard `VISUAL` or `EDITOR` variables. This adds similar support for Spack, in the
`SPACK_EDITOR` env var.

- [x] consolidate editor code from hooks into `spack.util.editor`
- [x] add more editor tests
- [x] add support for `SPACK_EDITOR`
- [x] add a documentation section for controlling the editor and reference it

lib/spack/spack/test/util/editor.py

@@ -19,7 +19,7 @@
 
 
 # env vars that control the editor
-EDITOR_VARS = ["VISUAL", "EDITOR"]
+EDITOR_VARS = ["SPACK_EDITOR", "VISUAL", "EDITOR"]
 
 
 @pytest.fixture(scope="module", autouse=True)
@@ -104,6 +104,30 @@ def assert_exec(exe, args):
     assert ed.editor("/path/to/file", exec_fn=assert_exec)
 
 
+def test_editor_precedence(good_exe, gvim_exe, vim_exe, bad_exe):
+    """Ensure we prefer editor variables in order of precedence."""
+    os.environ["SPACK_EDITOR"] = good_exe
+    os.environ["VISUAL"] = gvim_exe
+    os.environ["EDITOR"] = vim_exe
+    correct_exe = good_exe
+
+    def assert_callback(exe, args):
+        result = ed.executable(exe, args)
+        if result == 0:
+            assert exe == correct_exe
+        return result
+
+    ed.editor(exec_fn=assert_callback)
+
+    os.environ["SPACK_EDITOR"] = bad_exe
+    correct_exe = gvim_exe
+    ed.editor(exec_fn=assert_callback)
+
+    os.environ["VISUAL"] = bad_exe
+    correct_exe = vim_exe
+    ed.editor(exec_fn=assert_callback)
+
+
 def test_find_exe_from_env_var_no_editor():
     if "FOO" in os.environ:
         os.environ.unset("FOO")

lib/spack/spack/util/editor.py

@@ -127,6 +127,8 @@ def try_env_var(var):
         return try_exec(exe, full_args, var)
 
     # try standard environment variables
+    if try_env_var("SPACK_EDITOR"):
+        return True
     if try_env_var("VISUAL"):
         return True
     if try_env_var("EDITOR"):