readparams.3

speech signal process tools

.\" Copyright (c) 1986-1990 Entropic Speech, Inc.
.\" Copyright (c) 1991 Entropic Research Laboratory, Inc.; All rights reserved
.\" @(#)readparams.3	1.11 02 May 1997 ESI/ERL
.ds ]W (c) 1991 Entropic Research Laboratory, Inc.
.TH READ_PARAMS 3\-ESPSu 02 May 1997
.SH "NAME"
read_params - read parameters from either an ESPS Parameter or Common file
.SH "SYNOPSIS"
.B #include <esps/param.h>
.br
extern int debug_level;
.br
.B int
.br
.B read_params (param_file, flag, check_file)
.br
.B char	*param_file;
.br
.B int flag;
.br
.B char *check_file;
.SH "DESCRIPTION"
.PP
.I read_params
reads an ESPS Parameter file \fIparam_file\fP, processes ESPS Common,
and produces a symbol table.  ESPS Parameter files are written in a
C-like language; they are processed by \fIlex\fP (see below and [1]
for more information).
.PP
After the symbol table has been created (by \fIread_params\fP), symbol
values can be obtained by calls to \fIgetsym\fP(3\-\s-1ESPS\s+1).
Other information about the parameters can be obtained from
\fIsymtype\fP(3\-\s-1ESPS\s+1), \fIsymsize\fP(3\-\s-1ESPS\s+1),
\fIsymlist\fP(3\-\s-1ESPS\s+1), 
.br
\fIsymdefinite\fP(3\-\s-1ESPS\s+1),
\fIsymchoices\fP(3\-\s-1ESPS\s+1), \fIsymrange\fP(3\-\s-1ESPS\s+1),
and \fIsymprompt\fP(3\-\s-1ESPS\s+1).
.PP
If the value of \fIflag\fR is \s-2\fBSC_NOCOMMON\fR\s+2 then only
\fIparam_file\fR is processed.
.PP
If \fIparam_file\fR is null, then \fIread_params\fP uses the ESPS
default parameter file name "params".  If \fIparam_file\fP is
non-NULL, and if \fIread_params\fP is unable to find a corresponding,
readable parameter file, a warning is printed.  By default,
\fIread_params\fP uses \fIfind_esps_file\fP (3\-\s-1ESPS\s+1) to
search for \fIparam_file\fP along the path ".:$ESPS_BASE/lib/params".
This default search path can be overridden by setting the \fIunix\fP
environment variable ESPS_PARAMS_PATH.
.PP
If \fIflag\fR is \s-2\fBSC_CHECK_FILE\fR\s+2, if an ESPS Common file
exists, and if Common processing is enabled (see ESPS COMMON, below),
then the Common file is processed if \fIcheck_file\fR matches the
value of the \fIfilename\fR entry in the Common file or if
\fIcheck_file\fR is NULL.  If a Common file is processed,
\fIread_params\fP compares the last modification time of the ESPS
Common and \fIparam_file\fR.  The parameter values in the younger of
the two files takes precedence.  Parameter values not occurring in the
ESPS Common file are read from the ESPS Parameter file.  Note that, in
the case of indefinite assignment ("?=" or "=?" used as the assignment
operator in the parameter file), Common processing will still occur
for the assigned default value.  If the value from Common takes 
precedence, it will be this value that is shown as the default 
when a runtime prompt is generated by a call to 
.br
\fIgetsym\fP (3\-\s-1ESPS\s+1).  
.PP
The \fIunix\fP environment variable ESPS_VERBOSE is used to control
the extent of parameter processing feedback messages issued by
\fIread_params\fP. There are three significant settings: 0, 1, and 2.
If it is equal to 0, no feedback is provided.  If ESPS_VERBOSE is 1,
programs report the value of any parameters taken from ESPS common.
If it is 2 or greater, programs report the values of parameters taken
from ESPS common, the name of the actual parameter file used (if any),
and the values of parameters taken from the parameter file.  If
ESPS_VERBOSE is not set, a value of 2 is assumed.  Note that parameter
file selection is affected by ESPS_PARAMS_PATH (as described above).
.PP
Regardless of ESPS_VERBOSE, if \fIdebug_level\fP is non-zero,
\fIread_params\fP will warn if a parameter file cannot be found
(including the default "params"), will report the name of any
parameter file found, and will report if ESPS Common is processed,
.SH PARAMETER FILE FORMAT
.PP
Parameter files and common files are written in a C-like language.
Parameters may have six types: integer, real (stored as double
precision values), string, character, array of integer, and array of
real.
.PP
For each parameter, the parameter file contains the following: 
.IP
parameter type
.IP
parameter name
.IP
definite assigned value (operator "=") or indefinite assigned value
(operator "?=")
.IP
(optional) prompt string
.IP
(optional) parameter limitations (discrete choices or range of values)
.PP
If the assigned value for a parameter is indefinite (indicated by the
assignment operator "?=" or "=?"), then the user will be prompted for
the value to be used. The prompt will occur at runtime when the
corresponding \fIgetsym\fP (3\-\s-1ESPS\s+1) call is made.  If the
optional prompt string was supplied in the parameter file, that string
will be used as the prompt; otherwise the parameter name will be used.
If the user enters a RETURN in answer to the prompt, the default value
will be used.
.PP
If the optional parameter limitations are supplied, they are appended
to the prompt string that is used for indefinite assignments.  While
they are not enforced by the 
.br
\fIgetsym\fP (3\-\s-1ESPS\s+1) routines,
the limitations are available to user programs by means of
\fIsymchoices\fP (3\-\s-1ESPS\s+1) and 
.br\fIsymrange\fP (3\-\s-1ESPS\s+1).  
.PP
Here is an example of a parameter file:
.nf
.ft CW

