net.httpd.conf
The reader of the web server config: blocks, settings and values in Salam block syntax, with positions for errors.
import net.httpd.conf
This package reads text written in the block style that net.httpd uses for its config, and gives back a tree. It knows nothing about web servers: it only recognises the shapes, and net.httpd decides which names are valid. You can use it for settings files of your own that look like Salam.
There are two shapes. A setting is a name, an equals sign and one or more values on the same line: max connections = 100. A block is a name, optional strings, a colon, its contents and end: location "/api/": cache = 1h end. A name may be several words (error page), values are strings in double quotes (with \n, \t, \" and \\), strings in backticks (taken as written, so a regular expression needs no doubling of backslashes), numbers with an optional unit such as 64mb or 30d, and plain words such as tls. Comments are // to the end of the line, or /* ... */.
Everything lives in a Doc, a list of nodes that point at each other by number: node 0 is the root, Find and ChildAt move down, and the fields of a node hold its words, labels, values and children. Free the document with Free when you are done with it.
The things people get wrong:
- A value list ends at the end of the line, at
end, or where the next setting starts on the same line, soa = 1 b = 2is two settings. A bare word at the end of a list is read as a value, which is whylisten = 443 tlsworks. - A parse stops at the first error, and
okis then false. The error has the line and the column, andErrorTextputs them in front of the message the way compilers do. - Addresses and anything with a colon in it need quotes:
listen = "127.0.0.1:8080". Without them the colon would read as the start of a block. - A node's
wordshold its name, soNamejoins them with single spaces. Block labels, such as the path of a location, are inlabels, not in the name.
Parse a config and read a value
Parse returns a Doc. Check ok first, then walk down from the root: Find returns the number of the first child with a given name, and ValueText reads one value of a setting by position. A node number of -1 means the child was not found.
import net.httpd.conf
func main:
text := `
server:
max connections = 100
site:
listen = 8080
names = "a.test"
end
end
`
mut d := conf.Parse(text)
defer conf.Free(d)
if not d.ok:
println conf.ErrorText(d, "app.salam")
ret 1
end
server := conf.Find(d, conf.Root(), "server")
println conf.Name(d, server), conf.Count(d, server)
limit := conf.Find(d, server, "max connections")
println conf.ValueText(d, limit, 0)
site := conf.Find(d, server, "site")
println conf.ValueText(d, conf.Find(d, site, "names"), 0)
endThe setting name max connections has two words and is found by that full name with a single space. Always free the document, here with defer, because the nodes are heap memory.
Walk the children and tell the kinds apart
To go through everything in a block, use Count and ChildAt, then look at the node itself in d.nodes. A block has block set and its strings in labels; a setting has its values, and each value has a kind that is VAL_WORD, VAL_STR or VAL_NUM, plus the line and column where it was written.
import net.httpd.conf
func main:
text := `
server:
site:
listen = 80 tls
names = "a.test"
location "/api/": cache = 1h end
end
end
`
mut d := conf.Parse(text)
defer conf.Free(d)
site := conf.Find(d, conf.Find(d, conf.Root(), "server"), "site")
repeat conf.Count(d, site) in i:
n := d.nodes.Get(conf.ChildAt(d, site, i))
if n.block:
println "block", conf.Name(d, conf.ChildAt(d, site, i)), n.labels.Get(0), n.line
else:
v := n.values.Get(0)
println "setting", conf.Name(d, conf.ChildAt(d, site, i)), v.text, v.kind == conf.VAL_NUM
end
end
end80 is a number, and tls, which follows it on the same line, is a second value of the same setting. The numbers keep their unit as text, so 30d is one VAL_NUM value whose text is 30d; turning it into seconds is up to the program that owns the config.
Report errors with their position
The parser stops at the first error and sets ok to false. ErrorText turns it into file:line:column: message, with the file name you pass in, so a user can jump straight to the spot.
import net.httpd.conf
func check(text: str):
mut d := conf.Parse(text)
defer conf.Free(d)
if d.ok:
println "ok"
else:
println conf.ErrorText(d, "app.salam")
end
end
func main:
check("listen = 80\n")
check("server:\n site:\n")
check("names = \"open\n")
check("listen 80\n")
endThe first text is fine: this package only reads the shapes, so listen = 80 at the top level is not an error here. Whether a setting makes sense in that place is for the program that reads the tree, as net.httpd does for its own names.
Types
Value
struct Value| Name | Type | Description |
|---|---|---|
kind | int = 0 | VAL_WORD, VAL_STR or VAL_NUM. |
text | str = "" | The value as text; strings without their quotes and with escapes resolved. |
line | int = 0 | The line, counting from 1. |
col | int = 0 | The column, counting from 1. |
import net.httpd.conf
func main:
text := `
server:
site:
listen = 80 tls
names = "a.test www.a.test"
location "/api/": cache = 1h end
end
end
`
mut d := conf.Parse(text)
println d.ok, d.nodes.Len(), conf.Count(d, conf.Root())
server := conf.Find(d, conf.Root(), "server")
site := conf.Find(d, server, "site")
println conf.Name(d, site), conf.Count(d, site), d.nodes.Get(site).block
listen := conf.Find(d, site, "listen")
v := d.nodes.Get(listen).values.Get(0)
println v.text, v.kind == conf.VAL_NUM, v.line, v.col
w := d.nodes.Get(listen).values.Get(1)
println w.text, w.kind == conf.VAL_WORD, conf.ValueText(d, conf.Find(d, site, "names"), 0)
names := d.nodes.Get(conf.Find(d, site, "names")).values.Get(0)
println names.kind == conf.VAL_STR
loc := conf.ChildAt(d, site, 2)
n := d.nodes.Get(loc)
println conf.Name(d, loc), n.labels.Get(0), n.block, n.words.Len(), n.children.Len(), n.line, n.col
conf.Free(d)
endNode
struct Node| Name | Type | Description |
|---|---|---|
block | bool = false | True for a block, false for a setting. |
words | Vector | The words of the name, such as error and page. |
labels | Vector | The strings written between the name and the colon of a block. |
values | Vector | The values of a setting. |
children | Vector | The numbers of the nodes inside a block. |
line | int = 0 | The line where it starts. |
col | int = 0 | The column where it starts. |
The example for this item is shown with the ones above: net-httpd-conf-Parse.salam
Doc
struct Doc| Name | Type | Description |
|---|---|---|
nodes | Vector | Every node; node 0 is the root. |
ok | bool = true | True when the text parsed without an error. |
error | str = "" | The message of the first error, empty when there is none. |
line | int = 0 | The line of the error. |
col | int = 0 | The column of the error. |
The example for this item is shown with the ones above: net-httpd-conf-Parse.salam
Constants and variables
VAL_WORD
const VAL_WORD: i32 = 0tls or auto.The example for this item is shown with the ones above: net-httpd-conf-Parse.salam
VAL_STR
const VAL_STR: i32 = 1The example for this item is shown with the ones above: net-httpd-conf-Parse.salam
VAL_NUM
const VAL_NUM: i32 = 28080 or 30d; the text keeps the unit.The example for this item is shown with the ones above: net-httpd-conf-Parse.salam
Functions
Parse
func Parse(text: str): Docok before using it.The example for this item is shown with the ones above: net-httpd-conf-Parse.salam
Free
func Free(d &: Doc)The example for this item is shown with the ones above: net-httpd-conf-Parse.salam
ErrorText
func ErrorText(d: Doc, file: str): strfile:line:column: message, or an empty string when the document is valid. The first argument is the name to show for the file.import net.httpd.conf
func show(text: str):
mut d := conf.Parse(text)
println d.ok, conf.ErrorText(d, "web.salam"), d.error, d.line, d.col
conf.Free(d)
end
func main:
show("server:\n site:\n")
show("server:\nend\nend\n")
show("listen = \n")
show("names = \"open\n")
show("listen 80\n")
show("a = 1 # no\n")
show("ok = 1\n")
endName
func Name(d: Doc, node: int): strThe example for this item is shown with the ones above: net-httpd-conf-Parse.salam
Root
func Root(): intThe example for this item is shown with the ones above: net-httpd-conf-Parse.salam
Count
func Count(d: Doc, node: int): intThe example for this item is shown with the ones above: net-httpd-conf-Parse.salam
ChildAt
func ChildAt(d: Doc, node: int, i: int): intThe example for this item is shown with the ones above: net-httpd-conf-Parse.salam
Find
func Find(d: Doc, node: int, name: str): intThe example for this item is shown with the ones above: net-httpd-conf-Parse.salam
ValueText
func ValueText(d: Doc, node: int, i: int): strThe example for this item is shown with the ones above: net-httpd-conf-Parse.salam