From a5269a3b345ff1abc72e171951700005ccfd35f2 Mon Sep 17 00:00:00 2001
From: stuebinm <stuebinm@disroot.org>
Date: Sun, 14 Nov 2021 18:44:28 +0100
Subject: [PATCH] add readme
---
Readme.md | 107 ++++++++++++++++++++++++++++++++++++++++++++++++++++
src/Main.hs | 5 ++-
2 files changed, 111 insertions(+), 1 deletion(-)
create mode 100644 Readme.md
diff --git a/Readme.md b/Readme.md
new file mode 100644
index 0000000..1f4b17d
--- /dev/null
+++ b/Readme.md
@@ -0,0 +1,107 @@
+# walint: lint & adjust workadventure maps
+
+`walint` is intended as a simple linter that will check workadventure maps for
+common errors, such as non-existent map entrypoints or missing asset files, and
+additionally suggest changes to improve accessability.
+
+Optionally, it can also *adjust* maps — e.g. to automatically insert property
+values or help enforce an event's map policies — and then write them out again,
+copying all needed assets and minifying the map's json.
+
+## Usage
+``` sh
+walint --config-file config.json --repository path \
+ [--out path] [--json] [--pretty] [--entrypoint main.json]
+
+```
+
+### Options
+ - `--repository`: path to a map repository
+ - `--entrypoint`: entrypoint of a map repository, i.e. a tiled map in its root
+ directory. `walint` will lint all maps reachable from it. If not given, it
+ defaults to `main.json`
+ - `--lintLevel`: limit output only to messages that have at most the given
+ level. Valid levels are `Info`, `Suggestion`, `Warning`, `Error`, `Fatal`.
+ Defaults to `Suggestion` if not given.
+ - `--json`: print output as json instead of the normal more human-friendly format
+ - `--pretty`: if used with `--json`, insert line breaks and indentation to make
+ the output more readable. Otherwise no effect.
+ - `--out path`: write the linted & adjusted repository to the given path. Any
+ json written to this path will be minimised, and *only those maps and assets
+ which are reachable from the entrypoint* will be writen at all. If not given,
+ `walint` will only run the linter and do nothing else. If `walint` encounters
+ any references to local map assets which are not present in the repository, it
+ will fail.
+ - `--config-file file`: path to a configuation file. Required (for now).
+ - `--config json`: takes a string which should contain a json object conforming
+ to the same schema as the configuration file, except that all keys are
+ optional. Keys given here will override whatever values are set in the
+ configuration file.
+
+### Configuation
+Take a look at `config.json` for an example. Most keys are required, and do not
+have default values.
+
+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`)
+
+
+### Output
+By default `walint` prints lints in a hopefully human-readable manner. If the
+`--json` option is given, it will instead give a json that should conform to
+the following schema:
+
+```purescript
+-- | The main type of walint's output
+type Output =
+ { mapLints :: Map FilePath MapLint
+ -- ^ an object of per-map lints. Each key is a filepath from the repository's root
+ , missingAssets :: List Asset
+ -- ^ a list of missing assets
+ , missingDeps :: List Entrypoint
+ -- ^ a list of other missing dependencies (for now, just entrypoints)
+ }
+
+-- | An object containing map lints
+type MapLint =
+ { general :: List Lint
+ -- ^ general lints (most often empty)
+ , layer :: Map Message Where
+ -- ^ an object of per-layer lints. Each key is a lint message
+ , tileset :: Map Message Where
+ -- ^ an object of per-tileset lints. Again, each key is a lint message
+ }
+
+-- | Further desription of a single lint
+type Where =
+ { in :: List String
+ -- ^ where did this lint occur? (list of layers / tileset names)
+ , level :: Level
+ -- ^ what is this lint's level?
+ }
+
+-- | Valid lint levels. Encoded as strings.
+data Level = Info | Suggestion | Warning | Error | Fatal
+
+
+-- | description of a single (missing) asset
+type Asset =
+ { asset :: FilePath
+ -- ^ the filename, as referenced somewhere within the repository
+ , neededBy :: List FilePath
+ -- ^ list of filenames of maps which reference this asset
+ }
+
+-- | description of a single (missing) entrypoint
+type Entrypoint =
+ { entrypoint :: String
+ -- ^ the entrypoint, as a string, e.g. path/to/map#entrypoint
+ , neededBy :: List FilePath
+ -- ^ list of filenames of maps which reference this entrypoint
+ }
+
+```
diff --git a/src/Main.hs b/src/Main.hs
index 5b8b66f..be28f07 100644
--- a/src/Main.hs
+++ b/src/Main.hs
@@ -37,8 +37,11 @@ data Options = Options
, pretty :: Bool
-- ^ pretty-print the json to make it human-readable
, out :: Maybe String
- , config :: Maybe (LintConfig Maybe)
+ -- ^ path to write the (possibly adjusted) maps to after linting
, configFile :: Maybe FilePath
+ -- ^ path to a config file. Currently required.
+ , config :: Maybe (LintConfig Maybe)
+ -- ^ a "patch" for the configuration file
} deriving (Show, Generic, HasArguments)
--
GitLab