usr.bin/nl/nl.1

   1 .\"
   2 .\" Copyright (c) 1999 The NetBSD Foundation, Inc.
   3 .\" All rights reserved.
   4 .\"
   5 .\" This code is derived from software contributed to The NetBSD Foundation
   6 .\" by Klaus Klein.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\"
  17 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  18 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  19 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  20 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  21 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  22 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  23 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  24 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  25 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  26 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  27 .\" POSSIBILITY OF SUCH DAMAGE.
  28 .\"
  29 .Dd July 24, 2022
  30 .Dt NL 1
  31 .Os
  32 .Sh NAME
  33 .Nm nl
  34 .Nd line numbering filter
  35 .Sh SYNOPSIS
  36 .Nm
  37 .Op Fl p
  38 .Bk -words
  39 .Op Fl b Ar type
  40 .Ek
  41 .Bk -words
  42 .Op Fl d Ar delim
  43 .Ek
  44 .Bk -words
  45 .Op Fl f Ar type
  46 .Ek
  47 .Bk -words
  48 .Op Fl h Ar type
  49 .Ek
  50 .Bk -words
  51 .Op Fl i Ar incr
  52 .Ek
  53 .Bk -words
  54 .Op Fl l Ar num
  55 .Ek
  56 .Bk -words
  57 .Op Fl n Ar format
  58 .Ek
  59 .Bk -words
  60 .Op Fl s Ar sep
  61 .Ek
  62 .Bk -words
  63 .Op Fl v Ar startnum
  64 .Ek
  65 .Bk -words
  66 .Op Fl w Ar width
  67 .Ek
  68 .Op Ar file
  69 .Sh DESCRIPTION
  70 The
  71 .Nm
  72 utility reads lines from the named
  73 .Ar file ,
  74 applies a configurable line numbering filter operation,
  75 and writes the result to the standard output.
  76 If
  77 .Ar file
  78 is a single dash
  79 .Pq Sq Fl
  80 or absent,
  81 .Nm
  82 reads from the standard input.
  83 .Pp
  84 The
  85 .Nm
  86 utility treats the text it reads in terms of logical pages.
  87 Unless specified otherwise, line numbering is reset at the start of each
  88 logical page.
  89 A logical page consists of a header, a body and a footer
  90 section; empty sections are valid.
  91 Different line numbering options are
  92 independently available for header, body and footer sections.
  93 .Pp
  94 The starts of logical page sections are signalled by input lines containing
  95 nothing but one of the following sequences of delimiter characters:
  96 .Bl -column "\e:\e:\e:" "Start of" -offset indent
  97 .Em "Line       Start of"
  98 .It "\e:\e:\e:  header"
  99 .It "\e:\e:     body"
 100 .It "\e:        footer"
 101 .El
 102 .Pp
 103 If the input does not contain any logical page section signalling directives,
 104 the text being read is assumed to consist of a single logical page body.
 105 .Pp
 106 The following options are available:
 107 .Bl -tag -width ".Fl v Ar startnum"
 108 .It Fl b Ar type
 109 Specify the logical page body lines to be numbered.
 110 Recognized
 111 .Ar type
 112 arguments are:
 113 .Bl -tag -width indent
 114 .It Cm a
 115 Number all lines.
 116 .It Cm t
 117 Number only non-empty lines.
 118 .It Cm n
 119 No line numbering.
 120 .It Cm p Ns Ar expr
 121 Number only those lines that contain the basic regular expression specified
 122 by
 123 .Ar expr .
 124 .El
 125 .Pp
 126 The default
 127 .Ar type
 128 for logical page body lines is
 129 .Cm t .
 130 .It Fl d Ar delim
 131 Specify the delimiter characters used to indicate the start of a logical
 132 page section in the input file.
 133 At most two characters may be specified;
 134 if only one character is specified, the first character is replaced and the
 135 second character remains unchanged.
 136 The default
 137 .Ar delim
 138 characters are
 139 .Dq Li \e: .
 140 .It Fl f Ar type
 141 Specify the same as
 142 .Fl b Ar type
 143 except for logical page footer lines.
 144 The default
 145 .Ar type
 146 for logical page footer lines is
 147 .Cm n .
 148 .It Fl h Ar type
 149 Specify the same as
 150 .Fl b Ar type
 151 except for logical page header lines.
 152 The default
 153 .Ar type
 154 for logical page header lines is
 155 .Cm n .
 156 .It Fl i Ar incr
 157 Specify the increment value used to number logical page lines.
 158 The default
 159 .Ar incr
 160 value is 1.
 161 .It Fl l Ar num
 162 If numbering of all lines is specified for the current logical section
 163 using the corresponding
 164 .Fl b Cm a ,
 165 .Fl f Cm a
 166 or
 167 .Fl h Cm a
 168 option,
 169 specify the number of adjacent blank lines to be considered as one.
 170 For example,
 171 .Fl l
 172 2 results in only the second adjacent blank line being numbered.
 173 The default
 174 .Ar num
 175 value is 1.
 176 .It Fl n Ar format
 177 Specify the line numbering output format.
 178 Recognized
 179 .Ar format
 180 arguments are:
 181 .Bl -tag -width indent -compact
 182 .It Cm ln
 183 Left justified.
 184 .It Cm rn
 185 Right justified, leading zeros suppressed.
 186 .It Cm rz
 187 Right justified, leading zeros kept.
 188 .El
 189 .Pp
 190 The default
 191 .Ar format
 192 is
 193 .Cm rn .
 194 .It Fl p
 195 Specify that line numbering should not be restarted at logical page delimiters.
 196 .It Fl s Ar sep
 197 Specify the characters used in separating the line number and the corresponding
 198 text line.
 199 The default
 200 .Ar sep
 201 setting is a single tab character.
 202 .It Fl v Ar startnum
 203 Specify the initial value used to number logical page lines; see also the
 204 description of the
 205 .Fl p
 206 option.
 207 The default
 208 .Ar startnum
 209 value is 1.
 210 .It Fl w Ar width
 211 Specify the number of characters to be occupied by the line number;
 212 in case the
 213 .Ar width
 214 is insufficient to hold the line number, it will be truncated to its
 215 .Ar width
 216 least significant digits.
 217 The default
 218 .Ar width
 219 is 6.
 220 .El
 221 .Sh ENVIRONMENT
 222 The
 223 .Ev LANG , LC_ALL , LC_CTYPE
 224 and
 225 .Ev LC_COLLATE
 226 environment variables affect the execution of
 227 .Nm
 228 as described in
 229 .Xr environ 7 .
 230 .Sh EXIT STATUS
 231 .Ex -std
 232 .Sh EXAMPLES
 233 Number all non-blank lines:
 234 .Bd -literal -offset indent
 235 $ echo -e "This is\\n\\n\\na simple text" | nl
 236      1  This is
 237
 238
 239      2  a simple text
 240 .Ed
 241 .Pp
 242 Number all lines including blank ones, with right justified line numbers with
 243 leading zeroes, starting at 2, with increment of 2 and a custom multi-character
 244 separator:
 245 .Bd -literal -offset indent
 246 $ echo -e "This\\nis\\nan\\n\\n\\nexample" | nl -ba -n rz -i2 -s "->" -v2
 247 000002->This
 248 000004->is
 249 000006->an
 250 000008->
 251 000010->
 252 000012->example
 253 .Ed
 254 .Pp
 255 Number lines matching regular expression for an
 256 .Em i
 257 .No followed by either
 258 .Em m
 259 .No or
 260 .Em n
 261 .Bd -literal -offset indent
 262 $ echo -e "This is\\na simple text\\nwith multiple\\nlines" | nl -bp'i[mn]'
 263         This is
 264      1  a simple text
 265         with multiple
 266      2  lines
 267 .Ed
 268 .Sh SEE ALSO
 269 .Xr jot 1 ,
 270 .Xr pr 1
 271 .Sh STANDARDS
 272 The
 273 .Nm
 274 utility conforms to
 275 .St -p1003.1-2001 .
 276 .Sh HISTORY
 277 The
 278 .Nm
 279 utility first appeared in
 280 .At III .
 281 .Sh BUGS
 282 Input lines are limited to
 283 .Dv LINE_MAX
 284 (2048) bytes in length.