Add a Stdin Specification

This completes step 1 of
#573 (comment).

Author: jfly

docs/site/reference/formatter-spec.md

@@ -30,8 +30,8 @@ The formatter's CLI must be of the form:
 Where:
 
 - `<command>` is the name of the formatter executable.
-- `[options]` is any number of flags and options that the formatter accepts.
-- `[...<files>]` is one or more files given to the formatter for processing.
+- `[options]` are any number of flags and options that the formatter accepts.
+- `[...<files>]` are one or more files given to the formatter for processing.
 
 Example:
 

docs/site/reference/stdin-spec.md

@@ -0,0 +1,63 @@
+---
+outline: deep
+---
+
+# Stdin Specification
+
+Formatters **MAY** also implement the Stdin Specification, which allows
+formatting "virtual files" passed via stdin.
+
+A formatter **MUST** implement the Stdin Specification if its formatting behavior
+can depend on the name of the file being formatted.
+
+## Rules
+
+In order for the formatter to comply with this spec, it **MUST** satisfy the following:
+
+### 1. `--stdin` flag
+
+The formatter's CLI must be of the form:
+
+```
+<command> [options] [--stdin] [...<files>]
+```
+
+Where:
+
+- `<command>` is the name of the formatting tool.
+- `[options]` are any number of flags and options that the formatter accepts.
+- `--stdin` is an optional flag that puts the formatter in "stdin mode". In
+  stdin mode, the formatter reads file contents from stdin rather than the
+  filesystem.
+- `[...<files>]` are one or more files given to the formatter for processing. If
+  `--stdin` is specified, then exactly 1 must be present, and is treated as a
+  filename.
+
+Example:
+
+```
+$ echo "{}" | nixfmt --stdin path/to/file.nix
+```
+
+!!! note
+
+    This CLI **MUST** be implemented in a way that is compatibile with the
+    vanilla [Formatter Specification](#1-files-passed-as-arguments).
+
+### 2. Print to stdout, do not assume file is present on filesystem
+
+When in stdin mode, the formatter:
+
+1. **MUST** print the formatted file to stdout.
+2. **MUST NOT** attempt to read the file on the filesystem. Instead, it
+   **MUST** read from stdin.
+3. **MUST NOT** write to the given path on the filesytem. It _MAY_ write to
+   temporary files elsewhere on disk, but _SHOULD_ clean them up when done.
+
+### 3. Exit nonzero on error
+
+When something goes wrong when formatting (for example, the source code is
+syntactically invalid), the formatter **MUST** exit nonzero.
+
+The formatter _SHOULD_ print useful information about what went wrong to
+stderr.