int order      ?= 10 : "Model order"; # ask for prompt
int verbose     = no;
#preemphasis specification
int preflg      = yes;
float pre_num   = { 0.9, -0.5 },   # zeros of preemph filter
      pre_den   = { 0.99, -0.99 }, # poles of preemph filter
      scale     = 0.25;
# prompt for framelength
int frmlen     ?= 150: "Length of analysis window";
# prompt for frame shift - show permitted range
int nshft      ?= 180: "Distance between frames":[0,360];
# method for autocorrelation computation; ask for prompt and show 3 choices
string method   ?= "BURG":"Enter analysis method":{"BURG", "AUTOC", "COVAR"};

.ft LR
.fi
.PP
A simplified grammar follows. In this grammar, parentheses indicate that the
contents may be repeated zero or more times. Square brackets indicate that
the contents are optional (zero or one repetitions). Vertical bars indicate
"or". CHRVAL, STRVAL, FLOVAL, and INTVAL represent legal C tokens for
characters, strings, real values, and integers respectively. IDENT
represents any legal C variable name, other than one of the reserved
keywords. Case is significant, and all characters of names are significant
(the restriction imposed by LEX, which builds the lexical analyzer, is about
200 characters). Most C escape sequences like '\en' are supported in
character and string constants. Character constants like '^b', meaning
control-b, are also supported. However, octal and hexadecimal numbers are
not supported. Multiline strings are not supported.
.nf
.ft CW

file      :==  ( statement )
statement :== type decl ( \fR'\fP,\fR'\fP decl ) \fR'\fP;\fR'\fP
type      :== "int" | "float" | "char" | "string" | "char *"
decl      :== IDENT assop value [prompt] [limits]
value     :== CHRVAL | STRVAL | FLOVAL | INTVAL | array
array     :== \fR'\fP{\fR'\fP num ( \fR'\fP,\fR'\fP num ) \fR'\fP}\fR'\fP
num       :== INTVAL | FLOVAL
prompt    :== \fR'\fP:\fR'\fP STRVAL
limits    :== choices | range
choices   :== \fR'\fP:\fR'\fP strarray
strarray  :== \fR'\fP{\fR'\fP STRVAL ( \fR'\fP,\fR'\fP STRVAL) \fR'\fP}\fR'\fP
range     :== \fR'\fP:\fR'\fP \fR'\fP[\fR'\fP min \fR'\fP,\fR'\fP max \fR'\fP]\fR'\fP 
min       :== num
max       :== num
assop     :== \fR'\fP=\fR'\fP | \fR'\fP=\fR'\fP \fR'\fP?\fR'\fP | \fR'\fP?\fR'\fP \fR'\fP=\fR'\fP
.ft LR

.fi
The following keywords are reserved: int, char, string, float, yes,
no, true, false. The keywords "yes" and "true" are treated as integer
conqstants with value one (the C convention for expressing logical
true); the keywords "no" and "false" are integer constants with value
zero.
.PP
The comment convention is different from C. It is the same as for the
C shell. A '#' character indicates that the rest of the line is a
comment, unless it is contained in a character or string constant.
This makes it easier to comment out lines.
.PP
Note that it is an error to provide a range for a string parameter,
but it is OK to provide choices for a numeric parameter.  
.SH ESPS COMMON
.PP
ESPS Common processing may be disabled by setting the environment variable
USE_ESPS_COMMON to "off".  The default ESPS Common file is .espscom 
in the user's home directory.  This may be overidden by setting
the environment variable ESPSCOM to the desired path.  If ESPS_VERBOSE
is set to 1 or greater, \fIread_params\fP will report the values of 
any parameters take from Common. 
.PP
Upon successful completion, \fIread_params\fR returns 0.
If it could not read the parameter file, \-1 is returned.
If it could not read the common file, \-2 is returned.
If it could not read either then \-3 is returned.
.SH "EXAMPLE"
.nf
Here is a typical ESPS Parameter file:

# This line is a comment
int start = 0: "First point";
int nan = 1000: "Number of points";
string decrem = "no";
float harmonic_mult = -99.0;

read_params ("params",SC_NOCOMMON,NULL);	/* read default parameter file */
			/* in this case process only "params" */
start = getsym_i ("start");		/* read symbol from symbol table */
.fi
.SH DIAGNOSTICS
.PP
.SH "BUGS"
.PP
.SH FILES
.PP
~/.espscom \- the default ESPS common file.
.SH "SEE ALSO"
.PP
\fIgetsym\fP(3\-\s-1ESPS\s+1), \fIgetsymdef\fP(3\-\s-1ESPS\s+1),
\fIputsym\fP(3\-\s-1ESPS\s+1), 
.br
\fIfputsym\fP(3\-\s-1ESPS\s+1),
\fIsymtype\fP(3\-\s-1ESPS\s+1), 
\fIsymsize\fP(3\-\s-1ESPS\s+1),
.br
\fIsymlist\fP(3\-\s-1ESPS\s+1), \fIsymdefinite\fP(3\-\s-1ESPS\s+1),
\fIsymchoices\fP(3\-\s-1ESPS\s+1), \fIsymrange\fP(3\-\s-1ESPS\s+1),
\fIsymprompt\fP(3\-\s-1ESPS\s+1), \fIsymerr_exit\fP
(3\-\s-1ESPS\s+1), \fIfind_esps_file\fP(3\-\s-1ESPS\s+1), 
\fIespsenv\fP(1\-\s-1ESPS\s+1)
.SH "REFERENCES"
[1] ETM-S-86-12:jtb, Parameter Files in the Speech Processing System
.SH "AUTHOR"
Joe Buck, Man page by Ajaipal S. Virdy; modifications by Alan Parker
and John Shore