# *********************************************************************
#  Written by and copyright Carlo Strozzi <carlos@linux.it>.
#
#  row.txt: help text
#  Copyright (C) 2001 Carlo Strozzi <carlos@linux.it>
# 
#  This program is free software; you can redistribute it and/or modify
#  it under the terms of the GNU General Public License as published by
#  the Free Software Foundation; either version 2 of the License, or
#  (at your option) any later version.
# 
#  This program 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 General Public License for more details.
# 
#  You should have received a copy of the GNU General Public License
#  along with this program; if not, write to the Free Software
#  Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
#
# *********************************************************************

                      NoSQL operator: row

Selects rows matching a given AWK expression using column names.

Usage: row [options] expression

Options:
    --input (-i) 'file'
      Read input from 'file' instead of STDIN.

    --output (-o) 'file'
      Write output to 'file' instead of STDOUT.

    --help (-h)
      Display this help text.

    --no-header (-N)
      Remove header from output.

    --debug (-x)
      Display the resulting awk(1) program before running it.

    --not-empty (-e)
      Rows that contain only blanks and/or tabs are excluded
      from output.

    --test (-t)
      Instead of printing the table of matching rows, just print
      '1' if at least one matching row was found, or '0' otherwise.
      This way of returning a result code resembles the one used
      by expr(1).

    --key (-K)
      Instead of printing the complete matching rows, just print
      their first (leftmost) field, supposedly the record key.
      This will save a subsequent call to 'column' if all we
      need is to extract the matching record keys.

    --first-match (-f)
      Print only the first successful match and exit.

    --add (-a) 'string'
      If the input table contains no match, print an empty row
      to STDOUT and set its key field to 'string'. To assign an
      empty key, 'string' must be an empty shell string, like ''
      or "". Special NoSQL characters in 'string' are automatically
      escaped.

Notes:

If the input table contains duplicated columns, with the same name
but different values, only the first (leftmost) one is taken into
account, but the output table will still have the duplicates with
their different values.

If no expression is specified, then nothing is printed. The awk
expression must be enclosed in single quotes, to prevent the shell from
parsing it.

The following names are reserved to the awk language, and should not
be used to indicate column names:

BEGIN, END, break, continue, else, exit, exp, for, getline, if, in,
index, int, length, log, next, print, printf, split, sprintf, sqrt,
substr, while, and possibly others. See mawk(1) for more on this.

$Id$
