From 716ca530e1c4515d8683c9d5be3d56b301758b66 Mon Sep 17 00:00:00 2001
From: James <>
Date: Wed, 4 Nov 2015 11:49:21 +0000
Subject: trunk-47381

---
 docs/config.tex | 101 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 101 insertions(+)
 create mode 100644 docs/config.tex

(limited to 'docs/config.tex')

diff --git a/docs/config.tex b/docs/config.tex
new file mode 100644
index 0000000..08318b4
--- /dev/null
+++ b/docs/config.tex
@@ -0,0 +1,101 @@
+\subsubsection{Structure of the configuration files}
+
+The config files are divided into sections and options/values.
+
+Every section has a type, but does not necessarily have a name.
+Every option has a name and a value and is assigned to the section
+it was written under.
+
+Syntax:
+
+\begin{Verbatim}
+config      <type> ["<name>"]      # Section
+    option  <name> "<value>"       # Option
+\end{Verbatim}
+
+Every parameter needs to be a single string and is formatted exactly
+like a parameter for a shell function. The same rules for Quoting and
+special characters also apply, as it is parsed by the shell.
+
+\subsubsection{Parsing configuration files in custom scripts}
+
+To be able to load configuration files, you need to include the common
+functions with:
+
+\begin{Verbatim}
+. /lib/functions.sh
+\end{Verbatim}
+
+Then you can use \texttt{config\_load \textit{<name>}} to load config files. The function
+first checks for \textit{<name>} as absolute filename and falls back to loading
+it from \texttt{/etc/config} (which is the most common way of using it).
+
+If you want to use special callbacks for sections and/or options, you
+need to define the following shell functions before running \texttt{config\_load}
+(after including \texttt{/lib/functions.sh}):
+
+\begin{Verbatim}
+config_cb() {
+    local type="$1"
+    local name="$2"
+    # commands to be run for every section
+}
+
+option_cb() {
+    # commands to be run for every option
+}
+\end{Verbatim}
+
+You can also alter \texttt{option\_cb} from \texttt{config\_cb} based on the section type.
+This allows you to process every single config section based on its type
+individually.
+
+\texttt{config\_cb} is run every time a new section starts (before options are being
+processed). You can access the last section through the \texttt{CONFIG\_SECTION}
+variable. Also an extra call to \texttt{config\_cb} (without a new section) is generated
+after \texttt{config\_load} is done.
+That allows you to process sections both before and after all options were
+processed.
+
+Another way of iterating on config sections is using the \texttt{config\_foreach} command.
+
+Syntax:
+\begin{Verbatim}
+config_foreach <function name> [<sectiontype>] [<arguments...>]
+\end{Verbatim}
+
+This command will run the supplied function for every single config section in the currently
+loaded config. The section name will be passed to the function as argument 1.
+If the section type is added to the command line, the function will only be called for
+sections of the given type.
+
+
+You can access already processed options with the \texttt{config\_get} command
+Syntax:
+
+\begin{Verbatim}
+# print the value of the option
+config_get <section> <option>
+
+# store the value inside the variable
+config_get <variable> <section> <option>
+\end{Verbatim}
+
+In busybox ash the three-option \texttt{config\_get} is faster, because it does not
+result in an extra fork, so it is the preferred way.
+
+Additionally you can also modify or add options to sections by using the
+\texttt{config\_set} command.
+
+Syntax:
+
+\begin{Verbatim}
+config_set <section> <option> <value>
+\end{Verbatim}
+
+If a config section is unnamed, an automatically generated name will
+be assigned internally, e.g. \texttt{cfg1}, \texttt{cfg2}, ...
+
+While it is possible, using unnamed sections through these autogenerated names is
+strongly discouraged. Use callbacks or \texttt{config\_foreach} instead.
+
-- 
cgit v1.2.3