%%% This file is part of the Open HörTech Master Hearing Aid (openMHA)
%%% Copyright © 2005 2006 2007 2008 2009 2011 2013 2017 2018 2019 HörTech gGmbH
%%%
%%% openMHA is free software: you can redistribute it and/or modify
%%% it under the terms of the GNU Affero General Public License as published by
%%% the Free Software Foundation, version 3 of the License.
%%%
%%% openMHA is distributed in the hope that it will be useful,
%%% but WITHOUT ANY WARRANTY; without even the implied warranty of
%%% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
%%% GNU Affero General Public License, version 3 for more details.
%%%
%%% You should have received a copy of the GNU Affero General Public License, 
%%% version 3 along with openMHA.  If not, see <http://www.gnu.org/licenses/>.


\section{The \mha{} configuration language}
\label{sec:script}\index{script language}\index{\mha{} script language}\index{language}\index{configuration}\index{hierarchical configuration}\index{configuration!hierarchical}\index{configuration language}\index{\mha{} configuration language}

The \mhad{} and most of the \mha{} plugins are controlled
through the \mha{} configuration language. This language is implemented in the
openMHA library. It allows hierarchical configuration. 
Each configuration level (parser)\index{parser}
can contain items like variables or sub-parsers. Properties of any item can be
queried.  Write access to items can be connected with C++ callback functions
which makes it possible to change the configuration and state of the \mha{} 
and all plugins while the audio signal is being processed.

The \mha{} configuration language consists of line-based human-readable
text commands.
The \mha{} configuration language interpreter receives commands by
reading text files or through a TCP network stream.  
The \mha{} also provides access to the configuration language parser via
a C++ object, 
which also uses the text interface\index{text interface},
for embedding the \mha{} into other applications (e.g. \Octave or \Matlab{} access).

\subsection{Structure of the \mha{} configuration language}

An \mha{} configuration language command has a simple structure: Each
command consists of a left value, an operator\index{operator} and a
right value. Three operators are defined:

\index{access operator}\index{operator!access-}%
\index{query operator}\index{operator!query-}%
\index{descending operator}\index{operator!descending-}%
\begin{itemize}
\item An {\bf access operator "="} is used to set a value of a variable.
\item A {\bf query operator "?"}
  is used to query a value, type or other information of a variable or other
  nodes (with some exceptions).
\item A {\bf descending operator "."} descends into the next level of the
  hierarchical \mha{} configuration.
\end{itemize}

Each left value is the name of a parser entry. Not all operators are
available for all parser entries: A subparser supports only "?" and
".", a monitor only "?". In the configuration files, \mha{} script
language commands can be split up into multiple lines: If a lines ends with "\verb!...!", the next line will be
appended. This does not hold for the command prompt (e.g. TCP interface).

The \mha{} configuration language features strong static typing, the data type
of a variable is defined by the plugin that implements this variable.
Many configuration language commands like write access ("=") to variables can
be connected to C++ callbacks by the plugin developer.

\subsubsection{Query commands}

\index{query command}\index{command!query}%
The query operator without any right value shows the contents of a parser item
in a human readable way. By passing a right value to the query operator, the
type of query can be influenced. A query operator together with its right
value forms a {\em query command}. Valid query commands
are:
\index{\verb.?.}%
\index{\verb.?cmds.}%
\index{\verb.?val.}%
\index{\verb.?type.}%
\index{\verb.?perm.}%
\index{\verb.?range.}%
\index{\verb.?subst.}%
\index{\verb.?entries.}%

\begin{itemize}
\item {\bf ?}: Show contents of a parser element.
\item {\bf ?cmds}: Show a list of all query commands for this element.
\item {\bf ?help}: Show the detailed description of an element.
\item {\bf ?val}: Return the value of an element.
\item {\bf ?type}: Return the data type of an element.
\item {\bf ?perm}: Return the access rights for an element.
\item {\bf ?range}: Return the range of valid values for this variable.
\item {\bf ?subst}: Show all variable substitutions applied to this node.
\item {\bf ?entries}: Show a list of all entries in this node.
\end{itemize}

Special query commands are:
\index{\verb.?save.}%
\index{\verb.?saveshort.}%
\index{\verb.?savemons.}%
\index{\verb.?read.}%

\begin{itemize}
\item {\bf ?save:<filename>}: Save the contents of this node into the
text file "filename", complete with element description comments.
\item {\bf ?saveshort:<filename>}: Save the contents of this node into the
text file "filename", without additional comments or blank lines.
\item {\bf ?savemons:<filename>}: Save the contents of all monitor variables to
  the file 'filename'.
\item {\bf ?read:<filename>}: Read the file "filename" into the current
parser node.
\end{itemize}

\subsubsection{Multidimensional variables}%
\index{multidimensional variable}%
\index{variable!multidimensional}%

The \mha{} configuration language supports vectors and matrices in a way similar
to the \Octave{} / \Matlab{} notation: Vectors are put into squared brackets, with
the items separated by whitespace. Matrices are
noted as vectors of vectors, with each vector separated by a semicolon
from the other vectors:

\begin{verbatim}
vector = [1.0 2.7 4]
matrix = [[1 2 3];[4 5 6]]
\end{verbatim}

Vectors with real values support also the special notation
\verb!min:increment:max!. A mixture of explicit and incremental
notation is allowed. The vector is internally expanded and will return
the explicit notation on read:

