From: Sergey Matveev <stargrave@stargrave.org>
Date: Mon, 6 Oct 2025 07:18:19 +0000 (+0300)
Subject: Documentation
X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;ds=sidebyside;p=dsc.git

Documentation
---

diff --git a/README b/README
new file mode 100644
index 0000000..d53fe7b
--- /dev/null
+++ b/README
@@ -0,0 +1,49 @@
+dsc -- damn small configuration utility.
+dsc is very similar to OpenWRT's Unified Configuration Interface.
+It keeps configuration values in a hierarchical directory layout.
+It has an explicit schema defining what values can be set and how
+they must be sanitised.
+
+There are three environmental variables used:
+* DSC_SCHEMA -- path to the directory with the schema
+* DSC_SAVED -- path to the directory with saved (committed) configuration
+* DSC_STASH -- path to the directory with stash (current) uncommitted one
+
+Option's value foo/bar is located in the saved/stash directory in the
+"foo" subdirectory, "bar" file.
+
+    $ dsc set foo/bar "my value"
+    $ dsc get foo/bar
+    my value
+    $ dsc get ""
+    $ dsc get foo/bar
+
+There are two kind of options: scalar ones, and a dynamic list ones.
+
+    $ dsc add net/iface-name0
+    $ dsc add net/iface-name1
+    $ dsc get net/*
+    iface-name0
+    iface-name1
+    $ dsc del net/iface-name0
+    $ dsc get net/*
+    iface-name1
+    $ dsc set net/iface-name1/mtu 1300
+
+Schema is a directory with the same hierarchy, but each option is a
+directory, that contains:
+
+* "title" file -- with the brief single line description
+* optional "descr" file -- with descriptive information
+* executable "check" file, that is run when option either is set, or get
+  with an empty value. It takes a single argument -- option name. Value
+  is read from stdin. If value is not valid, then checker must return
+  bad return code, writing the descriptive message to stderr. Otherwise
+  the sanitised value is read from stdout. If an input is empty, then
+  checker may print default value of the option
+
+Option having "*" name is treated like a dynamic list.
+
+By default all options you set are saved in the stash. "commit" command
+will move it to the saved directory. "diff" allows you to see the
+difference between the stash and saved directories.