1S2P(1)                User Contributed Perl Documentation               S2P(1)
2
3
4

NAME

6       psed - a stream editor
7

SYNOPSIS

9          psed [-an] script [file ...]
10          psed [-an] [-e script] [-f script-file] [file ...]
11
12          s2p  [-an] [-e script] [-f script-file]
13

DESCRIPTION

15       A stream editor reads the input stream consisting of the specified
16       files (or standard input, if none are given), processes is line by line
17       by applying a script consisting of edit commands, and writes resulting
18       lines to standard output. The filename '"-"' may be used to read
19       standard input.
20
21       The edit script is composed from arguments of -e options and script-
22       files, in the given order. A single script argument may be specified as
23       the first parameter.
24
25       If this program is invoked with the name s2p, it will act as a sed-to-
26       Perl translator. See "SED SCRIPT TRANSLATION".
27
28       sed returns an exit code of 0 on success or >0 if an error occurred.
29

OPTIONS

31       -a  A file specified as argument to the w edit command is by default
32           opened before input processing starts. Using -a, opening of such
33           files is delayed until the first line is actually written to the
34           file.
35
36       -e script
37           The editing commands defined by script are appended to the script.
38           Multiple commands must be separated by newlines or semicolons.
39
40       -f script-file
41           Editing commands from the specified script-file are read and
42           appended to the script.
43
44       -n  By default, a line is written to standard output after the editing
45           script has been applied to it. The -n option suppresses automatic
46           printing.
47

COMMANDS

