select.1t

speech signal process tools

.\" Copyright (c) 1986-1990 Entropic Speech, Inc.
.\" Copyright (c) 1992 Entropic Research Laboratory, Inc.; All rights reserved
.\" @(#)select.1t	3.14 19 Sep 1997 ESI/ERL
.ds ]W (c) 1992 Entropic Research Laboratory, Inc.
.TH SELECT 1\-ESPS 19 Sep 1997
.SH "NAME"
.nf
select - applies arbitrary queries to select records from FEA files
.sp
eselect - applies arbitrary queries to select records from FEA files
.fi
.SH "SYNOPSIS"
.B select
[
.B \-n
] [
.BI \-c 
] [
.BI \-q " query"
] [
.BI \-e " expression"
] [
.BI \-f " format string"
] [
.BI \-l " log"
] [
.BI \-o " output"
] [
.I "input1 input2 ..."
] 
.SH "DESCRIPTION"
.PP
This program is stored under the name \fIselect\fR and \fIeselect\fR in
order to avoid a name conflict with the \fIksh\fR builtin command \fIselect\fR.
.PP
.I Select
applies selection criteria to FEA files.  The selected records
may be printed and may appended to an internal record buffer, which
in turn may be output to another FEA file.  The selection criteria
are specified as a set of queries, with each query being a condition
on the fields in the FEA record.
.PP
.I Select
operates in two modes:  non-interactive and interactive.  The
non-interactive mode applies when the \fB\-q\fP and \fB\-o\fP options
are used.  In this case, the specified query is applied to all of the
.I input 
files and the selected records are written
to
.I output.  
.PP
In interactive mode (no \fB\-q\fP option), 
.I select
prompts the user for commands (see below).  Alternatively, a file of
selection commands can be used as standard input (e.g., \fIselect <
command_file)\fP.  Command files can also be invoked interactively.
.PP
The following options are interpreted by \fIselect\fP:
.TP
.BI \-n
No source files or comments about queries are added to the headers
of output files.  Normally, the headers of output files are expanded
to include the the input files as sources and the selection queries as 
comments in the \fIvariable.comment\fP field.  The \fB\-n\fP option 
disables this and results in faster operation, especially when 
the output file already exists and is large.  
.TP
.BI \-c 
By default, comparisons involving feature fields of type coded are case
insensitive.   When the \fB\-c\fR option is used, these comparisons are
case sensitive.
.TP
.BI \-q " query"
Apply the 
.I query
to the
.I input
files and write the selected records to 
.I output
(see \fB\-o\fP).  
.TP
.BI \-e " expression"
Execute the \fIeval\fR command on the input file and print the result to
standard output.   For details, see the \fIeval\fR command below.
.TP
.BI \-f " printf format string"
This option allows the specification of a \fIprintf\fR format string to
be used to output the values resulting from use of the \fB-e\fR option.
The string can be any valid \fIprintf\fR format string, except that only
the following character escapes are handled: \\n, \\t, \\b, \\r, \\f, \\\\ 
(to enter a slash), and \\' (to enter a single quote).    (Note in
particular, that \\ddd is not handled.)  Keep in mind that the value
being displayed is typed \fIdouble\fR inside of the program.  So use of
an incompatible output specification will result in garbage dispplay.
For example the following option might be used: \fB-f 'Value:\\t%e\\n'\fR or
\fB-f Any string: %f units\\n'\fR.   The specification string should
contain at most one output format control appropriate for double values
(%e, %f, %g). 
.TP
.BI \-o " output"
Specifies an output file.  This option must be used if the 
.B \-q
option is used, and it cannot be used unless one or more input 
files are specified on the command line.  
.TP
.BI \-l " log"
All user commands, together with all terminal output from
.IR select ,
will be recorded on a file named
.IR log .
.PP
Each command to \fIselect\fP consists of one or two keywords
followed by arguments.  The keywords may be abbreviated.  Your unix
interrupt character (\fIe.g.\fR ^C) will always terminate the current command.
Required portions of the keywords are shown in capital letters in the
description below;
.I select
is not sensitive to case.  An EOF is equivalent to a 
.B Write
followed by a
.B Quit.
.PP
Tagged and segment labelled input files involve some special handling in
order to make it possible to associate output records with the sampled data
files to which the input records refer.  If the output file does not exist,
and if there is only one tagged input file, then the output file is also
tagged, with the tags being pointers into the same refer file as specified
in the input file.  If the output file does not exist, and if there are two
or more tagged input files, the output file is segment labelled, and all
tagged records written to the output file are converted to segment
labelled.  For the case of an existing output file, see the note under
BUGS below.
For more information
about taggged and segment labelled FEA files, see FEA (5\-\s-1ESPS\s+1).  
.TP
.BI "@" "comfile "
.br
This command causes
.I select
to read commands from the file
.I comfile ,
rather than from the standard input. When end-of-file is reached,
.I select
resumes reading from the standard input.  Command files may be
nested; the maximum nesting depth is three.  Command files are
aborted (all remaining commands are skipped) if an error or user
interrupt occurs while the command file is being read.
.TP
.BI "!" command
Shell escape.
A shell is forked off to execute
.IR command .
The command output does not appear in the log file.  The exclamation point
must be in the first column.  A "#" character is not considered a comment in
.IR command ,
since the command may require that character.
.TP
.B CLEar
If the record buffer has been changed since the last write, a 
warning is printed and the user is asked to confirm.   If the user
answers the confirmation request with "yes", the the record buffer is
cleared.
.TP
.B CLOse
Closes the log file, if any.
.TP
.BI EVal " QUERY"
Prints the value of the \fIQUERY\fR expression (see
SYNTAX DETAILS) for each record in the
input set.  The record number relative to the input file and relative to
the set of input files (if there is more than one input file) is also
printed. 
.TP
.BI From " input1, input2, ..."
Closes an existing input files, if any are open, and opens the new
ones.  All input files must be FEA files.  Note that an initial set
of input files can be specified on the command line.
.TP
.BI HEAder " flags"
Prints the headers of the current set of input files, using \fIpsps\fR(1\-ESPS)
with the \fB\-x\fR flag.  The \fIpsps\fP flags \fB\-frhv\fP may also be
specified.  The outputs are run through the
.I more
program (unless PAGER is set to a different program name; see ENVIRONMENT).
The output is not written to the log file.
.TP
.B HELp
Prints a summary of the commands accepted by
.I select.
The help file is run through the
.I more
program (unless PAGER is set to a different program name; see ENVIRONMENT).
.TP
.BI Log " logfile"
Specifies that the dialog with the user will be saved on
.I logfile
(equivalent to the
.B \-l
command line option).  If a log file is already open, the old log file is
closed and a new file is started.  If the argument is omitted, the command is
equivalent to Show Log.
.TP
.BI Select " QUERY"
Processes the input files one at a time, selects all records that
satisfy the \fIQUERY\fP, and appends them to the
record buffer. 
During queries that scan more than 1000 records, a dot will be printed
for each 1000 records scanned.
The number of records selected from each file and 
the total number selected are printed when the select is complete or
interrupted.
.TP
.B "SHow Buffer"
Prints the records in the record buffer.  
The output is run through the
.I more
program (unless PAGER is set to a different program name; see ENVIRONMENT).
.TP
.B "SHow FIelds"
Prints the field definitions of 
.I input.
.TP
.BI "SHow FRom" " flags"
Runs \fIpsps\fP on the current set of input files.  Any of the
\fIpsps\fP flags may be specified.  The output is run through the
.I more
program (unless PAGER is set to a different program name; see ENVIRONMENT).
.TP 
.B "SHow LOg"
This command tells whether a log file is open, and gives its name if
there is an open file.
.TP
.B "SHow LAst"
Prints the last record in the select buffer.  
.TP 
.BI "SHow Select" " QUERY"
Processes the input files one at a time, selects all records that
satisfy the \fIQUERY\fP, and
prints them. 
The number of records selected from each file and the total number
selected are printed.  The output is run through the
.I more
program (unless PAGER is set to a different program name; see ENVIRONMENT).
If this command is interrupted with one interrupt character, then
printing of the records is suspended, but the selection continues.  The
total records that match the \fIQUERY\fR will be printed as usual.   If
the command is interrupted for a second time the command will quit
without checking additional records.
.TP
.BI "SHow To" " flags"
Runs \fIpsps\fP on \fIoutput\fP.  Any of the \fIpsps\fP flags may 
be specified.  
The output is run through the
.I more
program (unless PAGER is set to a different program name; see
ENVIRONMENT).
.TP
.B "SIze"
Prints the number of records in the record buffer. 
.TP
.BI To " output \fR[ \fBWith\fI fieldname1, fieldname2, ...\fR]"
.TP
.BI To " output \fR[ \fBWithout\fI fieldname1, fieldname2, ...\fR]"
Specifies an output file.  If an output file has already been
specified, \fIselect\fP closes it and opens the new one provided that
the record buffer has not changed since the last write.  If the
record buffer has been changed since the last write, a warning is
printed and no action is taken.  If the TO command is then repeated
as the next command, the existing output file is closed and the new
one is opened.  Note that an output file can be specified on the
command line.  An output file cannot be specified until an input file
has been specified.  Furthermore, the output file, if it exists, must
have a compatible header with that of the first input file (same
field definitions).  If the 
output file does not exist, the \fBWith\fP clause can be used to 
specify which fields from input records will be written to the output 
file, or the \fBWithout\fP clause can be used to specify which 
fields to omit.   
.TP
.B Quit
If the record buffer has not changed since the last write,
\fIselect\fP exits.  If the record buffer has been changed since the
last write, a warning is printed and the user is asked to confirm the
command.   If the user responds to the confirmation request with "yes",
then the program is terminated without writing the output file.
.TP
.B Undo
This command removes the records from the record buffer resulting from
the last Select command.   This command can only be given between a
Select and a Write.  Undo cannot be undone.   
.TP
.B Version
Prints out the version number and the date of the last edit (actually, the
date of the last modification of the SCCS database where
.I select
is maintained).
.TP
.B Write
If \fIoutput\fP does not exist (see the TO 
command), it is created and the contents of the record buffer are written 
to it.  If \fIoutput\fP exists, the contents of the record buffer 
are appended.  The record buffer is then cleared.  
.SH SYNTAX DETAILS
.PP
A \fIQUERY\fR consists of an expression, which has the following form:
.nf

<expr> ::= <value>
	| <field_name>{[<index>]}
	| <character_string>
	| $<external_function>
	| <function> (<field_name>)
	| <function> (<expr>)
	| ( <expr> )
	| <expr> <arith_op> <expr>
	| <expr> <rel_op> <expr>
	| \- <expr>