From 0682e115c350ad01ed0523f323e726d401cce04e Mon Sep 17 00:00:00 2001
From: stuebinm <stuebinm@disroot.org>
Date: Sat, 20 Nov 2021 02:58:25 +0100
Subject: [PATCH] documentation for URI rewrite rules
---
Readme.md | 43 ++++++++++++++++++++++++++++++++++---------
1 file changed, 34 insertions(+), 9 deletions(-)
diff --git a/Readme.md b/Readme.md
index c1cd707..7d66ea3 100644
--- a/Readme.md
+++ b/Readme.md
@@ -39,19 +39,44 @@ walint --config-file config.json --repository path \
optional. Keys given here will override whatever values are set in the
configuration file.
-### Configuation
+## Configuation
Take a look at `config.json` for an example. Most keys are required, and do not
-have default values.
+have default values. In `config.json`, all possible keys are given.
-For the schema, take a look at the definition of the `LintConfig` type in
-`lib/LintConfig.hs`; I'll attempt to remember documenting options there (if you
-are unfamiliar with Haskell: key names come first, though there are all prepended
-with `config` here. Types come after the `::`; ignore the `HKD f` bit and look
-at whatever comes after that. Most types should be self-explanatory; Note that
-you may leave out keys whose type includes `Maybe`)
+Most options should be reasonably self-explanatory. Note that `MaxLintLevel`
+differs from the option `--lintLevel`: the latter merely determines what is
+*printed* (in case json output is not enabled), the former determines the
+maximum lint level allowed before the linter rejects the map and does not
+copy it to the path given to `--out`.
+### Uri Schemas
-### Output
+`walint` supports (limited) rewriting of URIs contained in the map json via
+the `UriSchemas` option, which takes a map from uri schemas to a rule describing
+what to do with such links, depending on the scope in which they appear.
+
+`walint` takes a very reductive view or URIs: `schema://domain/tail`
+
+#### Rewrite Rules
+
+For now there are three types of such rules:
+ - `schema: {"scope":[scopes]}`: if in a scope listed in `scopes`, allow any
+ links of the given `schema`
+ - `schema: {"scope":[scopes], "allowed":[allowed], "blocked":[blocked], "prefix":prefix}`:
+ if in a scope listed in `scopes`, prefix any URIs of the given `schema` with
+ the given `prefix`, unless the URI's domain occurs in `allowed` (in which case
+ leave it untouched), or it occurs in `blocked`, in which
+ case it will be rejected as a lint error.
+ - `schema: {"scope":[scopes], "subst":{domain: prefix, ...}}`: if in a scope
+ listed in `scopes` and given a URI with the domain `domain`, concatenate
+ `prefix` with the tail of this URI. If there is no applicable `domain`,
+ reject the URI
+
+For now there are two (useful) scopes: `map` applies to tiled map links
+(i.e. `exitUrl`), and `website` applies to weblinks (i.e. `openWebsite`).
+
+
+## Output
By default `walint` prints lints in a hopefully human-readable manner. Its exit
code will be 1 if the maximum lint level set in its config was exceeded, and 0
otherwise. Only in the latter case will it write out an adjusted map respository
--
GitLab