mirror of
https://github.com/alsa-project/alsa-lib.git
synced 2025-10-29 05:40:25 -04:00
220 lines
4 KiB
Text
220 lines
4 KiB
Text
/*! \page conf Configuration files
|
|
|
|
<P>Configuration files are using a simple format allowing the modern
|
|
data description like nesting and array assignments.</P>
|
|
|
|
\section conf_whitespace Whitespace
|
|
|
|
Whitespace is the collective name given to spaces (blanks), horizontal and
|
|
vertical tabs, newline characters, and comments. Whitespace can serve to
|
|
indicate where configuration tokens start and end, but beyond this function,
|
|
any surplus whitespace is discarded. For example, the two sequences
|
|
|
|
\code
|
|
a 1 b 2
|
|
\endcode
|
|
|
|
and
|
|
|
|
\code
|
|
a 1
|
|
b 2
|
|
\endcode
|
|
|
|
are lexically equivalent and parse identically to give the four tokens:
|
|
|
|
\code
|
|
a
|
|
1
|
|
b
|
|
2
|
|
\endcode
|
|
|
|
The ASCII characters representing whitespace can occur within literal
|
|
strings, int which case they are protected from the normal parsing process
|
|
(tey remain as part of the string). For example:
|
|
|
|
\code
|
|
name "John Smith"
|
|
\endcode
|
|
|
|
parses to two tokens, including the single literal-string token "John
|
|
Smith".
|
|
|
|
\section conf_linesplicing Line splicing with \
|
|
|
|
A special case occurs, if the final newline character encountered is
|
|
preceded by a backslash (\) in the string value definition. The backslash
|
|
and new line are both discarded, allowing two physical lines of text to be
|
|
treated as one unit.
|
|
|
|
\code
|
|
"John \
|
|
Smith"
|
|
\endcode
|
|
|
|
is parsed as "John Smith".
|
|
|
|
\section conf_comments Comments
|
|
|
|
A single-line comments are defined using character #. The comment can start
|
|
in any position, and extends until the next new line.
|
|
|
|
\code
|
|
a 1 # this is a comment
|
|
\endcode
|
|
|
|
\section conf_include Include another configuration file
|
|
|
|
A new configuration file can be included using <filename> syntax. The global
|
|
configuration directory can be referenced using <confdir:filename> syntax.
|
|
|
|
\code
|
|
</etc/alsa1.conf>
|
|
<confdir:pcm/surround.conf>
|
|
\endcode
|
|
|
|
\section conf_punctuators Punctuators
|
|
|
|
The configuration punctuators (also known as separators) are:
|
|
|
|
\code
|
|
{} [] , ; = . ' " new-line form-feed carriage-return whitespace
|
|
\endcode
|
|
|
|
\subsection conf_braces Braces
|
|
|
|
Open and close braces { } indicate the start and end of a compound
|
|
statement:
|
|
|
|
\code
|
|
a {
|
|
b 1
|
|
}
|
|
\endcode
|
|
|
|
\subsection conf_brackets Brackets
|
|
|
|
Open and close brackets indicate single array definition. The identificators
|
|
are automatically generated starting with zero.
|
|
|
|
\code
|
|
a [
|
|
"first"
|
|
"second"
|
|
]
|
|
\endcode
|
|
|
|
Above code is equal to
|
|
|
|
\code
|
|
a.0 "first"
|
|
a.1 "second"
|
|
\endcode
|
|
|
|
\subsection conf_comma_semicolon Comma and semicolon
|
|
|
|
The comma (,) or semicolon (;) can separate the value assignments. It is not
|
|
strictly required to use these separators, because any whitespace supplies
|
|
them.
|
|
|
|
\code
|
|
a 1;
|
|
b 1,
|
|
\endcode
|
|
|
|
\subsection conf_equal Equal sign
|
|
|
|
The equal sign (=) separates can separate variable declarations from
|
|
initialization lists:
|
|
|
|
\code
|
|
a=1
|
|
b=2
|
|
\endcode
|
|
|
|
Using the equal signs is not required, because any whitespace supplies
|
|
them.
|
|
|
|
\section conf_assigns Assigns
|
|
|
|
The configuration file defines id (key) and value pairs. The id (key) can be
|
|
composed from any ASCII digits or chars from a to z or A to Z, including
|
|
char _. The value can be either a string, integer or real number.
|
|
|
|
\subsection conf_single Single assign
|
|
|
|
\code
|
|
a 1 # is equal to
|
|
a=1 # is equal to
|
|
a=1; # is equal to
|
|
a 1,
|
|
\endcode
|
|
|
|
\subsection conf_compound Compound assign (definition using braces)
|
|
|
|
\code
|
|
a {
|
|
b = 1
|
|
}
|
|
a={
|
|
b 1,
|
|
}
|
|
\endcode
|
|
|
|
\section conf_compound1 Compound assign (one key definition)
|
|
|
|
\code
|
|
a.b 1
|
|
a.b=1
|
|
\endcode
|
|
|
|
\subsection conf_array Array assign (definition using brackets)
|
|
|
|
\code
|
|
a [
|
|
"first"
|
|
"second"
|
|
]
|
|
\endcode
|
|
|
|
\subsection conf_array1 Array assign (one key definition)
|
|
|
|
\code
|
|
a.0 "first"
|
|
a.1 "second"
|
|
\endcode
|
|
|
|
\section conf_summary Summary
|
|
|
|
\code
|
|
# Configuration file syntax
|
|
|
|
# Include a new configuration file
|
|
<filename>
|
|
|
|
# Simple assign
|
|
name [=] value [,|;]
|
|
|
|
# Compound assign (first style)
|
|
name [=] {
|
|
name1 [=] value [,|;]
|
|
...
|
|
}
|
|
|
|
# Compound assign (second style)
|
|
name.name1 [=] value [,|;]
|
|
|
|
# Array assign (first style)
|
|
name [
|
|
value0 [,|;]
|
|
value1 [,|;]
|
|
...
|
|
]
|
|
|
|
# Array assign (second style)
|
|
name.0 [=] value0 [,|;]
|
|
name.1 [=] value1 [,|;]
|
|
\endcode
|
|
|
|
*/
|