# *********************************************************************
# 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,v 1.4 2006/03/10 11:26:13 carlo Exp $

                      NoSQL operator: keysearch

Display table records which leftmost field begins with 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 look(1) utility.
Refer to the man page of the latter for more info. Since return code '1'
is used by look(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 look(1), no other look(1) options are recognized.
The maximum acceptable length of the 'string' argument is 255 characters.

