.\" $Id: metadb.1,v 1.12 2019/09/09 22:35:36 stolcke Exp $
.TH metadb 1 "$Date: 2019/09/09 22:35:36 $" "SRILM Tools"
.SH NAME
metadb \- retrieve configuration information
.SH SYNOPSIS
.B metadb
[
.I -options
\&...]
.I key
[ ... ]
.SH DESCRIPTION
.B metadb
retrieves string values associates with keys in configuration files.
The key(s) to be retrieved are specified as arguments.
The configuration file is located through the enviroment variable
.BR METADB_CONFIG ,
possibly overridden by the 
.B \-config 
option.
.PP
Scripts and programs that need to operate on a variety of data
or with different parameters should retrieve all variable information
via 
.BR metadb .
.SH "CONFIG FILE SYNTAX"
The format of a line in the configuration file is 
.br
	\fIkey\fP \fIvalue\fP
.br
where
.I key
is the first word in a line.
Anything starting with the second
word is the
.I value
associated with the
.IR key .
Initial and final whitespace
is removed, but otherwise whitespace can be embedded in the
.IR value .
Only the first of multiple lines with the same
.I key
is significant for a lookup, unless the
.B \-all
flag was given.
.PP
The special key
.B INCLUDE
is used to perform file inclusions:
.br
	\fBINCLUDE\fP /some/other/config/file
.br
allowing config files to ``inherit'' from other config files.
Note that key-value pairs preceding an inclusion override any identical
key in the included file.
.PP
The 
.B ALIAS
keyword redirects a lookup for one key
.I key1
by another lookup for 
.IR key2 :
.br
	\fBALIAS\fP \fIkey1\fP \fIkey2\fP
.br
.PP
The 
.B ALIAS_SUFFIX
keyword redirects a lookup for any key
with suffix
.I suffix1
to another lookup with the suffix replaced by 
.IR suffix2 :
.br
	\fBALIAS_SUFFIX\fP \fIsuffix1\fP \fIsuffix2\fP
.br
This is a convenient way to apply a string mapping to an entire
family of keys.
To avoid infinite recursions and ambiguities in matching keys,
the prefix of the key that is matched by
.I suffix1 
must no contain any underscore characters.
.PP
Lines containing only whitespace or starting with a pound sign are ignored:
.br
	# this is a comment
.br
.PP
There is also a primitive macro facility:
.br
	\fBDEFINE\fP \fIstring\fP \fIstring2\fP
.br
causes
.I string
to be replaced by
.I string2
in the output.
.br
	\fBSDEFINE\fP \fIstring\fP \fIcomand\fP \fIarg1\fP \fIarg2\fP ...
.br
defines
.I string
as a macro expanding to the first line of output of
.IR command .
This also allows ``importing'' environment variables:
.br
	\fBSDEFINE\fP MACHINE_TYPE printenv MACHINE_TYPE
.br
(but note the expansion of macros inside the config file does not use
dollar signs).
.br
The directive
.br
	\fBMDEFINE\fP \fIstring\fP \fIkey\fP
.br
defines
.I string
as a macro expanding to the result of looking up 
.I key
using 
.B metadb
itself in the current configuration file.
This allows piecing together of strings from various key values,
and other back-handed uses.
.br
	\fBUNDEF\fP \fIstring\fP
.br
undoes the definition of
.IR string .
.PP
Macros are expanded in key values, include filenames, and the definitions
of other macros (at the time of definition).
.SH OPTIONS
.TP
.BI \-config " file"
Use
.I file 
as the configuration file, instead of 
.BR $METADB_CONFIG .
.TP
.B \-all
Return all key values, instead of the first value.
This allows using multiple instances of a key to construct lists of strings.
.TP
.B \-dump
Output all key-value pairs found in the config file (prior to
any values indexed by command line arguments).
.TP
.B \-includes
Trace the names of INCLUDEd files.
.TP
.B \-e
Print an error message and exit with error status if a requested key value
is undefined or empty.
.TP
.B \-q
Check for the presence of a key and do not output key values.
A program exit status of 0 (``true'' to the shell)
indicates that at least one of the keys is present
in the configuration file.
Otherwise, a status of 1 (``false'' to the shell) is returned.
.SH BUGS
Probably.
.SH AUTHOR
Andreas Stolcke <stolcke@icsi.berkeley.edu>
.br
Copyright (c) 1999\-2011 SRI International