Writing lowstruct Files#

English · 한국어

This page teaches the format by example. The rules are defined in the specification.

Statements#

A statement is a path (one or more names), then its values (literals), then a full stop.

title "my-app" .
server port 8080 .
server debug false .

The path ends at the first literal, so no = is needed. The two server … statements build a server branch holding port and debug.

Names are ASCII letters, digits and _, starting with a letter or _, and are case-sensitive. Seven words are reserved: rem note text do end true false.

Blocks#

do … end writes a common prefix once. These two files build the same tree:

server do
  host "0.0.0.0" .
  tls do
    cert "a.pem" .
  end
end

server host "0.0.0.0" .
server tls cert "a.pem" .

A path opened as a block belongs to that block. You cannot open it again later, or add to it with a flat statement outside it (E-LOWS-SEALED) — everything about server is in one place. Blocks nest up to 64 deep.

Several things of the same sort get names of their own:

remote origin do
  url "https://example.invalid/r.git" .
end
remote backup do
  url "https://example.invalid/b.git" .
end

Lists#

Several values are a list. There are no brackets and no commas; a long list may span lines, and the full stop ends it.

ports 80 443 8443 .
allow
  "10.0.0.0/8"
  "192.168.0.0/16"
  .

All values of one statement are of one kind: 1 2.0 mixes an integer and a float and is rejected. A statement with no values (feature_x .) is an empty list — it records that the key is present.

A key is written once. Repeating a statement is an error (E-LOWS-DUP), not a way to build a list.

Comments#

rem a comment runs to the end of the line
port 8080 .   rem also after a statement

note END
A block comment.
Anything goes here until a line holding only END.
END

Numbers#

Integers run from −2⁶³ to 2⁶⁴−1. Floats are IEEE 754 doubles; there is no inf or nan. true and false are booleans.

Strings#

"…" is a string. It must close on its line. A backslash starts one of a closed set of escapes:

Any other backslash sequence is an error (E-LOWS-ESCAPE); a stray backslash never silently becomes something else.

Windows paths#

Write every backslash twice:

windir "C:\\Windows" .
share "\\\\server\\share" .

"C:\temp" is not an error — \t is the tab escape — but it is not the path you meant. Always double the backslash.

Multi-line and raw text#

A text heredoc keeps its body exactly as written, with no escapes. It ends at a line holding only its tag.

banner text END
Welcome.
  Indentation and \backslashes stay as they are.
END
.

The line break after the last body line is not part of the value. The heredoc is a value like any other, so the statement still ends with a full stop.

Byte strings and prefixes#

A plain "…" holds bytes: "\xE9" is one byte that is not valid UTF-8. The libraries give you the bytes and a helper that decodes UTF-8 text. Two prefixes change what a string holds:

Character literals such as 'a', u'é' and U'😀' hold exactly one element of the same kind.

Errors you will meet#

Every rejection names a line, a column (counted in characters) and a code.

The complete list, with where each one points, is in the specification, section 5.