sam.1 (18563B)
1 .TH SAM 1 2 .ds a \fR*\ \fP 3 .SH NAME 4 sam, B, E, sam.save, samterm, samsave \- screen editor with structural regular expressions 5 .SH SYNOPSIS 6 .B sam 7 [ 8 .I option ... 9 ] [ 10 .I files 11 ] 12 .PP 13 .B sam 14 .B -r 15 .I machine 16 .PP 17 .B sam.save 18 .PP 19 .B B 20 .IB file \fR[\fP: line \fR] 21 \&... 22 .PP 23 .B E 24 .I file 25 .SH DESCRIPTION 26 .I Sam 27 is a multi-file editor. 28 It modifies a local copy of an external file. 29 The copy is here called a 30 .IR file . 31 The files are listed in a menu available through mouse button 3 32 or the 33 .B n 34 command. 35 Each file has an associated name, usually the name of the 36 external file from which it was read, and a `modified' bit that indicates whether 37 the editor's file agrees with the external file. 38 The external file is not read into 39 the editor's file until it first becomes the current file\(emthat to 40 which editing commands apply\(emwhereupon its menu entry is printed. 41 The options are 42 .TF -rmachine 43 .TP 44 .B -a 45 Autoindent. In this mode, when a newline character is typed 46 in the terminal interface, 47 .I samterm 48 copies leading white space on the current line to the new line. 49 .TP 50 .B -d 51 Do not `download' the terminal part of 52 .IR sam . 53 Editing will be done with the command language only, as in 54 .IR ed (1). 55 .TP 56 .BI -r " machine 57 Run the host part remotely 58 on the specified machine, the terminal part locally. 59 .TP 60 .BI -s " path 61 Start the host part from the specified file on the remote host. 62 Only meaningful with the 63 .BI -r 64 option. 65 .TP 66 .BI -t " path 67 Start the terminal part from the specified file. Useful 68 for debugging. 69 .PD 70 .SS Regular expressions 71 Regular expressions are as in 72 .IR regexp (7) 73 with the addition of 74 .BR \en 75 to represent newlines. 76 A regular expression may never contain a literal newline character. 77 The empty 78 regular expression stands for the last complete expression encountered. 79 A regular expression in 80 .I sam 81 matches the longest leftmost substring formally 82 matched by the expression. 83 Searching in the reverse direction is equivalent 84 to searching backwards with the catenation operations reversed in 85 the expression. 86 .SS Addresses 87 An address identifies a substring in a file. 88 In the following, `character 89 .IR n ' 90 means the null string 91 after the 92 .IR n -th 93 character in the file, with 1 the 94 first character in the file. 95 `Line 96 .IR n ' 97 means the 98 .IR n -th 99 match, 100 starting at the beginning of the file, of the regular expression 101 .LR .*\en? . 102 All files always have a current substring, called dot, 103 that is the default address. 104 .SS Simple Addresses 105 .PD 0 106 .TP 107 .BI # n 108 The empty string after character 109 .IR n ; 110 .B #0 111 is the beginning of the file. 112 .TP 113 .I n 114 Line 115 .IR n ; 116 .B 0 117 is the beginning of the file. 118 .TP 119 .BI / regexp / 120 .PD 0 121 .TP 122 .BI ? regexp ? 123 The substring that matches the regular expression, 124 found by looking toward the end 125 .RB ( / ) 126 or beginning 127 .RB ( ? ) 128 of the file, 129 and if necessary continuing the search from the other end to the 130 starting point of the search. 131 The matched substring may straddle 132 the starting point. 133 When entering a pattern containing a literal question mark 134 for a backward search, the question mark should be 135 specified as a member of a class. 136 .PD 137 .TP 138 .B 0 139 The string before the first full line. 140 This is not necessarily 141 the null string; see 142 .B + 143 and 144 .B - 145 below. 146 .TP 147 .B $ 148 The null string at the end of the file. 149 .TP 150 .B . 151 Dot. 152 .TP 153 .B \&' 154 The mark in the file (see the 155 .B k 156 command below). 157 .TP 158 \fB"\f2regexp\fB"\f1\f1 159 Preceding a simple address (default 160 .BR . ), 161 refers to the address evaluated in the unique file whose menu line 162 matches the regular expression. 163 .PD 164 .SS Compound Addresses 165 In the following, 166 .I a1 167 and 168 .I a2 169 are addresses. 170 .TF a1+a2 171 .TP 172 .IB a1 + a2 173 The address 174 .I a2 175 evaluated starting at the end of 176 .IR a1 . 177 .TP 178 .IB a1 - a2 179 The address 180 .I a2 181 evaluated looking in the reverse direction 182 starting at the beginning of 183 .IR a1 . 184 .TP 185 .IB a1 , a2 186 The substring from the beginning of 187 .I a1 188 to the end of 189 .IR a2 . 190 If 191 .I a1 192 is missing, 193 .B 0 194 is substituted. 195 If 196 .I a2 197 is missing, 198 .B $ 199 is substituted. 200 .TP 201 .IB a1 ; a2 202 Like 203 .IB a1 , a2\f1, 204 but with 205 .I a2 206 evaluated at the end of, and dot set to, 207 .IR a1 . 208 .PD 209 .PP 210 The operators 211 .B + 212 and 213 .B - 214 are high precedence, while 215 .B , 216 and 217 .B ; 218 are low precedence. 219 .PP 220 In both 221 .B + 222 and 223 .B - 224 forms, if 225 .I a2 226 is a line or character address with a missing 227 number, the number defaults to 1. 228 If 229 .I a1 230 is missing, 231 .L . 232 is substituted. 233 If both 234 .I a1 235 and 236 .I a2 237 are present and distinguishable, 238 .B + 239 may be elided. 240 .I a2 241 may be a regular 242 expression; if it is delimited by 243 .LR ? 's, 244 the effect of the 245 .B + 246 or 247 .B - 248 is reversed. 249 .PP 250 It is an error for a compound address to represent a malformed substring. 251 Some useful idioms: 252 .IB a1 +- 253 \%(\f2a1\fB-+\f1) 254 selects the line containing 255 the end (beginning) of a1. 256 .BI 0/ regexp / 257 locates the first match of the expression in the file. 258 (The form 259 .B 0;// 260 sets dot unnecessarily.) 261 .BI ./ regexp /// 262 finds the second following occurrence of the expression, 263 and 264 .BI .,/ regexp / 265 extends dot. 266 .SS Commands 267 In the following, text demarcated by slashes represents text delimited 268 by any printable 269 character except alphanumerics. 270 Any number of 271 trailing delimiters may be elided, with multiple elisions then representing 272 null strings, but the first delimiter must always 273 be present. 274 In any delimited text, 275 newline may not appear literally; 276 .B \en 277 may be typed for newline; and 278 .B \e/ 279 quotes the delimiter, here 280 .LR / . 281 Backslash is otherwise interpreted literally, except in 282 .B s 283 commands. 284 .PP 285 Most commands may be prefixed by an address to indicate their range 286 of operation. 287 Those that may not are marked with a 288 .L * 289 below. 290 If a command takes 291 an address and none is supplied, dot is used. 292 The sole exception is 293 the 294 .B w 295 command, which defaults to 296 .BR 0,$ . 297 In the description, `range' is used 298 to represent whatever address is supplied. 299 Many commands set the 300 value of dot as a side effect. 301 If so, it is always set to the `result' 302 of the change: the empty string for a deletion, the new text for an 303 insertion, etc. (but see the 304 .B s 305 and 306 .B e 307 commands). 308 .br 309 .ne 1.2i 310 .SS Text commands 311 .PD 0 312 .TP 313 .BI a/ text / 314 .TP 315 or 316 .TP 317 .B a 318 .TP 319 .I lines of text 320 .TP 321 .B . 322 Insert the text into the file after the range. 323 Set dot. 324 .PD 325 .TP 326 .B c\fP 327 .br 328 .ns 329 .TP 330 .B i\fP 331 Same as 332 .BR a , 333 but 334 .B c 335 replaces the text, while 336 .B i 337 inserts 338 .I before 339 the range. 340 .TP 341 .B d 342 Delete the text in the range. 343 Set dot. 344 .TP 345 .BI s/ regexp / text / 346 Substitute 347 .I text 348 for the first match to the regular expression in the range. 349 Set dot to the modified range. 350 In 351 .I text 352 the character 353 .B & 354 stands for the string 355 that matched the expression. 356 Backslash behaves as usual unless followed by 357 a digit: 358 .BI \e d 359 stands for the string that matched the 360 subexpression begun by the 361 .IR d -th 362 left parenthesis. 363 If 364 .I s 365 is followed immediately by a 366 number 367 .IR n , 368 as in 369 .BR s2/x/y/ , 370 the 371 .IR n -th 372 match in the range is substituted. 373 If the 374 command is followed by a 375 .BR g , 376 as in 377 .BR s/x/y/g , 378 all matches in the range 379 are substituted. 380 .TP 381 .BI m " a1 382 .br 383 .ns 384 .TP 385 .BI t " a1 386 Move 387 .RB ( m ) 388 or copy 389 .RB ( t ) 390 the range to after 391 .IR a1 . 392 Set dot. 393 .SS Display commands 394 .PD 0 395 .TP 396 .B p 397 Print the text in the range. 398 Set dot. 399 .TP 400 .B = 401 Print the line address and character address of the range. 402 .TP 403 .B =# 404 Print just the character address of the range. 405 .PD 406 .SS File commands 407 .PD 0 408 .TP 409 .BI \*ab " file-list 410 Set the current file to the first file named in the list 411 that 412 .I sam 413 also has in its menu. 414 The list may be expressed 415 .BI < "Plan 9 command" 416 in which case the file names are taken as words (in the shell sense) 417 generated by the Plan 9 command. 418 .TP 419 .BI \*aB " file-list 420 Same as 421 .BR b , 422 except that file names not in the menu are entered there, 423 and all file names in the list are examined. 424 .TP 425 .B \*an 426 Print a menu of files. 427 The format is: 428 .RS 429 .TP 11 430 .BR ' " or blank 431 indicating the file is modified or clean, 432 .TP 11 433 .BR - " or \&" + 434 indicating the file is unread or has been read 435 (in the terminal, 436 .B * 437 means more than one window is open), 438 .TP 11 439 .BR . " or blank 440 indicating the current file, 441 .TP 11 442 a blank, 443 .TP 11 444 and the file name. 445 .RE 446 .TP 0 447 .BI \*aD " file-list 448 Delete the named files from the menu. 449 If no files are named, the current file is deleted. 450 It is an error to 451 .B D 452 a modified file, but a subsequent 453 .B D 454 will delete such a file. 455 .PD 456 .SS I/O Commands 457 .PD 0 458 .TP 459 .BI \*ae " filename 460 Replace the file by the contents of the named external file. 461 Set dot to the beginning of the file. 462 .TP 463 .BI r " filename 464 Replace the text in the range by the contents of the named external file. 465 Set dot. 466 .TP 467 .BI w " filename 468 Write the range (default 469 .BR 0,$ ) 470 to the named external file. 471 .TP 472 .BI \*af " filename 473 Set the file name and print the resulting menu entry. 474 .PP 475 If the file name is absent from any of these, the current file name is used. 476 .B e 477 always sets the file name; 478 .B r 479 and 480 .B w 481 do so if the file has no name. 482 .TP 483 .BI < " Plan 9-command 484 Replace the range by the standard output of the 485 Plan 9 command. 486 .TP 487 .BI > " Plan 9-command 488 Send the range to the standard input of the 489 Plan 9 command. 490 .TP 491 .BI | " Plan 9-command 492 Send the range to the standard input, and replace it by 493 the standard output, of the 494 Plan 9 command. 495 .TP 496 .BI \*a! " Plan 9-command 497 Run the 498 Plan 9 command. 499 .TP 500 .BI \*acd " directory 501 Change working directory. 502 If no directory is specified, 503 .B $home 504 is used. 505 .PD 506 .PP 507 In any of 508 .BR < , 509 .BR > , 510 .B | 511 or 512 .BR ! , 513 if the 514 .I Plan 9 command 515 is omitted the last 516 .I Plan 9 command 517 (of any type) is substituted. 518 If 519 .I sam 520 is 521 .I downloaded 522 (using the mouse and raster display, i.e. not using option 523 .BR -d ), 524 .B ! 525 sets standard input to 526 .BR /dev/null , 527 and otherwise 528 unassigned output 529 .RB ( stdout 530 for 531 .B ! 532 and 533 .BR > , 534 .B stderr 535 for all) is placed in 536 .B /tmp/sam.err 537 and the first few lines are printed. 538 .SS Loops and Conditionals 539 .PD 0 540 .TP 541 .BI x/ regexp / " command 542 For each match of the regular expression in the range, run the command 543 with dot set to the match. 544 Set dot to the last match. 545 If the regular 546 expression and its slashes are omitted, 547 .L /.*\en/ 548 is assumed. 549 Null string matches potentially occur before every character 550 of the range and at the end of the range. 551 .TP 552 .BI y/ regexp / " command 553 Like 554 .BR x , 555 but run the command for each substring that lies before, between, 556 or after 557 the matches that would be generated by 558 .BR x . 559 There is no default regular expression. 560 Null substrings potentially occur before every character 561 in the range. 562 .TP 563 .BI \*aX/ regexp / " command 564 For each file whose menu entry matches the regular expression, 565 make that the current file and 566 run the command. 567 If the expression is omitted, the command is run 568 in every file. 569 .TP 570 .BI \*aY/ regexp / " command 571 Same as 572 .BR X , 573 but for files that do not match the regular expression, 574 and the expression is required. 575 .TP 576 .BI g/ regexp / " command 577 .br 578 .ns 579 .TP 580 .BI v/ regexp / " command 581 If the range contains 582 .RB ( g ) 583 or does not contain 584 .RB ( v ) 585 a match for the expression, 586 set dot to the range and run the command. 587 .PP 588 These may be nested arbitrarily deeply, but only one instance of either 589 .B X 590 or 591 .B Y 592 may appear in a \%single command. 593 An empty command in an 594 .B x 595 or 596 .B y 597 defaults to 598 .BR p ; 599 an empty command in 600 .B X 601 or 602 .B Y 603 defaults to 604 .BR f . 605 .B g 606 and 607 .B v 608 do not have defaults. 609 .PD 610 .SS Miscellany 611 .TF (empty) 612 .TP 613 .B k 614 Set the current file's mark to the range. Does not set dot. 615 .TP 616 .B \*aq 617 Quit. 618 It is an error to quit with modified files, but a second 619 .B q 620 will succeed. 621 .TP 622 .BI \*au " n 623 Undo the last 624 .I n 625 (default 1) 626 top-level commands that changed the contents or name of the 627 current file, and any other file whose most recent change was simultaneous 628 with the current file's change. 629 Successive 630 .BR u 's 631 move further back in time. 632 The only commands for which u is ineffective are 633 .BR cd , 634 .BR u , 635 .BR q , 636 .B w 637 and 638 .BR D . 639 If 640 .I n 641 is negative, 642 .B u 643 `redoes,' undoing the undo, going forwards in time again. 644 .TP 645 (empty) 646 If the range is explicit, set dot to the range. 647 If 648 .I sam 649 is downloaded, the resulting dot is selected on the screen; 650 otherwise it is printed. 651 If no address is specified (the 652 command is a newline) dot is extended in either direction to 653 line boundaries and printed. 654 If dot is thereby unchanged, it is set to 655 .B .+1 656 and printed. 657 .PD 658 .SS Grouping and multiple changes 659 Commands may be grouped by enclosing them in braces 660 .BR {} . 661 Commands within the braces must appear on separate lines (no backslashes are 662 required between commands). 663 Semantically, an opening brace is like a command: 664 it takes an (optional) address and sets dot for each sub-command. 665 Commands within the braces are executed sequentially, but changes made 666 by one command are not visible to other commands (see the next 667 paragraph). 668 Braces may be nested arbitrarily. 669 .PP 670 When a command makes a number of changes to a file, as in 671 .BR x/re/c/text/ , 672 the addresses of all changes to the file are computed in the original file. 673 If the changes are in sequence, 674 they are applied to the file. 675 Successive insertions at the same address are catenated into a single 676 insertion composed of the several insertions in the order applied. 677 .SS The terminal 678 What follows refers to behavior of 679 .I sam 680 when downloaded, that is, when 681 operating as a display editor on a raster display. 682 This is the default 683 behavior; invoking 684 .I sam 685 with the 686 .B -d 687 (no download) option provides access 688 to the command language only. 689 .PP 690 Each file may have zero or more windows open. 691 Each window is equivalent 692 and is updated simultaneously with changes in other windows on the same file. 693 Each window has an independent value of dot, indicated by a highlighted 694 substring on the display. 695 Dot may be in a region not within 696 the window. 697 There is usually a `current window', 698 marked with a dark border, to which typed text and editing 699 commands apply. 700 Text may be typed and edited as in 701 .IR rio (1); 702 also the escape key (ESC) selects (sets dot to) text typed 703 since the last mouse button hit. 704 .PP 705 The button 3 menu controls window operations. 706 The top of the menu 707 provides the following operators, each of which uses one or 708 more 709 .IR rio -like 710 cursors to prompt for selection of a window or sweeping 711 of a rectangle. 712 `Sweeping' a null rectangle gets a large window, disjoint 713 from the command window or the whole screen, depending on 714 where the null rectangle is. 715 .TF resize 716 .TP 717 .B new 718 Create a new, empty file. 719 .TP 720 .B zerox 721 Create a copy of an existing window. 722 .TP 723 .B resize 724 As in 725 .IR rio . 726 .TP 727 .B close 728 Delete the window. 729 In the last window of a file, 730 .B close 731 is equivalent to a 732 .B D 733 for the file. 734 .TP 735 .B write 736 Equivalent to a 737 .B w 738 for the file. 739 .PD 740 .PP 741 Below these operators is a list of available files, starting with 742 .BR ~~sam~~ , 743 the command window. 744 Selecting a file from the list makes the most recently 745 used window on that file current, unless it is already current, in which 746 case selections cycle through the open windows. 747 If no windows are open 748 on the file, the user is prompted to open one. 749 Files other than 750 .B ~~sam~~ 751 are marked with one of the characters 752 .B -+* 753 according as zero, one, or more windows 754 are open on the file. 755 A further mark 756 .L . 757 appears on the file in the current window and 758 a single quote, 759 .BR ' , 760 on a file modified since last write. 761 .PP 762 The command window, created automatically when 763 .B sam 764 starts, is an ordinary window except that text typed to it 765 is interpreted as commands for the editor rather than passive text, 766 and text printed by editor commands appears in it. 767 The behavior is like 768 .IR rio , 769 with an `output point' that separates commands being typed from 770 previous output. 771 Commands typed in the command window apply to the 772 current open file\(emthe file in the most recently 773 current window. 774 .SS Manipulating text 775 Button 1 changes selection, much like 776 .IR rio . 777 Pointing to a non-current window with button 1 makes it current; 778 within the current window, button 1 selects text, thus setting dot. 779 Double-clicking selects text to the boundaries of words, lines, 780 quoted strings or bracketed strings, depending on the text at the click. 781 .PP 782 Button 2 provides a menu of editing commands: 783 .TF /regexp 784 .TP 785 .B cut 786 Delete dot and save the deleted text in the snarf buffer. 787 .TP 788 .B paste 789 Replace the text in dot by the contents of the snarf buffer. 790 .TP 791 .B snarf 792 Save the text in dot in the snarf buffer. 793 .TP 794 .B plumb 795 Send the text in the selection as a plumb 796 message. If the selection is empty, 797 the white-space-delimited block of text is sent as a plumb message 798 with a 799 .B click 800 attribute defining where the selection lies (see 801 .IR plumb (7)). 802 .TP 803 .B look 804 Search forward for the next occurrence of the literal text in dot. 805 If dot is the null string, the text in the snarf buffer is 806 used. 807 The snarf buffer is unaffected. 808 .TP 809 .B <rio> 810 Exchange snarf buffers with 811 .IR rio . 812 .TP 813 .BI / regexp 814 Search forward for the next match of the last regular expression 815 typed in a command. 816 (Not in command window.) 817 .TP 818 .B send 819 Send the text in dot, or the snarf buffer if 820 dot is the null string, as if it were typed to the command window. 821 Saves the sent text in the snarf buffer. 822 (Command window only.) 823 .PD 824 .SS External communication 825 .I Sam 826 listens to the 827 .B edit 828 plumb port. 829 If plumbing is not active, 830 on invocation 831 .I sam 832 creates a named pipe 833 .BI /srv/sam. user 834 which acts as an additional source of commands. Characters written to 835 the named pipe are treated as if they had been typed in the command window. 836 .PP 837 .I B 838 is a shell-level command that causes an instance of 839 .I sam 840 running on the same terminal to load the named 841 .IR files . 842 .I B 843 uses either plumbing or the named pipe, whichever service is available. 844 If plumbing is not enabled, 845 the option allows a line number to be specified for 846 the initial position to display in the last named file 847 (plumbing provides a more general mechanism for this ability). 848 .PP 849 .I E 850 is a shell-level command that can be used as 851 .B $EDITOR 852 in a Unix environment. 853 It runs 854 .I B 855 on 856 .I file 857 and then does not exit until 858 .I file 859 is changed, which is taken as a signal that 860 .I file 861 is done being edited. 862 .SS Abnormal termination 863 If 864 .I sam 865 terminates other than by a 866 .B q 867 command (by hangup, deleting its window, etc.), modified 868 files are saved in an 869 executable file, 870 .BR $HOME/sam.save . 871 This program, when executed, asks whether to write 872 each file back to a external file. 873 The answer 874 .L y 875 causes writing; anything else skips the file. 876 .SH FILES 877 .TF $HOME/sam.save 878 .TP 879 .B $HOME/sam.save 880 .TP 881 .B $HOME/sam.err 882 .TP 883 .B \*9/bin/samsave 884 the program called to unpack 885 .BR $HOME/sam.save . 886 .SH SOURCE 887 .TF \*9/src/cmd/samterm 888 .TP 889 .B \*9/src/cmd/sam 890 source for 891 .I sam 892 itself 893 .TP 894 .B \*9/src/cmd/samterm 895 source for the separate terminal part 896 .TP 897 .B \*9/bin/B 898 .TP 899 .B \*9/bin/E 900 .SH SEE ALSO 901 .IR ed (1), 902 .IR sed (1), 903 .IR grep (1), 904 .IR rio (1), 905 .IR regexp (7). 906 .PP 907 Rob Pike, 908 ``The text editor sam''.