# *********************************************************************
# keysearch.txt: help text
# Copyright (c) 2003,2006 Carlo Strozzi
#
# 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; version 2 dated June, 1991.
#
# 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.
#
# *********************************************************************
# $Id: keysearch.txt 39 2007-05-02 14:46:09Z carlo $

                      NoSQL operator: keysearch

Display table records which leftmost field matches a given string.

Usage:  keysearch [options] string table

Options:
    --help (-h)
      Print this help info.

    --fold (-f)
      Ignore the case of alphabetic characters.

    --partial (-p)
      Partial (initial) match.

    --no-header (-N)
      Strip table header from output.

    --index (-I) 'file'
      Use the specified secondary index file.

    --soundex[=n] (-S[n])
      Search for the Soundex code of 'string', as opposed to
      its literal value. It is assumed that the table (or the
      index) being searched is also built on soundex codes as
      opposed to literal strings. If 'n' is not specified, it
      defaults to the standard soundex code length of four
      characters. Option '-S' overrides '-f' and '-p'.

    --test (-t)
      Instead of printing the table of matching rows, just
      return 0 if at least one matching row was found, or 1
      otherwise.

Notes:

This operator does a fast binary search on a NoSQL table file, looking
for records which first column begins with the specified 'string'. The
table being searched must be sorted alphabetically on the leftmost column.
This program is a header-aware front-end to the bsearch(1) utility. Refer
to the man page of the latter for more info. Since return code '1' is used
by bsearch(1) to signal the no-match condition, 'keysearch' will exit with
return code '2' in case of any other errors. Apart from option '-f', which
is passed to bsearch(1), no other bsearch(1) options are recognized. The
maximum acceptable length of the 'string' argument is 255 characters.

