sbase

suckless unix tools
git clone git://git.suckless.org/sbase
Log | Files | Refs | README | LICENSE

join.1 (2175B)


      1 .Dd 2015-10-08
      2 .Dt JOIN 1
      3 .Os sbase
      4 .Sh NAME
      5 .Nm join
      6 .Nd relational database operator
      7 .Sh SYNOPSIS
      8 .Nm
      9 .Op Fl 1 Ar field
     10 .Op Fl 2 Ar field
     11 .Op Fl o Ar list
     12 .Op Fl e Ar string
     13 .Op Fl a Ar fileno | Fl v Ar fileno
     14 .Op Fl t Ar delim
     15 .Ar file1 file2
     16 .Sh DESCRIPTION
     17 .Nm
     18 lines from
     19 .Ar file1
     20 and
     21 .Ar file2
     22 on a matching field.
     23 If one of the input files is '-', standard input is read for that file.
     24 .Pp
     25 Files are read sequentially and are assumed to be sorted on the join
     26 field.
     27 .Nm
     28 does not check the order of input, and joining two unsorted files will
     29 produce unexpected output.
     30 .Pp
     31 By default, input lines are matched on the first blank-separated
     32 field; output lines are space-separated and consist of the join field
     33 followed by the remaining fields from
     34 .Ar file1 ,
     35 then the remaining fields from
     36 .Ar file2 .
     37 .Sh OPTIONS
     38 .Bl -tag -width Ds
     39 .It Fl 1 Ar field
     40 Join on the
     41 .Ar field Ns th
     42 field of file 1.
     43 .It Fl 2 Ar field
     44 Join on the
     45 .Ar field Ns th
     46 field of file 2.
     47 .It Fl a Ar fileno
     48 Print unpairable lines from file
     49 .Ar fileno
     50 in addition to normal output.
     51 .It Fl e Ar string
     52 When used with
     53 .Fl o ,
     54 replace empty fields in the output list with
     55 .Ar string .
     56 .It Fl o Ar list
     57 Format output according to the string
     58 .Ar list .
     59 Each element of
     60 .Ar list
     61 may be either
     62 .Ar fileno.field
     63 or 0 (representing the join field).
     64 Elements in
     65 .Ar list
     66 may be separated by blanks or commas.
     67 For example,
     68 .Bd -literal -offset indent
     69 join -o "0 2.1 1.3"
     70 .Ed
     71 .Pp
     72 would print the join field, the first field of
     73 .Ar file2 ,
     74 then the third field of
     75 .Ar file1 .
     76 .Pp
     77 Only paired lines are formatted with the
     78 .Fl o
     79 option.
     80 Unpairable lines (selected with
     81 .Fl a
     82 or
     83 .Fl v )
     84 are printed raw.
     85 .It Fl t Ar delim
     86 Use the arbitrary string
     87 .Ar delim
     88 as field delimiter for both input and output.
     89 .It Fl v Ar fileno
     90 Print unpairable lines from file
     91 .Ar fileno
     92 instead of normal output.
     93 .El
     94 .Sh STANDARDS
     95 The
     96 .Nm
     97 utility is compliant with the
     98 .St -p1003.1-2013
     99 specification with the following exeption:
    100 .Bl -bullet -offset indent
    101 .It
    102 Unpairable lines ignore formatting specified with
    103 .Fl o .
    104 .El
    105 .Pp
    106 The possibility of specifying multibyte delimiters of arbitrary
    107 length is an extension to the specification.