Media types extension

Work in progress

argtype is early-stage and the extension mechanism is still being designed; this extension's surface may change.

Extension name: mediatypes

Annotates a path terminal with the media type of the file it refers to (image/png, application/json, and so on). This describes the contents a tool expects at that path, not the syntactic type of the argument (which is already path). That's why it's an extension rather than core: it's metadata about the referenced file, not a refinement of the argv element itself.

Compare with value constraints like int.min(1).max(100), which are core: those narrow the set of strings the argument accepts. .mediaType("image/png") doesn't narrow the set of valid path strings at all; it's advisory information for consumers that care.

---
exe: "convert"
---

Image = path.mediaType("image/png")

convert: seq(
  input:  Image,
  output: Image,
)

What consumers do with it

• GUI / form generators use it to filter file pickers.
• Wrapper generators may surface it as a doc hint or a stricter parameter type where the host language has one.
• Validators may (optionally) sniff the file and warn on a mismatch, but like all extensions this is advisory: a consumer that doesn't implement mediatypes ignores it.

A media type describes a file, so it applies to path only - argtype's file-reference terminal. If an argument is a file, model it as path and annotate that; .mediaType() on a non-path terminal has nothing to describe, so a consumer that implements mediatypes treats it as an error (see the metadata-chaining rule). A consumer that does not implement the extension ignores .mediaType() everywhere, as the ignorable rule requires.

Methods

Method	Meaning
path.mediaType(mime)	The file at this path is expected to be of the given media type (an RFC 6838 media type string).

Chaining API

// On a terminal, for a `path` (provided by the mediatypes extension):
interface TerminalNode {
  mediaType(mime: string): TerminalNode
}