(simple) Document-level metadata

[marrus-sh]

Right now it’s not possible to tell the “type” of a KDL file by just looking at its contents; this information needs to be conveyed out-of-band. Likewise for any other parser configuration or additional information which might need to be conveyed to applications about the file (#329).

I don’t think KDL should specify any of this metadata, but I do think it should provide a place for it, ideally at the top of the file (#143). Ideally the syntax should be simple and restricted (e.g. plain key-value pairs) so that you don't need a KDL parser to configure your KDL parser.

For the sake of discussion, I’ll propose a line consisting of:

• /!, playing off of other uses of / to introduce comments

• an escaped-string or identifier identifying the type of file, or kdl for a generic kdl file

  • it would be nice for this to support slashes (e.g. mime types), so support for quoted strings is necessary

• any number of key=value pairs, where both key and value are identifiers or match escaped-string, each preceded by whitespace / line continuations

• optional whitespace / line continuations

• a newline or eof

For example:

/!kdl kdl-version="2.0" base-uri="http://example.com"

website {
  url (resolve-uri)"/home"
}

(kdl-version strikes me as an immediately useful piece of information so that parsers can continue to support older versions.)

(let’s say names which begin with kdl are reserved)