49       sed command syntax is defined as
50
51          [address[,address]][!]function[argument]
52
53       with whitespace being permitted before or after addresses, and between
54       the function character and the argument. The addresses and the address
55       inverter ("!") are used to restrict the application of a command to the
56       selected line(s) of input.
57
58       Each command must be on a line of its own, except where noted in the
59       synopses below.
60
61       The edit cycle performed on each input line consist of reading the line
62       (without its trailing newline character) into the pattern space,
63       applying the applicable commands of the edit script, writing the final
64       contents of the pattern space and a newline to the standard output.  A
65       hold space is provided for saving the contents of the pattern space for
66       later use.
67
68   Addresses
69       A sed address is either a line number or a pattern, which may be
70       combined arbitrarily to construct ranges. Lines are numbered across all
71       input files.
72
73       Any address may be followed by an exclamation mark ('"!"'), selecting
74       all lines not matching that address.
75
76       number
77           The line with the given number is selected.
78
79       $   A dollar sign ("$") is the line number of the last line of the
80           input stream.
81
82       /regular expression/
83           A pattern address is a basic regular expression (see "BASIC REGULAR
84           EXPRESSIONS"), between the delimiting character "/".  Any other
85           character except "\" or newline may be used to delimit a pattern
86           address when the initial delimiter is prefixed with a backslash
87           ('"\"').
88
89       If no address is given, the command selects every line.
90
91       If one address is given, it selects the line (or lines) matching the
92       address.
93
94       Two addresses select a range that begins whenever the first address
95       matches, and ends (including that line) when the second address
96       matches.  If the first (second) address is a matching pattern, the
97       second address is not applied to the very same line to determine the
98       end of the range. Likewise, if the second address is a matching
99       pattern, the first address is not applied to the very same line to
100       determine the begin of another range. If both addresses are line
101       numbers, and the second line number is less than the first line number,
102       then only the first line is selected.
103
104   Functions
105       The maximum permitted number of addresses is indicated with each
106       function synopsis below.
107
108       The argument text consists of one or more lines following the command.
109       Embedded newlines in text must be preceded with a backslash.  Other
110       backslashes in text are deleted and the following character is taken
111       literally.
112
113       [1addr]a\ text
114           Write text (which must start on the line following the command) to
115           standard output immediately before reading the next line of input,
116           either by executing the N function or by beginning a new cycle.
117
118       [2addr]b [label]
119           Branch to the : function with the specified label. If no label is
120           given, branch to the end of the script.
121
122       [2addr]c\ text
123           The line, or range of lines, selected by the address is deleted.
124           The text (which must start on the line following the command) is
125           written to standard output. With an address range, this occurs at
126           the end of the range.
127
128       [2addr]d
129           Deletes the pattern space and starts the next cycle.
130
131       [2addr]D
132           Deletes the pattern space through the first embedded newline or to
133           the end.  If the pattern space becomes empty, a new cycle is
134           started, otherwise execution of the script is restarted.
135
136       [2addr]g
137           Replace the contents of the pattern space with the hold space.
138
139       [2addr]G
140           Append a newline and the contents of the hold space to the pattern
141           space.
142
143       [2addr]h
144           Replace the contents of the hold space with the pattern space.
145
146       [2addr]H
147           Append a newline and the contents of the pattern space to the hold
148           space.
149
150       [1addr]i\ text
151           Write the text (which must start on the line following the command)
152           to standard output.
153
154       [2addr]l
155           Print the contents of the pattern space: non-printable characters
156           are shown in C-style escaped form; long lines are split and have a
157           trailing ^'"\"' at the point of the split; the true end of a line
158           is marked with a '"$"'. Escapes are: '\a', '\t', '\n', '\f', '\r',
159           '\e' for BEL, HT, LF, FF, CR, ESC, respectively, and '\' followed
160           by a three-digit octal number for all other non-printable
161           characters.
162
163       [2addr]n
164           If automatic printing is enabled, write the pattern space to the
165           standard output. Replace the pattern space with the next line of
166           input. If there is no more input, processing is terminated.
167
168       [2addr]N
169           Append a newline and the next line of input to the pattern space.
170           If there is no more input, processing is terminated.
171
172       [2addr]p
173           Print the pattern space to the standard output. (Use the -n option
174           to suppress automatic printing at the end of a cycle if you want to
175           avoid double printing of lines.)
176
177       [2addr]P
178           Prints the pattern space through the first embedded newline or to
179           the end.
180
181       [1addr]q
182           Branch to the end of the script and quit without starting a new
183           cycle.
184
185       [1addr]r file
186           Copy the contents of the file to standard output immediately before
187           the next attempt to read a line of input. Any error encountered
188           while reading file is silently ignored.
189
190       [2addr]s/regular expression/replacement/flags
191           Substitute the replacement string for the first substring in the
192           pattern space that matches the regular expression.  Any character
193           other than backslash or newline can be used instead of a slash to
194           delimit the regular expression and the replacement.  To use the
195           delimiter as a literal character within the regular expression and
196           the replacement, precede the character by a backslash ('"\"').
197
198           Literal newlines may be embedded in the replacement string by
199           preceding a newline with a backslash.
200
201           Within the replacement, an ampersand ('"&"') is replaced by the
202           string matching the regular expression. The strings '"\1"' through
203           '"\9"' are replaced by the corresponding subpattern (see "BASIC
204           REGULAR EXPRESSIONS").  To get a literal '"&"' or '"\"' in the
205           replacement text, precede it by a backslash.
206
207           The following flags modify the behaviour of the s command:
208
209           g       The replacement is performed for all matching, non-
210                   overlapping substrings of the pattern space.
211
212           1..9    Replace only the n-th matching substring of the pattern
213                   space.
214
215           p       If the substitution was made, print the new value of the
216                   pattern space.
217
218           w file  If the substitution was made, write the new value of the
219                   pattern space to the specified file.
220
221       [2addr]t [label]
222           Branch to the : function with the specified label if any s
223           substitutions have been made since the most recent reading of an
224           input line or execution of a t function. If no label is given,
225           branch to the end of the script.
226
227       [2addr]w file
228           The contents of the pattern space are written to the file.
229
230       [2addr]x
231           Swap the contents of the pattern space and the hold space.
232
233       [2addr]y/string1/string2/
234           In the pattern space, replace all characters occurring in string1
235           by the character at the corresponding position in string2. It is
236           possible to use any character (other than a backslash or newline)
237           instead of a slash to delimit the strings.  Within string1 and
238           string2, a backslash followed by any character other than a newline
239           is that literal character, and a backslash followed by an 'n' is
240           replaced by a newline character.
241
242       [1addr]=
243           Prints the current line number on the standard output.
244
245       [0addr]: [label]
246           The command specifies the position of the label. It has no other
247           effect.
248
249       [2addr]{ [command]
250       [0addr]}
251           These two commands begin and end a command list. The first command
252           may be given on the same line as the opening { command. The
253           commands within the list are jointly selected by the address(es)
254           given on the { command (but may still have individual addresses).
255
256       [0addr]# [comment]
257           The entire line is ignored (treated as a comment). If, however, the
258           first two characters in the script are '"#n"', automatic printing
259           of output is suppressed, as if the -n option were given on the
260           command line.
261

BASIC REGULAR EXPRESSIONS

263       A Basic Regular Expression (BRE), as defined in POSIX 1003.2, consists
264       of atoms, for matching parts of a string, and bounds, specifying
265       repetitions of a preceding atom.
266
267   Atoms
268       The possible atoms of a BRE are: ., matching any single character; ^
269       and $, matching the null string at the beginning or end of a string,
270       respectively; a bracket expressions, enclosed in [ and ] (see below);
271       and any single character with no other significance (matching that
272       character). A \ before one of: ., ^, $, [, *, \, matching the character
273       after the backslash. A sequence of atoms enclosed in \( and \) becomes
274       an atom and establishes the target for a backreference, consisting of
275       the substring that actually matches the enclosed atoms.  Finally, \
276       followed by one of the digits 0 through 9 is a backreference.
277
278       A ^ that is not first, or a $ that is not last does not have a special
279       significance and need not be preceded by a backslash to become literal.
280       The same is true for a ], that does not terminate a bracket expression.
281
282       An unescaped backslash cannot be last in a BRE.
283
284   Bounds
285       The BRE bounds are: *, specifying 0 or more matches of the preceding
286       atom; \{count\}, specifying that many repetitions; \{minimum,\}, giving
287       a lower limit; and \{minimum,maximum\} finally defines a lower and
288       upper bound.
289
290       A bound appearing as the first item in a BRE is taken literally.
291
292   Bracket Expressions
293       A bracket expression is a list of characters, character ranges and
294       character classes enclosed in [ and ] and matches any single character
295       from the represented set of characters.
296
297       A character range is written as two characters separated by - and
298       represents all characters (according to the character collating
299       sequence) that are not less than the first and not greater than the
300       second.  (Ranges are very collating-sequence-dependent, and portable
301       programs should avoid relying on them.)
302
303       A character class is one of the class names
304
305          alnum     digit     punct
306          alpha     graph     space
307          blank     lower     upper
308          cntrl     print     xdigit
309
310       enclosed in [: and :] and represents the set of characters as defined
311       in ctype(3).
312
313       If the first character after [ is ^, the sense of matching is inverted.
314
315       To include a literal '"^"', place it anywhere else but first. To
316       include a literal '"]"' place it first or immediately after an initial
317       ^. To include a literal '"-"' make it the first (or second after ^) or
318       last character, or the second endpoint of a range.
319
320       The special bracket expression constructs "[[:<:]]" and "[[:>:]]" match
321       the null string at the beginning and end of a word respectively.  (Note
322       that neither is identical to Perl's '\b' atom.)
323
324   Additional Atoms
325       Since some sed implementations provide additional regular expression
326       atoms (not defined in POSIX 1003.2), psed is capable of translating the
327       following backslash escapes:
328
329       \< This is the same as "[[:>:]]".
330       \> This is the same as "[[:<:]]".
331       \w This is an abbreviation for "[[:alnum:]_]".
332       \W This is an abbreviation for "[^[:alnum:]_]".
333       \y Match the empty string at a word boundary.
334       \B Match the empty string between any two either word or non-word
335       characters.
336
337       To enable this feature, the environment variable PSEDEXTBRE must be set
338       to a string containing the requested characters, e.g.:
339       "PSEDEXTBRE='<>wW'".
340

ENVIRONMENT

342       The environment variable "PSEDEXTBRE" may be set to extend BREs.  See
343       "Additional Atoms".
344

DIAGNOSTICS

346       ambiguous translation for character '%s' in 'y' command
347           The indicated character appears twice, with different translations.
348
349       '[' cannot be last in pattern
350           A '[' in a BRE indicates the beginning of a bracket expression.
351
352       '\' cannot be last in pattern
353           A '\' in a BRE is used to make the subsequent character literal.
354
355       '\' cannot be last in substitution
356           A '\' in a substitution string is used to make the subsequent
357           character literal.
358
359       conflicting flags '%s'
360           In an s command, either the 'g' flag and an n-th occurrence flag,
361           or multiple n-th occurrence flags are specified. Note that only the
362           digits ^'1' through '9' are permitted.
363
364       duplicate label %s (first defined at %s)
365       excess address(es)
366           The command has more than the permitted number of addresses.
367
368       extra characters after command (%s)
369       illegal option '%s'
370       improper delimiter in s command
371           The BRE and substitution may not be delimited with '\' or newline.
372
373       invalid address after ','
374       invalid backreference (%s)
375           The specified backreference number exceeds the number of
376           backreferences in the BRE.
377
378       invalid repeat clause '\{%s\}'
379           The repeat clause does not contain a valid integer value, or pair
380           of values.
381
382       malformed regex, 1st address
383       malformed regex, 2nd address
384       malformed regular expression
385       malformed substitution expression
386       malformed 'y' command argument
387           The first or second string of a y command  is syntactically
388           incorrect.
389
390       maximum less than minimum in '\{%s\}'
391       no script command given
392           There must be at least one -e or one -f option specifying a script
393           or script file.
394
395       '\' not valid as delimiter in 'y' command
396       option -e requires an argument
397       option -f requires an argument
398       's' command requires argument
399       start of unterminated '{'
400       string lengths in 'y' command differ
401           The translation table strings in a y command must have equal
402           lengths.
403
404       undefined label '%s'
405       unexpected '}'
406           A } command without a preceding { command was encountered.
407
408       unexpected end of script
409           The end of the script was reached although a text line after a a, c
410           or i command indicated another line.
411
412       unknown command '%s'
413       unterminated '['
414           A BRE contains an unterminated bracket expression.
415
416       unterminated '\('
417           A BRE contains an unterminated backreference.
418
419       '\{' without closing '\}'
420           A BRE contains an unterminated bounds specification.
421
422       '\)' without preceding '\('
423       'y' command requires argument
424

EXAMPLE

426       The basic material for the preceding section was generated by running
427       the sed script
428
429          #no autoprint
430          s/^.*Warn( *"\([^"]*\)".*$/\1/
431          t process
432          b
433          :process
434          s/$!/%s/g
435          s/$[_[:alnum:]]\{1,\}/%s/g
436          s/\\\\/\\/g
437          s/^/=item /
438          p
439
440       on the program's own text, and piping the output into "sort -u".
441

SED SCRIPT TRANSLATION

443       If this program is invoked with the name s2p it will act as a sed-to-
444       Perl translator. After option processing (all other arguments are
445       ignored), a Perl program is printed on standard output, which will
446       process the input stream (as read from all arguments) in the way
447       defined by the sed script and the option setting used for the
448       translation.
449

SEE ALSO

451       perl(1), re_format(7)
452

BUGS

454       The l command will show escape characters (ESC) as '"\e"', but a
455       vertical tab (VT) in octal.
456
457       Trailing spaces are truncated from labels in :, t and b commands.
458
459       The meaning of an empty regular expression ('"//"'), as defined by sed,
460       is "the last pattern used, at run time". This deviates from the Perl
461       interpretation, which will re-use the "last successfully executed
462       regular expression". Since keeping track of pattern usage would create
463       terribly cluttered code, and differences would only appear in obscure
464       context (where other sed implementations appear to deviate, too), the
465       Perl semantics was adopted. Note that common usage of this feature,
466       such as in "/abc/s//xyz/", will work as expected.
467
468       Collating elements (of bracket expressions in BREs) are not
469       implemented.
470

STANDARDS

472       This sed implementation conforms to the IEEE Std1003.2-1992 ("POSIX.2")
473       definition of sed, and is compatible with the OpenBSD implementation,
474       except where otherwise noted (see "BUGS").
475

AUTHOR

477       This Perl implementation of sed was written by Wolfgang Laun,
478       Wolfgang.Laun@alcatel.at.
479
481       This program is free and open software. You may use, modify,
482       distribute, and sell this program (and any modified variants) in any
483       way you wish, provided you do not restrict others from doing the same.
484
485
486
487perl v5.36.0                      2023-01-19                            S2P(1)
Impressum