EDAM(1)

📦 version 1.0.2, in alpine 3.24

EDAM(1) 🌸

okay so bestie, this is the manual page for edam — a multi-file line editor with structural regular expressions — and it is lowkey iconic. buckle up, we’re going in 💅

💖 NAME 💖

edam — multi-file line editor with structural regular expressions

✨ SYNOPSIS ✨

edam [ -d ] [ files ]

edam.save

🦋 DESCRIPTION 🦋

okay so edam is a multi-file editor. it modifies a local copy of a Unix file. the copy is here called a file; a Unix file is distinguished by the trademarked adjective. the files are listed in a menu available through the n command.

each file has an associated name — usually the name of the Unix file from which it was read — and a modified bit that indicates whether the editor’s file agrees with the Unix file. the Unix file is not read into the editor’s file until it first becomes the current file — that is, the file to which editing commands apply — whereupon its menu entry is printed. periodt.

the options are:

  • -d — ignored. here for compatibility with original sam(1).

🌈 Regular expressions 🌈

regular expressions are as in egrep (see gre(1)), with the addition of @ and \n.

🚨 bestie, a regular expression may never contain a literal newline character. no cap.

the elements of regular expressions are:

  • . — match any character except newline.
  • \n — match newline.
  • \x — for any character except n, match the character (here x).
  • @ — match any character.
  • [abc] — match any character in the square brackets. \n may be mentioned.
  • [^abc] — match any character not in the square brackets, but never a newline. both these forms accept a range of characters indicated by a dash, as in a-z.
  • ^ — match the null string immediately after a newline.
  • $ — match the null string immediately before a newline.

any other character except newline matches itself.

in the following, r1 and r2 are regular expressions.

  • (r1) — match what r1 matches.
  • r1|r2 — match what r1 or what r2 matches.
  • r1* — match zero or more adjacent matches of r1.
  • r1+ — match one or more adjacent matches of r1.
  • r1? — match zero or one matches of r1.

the operators *, + and ? are highest precedence, then catenation, then | is lowest. the empty regular expression stands for the last complete expression encountered. a regular expression in edam matches the longest leftmost substring formally matched by the expression. searching in the reverse direction is equivalent to searching backwards with the catenation operations reversed in the expression.

🧚 Addresses 🧚

an address identifies a substring in a file. in the following, character n means the null string after the n-th character in the file, with 1 the first character in the file. Line n means the n-th match, starting at the beginning of the file, of the regular expression .*\n?. (the peculiar properties of a last line without a newline are temporarily undefined.) all files always have a current substring, called dot, that is the default address.

🌸 Simple Addresses 🌸

  • #n — the empty string after character n; #0 is the beginning of the file.
  • n — line n.
  • /regexp/ and ?regexp? — the substring that matches the regular expression, found by looking toward the end (/) or beginning (?) of the file, and if necessary continuing the search from the other end to the starting point of the search. the matched substring may straddle the starting point.
  • 0 — the string before the first full line. this is not necessarily the null string; see + and - below.
  • $ — the null string at the end of the file.
  • . — dot.
  • ' — the mark in the file (see the k command below).
  • "regexp" — preceding a simple address (default .), refers to the address evaluated in the unique file whose menu line matches the regular expression.

💜 Compound Addresses 💜

in the following, a1 and a2 are addresses.

  • a1+a2 — the address a2 evaluated starting at the end of a1.
  • a1-a2 — the address a2 evaluated looking in the reverse direction starting at the beginning of a1.
  • a1,a2 — the substring from the beginning of a1 to the end of a2. if a1 is missing, 0 is substituted. if a2 is missing, $ is substituted.
  • a1;a2 — like a1,a2, but with a2 evaluated at the end of, and dot set to, a1.

the operators + and - are high precedence, while , and ; are low precedence.

in both + and - forms, if a2 is a line or character address with a missing number, the number defaults to 1. if a1 is missing, . is substituted. if both a1 and a2 are present and distinguishable, + may be elided. a2 may be a regular expression; if it is delimited by ?’s, the effect of the + or - is reversed.

