sam.tut 40 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307130813091310131113121313131413151316131713181319132013211322132313241325132613271328132913301331133213331334133513361337133813391340134113421343134413451346134713481349135013511352135313541355135613571358135913601361136213631364136513661367136813691370137113721373137413751376137713781379138013811382138313841385138613871388138913901391139213931394139513961397139813991400140114021403140414051406140714081409141014111412141314141415141614171418141914201421142214231424142514261427142814291430143114321433143414351436143714381439144014411442144314441445144614471448144914501451145214531454145514561457145814591460146114621463146414651466146714681469147014711472147314741475147614771478147914801481148214831484148514861487148814891490149114921493149414951496149714981499150015011502150315041505150615071508150915101511151215131514151515161517151815191520152115221523152415251526152715281529153015311532153315341535153615371538153915401541154215431544154515461547154815491550155115521553155415551556155715581559156015611562156315641565156615671568156915701571157215731574157515761577157815791580158115821583158415851586158715881589159015911592159315941595159615971598159916001601160216031604160516061607160816091610161116121613161416151616161716181619162016211622162316241625162616271628162916301631163216331634163516361637163816391640164116421643164416451646164716481649165016511652165316541655165616571658165916601661166216631664166516661667166816691670167116721673167416751676167716781679168016811682168316841685168616871688168916901691169216931694169516961697169816991700170117021703170417051706170717081709171017111712171317141715171617171718171917201721172217231724172517261727172817291730173117321733173417351736173717381739174017411742174317441745174617471748174917501751175217531754175517561757175817591760176117621763176417651766176717681769177017711772177317741775177617771778177917801781178217831784
  1. .de P1
  2. .KS
  3. .DS
  4. .ft CW
  5. .ta 5n 10n 15n 20n 25n 30n 35n 40n 45n 50n 55n 60n 65n 70n 75n 80n
  6. ..
  7. .de P2
  8. .ft 1
  9. .DE
  10. .KE
  11. ..
  12. .de CW
  13. .lg 0
  14. \%\&\\$3\f(CW\\$1\fP\&\\$2
  15. .lg
  16. ..
  17. .de WC
  18. .lg 0
  19. \%\&\\$3\f(CS\\$1\fP\&\\$2
  20. .lg
  21. ..
  22. .TL
  23. A tutorial for the
  24. .CW sam
  25. .B
  26. command language
  27. .AU
  28. Rob Pike
  29. .AI
  30. .MH
  31. .AB
  32. .CW sam
  33. is an interactive text editor with a command language that makes heavy use
  34. of regular expressions.
  35. Although the language is syntactically similar to
  36. .CW ed (1),
  37. the details are interestingly different.
  38. This tutorial introduces the command language, but does not discuss
  39. the screen and mouse interface.
  40. With apologies to those unfamiliar with the Ninth Edition Blit software,
  41. it is assumed that the similarity of
  42. .CW sam
  43. to
  44. .CW mux (9)
  45. at this level makes
  46. .CW sam 's
  47. mouse language easy to learn.
  48. .PP
  49. The
  50. .CW sam
  51. command language applies identically to two environments:
  52. when running
  53. .CW sam
  54. on an ordinary terminal
  55. (\f2via\f1\f1
  56. .CW sam\ -d ),
  57. and in the command window of a
  58. .I downloaded
  59. .CW sam ,
  60. that is, one using the bitmap display and mouse.
  61. .AE
  62. .SH
  63. Introduction
  64. .PP
  65. This tutorial describes the command language of
  66. .CW sam ,
  67. an interactive text editor that runs on Blits and
  68. some computers with bitmap displays.
  69. For most editing tasks, the mouse-based editing features
  70. are sufficient, and they are easy to use and to learn.
  71. .PP
  72. The command language is often useful, however, particularly
  73. when making global changes.
  74. Unlike the commands in
  75. .CW ed ,
  76. which are necessary to make changes,
  77. .CW sam
  78. commands tend to be used
  79. only for complicated or repetitive editing tasks.
  80. It is in these more involved uses that
  81. the differences between
  82. .CW sam
  83. and other text editors are most evident.
  84. .PP
  85. .CW sam 's
  86. language makes it easy to do some things that other editors,
  87. including programs like
  88. .CW sed
  89. and
  90. .CW awk ,
  91. do not handle gracefully, so this tutorial serves partly as a
  92. lesson in
  93. .CW sam 's
  94. manner of manipulating text.
  95. The examples below therefore concentrate entirely on the language,
  96. assuming that facility with the use of the mouse in
  97. .CW sam
  98. is at worst easy to pick up.
  99. In fact,
  100. .CW sam
  101. can be run without the mouse at all (not
  102. .I downloaded ),
  103. by specifying the
  104. .CW -d
  105. flag, and it is this domain that the tutorial
  106. occupies; the command language in these modes
  107. are identical.
  108. .PP
  109. A word to the Unix adept:
  110. although
  111. .CW sam
  112. is syntactically very similar to
  113. .CW ed ,
  114. it is fundamentally and deliberately different in design and detailed semantics.
  115. You might use knowledge of
  116. .CW ed
  117. to predict how the substitute command works,
  118. but you'd only be right if you had used some understanding of
  119. .CW sam 's
  120. workings to influence your prediction.
  121. Be particularly careful about idioms.
  122. Idioms form in curious nooks of languages and depend on
  123. undependable peculiarities.
  124. .CW ed
  125. idioms simply don't work in
  126. .CW sam :
  127. .CW 1,$s/a/b/
  128. makes one substitution in the whole file, not one per line.
  129. .CW sam
  130. has its own idioms.
  131. Much of the purpose of this tutorial is to publish them
  132. and make fluency in
  133. .CW sam
  134. a matter of learning, not cunning.
  135. .PP
  136. The tutorial depends on familiarity with regular expressions, although
  137. some experience with a more traditional Unix editor may be helpful.
  138. To aid readers familiar with
  139. .CW ed ,
  140. I have pointed out in square brackets [] some of
  141. the relevant differences between
  142. .CW ed
  143. and
  144. .CW sam .
  145. Read these comments only if you wish
  146. to understand the differences; the lesson is about
  147. .CW sam ,
  148. not
  149. .CW sam
  150. .I vs.
  151. .CW ed .
  152. Another typographic convention is that output appears in
  153. .CW "this font,
  154. while typed input appears as
  155. .WC "slanty text.
  156. .PP
  157. Nomenclature:
  158. .CW sam
  159. keeps a copy of the text it is editing.
  160. This copy is called a
  161. .I file .
  162. To avoid confusion, I have called the permanent storage on disc a
  163. .I
  164. Unix file.
  165. .R
  166. .SH
  167. Text
  168. .PP
  169. To get started, we need some text to play with.
  170. Any text will do; try something from
  171. James Gosling's Emacs manual:
  172. .P1
  173. $ \f(CSsam -d
  174. a
  175. This manual is organized in a rather haphazard manner. The first
  176. several sections were written hastily in an attempt to provide a
  177. general introduction to the commands in Emacs and to try to show
  178. the method in the madness that is the Emacs command structure.
  179. \&.
  180. .ft
  181. .P2
  182. .WC "sam -d
  183. starts
  184. .CW sam
  185. running.
  186. The
  187. .CW a
  188. command adds text until a line containing just a period, and sets the
  189. .I
  190. current text
  191. .R
  192. (also called
  193. .I dot )
  194. to what was typed \(em everything between the
  195. .CW a
  196. and the period.
  197. .CW ed "" [
  198. would leave dot set to only the last line.]
  199. The
  200. .CW p
  201. command prints the current text:
  202. .P1
  203. .WC p
  204. This manual is organized in a rather haphazard manner. The first
  205. several sections were written hastily in an attempt to provide a
  206. general introduction to the commands in Emacs and to try to show
  207. the method in the madness that is the Emacs command structure.
  208. .P2
  209. [Again,
  210. .CW ed
  211. would print only the last line.]
  212. The
  213. .CW a
  214. command adds its text
  215. .I after
  216. dot; the
  217. .CW i
  218. command is like
  219. .CW a,
  220. but adds the text
  221. .I before
  222. dot.
  223. .P1
  224. .ft CS
  225. i
  226. Introduction
  227. \&.
  228. p
  229. .ft
  230. Introduction
  231. .P2
  232. There is also a
  233. .CW c
  234. command that changes (replaces) the current text,
  235. and
  236. .CW d
  237. that deletes it; these are illustrated below.
  238. .PP
  239. To see all the text, we can specify what text to print;
  240. for the moment, suffice it to say that
  241. .WC 0,$
  242. specifies the entire file.
  243. .CW ed "" [
  244. users would probably type
  245. .WC 1,$ ,
  246. which in practice is the same thing, but see below.]
  247. .P1
  248. .WC 0,$p
  249. Introduction
  250. This manual is organized in a rather haphazard manner. The first
  251. several sections were written hastily in an attempt to provide a
  252. general introduction to the commands in Emacs and to try to show
  253. the method in the madness that is the Emacs command structure.
  254. .P2
  255. Except for the
  256. .CW w
  257. command described below,
  258. .I all
  259. commands,
  260. including
  261. .CW p ,
  262. set dot to the text they touch.
  263. Thus,
  264. .CW a
  265. and
  266. .CW i
  267. set dot to the new text,
  268. .CW p
  269. to the text printed, and so on.
  270. Similarly, all commands
  271. (except
  272. .CW w )
  273. by default operate on the current
  274. text [unlike
  275. .CW ed ,
  276. for which some commands (such as
  277. .CW g )
  278. default to the entire file].
  279. .PP
  280. Things are not going to get very interesting until we can
  281. set dot arbitrarily.
  282. This is done by
  283. .I addresses ,
  284. which specify a piece of the file.
  285. The address
  286. .CW 1 ,
  287. for example, sets dot to the first line of the file.
  288. .P1
  289. .WC 1p
  290. Introduction
  291. .WC c
  292. .WC Preamble
  293. .WC .
  294. .P2
  295. The
  296. .CW c
  297. command didn't need to specify dot; the
  298. .CW p
  299. left it on line one.
  300. It's therefore easy to delete the first line utterly;
  301. the last command left dot set to line one:
  302. .P1
  303. .WC d
  304. .WC 1p
  305. This manual is organized in a rather haphazard manner. The first
  306. .P2
  307. (Line numbers change
  308. to reflect changes to the file.)
  309. .PP
  310. The address \f(CW/\f2text\f(CW/\f1
  311. sets dot to the first appearance of
  312. .I text ,
  313. after dot.
  314. .CW ed "" [
  315. matches the first line containing
  316. .I text .]
  317. If
  318. .I text
  319. is not found, the search restarts at the beginning of the file
  320. and continues until dot.
  321. .P1
  322. .WC /Emacs/p
  323. Emacs
  324. .P2
  325. It's difficult to indicate typographically, but in this example no newline appears
  326. after
  327. .CW Emacs :
  328. the text to be printed is the string
  329. .CW Emacs ', `
  330. exactly.
  331. (The final
  332. .CW p
  333. may be left off \(em it is the default command.
  334. When downloaded, however, the default is instead to select the text,
  335. to highlight it,
  336. and to make it visible by moving the window on the file if necessary.
  337. Thus,
  338. .CW /Emacs/
  339. indicates on the display the next occurrence of the text.)
  340. .PP
  341. Imagine we wanted to change the word
  342. .CW haphazard
  343. to
  344. .CW thoughtless .
  345. Obviously, what's needed is another
  346. .CW c
  347. command, but the method used so far to insert text includes a newline.
  348. The syntax for including text without newlines is to surround the
  349. text with slashes (which is the same as the syntax for
  350. text searches, but what is going on should be clear from context).
  351. The text must appear immediately after the
  352. .CW c
  353. (or
  354. .CW a
  355. or
  356. .CW i ).
  357. Given this, it is easy to make the required change:
  358. .P1
  359. .WC /haphazard/c/thoughtless/
  360. .WC 1p
  361. This manual is organized in a rather thoughtless manner. The first
  362. .P2
  363. [Changes can always be done with a
  364. .CW c
  365. command, even if the text is smaller than a line].
  366. You'll find that this way of providing text to commands is much
  367. more common than is the multiple-lines syntax.
  368. If you want to include a slash
  369. .CW /
  370. in the text, just precede it with a backslash
  371. .CW \e ,
  372. and use a backslash to protect a backslash itself.
  373. .P1
  374. .WC /Emacs/c/Emacs\e\e360/
  375. .WC 4p
  376. general introduction to the commands in Emacs\e360 and to try to show
  377. .P2
  378. We could also make this particular change by
  379. .P1
  380. .WC /Emacs/a/\e\e360/
  381. .P2
  382. .PP
  383. This is as good a place as any to introduce the
  384. .CW u
  385. command, which undoes the last command.
  386. A second
  387. .CW u
  388. will undo the penultimate command, and so on.
  389. .P1
  390. .WC u
  391. .WC 4p
  392. general introduction to the commands in Emacs and to try to show
  393. .WC u
  394. .WC 3p
  395. This manual is organized in a rather haphazard manner. The first
  396. .P2
  397. Undoing can only back up; there is no way to undo a previous
  398. .CW u .
  399. .SH
  400. Addresses
  401. .PP
  402. We've seen the simplest forms of addresses, but there is more
  403. to learn before we can get too much further.
  404. An address selects a region in the file \(em a substring \(em
  405. and therefore must define the beginning and the end of a region.
  406. Thus, the address
  407. .CW 13
  408. selects from the beginning of line thirteen to the end of line thirteen, and
  409. .CW /Emacs/
  410. selects from the beginning of the word
  411. .CW Emacs ' `
  412. to the end.
  413. .PP
  414. Addresses may be combined with a comma:
  415. .P1
  416. 13,15
  417. .P2
  418. selects lines thirteen through fifteen. The definition of the comma
  419. operator is to select from the beginning of the left hand address (the
  420. beginning of line 13) to the end of the right hand address (the
  421. end of line 15).
  422. .PP
  423. A few special simple addresses come in handy:
  424. .CW .
  425. (a period) represents dot, the current text,
  426. .CW 0
  427. (line zero) selects the null string at the beginning of the file, and
  428. .CW $
  429. selects the null string at the end of the file
  430. [not the last line of the file].
  431. Therefore,
  432. .P1
  433. 0,13
  434. .P2
  435. selects from the beginning of the file to the end of line thirteen,
  436. .P1
  437. \&.,$
  438. .P2
  439. selects from the beginning of the current text to the end of the file, and
  440. .P1
  441. 0,$
  442. .P2
  443. selects the whole file [that is, a single string containing the whole file,
  444. not a list of all the lines in the file].
  445. .PP
  446. These are all
  447. .I absolute
  448. addresses: they refer to specific places in the file.
  449. .CW sam
  450. also has relative addresses, which depend
  451. on the value of dot,
  452. and in fact we have already seen one form:
  453. .CW /Emacs/
  454. finds the first occurrence of
  455. .CW Emacs
  456. searching forwards from dot.
  457. Which occurrence of
  458. .CW Emacs
  459. it finds depends on the value of dot.
  460. What if you wanted the first occurrence
  461. .CW before
  462. dot? Just precede the pattern with a minus sign, which reverses the direction
  463. of the search:
  464. .P1
  465. -/Emacs/
  466. .P2
  467. In fact, the complete syntax for forward searching is
  468. .P1
  469. +/Emacs/
  470. .P2
  471. but the plus sign is the default, and in practice is rarely used.
  472. Here is an example that includes it for clarity:
  473. .P1
  474. 0+/Emacs/
  475. .P2
  476. selects the first occurrence of
  477. .CW Emacs
  478. in the file; read it as ``go to line 0, then search forwards for
  479. .CW Emacs .''
  480. Since the
  481. .CW +
  482. is optional, this can be written
  483. .CW 0/Emacs/ .
  484. Similarly,
  485. .P1
  486. $-/Emacs/
  487. .P2
  488. finds the last occurrence in the file, so
  489. .P1
  490. 0/Emacs/,$-/Emacs/
  491. .P2
  492. selects the text from the first to last
  493. .CW Emacs ,
  494. inclusive.
  495. Slightly more interesting:
  496. .P1
  497. /Emacs/+/Emacs/
  498. .P2
  499. (there is an implicit
  500. .CW .+
  501. at the beginning) selects the second
  502. .CW Emacs
  503. following dot.
  504. .PP
  505. Line numbers may also be relative.
  506. .P1
  507. -2
  508. .P2
  509. selects the second previous line, and
  510. .P1
  511. +5
  512. .P2
  513. selects the fifth following line (here the plus sign is obligatory).
  514. .PP
  515. Since addresses may select (and dot may be) more than one line,
  516. we need a definition of `previous' and `following:'
  517. `previous' means
  518. .I
  519. before the beginning
  520. .R
  521. of dot, and `following'
  522. means
  523. .I
  524. after the end
  525. .R
  526. of dot.
  527. For example, if the file contains \f(CWA\f(CSAA\f(CWA\f1,
  528. with dot set to the middle two
  529. .CW A 's
  530. (the slanting characters),
  531. .CW -/A/
  532. sets dot to the first
  533. .CW A ,
  534. and
  535. .CW +/A/
  536. sets dot to the last
  537. .CW A .
  538. Except under odd circumstances (such as when the only occurrence of the
  539. text in the file is already the current text), the text selected by a
  540. search will be disjoint from dot.
  541. .PP
  542. To select the
  543. .CW "troff -ms
  544. paragraph containing dot, however long it is, use
  545. .P1
  546. -/.PP/,/.PP/-1
  547. .P2
  548. which will include the
  549. .CW .PP
  550. that begins the paragraph, and exclude the one that ends it.
  551. .PP
  552. When typing relative line number addresses, the default number is
  553. .CW 1 ,
  554. so the above could be written slightly more simply:
  555. .P1
  556. -/.PP/,/.PP/-
  557. .P2
  558. .PP
  559. What does the address
  560. .CW +1-1
  561. or the equivalent
  562. .CW +-
  563. mean? It looks like it does nothing, but recall that dot need not be a
  564. complete line of text.
  565. .CW +1
  566. selects the line after the end of the current text, and
  567. .CW -1
  568. selects the line before the beginning. Therefore
  569. .CW +1-1
  570. selects the line before the line after the end of dot, that is,
  571. the complete line containing the end of dot.
  572. We can use this construction to expand a selection to include a complete line,
  573. say the first line in the file containing
  574. .CW Emacs :
  575. .P1
  576. .WC 0/Emacs/+-p
  577. general introduction to the commands in Emacs and to try to show
  578. .P2
  579. The address
  580. .CW +-
  581. is an idiom.
  582. .SH
  583. Loops
  584. .PP
  585. Above, we changed one occurrence of
  586. .CW Emacs
  587. to
  588. .CW Emacs\e360 ,
  589. but if the name of the editor is really changing, it would be useful
  590. to change
  591. .I all
  592. instances of the name in a single command.
  593. .CW sam
  594. provides a command,
  595. .CW x
  596. (extract), for just that job.
  597. The syntax is
  598. \f(CWx/\f2pattern\f(CW/\f2command\f1.
  599. For each occurrence of the pattern in the selected text,
  600. .CW x
  601. sets dot to the occurrence and runs command.
  602. For example, to change
  603. .CW Emacs
  604. to
  605. .CW vi,
  606. .P1
  607. .WC 0,$x/Emacs/c/vi/
  608. .WC 0,$p
  609. This manual is organized in a rather haphazard manner. The first
  610. several sections were written hastily in an attempt to provide a
  611. general introduction to the commands in vi and to try to show
  612. the method in the madness that is the vi command structure.
  613. .P2
  614. This
  615. works by subdividing the current text
  616. .CW 0,$ "" (
  617. \(em the whole file) into appearances of its textual argument
  618. .CW Emacs ), (
  619. and then running the command that follows
  620. .CW c/vi/ ) (
  621. with dot set to the text.
  622. We can read this example as, ``find all occurrences of
  623. .CW Emacs
  624. in the file, and for each one,
  625. set the current text to the occurrence and run the command
  626. .CW c/vi/ ,
  627. which will replace the current text by
  628. .CW vi. ''
  629. [This command is somewhat similar to
  630. .CW ed 's
  631. .CW g
  632. command. The differences will develop below, but note that the
  633. default address, as always, is dot rather than the whole file.]
  634. .PP
  635. A single
  636. .CW u
  637. command is sufficient to undo an
  638. .CW x
  639. command, regardless of how many individual changes the
  640. .CW x
  641. makes.
  642. .P1
  643. .WC u
  644. .WC 0,$p
  645. This manual is organized in a rather haphazard manner. The first
  646. several sections were written hastily in an attempt to provide a
  647. general introduction to the commands in Emacs and to try to show
  648. the method in the madness that is the Emacs command structure.
  649. .P2
  650. .PP
  651. Of course,
  652. .CW c
  653. is not the only command
  654. .CW x
  655. can run. An
  656. .CW a
  657. command can be used to put proprietary markings on
  658. .CW Emacs :
  659. .P1
  660. .WC 0,$x/Emacs/a/{TM}/
  661. .WC /Emacs/+-p
  662. general introduction to the commands in Emacs{TM} and to try to show
  663. .P2
  664. [There is no way to see the changes as they happen, as in
  665. .CW ed 's
  666. .CW g/Emacs/s//&{TM}/p ;
  667. see the section on Multiple Changes, below.]
  668. .PP
  669. The
  670. .CW p
  671. command is also useful when driven by an
  672. .CW x ,
  673. but be careful that you say what you mean;
  674. .P1
  675. .WC 0,$x/Emacs/p
  676. EmacsEmacs
  677. .P2
  678. since
  679. .CW x
  680. sets dot to the text in the slashes, printing only that text
  681. is not going to be very
  682. informative. But the command that
  683. .CW x
  684. runs can contain addresses. For example, if we want to print all
  685. lines containing
  686. .CW Emacs ,
  687. just use
  688. .CW +- :
  689. .P1
  690. .WC 0,$x/Emacs/+-p
  691. general introduction to the commands in Emacs{TM} and to try to show
  692. the method in the madness that is the Emacs{TM} command structure.
  693. .P2
  694. Finally, let's restore the state of the file with another
  695. .CW x
  696. command, and make use of a handy shorthand:
  697. a comma in an address has its left side default to
  698. .CW 0 ,
  699. and its right side default to
  700. .CW $ ,
  701. so the easy-to-type address
  702. .CW ,
  703. refers to the whole file:
  704. .P1
  705. .WC ",x/Emacs/ /{TM}/d
  706. .WC ,p
  707. This manual is organized in a rather haphazard manner. The first
  708. several sections were written hastily in an attempt to provide a
  709. general introduction to the commands in Emacs and to try to show
  710. the method in the madness that is the Emacs command structure.
  711. .P2
  712. Notice what this
  713. .CW x
  714. does: for each occurrence of Emacs,
  715. find the
  716. .CW {TM}
  717. that follows, and delete it.
  718. .PP
  719. The `text'
  720. .CW sam
  721. accepts
  722. for searches in addresses and in
  723. .CW x
  724. commands is not simple text, but rather
  725. .I regular\ expressions.
  726. Unix has several distinct interpretations of regular expressions.
  727. The form used by
  728. .CW sam
  729. is that of
  730. .CW egrep (1),
  731. including parentheses
  732. .CW ()
  733. for grouping and an `or' operator
  734. .CW |
  735. for matching strings in parallel.
  736. .CW sam
  737. makes two extensions:
  738. although
  739. .CW .
  740. (the most overloaded character in Unix) matches any character
  741. .I except
  742. newline, the regular expression
  743. .CW @
  744. (think of it as a big dot) matches any character, even newlines;
  745. and the character sequence
  746. .CW \en
  747. matches a newline character.
  748. Replacement text, such as used in the
  749. .CW a
  750. and
  751. .CW c
  752. commands, is still plain text, but the sequence
  753. .CW \en
  754. represents newline in that context, too.
  755. .PP
  756. Here is an example. Say we wanted to double space the document, that is,
  757. turn every newline into two newlines.
  758. The following all do the job:
  759. .P1
  760. .WC ",x/\en/ a/\en/
  761. .WC ",x/\en/ c/\en\en/
  762. .WC ",x/$/ a/\en/
  763. .WC ",x/^/ i/\en/
  764. .P2
  765. The last example is slightly different, because it puts a newline
  766. .I before
  767. each line; the other examples place it after.
  768. The first two examples manipulate newlines directly
  769. [something outside
  770. .CW ed 's
  771. ken]; the last two
  772. use regular expressions:
  773. .CW $
  774. is the empty string at the end of a line, while
  775. .CW ^
  776. is the empty string at the beginning.
  777. .PP
  778. These solutions all have a possible drawback: if there is already a blank line
  779. (that is, two consecutive newlines), they make it much larger (four
  780. consecutive newlines).
  781. A better method is to extend every group of newlines by one:
  782. .P1
  783. .WC ",x/\en+/ a/\en/
  784. .P2
  785. The regular expression operator
  786. .CW +
  787. means `one or more;'
  788. .CW \en+
  789. is identical to
  790. .CW \en\en* .
  791. Thus, this example
  792. takes every sequence of newlines and adds another
  793. to the end.
  794. .PP
  795. A more common example is indenting a block of text by a tab stop.
  796. The following all work,
  797. although the first is arguably the cleanest (the blank text in slashes is a tab):
  798. .P1
  799. .WC ",x/^/a/ /
  800. .WC ",x/^/c/ /
  801. .WC ",x/.*\en/i/ /
  802. .P2
  803. The last example uses the pattern (idiom, really)
  804. .CW .*\en
  805. to match lines:
  806. .CW .*
  807. matches the longest possible string of non-newline characters.
  808. Taking initial tabs away is just as easy:
  809. .P1
  810. .WC ",x/^ /d
  811. .P2
  812. In these examples I have specified an address (the whole file), but
  813. in practice commands like these are more likely to be run without
  814. an address, using the value of dot set by selecting text with the mouse.
  815. .SH
  816. Conditionals
  817. .PP
  818. The
  819. .CW x
  820. command is a looping construct:
  821. for each match of a regular expression,
  822. it extracts (sets dot to) the match and runs a command.
  823. .CW sam
  824. also has a conditional,
  825. .CW g :
  826. \f(CWg/\f2pattern\f(CW/\f2command\f1
  827. runs the command if dot contains a match of the pattern
  828. .I
  829. without changing the value of dot.
  830. .R
  831. The inverse,
  832. .CW v ,
  833. runs the command if dot does
  834. .I not
  835. contain a match of the pattern.
  836. (The letters
  837. .CW g
  838. and
  839. .CW v
  840. are historical and have no mnemonic significance. You might
  841. think of
  842. .CW g
  843. as `guard.')
  844. .CW ed "" [
  845. users should read the above definitions very carefully; the
  846. .CW g
  847. command in
  848. .CW sam
  849. is fundamentally different from that in
  850. .CW ed .]
  851. Here is an example of the difference between
  852. .CW x
  853. and
  854. .CW g:
  855. .P1
  856. ,x/Emacs/c/vi/
  857. .P2
  858. changes each occurrence of the word
  859. .CW Emacs
  860. in the file to the word
  861. .CW vi ,
  862. but
  863. .P1
  864. ,g/Emacs/c/vi/
  865. .P2
  866. changes the
  867. .I "whole file
  868. to
  869. .CW vi
  870. if there is the word
  871. .CW Emacs
  872. anywhere in the file.
  873. .PP
  874. Neither of these commands is particularly interesting in isolation,
  875. but they are valuable when combined with
  876. .CW x
  877. and with themselves.
  878. .SH
  879. Composition
  880. .PP
  881. One way to think about the
  882. .CW x
  883. command is that, given a selection (a value of dot)
  884. it iterates through interesting subselections (values of dot within).
  885. In other words, it takes a piece of text and cuts it into smaller pieces.
  886. But the text that it cuts up may already be a piece cut by a previous
  887. .CW x
  888. command or selected by a
  889. .CW g .
  890. .CW sam 's
  891. most interesting property is the ability to define a sequence of commands
  892. to perform a particular task.\(dg
  893. .FS
  894. \(dg
  895. The obvious analogy with shell pipelines is only partially valid,
  896. because the individual
  897. .CW sam
  898. commands are all working on the same text; it is only how the text is
  899. sliced up that is changing.
  900. .FE
  901. A simple example is to change all occurrences of
  902. .CW Emacs
  903. to
  904. .CW emacs ;
  905. certainly the command
  906. .P1
  907. .WC ",x/Emacs/ c/emacs/
  908. .P2
  909. will work, but we can use an
  910. .CW x
  911. command to save retyping most of the word
  912. .CW Emacs :
  913. .P1
  914. .WC ",x/Emacs/ x/E/ c/e/
  915. .P2
  916. (Blanks can be used
  917. to separate commands on a line to make them easier to read.)
  918. What this command does is find all occurrences of
  919. .CW Emacs
  920. .CW ,x/Emacs/ ), (
  921. and then
  922. .I
  923. with dot set to that text,
  924. .R
  925. find all occurrences of the letter
  926. .CW E
  927. .CW x/E/ ), (
  928. and then
  929. .I
  930. with dot set to that text,
  931. .R
  932. run the command
  933. .CW c/e/
  934. to change the character to lower case.
  935. Note that the address for the command \(em the whole file, specified by a comma
  936. \(em is only given to the leftmost
  937. piece of the command; the rest of the pieces have dot set for them by
  938. the execution of the pieces to their left.
  939. .PP
  940. As another simple example, consider a problem
  941. solved above: printing all lines in the file containing the word
  942. .CW Emacs:
  943. .P1
  944. .WC ",x/.*\en/ g/Emacs/p
  945. general introduction to the commands in Emacs and to try to show
  946. the method in the madness that is the Emacs command structure.
  947. .P2
  948. This command says to break the file into lines
  949. .CW ,x/.*\en/ ), (
  950. and for each line that contains the string
  951. .CW Emacs
  952. .CW g/Emacs/ ), (
  953. run the command
  954. .CW p
  955. with dot set to the line (not the match of
  956. .CW Emacs ),
  957. which prints the line.
  958. To save typing, because
  959. .CW .*\en
  960. is a common pattern in
  961. .CW x
  962. commands,
  963. if the
  964. .CW x
  965. is followed immediately by a space, the pattern
  966. .CW .*\en
  967. is assumed.
  968. Therefore, the above could be written more succinctly:
  969. .P1
  970. .WC ",x g/Emacs/p
  971. .P2
  972. The solution we used before was
  973. .P1
  974. .WC ,x/Emacs/+-p
  975. .P2
  976. which runs the command
  977. .CW +-p
  978. with dot set to each match of
  979. .CW Emacs
  980. in the file (recall that the idiom
  981. .CW +-p
  982. prints the line containing the end of dot).
  983. .PP
  984. The two commands usually produce the same result
  985. (the
  986. .CW +-p
  987. form will print a line twice if it contains
  988. .CW Emacs
  989. twice). Which is better?
  990. .CW ,x/Emacs/+-p
  991. is easier to type and will be much faster if the file is large and
  992. there are few occurrences of the string, but it is really an odd special case.
  993. .CW ",x/.*\en/ g/Emacs/p
  994. is slower \(em it breaks each line out separately, then examines
  995. it for a match \(em but is conceptually cleaner, and generalizes more easily.
  996. For example, consider the following piece of the Emacs manual:
  997. .P1
  998. command name="append-to-file", key="[unbound]"
  999. Takes the contents of the current buffer and appends it to the
  1000. named file. If the files doesn't exist, it will be created.
  1001. command name="apropos", key="ESC-?"
  1002. Prompts for a keyword and then prints a list of those commands
  1003. whose short description contains that keyword. For example,
  1004. if you forget which commands deal with windows, just type
  1005. "@b[ESC-?]@t[window]@b[ESC]".
  1006. \&\f2and so on\f(CW
  1007. .P2
  1008. This text consists of groups of non-empty lines, with a simple format
  1009. for the text within each group.
  1010. Imagine that we wanted to find the description of the `apropos'
  1011. command.
  1012. The problem is to break the file into individual descriptions,
  1013. and then to find the description of `apropos' and to print it.
  1014. The solution is straightforward:
  1015. .P1
  1016. .WC ,x/(.+\en)+/\ g/command\ name="apropos"/p
  1017. command name="apropos", key="ESC-?"
  1018. Prompts for a keyword and then prints a list of those commands
  1019. whose short description contains that keyword. For example,
  1020. if you forget which commands deal with windows, just type
  1021. "@b[ESC-?]@t[window]@b[ESC]".
  1022. .P2
  1023. The regular expression
  1024. .CW (.+\en)+
  1025. matches one or more lines with one or more characters each, that is,
  1026. the text between blank lines, so
  1027. .CW ,x/(.+\en)+/
  1028. extracts each description; then
  1029. .CW g/command\ name="apropos"/
  1030. selects the description for `apropos' and
  1031. .CW p
  1032. prints it.
  1033. .PP
  1034. Imagine that we had a C program containing the variable
  1035. .CW n ,
  1036. but we wanted to change it to
  1037. .CW num .
  1038. This command is a first cut:
  1039. .P1
  1040. .WC ",x/n/ c/num/
  1041. .P2
  1042. but is obviously flawed: it will change all
  1043. .CW n 's
  1044. in the file, not just the
  1045. .I identifier
  1046. .CW n .
  1047. A better solution is to use an
  1048. .CW x
  1049. command to extract the identifiers, and then use
  1050. .CW g
  1051. to find the
  1052. .CW n 's:
  1053. .P1
  1054. .WC ",x/[a-zA-Z_][a-zA-Z_0-9]*/ g/n/ v/../ c/num/
  1055. .P2
  1056. It looks awful, but it's fairly easy to understand when read
  1057. left to right.
  1058. A C identifier is an alphabetic or underscore followed by zero or more
  1059. alphanumerics or underscores, that is, matches of the regular expression
  1060. .CW [a-zA-Z_][a-zA-Z_0-9]* .
  1061. The
  1062. .CW g
  1063. command selects those identifiers containing
  1064. .CW n ,
  1065. and the
  1066. .CW v
  1067. is a trick: it rejects those identifiers containing more than one
  1068. character. Hence the
  1069. .CW c/num/
  1070. applies only to free-standing
  1071. .CW n 's.
  1072. .PP
  1073. There is still a problem here:
  1074. we don't want to change
  1075. .CW n 's
  1076. that are part of the character constant
  1077. .CW \en .
  1078. There is a command
  1079. .CW y ,
  1080. complementary to
  1081. .CW x ,
  1082. that is just what we need:
  1083. \f(CWy/\f2pattern\f(CW/\f2command\f1
  1084. runs the command on the pieces of text
  1085. .I between
  1086. matches of the pattern;
  1087. if
  1088. .CW x
  1089. selects,
  1090. .CW y
  1091. rejects.
  1092. Here is the final command:
  1093. .P1
  1094. .WC ",y/\e\en/ x/[a-zA-Z_][a-zA-Z_0-9]*/ g/n/ v/../ c/num/
  1095. .P2
  1096. The
  1097. .CW y/\e\en/
  1098. (with backslash doubled to make it a literal character)
  1099. removes the two-character sequence
  1100. .CW \en
  1101. from consideration, so the rest of the command will not touch it.
  1102. There is more we could do here; for example, another
  1103. .CW y
  1104. could be prefixed to protect comments in the code.
  1105. I won't elaborate the example any further, but you should have
  1106. an idea of the way in which the looping and conditional commands
  1107. in
  1108. .CW sam
  1109. may be composed to do interesting things.
  1110. .SH
  1111. Grouping
  1112. .PP
  1113. There is another way to arrange commands.
  1114. By enclosing them in brace brackets
  1115. .CW {} ,
  1116. commands may be applied in parallel.
  1117. This example uses the
  1118. .CW =
  1119. command, which reports the line and character numbers of dot,
  1120. together with
  1121. .CW p ,
  1122. to report on appearances of
  1123. .CW Emacs
  1124. in our original file:
  1125. .P1
  1126. .WC ,p
  1127. This manual is organized in a rather haphazard manner. The first
  1128. several sections were written hastily in an attempt to provide a
  1129. general introduction to the commands in Emacs and to try to show
  1130. the method in the madness that is the Emacs command structure.
  1131. .ft CS
  1132. ,x/Emacs/{
  1133. =
  1134. +-p
  1135. }
  1136. .ft
  1137. 3; #171,#176
  1138. general introduction to the commands in Emacs and to try to show
  1139. 4; #234,#239
  1140. the method in the madness that is the Emacs command structure.
  1141. .P2
  1142. (The number before the semicolon is the line number;
  1143. the numbers beginning with
  1144. .CW #
  1145. are character numbers.)
  1146. As a more interesting example, consider changing all occurrences of
  1147. .CW Emacs
  1148. to
  1149. .CW vi
  1150. and vice versa. We can type
  1151. .P1
  1152. .ft CS
  1153. ,x/Emacs|vi/{
  1154. g/Emacs/ c/vi/
  1155. g/vi/ c/Emacs/
  1156. }
  1157. .ft
  1158. .P2
  1159. or even
  1160. .P1
  1161. .ft CS
  1162. ,x/[a-zA-Z]+/{
  1163. g/Emacs/ v/....../ c/vi/
  1164. g/vi/ v/.../ c/Emacs/
  1165. }
  1166. .ft
  1167. .P2
  1168. to make sure we don't change strings embedded in words.
  1169. .SH
  1170. Multiple Changes
  1171. .PP
  1172. You might wonder why, once
  1173. .CW Emacs
  1174. has been changed to
  1175. .CW vi
  1176. in the above example,
  1177. the second command in the braces doesn't put it back again.
  1178. The reason is that the commands are run in parallel:
  1179. within any top-level
  1180. .CW sam
  1181. command, all changes to the file refer to the state of the file
  1182. before any of the changes in that command are made.
  1183. After all the changes have been determined, they are all applied
  1184. simultaneously.
  1185. .PP
  1186. This means, as mentioned, that commands within a compound
  1187. command see the state of the file before any of the changes apply.
  1188. This method of evaluation makes some things easier (such as the exchange of
  1189. .CW Emacs
  1190. and
  1191. .CW vi ),
  1192. and some things harder.
  1193. For instance, it is impossible to use a
  1194. .CW p
  1195. command to print the changes as they happen,
  1196. because they haven't happened when the
  1197. .CW p
  1198. is executed.
  1199. An indirect ramification is that changes must occur in forward
  1200. order through the file,
  1201. and must not overlap.
  1202. .SH
  1203. Unix
  1204. .PP
  1205. .CW sam
  1206. has a few commands to connect to Unix processes.
  1207. The simplest is
  1208. .CW ! ,
  1209. which runs the command with input and output connected to the terminal.
  1210. .P1
  1211. .WC !date
  1212. Wed May 28 23:25:21 EDT 1986
  1213. !
  1214. .P2
  1215. (When downloaded, the input is connected to
  1216. .CW /dev/null
  1217. and only the first few lines of output are printed;
  1218. any overflow is stored in
  1219. .CW $HOME/sam.err .)
  1220. The final
  1221. .CW !
  1222. is a prompt to indicate when the command completes.
  1223. .PP
  1224. Slightly more interesting is
  1225. .CW > ,
  1226. which provides the current text as standard input to the Unix command:
  1227. .P1
  1228. .WC "1,2 >wc
  1229. 2 22 131
  1230. !
  1231. .P2
  1232. The complement of
  1233. .CW >
  1234. is, naturally,
  1235. .CW < :
  1236. it replaces the current text with the standard output of the Unix command:
  1237. .P1
  1238. .WC "1 <date
  1239. !
  1240. .WC 1p
  1241. Wed May 28 23:26:44 EDT 1986
  1242. .P2
  1243. The last command is
  1244. .CW | ,
  1245. which is a combination of
  1246. .CW <
  1247. and
  1248. .CW > :
  1249. the current text is provided as standard input to the Unix command,
  1250. and the Unix command's standard output is collected and used to
  1251. replace the original text.
  1252. For example,
  1253. .P1
  1254. .WC ",| sort
  1255. .P2
  1256. runs
  1257. .CW sort (1)
  1258. on the file, sorting the lines of the text lexicographically.
  1259. Note that
  1260. .CW < ,
  1261. .CW >
  1262. and
  1263. .CW |
  1264. are
  1265. .CW sam
  1266. commands, not Unix shell operators.
  1267. .PP
  1268. The next example converts all appearances of
  1269. .CW Emacs
  1270. to upper case using
  1271. .CW tr (1):
  1272. .P1
  1273. .WC ",x/Emacs/ | tr a-z A-Z
  1274. .P2
  1275. .CW tr
  1276. is run once for each occurrence of
  1277. .CW Emacs .
  1278. Of course, you could do this example more efficiently with a simple
  1279. .CW c
  1280. command, but here's a trickier one:
  1281. given a Unix mail box as input,
  1282. convert all the
  1283. .CW Subject
  1284. headers to distinct fortunes:
  1285. .P1
  1286. .WC ",x/^Subject:.*\en/ x/[^:]*\en/ < /usr/games/fortune
  1287. .P2
  1288. (The regular expression
  1289. .CW [^:]
  1290. refers to any character
  1291. .I except
  1292. .CW :
  1293. and newline; the negation operator
  1294. .CW ^
  1295. excludes newline from the list of characters.)
  1296. Again,
  1297. .CW /usr/games/fortune
  1298. is run once for each
  1299. .CW Subject
  1300. line, so each
  1301. .CW Subject
  1302. line is changed to a different fortune.
  1303. .SH
  1304. A few other text commands
  1305. .PP
  1306. For completeness, I should mention three other commands that
  1307. manipulate text. The
  1308. .CW m
  1309. command moves the current text to after the text specified by the
  1310. (obligatory) address after the command.
  1311. Thus
  1312. .P1
  1313. .WC "/Emacs/+- m 0
  1314. .P2
  1315. moves the next line containing
  1316. .CW Emacs
  1317. to the beginning of the file.
  1318. Similarly,
  1319. .CW t
  1320. (another historic character) copies the text:
  1321. .P1
  1322. .WC "/Emacs/+- t 0
  1323. .P2
  1324. would make, at the beginning of the file, a copy of the next line
  1325. containing
  1326. .CW Emacs .
  1327. .PP
  1328. The third command is more interesting: it makes substitutions.
  1329. Its syntax is
  1330. \f(CWs/\f2pattern\f(CW/\f2replacement\f(CW/\f1.
  1331. Within the current text, it finds the first occurrence of
  1332. the pattern and replaces it by the replacement text,
  1333. leaving dot set to the entire address of the substitution.
  1334. .P1
  1335. .WC 1p
  1336. This manual is organized in a rather haphazard manner. The first
  1337. .WC s/haphazard/thoughtless/
  1338. .WC p
  1339. This manual is organized in a rather thoughtless manner. The first
  1340. .P2
  1341. Occurrences of the character
  1342. .CW &
  1343. in the replacement text stand for the text matching the pattern.
  1344. .P1
  1345. .WC s/T/"&&&&"/
  1346. .WC p
  1347. "TTTT"his manual is organized in a rather thoughtless manner. The first
  1348. .P2
  1349. There are two variants. The first is that a number may be specified
  1350. after the
  1351. .CW s ,
  1352. to indicate which occurrence of the pattern to substitute; the default
  1353. is the first.
  1354. .P1
  1355. .WC s2/is/was/
  1356. .WC p
  1357. "TTTT"his manual was organized in a rather thoughtless manner. The first
  1358. .P2
  1359. The second is that suffixing a
  1360. .CW g
  1361. (global) causes replacement of all occurrences, not just the first.
  1362. .P1
  1363. .WC s/[a-zA-Z]/x/g
  1364. .WC p
  1365. "xxxx"xxx xxxxxx xxx xxxxxxxxx xx x xxxxxx xxxxxxxxxxx xxxxxxx xxx xxxxx
  1366. .P2
  1367. Notice that in all these examples
  1368. dot is left
  1369. set to the entire line.
  1370. .PP
  1371. [The substitute command is vital to
  1372. .CW ed,
  1373. because it is the only way to make changes within a line.
  1374. It is less valuable in
  1375. .CW sam ,
  1376. in which the concept of a line is much less important.
  1377. For example, many
  1378. .CW ed
  1379. substitution idioms are handled well by
  1380. .CW sam 's
  1381. basic commands. Consider the commands
  1382. .P1
  1383. s/good/bad/
  1384. s/good//
  1385. s/good/& bye/
  1386. .P2
  1387. which are equivalent in
  1388. .CW sam
  1389. to
  1390. .P1
  1391. /good/c/bad/
  1392. /good/d
  1393. /good/a/ bye/
  1394. .P2
  1395. and for which the context search is likely unnecessary because the desired
  1396. text is already dot.
  1397. Also, beware this
  1398. .CW ed
  1399. idiom:
  1400. .P1
  1401. 1,$s/good/bad/
  1402. .P2
  1403. which changes the first
  1404. .CW good
  1405. on each line; the same command in
  1406. .CW sam
  1407. will only change the first one in the whole file.
  1408. The correct
  1409. .CW sam
  1410. version is
  1411. .P1
  1412. ,x s/good/bad/
  1413. .P2
  1414. but what is more likely meant is
  1415. .P1
  1416. ,x/good/ c/bad/
  1417. .P2
  1418. .CW sam
  1419. operates under different rules.]
  1420. .SH
  1421. Files
  1422. .PP
  1423. So far, we have only been working with a single file,
  1424. but
  1425. .CW sam
  1426. is a multi-file editor.
  1427. Only one file may be edited at a time, but
  1428. it is easy to change which file is the `current' file for editing.
  1429. To see how to do this, we need a
  1430. .CW sam
  1431. with a few files;
  1432. the easiest way to do this is to start it
  1433. with a list of Unix file names to edit.
  1434. .P1
  1435. $ \f(CSecho *.ms\f(CW
  1436. conquest.ms death.ms emacs.ms famine.ms slaughter.ms
  1437. $ \f(CSsam -d *.ms\f(CW
  1438. -. conquest.ms
  1439. .P2
  1440. (I'm sorry the Horsemen don't appear in liturgical order.)
  1441. The line printed by
  1442. .CW sam
  1443. is an indication that the Unix file
  1444. .CW conquest.ms
  1445. has been read, and is now the current file.
  1446. .CW sam
  1447. does not read the Unix file until
  1448. the associated
  1449. .CW sam
  1450. file becomes current.
  1451. .PP
  1452. The
  1453. .CW n
  1454. command prints the names of all the files:
  1455. .P1
  1456. .WC n
  1457. -. conquest.ms
  1458. - death.ms
  1459. - emacs.ms
  1460. - famine.ms
  1461. - slaughter.ms
  1462. .P2
  1463. This list is also available in the menu on mouse button 3.
  1464. The command
  1465. .CW f
  1466. tells the name of just the current file:
  1467. .P1
  1468. .WC f
  1469. -. conquest.ms
  1470. .P2
  1471. The characters to the left of the file name encode helpful information about
  1472. the file.
  1473. The minus sign becomes a plus sign if the file has a window open, and an
  1474. asterisk if more than one is open.
  1475. The period (another meaning of dot) identifies the current file.
  1476. The leading blank changes to an apostrophe if the file is different
  1477. from the contents of the associated Unix file, as far as
  1478. .CW sam
  1479. knows.
  1480. This becomes evident if we make a change.
  1481. .P1
  1482. .WC 1d
  1483. .WC f
  1484. \&'-. conquest.ms
  1485. .P2
  1486. If the file is restored by an undo command, the apostrophe disappears.
  1487. .P1
  1488. .WC u
  1489. .WC f
  1490. -. conquest.ms
  1491. .P2
  1492. The file name may be changed by providing a new name with the
  1493. .CW f
  1494. command:
  1495. .P1
  1496. .CW "f pestilence.ms
  1497. \&'-. pestilence.ms
  1498. .P2
  1499. .WC f
  1500. prints the new status of the file,
  1501. that is, it changes the name if one is provided, and prints the
  1502. name regardless.
  1503. A file name change may also be undone.
  1504. .P1
  1505. .WC u
  1506. .WC f
  1507. -. conquest.ms
  1508. .P2
  1509. .PP
  1510. When
  1511. .CW sam
  1512. is downloaded, the current file may be changed simply by selecting
  1513. the desired file from the menu (selecting the same file subsequently
  1514. cycles through the windows opened on the file).
  1515. Otherwise, the
  1516. .CW b
  1517. command can be used to choose the desired file:\(dg
  1518. .FS
  1519. \(dg A bug prevents the
  1520. .CW b
  1521. command from working when downloaded.
  1522. Because the menu is more convenient anyway, and
  1523. because the method
  1524. of choosing files from the command language is slated to change,
  1525. the bug hasn't been fixed.
  1526. .FE
  1527. .P1
  1528. .WC "b emacs.ms
  1529. -. emacs.ms
  1530. .P2
  1531. Again,
  1532. .CW sam
  1533. prints the name (actually, executes an implicit
  1534. .CW f
  1535. command) because the Unix file
  1536. .CW emacs.ms
  1537. is being read for the first time.
  1538. It is an error to ask for a file
  1539. .CW sam
  1540. doesn't know about, but the
  1541. .CW B
  1542. command will prime
  1543. .CW sam 's
  1544. menu with a new file, and make it current.
  1545. .P1
  1546. .WC "b flood.pic
  1547. ?no such file `flood.pic'
  1548. .WC "B flood.pic
  1549. -. flood.pic
  1550. .WC n
  1551. - conquest.ms
  1552. - death.ms
  1553. - emacs.ms
  1554. - famine.ms
  1555. -. flood.pic
  1556. - slaughter.ms
  1557. .P2
  1558. Both
  1559. .CW b
  1560. and
  1561. .CW B
  1562. will accept a list of file names.
  1563. .CW b
  1564. simply takes the first file in the list, but
  1565. .CW B
  1566. loads them all.
  1567. The list may be typed on one line \(em
  1568. .P1
  1569. .WC "B devil.tex satan.tex 666.tex emacs.tex
  1570. .P2
  1571. \(em or generated by a Unix command \(em
  1572. .P1
  1573. .WC "B <echo *.tex
  1574. .P2
  1575. The latter form requires a Unix command;
  1576. .CW sam
  1577. does not understand the shell file name metacharacters, so
  1578. .CW "B *.tex
  1579. attempts to load a single file named
  1580. .CW *.tex .
  1581. (The
  1582. .CW <
  1583. form is of course derived from
  1584. .CW sam 's
  1585. .CW <
  1586. command.)
  1587. .CW echo
  1588. is not the only useful command to run subservient to
  1589. .CW B ;
  1590. for example,
  1591. .P1
  1592. .WC "B <grep -l Emacs *
  1593. .P2
  1594. will load only those files containing the string
  1595. .CW Emacs .
  1596. Finally, a special case: a
  1597. .CW B
  1598. with no arguments creates an empty, nameless file within
  1599. .CW sam .
  1600. .PP
  1601. The complement of
  1602. .CW B
  1603. is
  1604. .CW D :
  1605. .P1
  1606. .WC "D devil.tex satan.tex 666.tex emacs.tex
  1607. .P2
  1608. eradicates the files from
  1609. .CW sam 's
  1610. memory (not from the Unix machine's disc).
  1611. .CW D
  1612. without any file names removes the current file from
  1613. .CW sam .
  1614. .PP
  1615. There are three other commands that relate the current file
  1616. to Unix files.
  1617. The
  1618. .CW w
  1619. command writes the file to disc;
  1620. without arguments, it writes the entire file to the Unix file associated
  1621. with the current file in
  1622. .CW sam
  1623. (it is the only command whose default address is not dot).
  1624. Of course, you can specify an address to be written,
  1625. and a different file name, with the obvious syntax:
  1626. .P1
  1627. .WC "1,2w /tmp/revelations
  1628. /tmp/revelations: #44
  1629. .P2
  1630. .CW sam
  1631. responds with the file name and the number of characters written to the file.
  1632. The
  1633. .CW write
  1634. command on the button 3 menu is identical in function to an unadorned
  1635. .CW w
  1636. command.
  1637. .PP
  1638. The other two commands,
  1639. .CW e
  1640. and
  1641. .CW r ,
  1642. read data from Unix files.
  1643. The
  1644. .CW e
  1645. command clears out the current file,
  1646. reads the data from the named file (or uses the current file's old name if
  1647. none is explicitly provided), and sets the file name.
  1648. It's much like a
  1649. .CW B
  1650. command, but puts the information in the current file instead of a new one.
  1651. .CW e
  1652. without any file name is therefore an easy way to refresh
  1653. .CW sam 's
  1654. copy of a Unix file.
  1655. [Unlike in
  1656. .CW ed ,
  1657. .CW e
  1658. doesn't complain if the file is modified. The principle is not
  1659. to protect against things that can be undone if wrong.]
  1660. Since its job is to replace the whole text,
  1661. .CW e
  1662. never takes an address.
  1663. .PP
  1664. The
  1665. .CW r
  1666. command is like
  1667. .CW e ,
  1668. but it doesn't clear the file:
  1669. the text in the Unix file replaces dot, or the specified text if an
  1670. address is given.
  1671. .P1
  1672. .WC "r emacs.ms
  1673. .P2
  1674. has essentially the effect of
  1675. .P1
  1676. .WC "<cat emacs.ms
  1677. .P2
  1678. The commands
  1679. .CW r
  1680. and
  1681. .CW w
  1682. will set the name of the file if the current file has no name already defined;
  1683. .CW e
  1684. sets the name even if the file already has one.
  1685. .PP
  1686. There is a command, analogous to
  1687. .CW x ,
  1688. that iterates over files instead of pieces of text:
  1689. .CW X
  1690. (capital
  1691. .CW x ).
  1692. The syntax is easy; it's just like that of
  1693. .CW x
  1694. \(em \f(CWX/\f2pattern\f(CW/\f2command\f1.
  1695. (The complementary command is
  1696. .CW Y ,
  1697. analogous to
  1698. .CW y .)
  1699. The effect is to run the command in each file whose menu entry
  1700. (that is, whose line printed by an
  1701. .CW f
  1702. command) matches the pattern.
  1703. For example, since an apostrophe identifies modified files,
  1704. .P1
  1705. .WC "X/'/ w
  1706. .P2
  1707. writes the changed files out to disc.
  1708. Here is a longer example: find all uses of a particular variable
  1709. in the C source files:
  1710. .P1
  1711. .WC "X/\e.c$/ ,x/variable/+-p
  1712. .P2
  1713. We can use an
  1714. .CW f
  1715. command to identify which file the variable appears in:
  1716. .P1
  1717. .ft CS
  1718. X/\e.c$/ ,g/variable/ {
  1719. f
  1720. ,x/variable/+-{
  1721. =
  1722. p
  1723. }
  1724. }
  1725. .ft
  1726. .P2
  1727. Here, the
  1728. .CW g
  1729. command guarantees that only the names of files containing the variable
  1730. will be printed (but beware that
  1731. .CW sam
  1732. may confuse matters by printing the names of files it reads in during
  1733. the command).
  1734. The
  1735. .CW =
  1736. command shows where in the file the variable appears, and the
  1737. .CW p
  1738. command prints the line.
  1739. .PP
  1740. The
  1741. .CW D
  1742. command is handy as the target of an
  1743. .CW X .
  1744. This example deletes from the menu all C files that do not contain
  1745. a particular variable:
  1746. .P1
  1747. .WC "X/\e.c$/ ,v/variable/ D
  1748. .P2
  1749. If no pattern is provided for the
  1750. .CW X ,
  1751. the command (which defaults to
  1752. .CW f )
  1753. is run in all files, so
  1754. .P1
  1755. .WC "X D
  1756. .P2
  1757. cleans
  1758. .CW sam
  1759. up for a fresh start.
  1760. .PP
  1761. But rather than working any further, let's stop now:
  1762. .P1
  1763. .WC q
  1764. $
  1765. .P2
  1766. .fi
  1767. .PP
  1768. Some of the file manipulating commands can be undone:
  1769. undoing a
  1770. .CW f ,
  1771. .CW e ,
  1772. or
  1773. .CW r
  1774. restores the previous state of the file,
  1775. but
  1776. .CW w ,
  1777. .CW B
  1778. and
  1779. .CW D
  1780. are irrevocable.
  1781. And, of course, so is
  1782. .CW q .