fix(formatters): document and clean up a couple formatters

README.md

@@ -1,3 +1,18 @@
 # confit
 
-@sesamecare-oss/confit is a modern rewrite of [confit](https://github.com/krakenjs/confit) in Typescript using Promises and bundling the standard shortstop handlers. The general approach of stackable environment-aware configurations is retained, but we add proper typing for key lookups and just generally modernize the build pipeline.
+@sesamecare-oss/confit is a modern rewrite of [confit](https://github.com/krakenjs/confit) in Typescript using Promises and bundling the standard shortstop handlers. The general approach of stackable environment-aware configurations is retained, but we add proper typing for key lookups and just generally modernize the build pipeline. We also bundle the shortstop infrastructure and the common shortstop handlers.
+
+## env
+
+The env shortstop handler accepts the following format specificiations:
+
+* `env:SOMEVAR|u` - Return the variable if it exists and is non-empty, else undefined
+* `env:SOMEVAR|ud` - Return the variable as a number if it exists, or undefined
+* `env:SOMEVAR|d` - Return the value as a decimal, or NaN if not there
+* `env:SOMEVAR|b` - Return the value as a boolean - empty, false, 0 and undefined will be false
+* `env:SOMEVAR|!b` - Return the value as a boolean but inverted so that empty/undefined/0/false are true
+
+## file
+
+The file handler uses the pipe character to allow specifying the encoding with which to read the file. The valid encodings are
+`base64|binary|hex|utf8|ucs2|utf16le|ascii`. If you somehow have a pipe with one of these values at the end your filename (wow), use `|binary` at the end to make it clearer and behave as normal.

src/shortstop/envHandler.ts

@@ -10,15 +10,15 @@ export function envHandler() {
     '|ud': (value?: string) => {
       return value === '' || value === undefined ? undefined : parseInt(value, 10);
     },
-    // Return it as a decimal
+    // Return the value as a decimal
     '|d': (value?: string) => {
       return parseInt(value || '', 10);
     },
-    // Return it as a boolean - empty, false, 0 and undefined will be false
+    // Return the value as a boolean - empty, false, 0 and undefined will be false
     '|b': (value?: string) => {
       return value !== '' && value !== 'false' && value !== '0' && value !== undefined;
     },
-    // Return it as a boolean but inverted so that empty/undefined/0/false are true
+    // Return the value as a boolean but inverted so that empty/undefined/0/false are true
     '|!b': (value?: string) => {
       return value === '' || value === 'false' || value === '0' || value === undefined;
     },

src/shortstop/fileHandlers.ts

@@ -71,7 +71,7 @@ export function fileHandler(basedir?: string | ReadOptions, options?: ReadOption
     const finalOptions = { ...baseOptions };
     let filename = value;
     // Find the options value with a pipe character and a spec at the end
-    const match = filename.match(/(.*)\|(base64|hex|utf8|ucs2|utf16le|ascii)$/);
+    const match = filename.match(/(.*)\|(base64|binary|hex|utf8|ucs2|utf16le|ascii)$/);
     if (match) {
       filename = match[1];
       finalOptions.encoding = match[2] as BufferEncoding;