Add ability to specify defaults for variables

docs/configuration.md

@@ -12,6 +12,7 @@ for Vimspector.
      * [Debug profile configuration](#debug-profile-configuration)
      * [Replacements and variables](#replacements-and-variables)
      * [The splat operator](#the-splat-operator)
+     * [Default values](#default-values)
   * [Configuration Format](#configuration-format)
   * [Files and locations](#files-and-locations)
   * [Adapter configurations](#adapter-configurations)
@@ -28,7 +29,7 @@ for Vimspector.
   * [Appendix: Configuration file format](#appendix-configuration-file-format)
   * [Appendix: Editor configuration](#appendix-editor-configuration)
 
-<!-- Added by: ben, at: Sun 12 Jul 2020 16:46:18 BST -->
+<!-- Added by: ben, at: Fri 31 Jul 2020 22:13:39 BST -->
 
 <!--te-->
 
@@ -204,6 +205,37 @@ You can also combine with static values:
 This would yield the intuitive result:
 `[ "First",  "one", "two three", "four", "Last" ]`
 
+### Default values
+
+You can specify replacesments with default values. In this case if the user has
+not specified a value, they are prompted but with the default value
+pre-populated, allowing them to just press return to accept the default.
+
+The syntax is `${variableName:default value}`. The default value can contain any
+character, but to include a `}` you must escape it with a backslash. To include
+a backslash in the JSON you must write `\\`, as in:
+
+```json
+  { "key": "${value:default {\\} stuff}" }
+```
+
+The default value can also be a replacement variable. However, this _must_ be a
+veriable that's already defined, such as one of the [predefined
+variables](#predefined-variables), or one speified in a `variables` block. In
+order to reference them, you _must_ use `${var}` syntax and you _must_ escape
+the closing `}`. For example, the is a common and useful case:
+
+```json
+  {
+    "configuration": {
+      "program": "${script:${file\\}}"
+    }
+  }
+```
+
+This will prompt the user to specify `script`, but it will default to the path
+to the current file.
+
 ## Configuration Format
 
 All Vimspector configuration is defined in a JSON object. The complete

docs/custom_gadget_file.md

@@ -0,0 +1,25 @@
+---
+title: Configuration
+---
+
+This document describes how to use vimspector's `install_gadget.py` to install
+custom debug adapters. This can be useful as a way to get an adapter working
+that isn't officially supported by Vimspector, but otherwise can be made to work
+by simply downloading the VScode extension into the gadget directory.
+
+## Usage
+
+```
+./install_gadget.py --enable-custom=/path/to/a.json \
+                    --enable-custom=/path/to/b.json`
+```
+
+This tells `install_gadget.py` to read `a.json` and `b.json` as _gadget
+definitions_ and download/unpack the specified gadgets into the gadget dir, just
+like the supported adapters.
+
+## Gadget Definitions
+
+A _gadget definition_ is a file containing a single JSON object definition,
+describing the debug adapter and how to download and install it. This mechanism
+is crude but can be effective.