Add config documentation (addresses #254).

README.md

@@ -39,8 +39,38 @@ Options:
   --host      Hostname for web app to listen on  [string] [default: "localhost"]
   --port      Port for web app to listen on             [number] [default: 3000]
   --debug     Use verbose output for debugging        [boolean] [default: false]
+  -c --config Show current default configuration      [boolean] [default: false]
 ```
 
+## Configuration
+
+The above options can be permanently set with a configuration file found in a
+standard folder for configuration, depending on your operating system:
+
+- Linux: `$XDG_CONFIG_HOME/oasis/default.json`.
+  Usually this is `/home/<your username>/.config/oasis/default.json`
+  <!-- cspell:disable-next-line -->
+- Windows `%APPDATA%\oasis\default.json`.
+- Mac OS, `<Library>/Preferences/oasis/default.json`
+
+The configuration file can override any or all of the command-line _defaults_.
+Here is an example customizing the port number and the "open" settings:
+
+```json
+{
+  "open": false,
+  "port": 19192
+}
+```
+
+### Configuration Semantics
+
+Which value is given is decided like this:
+
+1. If an argument is given on the command-line, use that value.
+2. Otherwise, use the value from the configuration file if present.
+3. If neither command-line nor configuration file are given, use the built-in default value.
+
 ## Installation
 
 Most people should install stable releases with [npm](https://npmjs.org/) and

src/cli.js

@@ -3,7 +3,7 @@
 const yargs = require("yargs");
 const _ = require("lodash");
 
-module.exports = presets =>
+module.exports = (presets, defaultConfigFile) =>
   yargs
     .scriptName("oasis")
     .env("OASIS")
@@ -42,4 +42,5 @@ module.exports = presets =>
       describe: "Use verbose output for debugging",
       default: _.get(presets, "debug", false),
       type: "boolean"
-    }).argv;
+    })
+    .epilog(`The defaults can be configured in ${defaultConfigFile}.`).argv;

src/index.js

@@ -14,15 +14,17 @@ const defaultConfigFile = path.join(
 );
 
 const defaultConfig = {};
+var haveConfig;
 
 try {
   const defaultConfigOverride = fs.readFileSync(defaultConfigFile, "utf8");
   Object.entries(JSON.parse(defaultConfigOverride)).forEach(([key, value]) => {
     defaultConfig[key] = value;
   });
+  haveConfig = true;
 } catch (e) {
   if (e.code === "ENOENT") {
-    // No default config, no problem.
+    haveConfig = false;
   } else {
     console.log(`There was a problem loading ${defaultConfigFile}`);
     throw e;
@@ -30,7 +32,26 @@ try {
 }
 
 const cli = require("./cli");
-const config = cli(defaultConfig);
+const config = cli(defaultConfig, defaultConfigFile);
+delete config._;
+delete config.$0;
+
+console.log();
+if (haveConfig) {
+  console.log(`Configuration read defaults from ${defaultConfigFile}`);
+} else {
+  console.log(
+    `No configuration file found at ${defaultConfigFile}. ` +
+      "Using built-in default values."
+  );
+}
+console.log("Current configuration:");
+console.log();
+console.log(JSON.stringify(config, null, 2));
+console.log();
+console.log(`Note: You can save the above to ${defaultConfigFile} to make \
+these settings the default. See the readme for details.`);
+console.log();
 
 if (config.debug) {
   process.env.DEBUG = "oasis,oasis:*";