add SubmittingPatches document to docs/

[openwrt/openwrt.git] / docs / config.tex

diff --git a/docs/config.tex b/docs/config.tex
index 44b6689b538034b6482026b5d8acc95d29a40ca2..17417c99a1c2574aeac1d57397ffeade81f7c04a 100644 (file)
--- a/docs/config.tex
+++ b/docs/config.tex
@@ -9,25 +9,25 @@ it was written under.
 Syntax:
 
 \begin{Verbatim}
 Syntax:
 
 \begin{Verbatim}

-config    <type> [<name>]           # Section
-  option  <name>  <value>      # Option
+config      <type> ["<name>"]      # Section
+    option  <name> "<value>"       # Option

 \end{Verbatim}
 
 Every parameter needs to be a single string and is formatted exactly
 \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 
+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}
 
 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 
+To be able to load configuration files, you need to include the common

 functions with:
 
 \begin{Verbatim}
 . /etc/functions.sh
 \end{Verbatim}
 
 functions with:
 
 \begin{Verbatim}
 . /etc/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 
+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
 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


@@ -36,13 +36,13 @@ need to define the following shell functions before running \texttt{config\_load
 
 \begin{Verbatim}
 config_cb() {
 
 \begin{Verbatim}
 config_cb() {

-       local type="$1"
-       local name="$2"
-       # commands to be run for every section
+    local type="$1"
+    local name="$2"
+    # commands to be run for every section

 }
 
 option_cb() {
 }
 
 option_cb() {

-       # commands to be run for every option
+    # commands to be run for every option

 }
 \end{Verbatim}
 
 }
 \end{Verbatim}
 


@@ -57,18 +57,34 @@ after \texttt{config\_load} is done.
 That allows you to process sections both before and after all options were
 processed.
 
 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}
 You can access already processed options with the \texttt{config\_get} command
 Syntax:
 
 \begin{Verbatim}

-config_get <section> <option>            # prints the value of the option
-config_get <variable> <section> <option> # stores the value inside the variable
+# 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.
 
 \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 
+Additionally you can also modify or add options to sections by using the

 \texttt{config\_set} command.
 
 Syntax:
 \texttt{config\_set} command.
 
 Syntax:


@@ -77,3 +93,9 @@ Syntax:
 config_set <section> <option> <value>
 \end{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.
+