Skip to content

Add a Stdin Specification #586

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

Add a Stdin Specification #586

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 51 additions & 0 deletions docs/site/reference/formatter-spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,3 +60,54 @@ outputs.
### 4. Reliable

We expect the formatter to be reliable and not break the semantics of the formatted files.

## Stdin Specification
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should I actually promote this to a top level file? That is, docs/site/reference/stdin-spec.md?


Formatters **MAY** also implement the [Stdin Specification](#stdin-specification), which allows
formatting "virtual files" passed via stdin.

A formatter **MUST** implement the [Stdin Specification](#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]` is 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>]` is 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
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a bad example, as nixfmt doesn't actually behave this way yet.

Do folks know if there's an existing formatter (besides treefmt itself) that implements this spec?

```

!!! 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.
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a lie: it's OK for the formatter to fail to format, but it probably should (must?):

  • Print an explanation why to stderr
  • Exit non-zero

This made me realize the current formatter specification doesn't have anything to say about subprocess exit codes, but treefmt does check the exit code of the formatter it invokes. We should probably mention this in the spec?

2. **MUST NOT** attempt to read the file on the filesystem. Instead, it
**MUST** read from stdin.
3. **MUST NOT** write to the file on the filesytem.