Documentation
¶
Overview ¶
Package sed implements the sed builtin command.
sed — stream editor for filtering and transforming text
Usage: sed [OPTION]... [script] [FILE]...
sed [OPTION]... -e script [-e script]... [FILE]...
sed reads input files (or standard input if no files are given, or when FILE is -), applies editing commands from the script, and writes the result to standard output.
Accepted flags:
-n, --quiet, --silent
Suppress automatic printing of pattern space. Only lines
explicitly printed via the p command are output.
-e script, --expression=script
Add the script commands to the set of commands to execute.
Multiple -e options are allowed; they are concatenated in order.
-E, --regexp-extended
Use extended regular expressions (ERE) rather than basic (BRE).
-r
GNU alias for -E (extended regular expressions).
-h, --help
Print this usage message to stdout and exit 0.
Supported sed commands:
s/regex/replacement/[flags] Substitute matches of regex with replacement.
Flags: g (global), p (print), i/I (case-insensitive),
N (replace Nth match).
p Print the current pattern space.
d Delete pattern space, start next cycle.
q [code] Quit with optional exit code (prints pattern space first).
Q [code] Quit with optional exit code (does not print).
y/src/dst/ Transliterate characters from src to dst.
a\text / a text Append text after the current line.
i\text / i text Insert text before the current line.
c\text / c text Replace line(s) with text.
= Print the current line number.
l Print pattern space unambiguously.
n Read next input line into pattern space.
N Append next input line to pattern space.
h Copy pattern space to hold space.
H Append pattern space to hold space.
g Copy hold space to pattern space.
G Append hold space to pattern space.
x Exchange pattern and hold spaces.
b [label] Branch to label (or end of script).
: label Define a label for branching.
t [label] Branch to label if s/// made a substitution.
T [label] Branch to label if s/// did NOT make a substitution.
{...} Group commands.
!command Negate the address (apply to non-matching lines).
Addressing:
N Line number (1-based). $ Last line. /regex/ Lines matching regex. addr1,addr2 Range of lines. first~step Every step-th line starting from first (GNU extension).
Rejected commands (blocked for safety):
e Execute pattern space as shell command (blocked: command execution). w file Write pattern space to file (blocked: file write). W file Write first line to file (blocked: file write). r file Read file contents (blocked: unsandboxed file read). R file Read one line from file (blocked: unsandboxed file read).
In-place editing:
-i, --in-place Edit files in place. Only available in remediation
mode; refused with an error in the default read-only
mode. Backup-suffix forms (-i.bak, --in-place=.bak)
are not supported since this shell has no rename
primitive to create the backup atomically. An
explicit "=value" form (-i=.bak, --in-place=.bak) is
rejected with an error, and so is a suffix attached
directly to the cluster whose characters are not
themselves valid short flags (-i.bak: pflag itself
rejects it with "invalid option -- '.'", and the
edit does not happen). Only when every character of
an attached suffix with no "=" happens to also be a
valid *boolean* short flag (-iE, -niE) does the whole
token instead parse, per standard pflag/getopt short-
cluster parsing (see docs/RULES.md's flag-parsing
rules, which require pflag and prohibit hand-rolled
pre-scan loops), as -i followed by more combined
single-character flags (-iE enables -i and -E,
silently discarding any backup-suffix intent rather
than rejecting it, and the edit does happen in that
case) — a deliberate, documented divergence from GNU
sed's -i[SUFFIX], since this shell never creates the
backup file either way. This does not hold once the
cluster reaches -e (the one sed short flag that takes
a value): pflag stops there and consumes the rest of
the token (or the entire next argument, if nothing
follows in the same token) as -e's expression value
instead of parsing it as further combined flags
(-ien 's/a/b/' f parses as -i plus -e n, not -i/-e/-n,
leaving 's/a/b/' and f as file operands). Each input file is treated as
a separate stream (line numbers, $, and the hold
space all reset per file; the last-used regex for an
empty // pattern persists across files, matching GNU
sed -s), and the entire rewritten contents of a file
are buffered in memory (capped at MaxInPlaceOutputBytes)
before being written back, since the sandbox has no
atomic replace. "-" (standard input) is rejected as an
-i target. Unlike the streaming default mode (which
intentionally always terminates output with a newline
for consistent AI-agent-facing stdout), -i reproduces
GNU sed's on-disk behaviour exactly, including a file
whose last line has no trailing newline. The
destructive write is pinned to the exact file that was
read (via Sandbox.WriteRegularFile's expectedIdentity
check) so a path swapped for a different file between
the read and the write is rejected rather than
silently overwritten with content derived from the
wrong file.
Rejected flags:
-f, --file Read script from file (not implemented).
-s, --separate Treat files as separate streams (not implemented
as a standalone flag; -i always behaves this way).
-z, --null-data NUL-separated input (not implemented).
Exit codes:
0 Success (or custom code via q/Q command). 1 Invalid script syntax, missing file, or other error.
Memory safety:
Input is processed line-by-line via a buffered scanner with a per-line cap of 1 MiB (MaxLineBytes). Pattern space and hold space are each bounded to MaxSpaceBytes (1 MiB). Branch loops are capped at MaxBranchIterations (10 000) per input line to prevent infinite loops. Non-regular-file inputs are subject to a MaxTotalReadBytes (256 MiB) limit to guard against infinite sources.
Regex safety:
All regular expressions use Go's regexp package, which implements RE2 (guaranteed linear-time matching, no backtracking). This prevents ReDoS attacks. BRE patterns are converted to ERE syntax before compilation.
Index ¶
Constants ¶
const MaxAppendQueueBytes = 1 << 20 // 1 MiB
MaxAppendQueueBytes is the maximum total bytes that can be accumulated in the append queue within a single cycle.
const MaxBranchIterations = 10_000
MaxBranchIterations is the maximum number of branch iterations per input line to prevent infinite loops.
const MaxInPlaceOutputBytes = 256 << 20 // 256 MiB
MaxInPlaceOutputBytes is the maximum size of the rewritten contents of a single file that -i will buffer in memory before writing it back, and also the maximum size of the original content -i backs up in memory before the destructive write so a failed write-back (e.g. disk full) can be restored (see engine.go's writeBack). Unlike the streaming default mode, -i must hold both the entire rewritten file and a backup of the original in memory at once, because the sandbox has no atomic rename/replace primitive: the output can only be committed by reopening the same path for writing after the whole transformation has completed successfully, and doing so without a backup would risk destroying the original on a transient write failure. The two retained data buffers can therefore total 512 MiB. Their capacities are capped individually; transient growth copies and engine/scanner state add overhead, so this is not a process-wide or peak-memory limit.
const MaxLineBytes = 1 << 20 // 1 MiB
MaxLineBytes is the per-line buffer cap for the line scanner.
const MaxSpaceBytes = 1 << 20 // 1 MiB
MaxSpaceBytes is the maximum size for pattern space and hold space.
const MaxTotalReadBytes = 256 << 20 // 256 MiB
MaxTotalReadBytes is the maximum total bytes consumed from a single non-regular-file input source.
Variables ¶
var Cmd = builtins.Command{
Name: "sed",
Description: "stream editor for filtering and transforming text",
MakeFlags: registerFlags,
}
Cmd is the sed builtin command descriptor.
Functions ¶
This section is empty.
Types ¶
This section is empty.
Source Files