consume.1

   1 .\" SPDX-License-Identifier: BSD-2-Clause
   2
   3 .\" Copyright (c) 2022 Alessio Chiapperini
   4
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25
  26 .Dd January 31, 2022
  27 .Dt CONSUME 1
  28 .Os
  29 .Sh NAME
  30 .Nm consume
  31 .Nd split input, feed it into the given utility and consume it if successful.
  32 .Sh SYNOPSIS
  33 .Nm
  34 .Op Fl \&0ach
  35 .Op Fl i Ar file
  36 .Op Fl v
  37 .Op Ar utility Op Ar argument ...
  38 .Sh DESCRIPTION
  39 The
  40 .Nm
  41 utility reads input from the file named by the
  42 .Ar file
  43 operand or from stdin if absent, and splits it when encountering the given
  44 delimiter (defaults to newline).
  45 It then invokes the
  46 .Ar utility
  47 repeatedly, feeding it the generated data as input.
  48 On success the given data is consumed (removed) from the input file, if any.
  49 .Pp
  50 The options are as follows:
  51 .Bl -tag -width indent
  52 .It Fl 0
  53 Input items are teminated by a null character instead of by newline. The GNU
  54 find -print0 option produces input suitable for this mode.
  55 .It Fl a
  56 Input items are fed as a command-line argument to
  57 .Ar utility.
  58 .It Fl c
  59 Continue even if
  60 .Ar utility
  61 failed.
  62 .It Fl h
  63 Print usage information and exit.
  64 .It Fl i Ar file
  65 Read items from
  66 .Ar file
  67 instead of standard input.
  68 .It Fl v
  69 Print the command line on the standard error ouput before executing it.
  70 .El
  71 .Sh "EXIT STATUS"
  72 The
  73 .Nm
  74 utility exits 0 on success, and 1 if an error occurs.
  75 .Sh EXAMPLES
  76 Count the number of words in each line of 'La Divina Commedia':
  77 .Dl curl -s https://dmf.unicatt.it/~della/pythoncourse18/commedia.txt | consume wc -w
  78 .Pp
  79 Find files named
  80 .Ar core
  81 in or below the directory
  82 .Ar /tmp
  83 and delete them. Before deleting each file the full command is printed to stderr:
  84 .Dl find /tmp -name core -type f -print | consume -a -v /bin/rm -f
  85 .Pp
  86 Consume all lines delimited by
  87 .Sq 0
  88 in biglistoflinks.txt that wget has downloaded successfully:
  89 .Dl consume -0 -a -i biglistoflinks.txt wget -qc
  90 .Sh SEE ALSO
  91 .Xr split 1 ,
  92 .Xr tee 1 ,
  93 .Xr xargs 1
  94 .Sh BUGS
  95 .Bl -tag -width indent
  96 .It Input lines are limited to LINE_MAX bytes in length.
  97 .It Input file names are limited to BUFSIZ bytes in length.
  98 .El
  99 .Sh AUTHOR
 100 .An Alessio Chiapperini Aq Mt alessio.chiapperini@\:nullbuffer.com