it is an error for a compound address to represent a malformed substring. some useful idioms: a1+- (a1-+) selects the line containing the end (beginning) of a1. 0/regexp/ locates the first match of the expression in the file. (the form 0;// sets dot unnecessarily.) ./regexp/// finds the second following occurrence of the expression, and .,/regexp/ extends dot.

🎀 Commands 🎀

in the following, text demarcated by slashes represents text delimited by any printable ASCII character except alphanumerics. any number of trailing delimiters may be elided, with multiple elisions then representing null strings, but the first delimiter must always be present. in any delimited text, newline may not appear literally; \n may be typed for newline; and \/ quotes the delimiter, here /. backslash is otherwise interpreted literally, except in s commands.

most commands may be prefixed by an address to indicate their range of operation. those that may not are marked with a * below. if a command takes an address and none is supplied, dot is used. the sole exception is the w command, which defaults to 0,$. in the description, range is used to represent whatever address is supplied. many commands set the value of dot as a side effect. if so, it is always set to the result of the change: the empty string for a deletion, the new text for an insertion, etc. (but see the s and e commands).

🫶 Text commands 🫶

  • a/text/ or a followed by lines of text, ending with . — insert the text into the file after the range. set dot.
  • c, i — same as a, but c replaces the text, while i inserts before the range.
  • d — delete the text in the range. set dot.
  • s/regexp/text/ — substitute text for the first match to the regular expression in the range. set dot to the modified range. in text, the character & stands for the string that matched the expression. backslash behaves as usual unless followed by a digit: \d stands for the string that matched the subexpression begun by the d-th left parenthesis. if s is followed immediately by a number n, as in s2/x/y/, the n-th match in the range is substituted. if the command is followed by a g, as in s/x/y/g, all matches in the range are substituted.
  • m a1, t a1 — move the range to after a1 (m), or copy it (t). set dot.

⭐ Display commands ⭐

  • p — print the text in the range. set dot.
  • = — print the line address and character address of the range.
  • =# — print just the character address of the range.

🍓 File commands 🍓

in these commands a file-list may be expressed <Unix-command, in which case the file names are taken as words (in the shell sense) generated by the Unix command.

  • * b file-list — set the current file to the first file named in the list that edam also has in its menu.
  • * B file-list — same as b, except that file names not in the menu are entered there, and all file names in the list are examined.
  • * n — print a menu of files. the format is:
    • ' or blank — indicating the file is modified or clean,
    • - or + — indicating the file is unread or has been read,
    • . or blank — indicating the current file,
    • a blank,
    • and the file name.
  • * D file-list — delete the named files from the menu. if no files are named, the current file is deleted. it is an error to D a modified file, but a subsequent D will delete such a file.

💖 I/O Commands 💖

  • * e filename — replace the file by the contents of the named Unix file. set dot to the beginning of the file.
  • r filename — replace the text in the range by the contents of the named Unix file. set dot.
  • w filename — write the range (default 0,$) to the named Unix file.
  • * f filename — set the file name and print the resulting menu entry.

if the file name is absent from any of these, the current file name is used. e always sets the file name, r and w do so if the file has no name.

  • < Unix-command — replace the range by the standard output of the Unix command.
  • > Unix-command — sends the range to the standard input of the Unix command.
  • | Unix-command — send the range to the standard input, and replace it by the standard output, of the Unix command.
  • * ! Unix-command — run the Unix command.
  • * cd directory — change working directory. if no directory is specified, $HOME is used.

in any of <, >, | or !, if the Unix command is omitted the last Unix command (of any type) is substituted.

🔥 Loops and Conditionals 🔥

  • x/regexp/ command — for each match of the regular expression in the range, run the command with dot set to the match. set dot to the last match. if the regular expression and its slashes are omitted, /.*\n/ is assumed. null string matches potentially occur before every character of the range and at the end of the range.
  • y/regexp/ command — like x, but run the command for each substring that lies before, between, or after the matches that would be generated by x. there is no default behavior. null substrings potentially occur before every character in the range.
  • * X/regexp/ command — for each file whose menu entry matches the regular expression, run the command. if the expression is omitted, the command is run in every file.
  • * Y/regexp/ command — same as X, but for files that do not match the regular expression, and the expression is required.
  • g/regexp/ command, v/regexp/ command — if the range contains (g) or does not contain (v) a match for the expression, set dot to the range and run the command.

these may be nested arbitrarily deeply, but only one instance of either X or Y may appear in a single command. an empty command in an x or y defaults to p; an empty command in X or Y defaults to f. g and v do not have defaults.

🍓 Miscellany 🍓

  • k — set the current file’s mark to the range. does not set dot.
  • q — Quit 🚪. It is an error to quit with modified files, but a second q will succeed. (Yes bestie, it's a "are you sure" that you answer by just doing it again 💀)
  • u n — Undo the last n (default 1) top-level commands that changed the contents or name of the current file, and any other file whose most recent change was simultaneous with the current file's change. Successive u's move further back in time ⏪. The only commands for which u is ineffective are cd, u, q, w and D. Not me trying to undo my undo 😭
  • (empty) — If the range is explicit, set dot to the range, and print it. If no address is specified (the command is a newline) dot is extended in either direction to line boundaries and printed. If dot is thereby unchanged, it is set to .+1 and printed.

🎀 Grouping and multiple changes 🎀

Okay so this is the part where it gets chef's kiss ✨ — commands may be grouped by enclosing them in braces {}. Commands within the braces must appear on separate lines (no backslashes are required between commands — we love low-effort syntax 💅). Semantically, an opening brace is like a command: it takes an (optional) address and sets dot for each sub-command. Commands within the braces are executed sequentially, but changes made by one command are not visible to other commands (see the next section of this manual 👀). Braces may be nested arbitrarily — go as deep as your heart desires, bestie 🌀.

When a command makes a number of changes to a file, as in x/re/c/text/, the addresses of all changes to the file are computed in the original file. If the changes are in sequence, they are applied to the file. Successive insertions at the same address are catenated into a single insertion composed of the several insertions in the order applied. 🧵

💀 Abnormal termination 💀

If edam terminates other than by a q command (by hangup, deleting its layer, etc.), modified files are saved in an executable file, $HOME/edam.save. This program, when executed, asks whether to write each file back to a Unix file. The answer y causes writing; anything else skips the file.

🚨 Real talk: if your session goes down without a q, you didn't lose everything — but you did get a whole little rescue program, so go run it 🫶.

📂 FILES 📂

  • $HOME/edam.save

👀 SEE ALSO 👀

ed(1), sam(1),

That's the whole ride, bestie — EDAM(1), page done, no cap 💖🎀🦋 Go forth and <kbd>Ctrl</kbd>-less, group your commands, and remember to q twice if you have to 😭✨

📦 where this page comes from