# *********************************************************************
# seek.txt: help text
# Copyright (c) 2004 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; 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.
#
# *********************************************************************
# $Id: seek.txt,v 1.1 2004/08/08 21:09:06 carlo Exp $

                      NoSQL operator: seek

Extract rows at selected offsets from an indexed NoSQL table.

Usage:  seek [options] table < offset_list

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

    --raw-input (-R)
      The input offset list is not in table format.

    --hex (-X)
      Input offset are expressed in hexadecimal values.

    --no-header (-N)
      Do not print the table header on STDOUT.

    --info (-r)
      Instead of the actual table content, a new table is printed,
      containing a report of the data fouind at the requested offset(s).
      The information printed is the start, end and size (in bytes) of
      the relevant rows, and a flag that tells whether the latter are
      empty, i.e. contain just blanks and/or tabs.

    --blank (-b)
      Same as '--info', but only blank lines, if any, are taken into
      account.


Notes:

This operator takes a list of byte-offsets on STDIN and prints on STDOUT
the corresponding table records from the table specified as a command
line argument. The list of offsets can be built with the 'index' operator,
and 'seek' expects it to be a one-column table, like this:

        offset
        ------
        228
        1117
        518
        1225

The column name, 'offset' in the example, can take any name, provided
that the list has a valid NoSQL table format. If option '-R' is given,
then the offsets are expected to be a blank- , tab- or newline-separated
raw list of numbers on STDIN, i.e. they are not expected to to have a
valid NoSQL table header.

If option '-x' is given, then the offsets are expected to be base 16
numbers instead of the usual base 10 numbers.

Examples :

  seek table < offset_table

  or

  echo "228 1117 518 1225" | seek -R table
  echo "a28 1b1F 5c8 1425" | seek -R -x table