\begin{verbatim}
vector = [1.0 1.7 2.1:1.1:5]
\end{verbatim}

This will be expanded as:

\begin{verbatim}
vector = [1.0 1.7 2.1 3.2 4.3]
\end{verbatim}

\subsubsection{Complex variables}%
\index{complex variable}%
\index{variable!complex}%

Variables with complex values are notated in parenthesis as a sum of
real and imaginary part. Pure real values can be noted without
parenthesis:

\begin{verbatim}
complex = (1.3 + 2.7i)
vcomplex = [(1.3 + 2.7i) (2.0 - 1.1i) 6.3]
\end{verbatim}

\subsubsection{Text variables}\index{text variable}\index{variable!text}

Strings in the \mha{} configuration language can contain any characters. Special
characters do not have to be quoted; quote characters are treated
literally. Leading and trailing whitespace of strings is automatically
removed. Vector elements in string vectors are separated by a single
space character. This means that vector elements cannot contain spaces.

\begin{verbatim}
string =  This is a valid text string.
samestr=This is a valid text string.
strvec = [pears bananas green_apples]
\end{verbatim}

\subsubsection{Variable ranges}\index{variable range}\index{range}

Numeric variables can have a restricted range, the value of keyword list 
variables is always restricted to one of the keywords. New values are checked 
against this range when the variable is changed through the \mha{} configuration 
language interface. For numeric variables, the range can be 
$[x_{min},x_{max}]$ (boundaries included), $]x_{min},x_{max}[$
(boundaries excluded) or a mixed version of both. If $x_{min}$ or
$x_{max}$ are omitted then the variable will not have a lower or
upper boundary.

For keyword list variables, the range is simply a space separated list of valid
entries.

\subsubsection{Physical units}\index{physical units}

Numeric variables that describe physical facts like a distance or a
time duration need to be given in some physical unit. The default
physical units in \mha are the SI units, e.g. seconds for a time
value, meters for a length, kilogramms for a mass, Newton for a force,
Pascal for a pressure, square meters for an area, meters per second
for a velocity, Hertz for a frequency. Sometimes, configuration
variables differ from this convention, in this case, the description
of the variable will contain the unit to use.

When assigning or reading a configuration variable, only the numerical
value is given, the physical unit's name is never appended to the number.

\subsubsection{Variable Substitution and Environment
  Variables}\index{substitution}\index{environment variable}\index{variable!environment}

Each node in the \mha{} configuration tree can define a set of text
substitutions.  The pattern to be replaced has the form "\$[VARNAME]",
where VARNAME can be any text. Any occurrence of this pattern is
replaced. The set of substitutions can be queried with the "?subst"
query command. Replacements can be activated with the "?addsubst"
query command in the style
\verb!?addsubst:<VARNAME> <REPLACEMENT>!. Each parser node has its own
set of text substitutions, which is not inherited by children parser
nodes.

Environment variables can be used in the \mha{} configuration language in the form
"\$\{VARNAME\}", where VARNAME is the name of an environment variable. Each
occurrence of \$\{VARNAME\} is replaced by its contents before interpreting the
\mha{} configuration language, i.e.\ the left hand side or even operators can be part of
the substitution.

\subsection{Communication between \mha{} Plugins}\index{AC variable}\index{variable!AC}\index{communication}

Signal processing plugins in \mha{} often process the audio signal in a signal
processing chain, as provided by the \mha{} chain plugin 'mhachain'.
%
These plugins already communicate with each other such that the output
signal of one plugin is processed as the input signal to the next plugin in
the chain, while the audio signal can be either time-domain waveform data or
spectral-domain short-time fourier transform data.

Some algorithms can be implemented as a combination of several plugins but then
require more data to be shared between plugins than just the current audio
signal.
%
\mha{} supports this by providing a mechanism to share
any type of additional data between plugins in the form of algorithm
communication variables (AC vars or AC variables).

Some plugins provided with the \mha{} create AC variables, while
other plugins can be configured to make use of AC variables created by
other plugins. For example
\begin{itemize}
\item 
  the 'rmslevel' plugin publishes the measured sound levels as AC vars,
\item
  the 'noise\_psd\_estimator' plugin estimates the noise power spectral density
  and publishes it as an AC variable,
\item
  the 'smooth\_cepstrum' plugin uses the noise power spectral density from an
  AC var provided by another plugin to reduce noise in the signal.
\item
  the 'acmon' and 'acsave' plugins can be used to export AC variables from the
  \mha{} by mirroring them in parser monitors or by saving them to
  a file on disk.
\end{itemize}

AC variables are identified by a name.
%
The naming convention for AC variables is: \\
\textit{creator}\_\textit{varname} \\
where \textit{creator} is the configured name\footnote{
  Refer to the detailed description of plugin mhachain in the plugin manual for
  the description of "configured name".
}  of the plugin that creates this AC
variable, and \textit{varname} describes the content or purpose of the variable.
Plugins that create only a single AC variable may also name that variable like
their configured name only.

The above rules are conventions for plugin developers and not enforced by the
\mha{} therefore you may find plugins that do not adhere to this convention.

The command line tool \texttt{analysemhaplugin} can be used to find names of
AC variables created by a plugin.

%%% Local Variables: 
%%% mode: latex
%%% TeX-master: "openMHA_application_manual"
%%% indent-tabs-mode: nil
%%% coding: utf-8-unix
%%% End: 
