docs/config.tex

   1 \subsubsection{Structure of the configuration files}
   2
   3 The config files are divided into sections and options/values.
   4
   5 Every section has a type, but does not necessarily have a name.
   6 Every option has a name and a value and is assigned to the section
   7 it was written under.
   8
   9 Syntax:
  10
  11 \begin{Verbatim}
  12 config      <type> ["<name>"]      # Section
  13     option  <name> "<value>"       # Option
  14 \end{Verbatim}
  15
  16 Every parameter needs to be a single string and is formatted exactly
  17 like a parameter for a shell function. The same rules for Quoting and
  18 special characters also apply, as it is parsed by the shell.
  19
  20 \subsubsection{Parsing configuration files in custom scripts}
  21
  22 To be able to load configuration files, you need to include the common
  23 functions with:
  24
  25 \begin{Verbatim}
  26 . /etc/functions.sh
  27 \end{Verbatim}
  28
  29 Then you can use \texttt{config\_load \textit{<name>}} to load config files. The function
  30 first checks for \textit{<name>} as absolute filename and falls back to loading
  31 it from \texttt{/etc/config} (which is the most common way of using it).
  32
  33 If you want to use special callbacks for sections and/or options, you
  34 need to define the following shell functions before running \texttt{config\_load}
  35 (after including \texttt{/etc/functions.sh}):
  36
  37 \begin{Verbatim}
  38 config_cb() {
  39     local type="$1"
  40     local name="$2"
  41     # commands to be run for every section
  42 }
  43
  44 option_cb() {
  45     # commands to be run for every option
  46 }
  47 \end{Verbatim}
  48
  49 You can also alter \texttt{option\_cb} from \texttt{config\_cb} based on the section type.
  50 This allows you to process every single config section based on its type
  51 individually.
  52
  53 \texttt{config\_cb} is run every time a new section starts (before options are being
  54 processed). You can access the last section through the \texttt{CONFIG\_SECTION}
  55 variable. Also an extra call to \texttt{config\_cb} (without a new section) is generated
  56 after \texttt{config\_load} is done.
  57 That allows you to process sections both before and after all options were
  58 processed.
  59
  60 Another way of iterating on config sections is using the \texttt{config\_foreach} command.
  61
  62 Syntax:
  63 \begin{Verbatim}
  64 config_foreach <function name> [<sectiontype>] [<arguments...>]
  65 \end{Verbatim}
  66
  67 This command will run the supplied function for every single config section in the currently
  68 loaded config. The section name will be passed to the function as argument 1.
  69 If the section type is added to the command line, the function will only be called for
  70 sections of the given type.
  71
  72
  73 You can access already processed options with the \texttt{config\_get} command
  74 Syntax:
  75
  76 \begin{Verbatim}
  77 # print the value of the option
  78 config_get <section> <option>
  79
  80 # store the value inside the variable
  81 config_get <variable> <section> <option>
  82 \end{Verbatim}
  83
  84 In busybox ash the three-option \texttt{config\_get} is faster, because it does not
  85 result in an extra fork, so it is the preferred way.
  86
  87 Additionally you can also modify or add options to sections by using the
  88 \texttt{config\_set} command.
  89
  90 Syntax:
  91
  92 \begin{Verbatim}
  93 config_set <section> <option> <value>
  94 \end{Verbatim}
  95
  96 If a config section is unnamed, an automatically generated name will
  97 be assigned internally, e.g. \texttt{cfg1}, \texttt{cfg2}, ...
  98
  99 While it is possible, using unnamed sections through these autogenerated names is
 100 strongly discouraged. Use callbacks or \texttt{config\_foreach} instead.
 101