ftd::p1 grammar

ftd::p1 grammar

section

A ftd::p1 file is composed of “sections”. A section looks like this:

-- some section: the caption of the section
header-1: some header value
hello: world

the body of the first section

-- something:
yo: 42

-- some section: the caption of the section
header-1: some header value
hello: world

the body of the first section

-- something:
yo: 42

section name

The section name is the only mandatory parameter for a section. Name starts after -- , and ends with the first :. Trailing : is mandatory.

In our example, the name of the first section is some section, and the second section’s name is something.

Section name contains alphanumeric characters, underscores, space, dots(.), hash(#), and hyphens(-). Colon terminates the section name.

Leading and trailing whitespaces are not considered part of the section name.

section caption

What comes after : in the section line, till the end of the first line is called the caption of the section.

The caption is optional.

In our example, the first section’s caption is “the caption of the section”, and the second section does not have a caption.

Leading and trailing whitespaces are not considered part of the caption.

section headers

After the “section line” (the first line that starts with -- , zero or more section headers can be passed. In our example, the first section has two headers, header-1 and hello, with values some header value and world respectively.

An empty newline or the start of a new section marks the end of the headers.

Leading and trailing whitespaces of both header name and header value are ignored.

section body

After the first empty line that comes after the section header, till the start of next section is considered the body of the section.

The body is optional.

Leading and trailing newlines are not considered part of the body.

-- some-section:

optional body of "some-section"

this one has a body

-- some-section:

optional body of "some-section"

this one has a body

Programmatic Access

ftd::p1 module in ftd crate can be used to read ftd.p1 files. Wrappers of this crate in Python and other programming languages would hopefully come soon.

File Extension

Each user of ftd::p1 should come up with their own extension, but .p1 is an extension which can be used by convention in some cases.

Also consider using ftd itself, instead of this low-level library, this library should only be used as a fallback.