Subversion Repositories planix.SVN

.de P1

.KS

.DS

.ft CW

.ta 5n 10n 15n 20n 25n 30n 35n 40n 45n 50n 55n 60n 65n 70n 75n 80n

..

.de P2

.ft 1

.DE

.KE

..

.de CW

.lg 0

\%\&\\$3\f(CW\\$1\fP\&\\$2

.lg

..

.de WC

.lg 0

\%\&\\$3\f(CI\\$1\fP\&\\$2

.lg

..

.TL

A tutorial for the

.CW sam

.B

command language

.AU

Rob Pike

.AI

.MH

.AB

.CW sam

is an interactive text editor with a command language that makes heavy use

of regular expressions.

Although the language is syntactically similar to

.CW ed (1),

the details are interestingly different.

This tutorial introduces the command language, but does not discuss

the screen and mouse interface.

With apologies to those unfamiliar with the Ninth Edition Blit software,

it is assumed that the similarity of

.CW sam

to

.CW mux (9)

at this level makes

.CW sam 's

mouse language easy to learn.

.PP

The

.CW sam

command language applies identically to two environments:

when running

.CW sam

on an ordinary terminal

(\f2via\f1\f1

.CW sam\ -d ),

and in the command window of a

.I downloaded

.CW sam ,

that is, one using the bitmap display and mouse.

.AE

.SH

Introduction

.PP

This tutorial describes the command language of

.CW sam ,

an interactive text editor that runs on Blits and

some computers with bitmap displays.

For most editing tasks, the mouse-based editing features

are sufficient, and they are easy to use and to learn.

.PP

The command language is often useful, however, particularly

when making global changes.

Unlike the commands in

.CW ed ,

which are necessary to make changes,

.CW sam

commands tend to be used

only for complicated or repetitive editing tasks.

It is in these more involved uses that

the differences between

.CW sam

and other text editors are most evident.

.PP

.CW sam 's

language makes it easy to do some things that other editors,

including programs like

.CW sed

and

.CW awk ,

do not handle gracefully, so this tutorial serves partly as a

lesson in

.CW sam 's

manner of manipulating text.

The examples below therefore concentrate entirely on the language,

assuming that facility with the use of the mouse in

.CW sam

is at worst easy to pick up.

In fact,

.CW sam

can be run without the mouse at all (not

.I downloaded ),

by specifying the

.CW -d

flag, and it is this domain that the tutorial

occupies; the command language in these modes

are identical.

.PP

A word to the Unix adept:

although

.CW sam

is syntactically very similar to

.CW ed ,

it is fundamentally and deliberately different in design and detailed semantics.

You might use knowledge of

.CW ed

to predict how the substitute command works,

but you'd only be right if you had used some understanding of

.CW sam 's

workings to influence your prediction.

Be particularly careful about idioms.

Idioms form in curious nooks of languages and depend on

undependable peculiarities.

.CW ed

idioms simply don't work in

.CW sam :

.CW 1,$s/a/b/

makes one substitution in the whole file, not one per line.

.CW sam

has its own idioms.

Much of the purpose of this tutorial is to publish them

and make fluency in

.CW sam

a matter of learning, not cunning.

.PP

The tutorial depends on familiarity with regular expressions, although

some experience with a more traditional Unix editor may be helpful.

To aid readers familiar with

.CW ed ,

I have pointed out in square brackets [] some of

the relevant differences between

.CW ed

and

.CW sam .

Read these comments only if you wish

to understand the differences; the lesson is about

.CW sam ,

not

.CW sam

.I vs.

.CW ed .

Another typographic convention is that output appears in

.CW "this font,

while typed input appears as

.WC "slanty text.

.PP

Nomenclature:

.CW sam

keeps a copy of the text it is editing.

This copy is called a

.I file .

To avoid confusion, I have called the permanent storage on disc a

.I

Unix file.

.R

.SH

Text

.PP

To get started, we need some text to play with.

Any text will do; try something from

James Gosling's Emacs manual:

.P1

$ \f(CIsam -d

a

This manual is organized in a rather haphazard manner.  The first

several sections were written hastily in an attempt to provide a

general introduction to the commands in Emacs and to try to show

the method in the madness that is the Emacs command structure.

\&.

.ft

.P2

.WC "sam -d

starts

.CW sam

running.

The

.CW a

command adds text until a line containing just a period, and sets the

.I

current text

.R

(also called

.I dot )

to what was typed \(em everything between the

.CW a

and the period.

.CW ed "" [

would leave dot set to only the last line.]

The

.CW p

command prints the current text:

.P1

.WC p

This manual is organized in a rather haphazard manner.  The first

several sections were written hastily in an attempt to provide a

general introduction to the commands in Emacs and to try to show

the method in the madness that is the Emacs command structure.

.P2

[Again,

.CW ed

would print only the last line.]

The

.CW a

command adds its text

.I after

dot; the

.CW i

command is like

.CW a,

but adds the text

.I before

dot.

.P1

.ft CI

i

Introduction

\&.

p

.ft

Introduction

.P2

There is also a

.CW c

command that changes (replaces) the current text,

and

.CW d

that deletes it; these are illustrated below.

.PP

To see all the text, we can specify what text to print;

for the moment, suffice it to say that

.WC 0,$

specifies the entire file.

.CW ed "" [

users would probably type

.WC 1,$ ,

which in practice is the same thing, but see below.]

.P1

.WC 0,$p

Introduction

This manual is organized in a rather haphazard manner.  The first

several sections were written hastily in an attempt to provide a

general introduction to the commands in Emacs and to try to show

the method in the madness that is the Emacs command structure.

.P2

Except for the

.CW w

command described below,

.I all

commands,

including

.CW p ,

set dot to the text they touch.

Thus,

.CW a

and

.CW i

set dot to the new text,

.CW p

to the text printed, and so on.

Similarly, all commands

(except

.CW w )

by default operate on the current

text [unlike

.CW ed ,

for which some commands (such as

.CW g )

default to the entire file].

.PP

Things are not going to get very interesting until we can

set dot arbitrarily.

This is done by

.I addresses ,

which specify a piece of the file.

The address

.CW 1 ,

for example, sets dot to the first line of the file.

.P1

.WC 1p

Introduction

.WC c

.WC Preamble

.WC .

.P2

The

.CW c

command didn't need to specify dot; the

.CW p

left it on line one.

It's therefore easy to delete the first line utterly;

the last command left dot set to line one:

.P1

.WC d

.WC 1p

This manual is organized in a rather haphazard manner.  The first

.P2

(Line numbers change

to reflect changes to the file.)

.PP

The address \f(CW/\f2text\f(CW/\f1

sets dot to the first appearance of

.I text ,

after dot.

.CW ed "" [

matches the first line containing

.I text .]

If

.I text

is not found, the search restarts at the beginning of the file

and continues until dot.

.P1

.WC /Emacs/p

Emacs

.P2

It's difficult to indicate typographically, but in this example no newline appears

after

.CW Emacs :

the text to be printed is the string

.CW Emacs ', `

exactly.

(The final

.CW p

may be left off \(em it is the default command.

When downloaded, however, the default is instead to select the text,

to highlight it,

and to make it visible by moving the window on the file if necessary.

Thus,

.CW /Emacs/

indicates on the display the next occurrence of the text.)

.PP

Imagine we wanted to change the word

.CW haphazard

to

.CW thoughtless .

Obviously, what's needed is another

.CW c

command, but the method used so far to insert text includes a newline.

The syntax for including text without newlines is to surround the

text with slashes (which is the same as the syntax for

text searches, but what is going on should be clear from context).

The text must appear immediately after the

.CW c

(or

.CW a

or

.CW i ).

Given this, it is easy to make the required change:

.P1

.WC /haphazard/c/thoughtless/

.WC 1p

This manual is organized in a rather thoughtless manner.  The first

.P2

[Changes can always be done with a

.CW c

command, even if the text is smaller than a line].

You'll find that this way of providing text to commands is much

more common than is the multiple-lines syntax.

If you want to include a slash

.CW /

in the text, just precede it with a backslash

.CW \e ,

and use a backslash to protect a backslash itself.

.P1

.WC /Emacs/c/Emacs\e\e360/

.WC 4p

general introduction to the commands in Emacs\e360 and to try to show

.P2

We could also make this particular change by

.P1

.WC /Emacs/a/\e\e360/

.P2

.PP

This is as good a place as any to introduce the

.CW u

command, which undoes the last command.

A second

.CW u

will undo the penultimate command, and so on.

.P1

.WC u

.WC 4p

general introduction to the commands in Emacs and to try to show

.WC u

.WC 3p

This manual is organized in a rather haphazard manner.  The first

.P2

Undoing can only back up; there is no way to undo a previous

.CW u .

.SH

Addresses

.PP

We've seen the simplest forms of addresses, but there is more

to learn before we can get too much further.

An address selects a region in the file \(em a substring \(em

and therefore must define the beginning and the end of a region.

Thus, the address

.CW 13

selects from the beginning of line thirteen to the end of line thirteen, and

.CW /Emacs/

selects from the beginning of the word

.CW Emacs ' `

to the end.

.PP

Addresses may be combined with a comma:

.P1

13,15

.P2

selects lines thirteen through fifteen.  The definition of the comma

operator is to select from the beginning of the left hand address (the

beginning of line 13) to the end of the right hand address (the

end of line 15).

.PP

A few special simple addresses come in handy:

.CW .

(a period) represents dot, the current text,

.CW 0

(line zero) selects the null string at the beginning of the file, and

.CW $

selects the null string at the end of the file

[not the last line of the file].

Therefore,

.P1

0,13

.P2

selects from the beginning of the file to the end of line thirteen,

.P1

\&.,$

.P2

selects from the beginning of the current text to the end of the file, and

.P1

0,$

.P2

selects the whole file [that is, a single string containing the whole file,

not a list of all the lines in the file].

.PP

These are all

.I absolute

addresses: they refer to specific places in the file.

.CW sam

also has relative addresses, which depend

on the value of dot,

and in fact we have already seen one form:

.CW /Emacs/

finds the first occurrence of

.CW Emacs

searching forwards from dot.

Which occurrence of

.CW Emacs

it finds depends on the value of dot.

What if you wanted the first occurrence

.CW before

dot?  Just precede the pattern with a minus sign, which reverses the direction

of the search:

.P1

-/Emacs/

.P2

In fact, the complete syntax for forward searching is

.P1

+/Emacs/

.P2

but the plus sign is the default, and in practice is rarely used.

Here is an example that includes it for clarity:

.P1

0+/Emacs/

.P2

selects the first occurrence of

.CW Emacs

in the file; read it as ``go to line 0, then search forwards for

.CW Emacs .''

Since the

.CW +

is optional, this can be written

.CW 0/Emacs/ .

Similarly,

.P1

$-/Emacs/

.P2

finds the last occurrence in the file, so

.P1

0/Emacs/,$-/Emacs/

.P2

selects the text from the first to last

.CW Emacs ,

inclusive.

Slightly more interesting:

.P1

/Emacs/+/Emacs/

.P2

(there is an implicit

.CW .+

at the beginning) selects the second

.CW Emacs

following dot.

.PP

Line numbers may also be relative.

.P1

-2

.P2

selects the second previous line, and

.P1

+5

.P2

selects the fifth following line (here the plus sign is obligatory).

.PP

Since addresses may select (and dot may be) more than one line,

we need a definition of `previous' and `following:'

`previous' means

.I

before the beginning

.R

of dot, and `following'

means

.I

after the end

.R

of dot.

For example, if the file contains \f(CWA\f(CIAA\f(CWA\f1,

with dot set to the middle two

.CW A 's

(the slanting characters),

.CW -/A/

sets dot to the first

.CW A ,

and

.CW +/A/

sets dot to the last

.CW A .

Except under odd circumstances (such as when the only occurrence of the

text in the file is already the current text), the text selected by a

search will be disjoint from dot.

.PP

To select the

.CW "troff -ms

paragraph containing dot, however long it is, use

.P1

-/.PP/,/.PP/-1

.P2

which will include the

.CW .PP

that begins the paragraph, and exclude the one that ends it.

.PP

When typing relative line number addresses, the default number is

.CW 1 ,

so the above could be written slightly more simply:

.P1

-/.PP/,/.PP/-

.P2

.PP

What does the address

.CW +1-1

or the equivalent

.CW +-

mean?  It looks like it does nothing, but recall that dot need not be a

complete line of text.

.CW +1

selects the line after the end of the current text, and

.CW -1

selects the line before the beginning.  Therefore

.CW +1-1

selects the line before the line after the end of dot, that is,

the complete line containing the end of dot.

We can use this construction to expand a selection to include a complete line,

say the first line in the file containing

.CW Emacs :

.P1

.WC 0/Emacs/+-p

general introduction to the commands in Emacs and to try to show

.P2

The address

.CW +-

is an idiom.

.SH

Loops

.PP

Above, we changed one occurrence of

.CW Emacs

to

.CW Emacs\e360 ,

but if the name of the editor is really changing, it would be useful

to change

.I all

instances of the name in a single command.

.CW sam

provides a command,

.CW x

(extract), for just that job.

The syntax is

\f(CWx/\f2pattern\f(CW/\f2command\f1.

For each occurrence of the pattern in the selected text,

.CW x

sets dot to the occurrence and runs command.

For example, to change

.CW Emacs

to

.CW vi,

.P1

.WC 0,$x/Emacs/c/vi/

.WC 0,$p

This manual is organized in a rather haphazard manner.  The first

several sections were written hastily in an attempt to provide a

general introduction to the commands in vi and to try to show

the method in the madness that is the vi command structure.

.P2

This

works by subdividing the current text

.CW 0,$ "" (

\(em the whole file) into appearances of its textual argument

.CW Emacs ), (

and then running the command that follows

.CW c/vi/ ) (

with dot set to the text.

We can read this example as, ``find all occurrences of

.CW Emacs

in the file, and for each one,

set the current text to the occurrence and run the command

.CW c/vi/ ,

which will replace the current text by

.CW vi. ''

[This command is somewhat similar to

.CW ed 's

.CW g

command.  The differences will develop below, but note that the

default address, as always, is dot rather than the whole file.]

.PP

A single

.CW u

command is sufficient to undo an

.CW x

command, regardless of how many individual changes the

.CW x

makes.

.P1

.WC u

.WC 0,$p

This manual is organized in a rather haphazard manner.  The first

several sections were written hastily in an attempt to provide a

general introduction to the commands in Emacs and to try to show

the method in the madness that is the Emacs command structure.

.P2

.PP

Of course,

.CW c

is not the only command

.CW x

can run.  An

.CW a

command can be used to put proprietary markings on

.CW Emacs :

.P1

.WC 0,$x/Emacs/a/{TM}/

.WC /Emacs/+-p

general introduction to the commands in Emacs{TM} and to try to show

.P2

[There is no way to see the changes as they happen, as in

.CW ed 's

.CW g/Emacs/s//&{TM}/p ;

see the section on Multiple Changes, below.]

.PP

The

.CW p

command is also useful when driven by an

.CW x ,

but be careful that you say what you mean;

.P1

.WC 0,$x/Emacs/p

EmacsEmacs

.P2

since

.CW x

sets dot to the text in the slashes, printing only that text

is not going to be very

informative.  But the command that

.CW x

runs can contain addresses.  For example, if we want to print all

lines containing

.CW Emacs ,

just use

.CW +- :

.P1

.WC 0,$x/Emacs/+-p

general introduction to the commands in Emacs{TM} and to try to show

the method in the madness that is the Emacs{TM} command structure.

.P2

Finally, let's restore the state of the file with another

.CW x

command, and make use of a handy shorthand:

a comma in an address has its left side default to

.CW 0 ,

and its right side default to

.CW $ ,

so the easy-to-type address

.CW ,

refers to the whole file:

.P1

.WC ",x/Emacs/ /{TM}/d

.WC ,p

This manual is organized in a rather haphazard manner.  The first

several sections were written hastily in an attempt to provide a

general introduction to the commands in Emacs and to try to show

the method in the madness that is the Emacs command structure.

.P2

Notice what this

.CW x

does: for each occurrence of Emacs,

find the

.CW {TM}

that follows, and delete it.

.PP

The `text'

.CW sam

accepts

for searches in addresses and in

.CW x

commands is not simple text, but rather

.I regular\ expressions.

Unix has several distinct interpretations of regular expressions.

The form used by

.CW sam

is that of

.CW egrep (1),

including parentheses

.CW ()

for grouping and an `or' operator

.CW |

for matching strings in parallel.

.CW sam

makes two extensions:

although

.CW .

(the most overloaded character in Unix) matches any character

.I except

newline, the regular expression

.CW @

(think of it as a big dot) matches any character, even newlines;

and the character sequence

.CW \en

matches a newline character.

Replacement text, such as used in the

.CW a

and

.CW c

commands, is still plain text, but the sequence

.CW \en

represents newline in that context, too.

.PP

Here is an example.  Say we wanted to double space the document, that is,

turn every newline into two newlines.

The following all do the job:

.P1

.WC ",x/\en/ a/\en/

.WC ",x/\en/ c/\en\en/

.WC ",x/$/ a/\en/

.WC ",x/^/ i/\en/

.P2

The last example is slightly different, because it puts a newline

.I before

each line; the other examples place it after.

The first two examples manipulate newlines directly

[something outside

.CW ed 's

ken]; the last two

use regular expressions:

.CW $

is the empty string at the end of a line, while

.CW ^

is the empty string at the beginning.

.PP

These solutions all have a possible drawback: if there is already a blank line

(that is, two consecutive newlines), they make it much larger (four

consecutive newlines).

A better method is to extend every group of newlines by one:

.P1

.WC ",x/\en+/ a/\en/

.P2

The regular expression operator

.CW +

means `one or more;'

.CW \en+

is identical to

.CW \en\en* .

Thus, this example

takes every sequence of newlines and adds another

to the end.

.PP

A more common example is indenting a block of text by a tab stop.

The following all work,

although the first is arguably the cleanest (the blank text in slashes is a tab):

.P1

.WC ",x/^/a/	 /

.WC ",x/^/c/	 /

.WC ",x/.*\en/i/	 /

.P2

The last example uses the pattern (idiom, really)

.CW .*\en

to match lines:

.CW .*

matches the longest possible string of non-newline characters.

Taking initial tabs away is just as easy:

.P1

.WC ",x/^    /d

.P2

In these examples I have specified an address (the whole file), but

in practice commands like these are more likely to be run without

an address, using the value of dot set by selecting text with the mouse.

.SH

Conditionals

.PP

The

.CW x

command is a looping construct:

for each match of a regular expression,

it extracts (sets dot to) the match and runs a command.

.CW sam

also has a conditional,

.CW g :

\f(CWg/\f2pattern\f(CW/\f2command\f1

runs the command if dot contains a match of the pattern

.I

without changing the value of dot.

.R

The inverse,

.CW v ,

runs the command if dot does

.I not

contain a match of the pattern.

(The letters

.CW g

and

.CW v

are historical and have no mnemonic significance.  You might

think of

.CW g

as `guard.')

.CW ed "" [

users should read the above definitions very carefully; the

.CW g

command in

.CW sam

is fundamentally different from that in

.CW ed .]

Here is an example of the difference between

.CW x

and

.CW g:

.P1

,x/Emacs/c/vi/

.P2

changes each occurrence of the word

.CW Emacs

in the file to the word

.CW vi ,

but

.P1

,g/Emacs/c/vi/

.P2

changes the

.I "whole file

to

.CW vi

if there is the word

.CW Emacs

anywhere in the file.

.PP

Neither of these commands is particularly interesting in isolation,

but they are valuable when combined with

.CW x

and with themselves.

.SH

Composition

.PP

One way to think about the

.CW x

command is that, given a selection (a value of dot)

it iterates through interesting subselections (values of dot within).

In other words, it takes a piece of text and cuts it into smaller pieces.

But the text that it cuts up may already be a piece cut by a previous

.CW x

command or selected by a

.CW g .

.CW sam 's

most interesting property is the ability to define a sequence of commands

to perform a particular task.\(dg

.FS

\(dg

The obvious analogy with shell pipelines is only partially valid,

because the individual

.CW sam

commands are all working on the same text; it is only how the text is

sliced up that is changing.

.FE

A simple example is to change all occurrences of

.CW Emacs

to

.CW emacs ;

certainly the command

.P1

.WC ",x/Emacs/ c/emacs/

.P2

will work, but we can use an

.CW x

command to save retyping most of the word

.CW Emacs :

.P1

.WC ",x/Emacs/ x/E/ c/e/

.P2

(Blanks can be used

to separate commands on a line to make them easier to read.)

What this command does is find all occurrences of

.CW Emacs

.CW ,x/Emacs/ ), (

and then

.I

with dot set to that text,

.R

find all occurrences of the letter

.CW E

.CW x/E/ ), (

and then

.I

with dot set to that text,

.R

run the command

.CW c/e/

to change the character to lower case.

Note that the address for the command \(em the whole file, specified by a comma

\(em is only given to the leftmost

piece of the command; the rest of the pieces have dot set for them by

the execution of the pieces to their left.

.PP

As another simple example, consider a problem

solved above: printing all lines in the file containing the word

.CW Emacs:

.P1

.WC ",x/.*\en/ g/Emacs/p

general introduction to the commands in Emacs and to try to show

the method in the madness that is the Emacs command structure.

.P2

This command says to break the file into lines

.CW ,x/.*\en/ ), (

and for each line that contains the string

.CW Emacs

.CW g/Emacs/ ), (

run the command

.CW p

with dot set to the line (not the match of

.CW Emacs ),

which prints the line.

To save typing, because

.CW .*\en

is a common pattern in

.CW x

commands,

if the

.CW x

is followed immediately by a space, the pattern

.CW .*\en

is assumed.

Therefore, the above could be written more succinctly:

.P1

.WC ",x g/Emacs/p

.P2

The solution we used before was

.P1

.WC ,x/Emacs/+-p

.P2

which runs the command

.CW +-p

with dot set to each match of

.CW Emacs

in the file (recall that the idiom

.CW +-p

prints the line containing the end of dot).

.PP

The two commands usually produce the same result

(the

.CW +-p