sbase

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

join.1 (2202B)


      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. If one of the input files is '-', standard input
     23 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 Ns ,
     35 then the remaining fields from
     36 .Ar file2 Ns .
     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 Ns ,
     54 replace empty fields in the output list with
     55 .Ar string Ns .
     56 .It Fl o Ar list
     57 Format output according to the string
     58 .Ar list Ns .
     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. For example,
     67 .Bd -literal -offset indent
     68 join -o "0 2.1 1.3"
     69 .Ed
     70 .Pp
     71 would print the join field, the first field of
     72 .Ar file2 Ns ,
     73 then the third field of
     74 .Ar file1 Ns .
     75 .Pp
     76 Only paired lines are formatted with the
     77 .Fl o
     78 option. Unpairable lines (selected with
     79 .Fl a
     80 or
     81 .Fl v Ns )
     82 are printed raw.
     83 .It Fl t Ar delim
     84 Use the arbitrary string
     85 .Ar delim
     86 as field delimiter for both input and output.
     87 .It Fl v Ar fileno
     88 Print unpairable lines from file
     89 .Ar fileno
     90 instead of normal output.
     91 .El
     92 .Sh STANDARDS
     93 The
     94 .Nm
     95 utility is compliant with the
     96 .St -p1003.1-2013
     97 specification with the following exeption:
     98 .Bl -bullet -offset indent
     99 .It
    100 Unpairable lines ignore formatting specified with
    101 .Fl o Ns .
    102 .El
    103 .Pp
    104 The possibility of specifying multibyte delimiters of arbitrary
    105 length is an extension to the specification.