|
editor
NAME
ed
OVERVIEW
The Amylaar editors understand the following commands:
/ search forward for pattern
? search backward for a pattern
= show current line number
a append text starting after this line
A like 'a' but with inverse autoindent mode
c change current line, query for replacement text
d delete line(s)
e replace this file with another file
E same as 'e' but works if file has been modified
f show/change current file name
g Search and execute command on any matching line.
h help file (display this message)
i insert text starting before this line
I indent the entire file (from DGD ed v0.1)
j join lines together
k mark this line with a character - later referenced as 'a
l line line(s) with control characters displayed
m move line(s) to specified line
n toggle line numbering
p print line(s) in range
q quit editor
Q quit editor even if file modified and not saved
r read file into editor at end of file or behind the given line
s search and replace
set query, change or save option settings
t move copy of line(s) to specified line
v Search and execute command on any non-matching line.
x save file and quit
w write to current file (or specified file)
W like the 'w' command but appends instead
z display 20 lines, possible args are . + -
Z display 40 lines, possible args are . + -
DESCRIPTION
The mud's editor is a clone of the ex, the standard UNIX line-
based editor. Unlike vi or ex, ed() edits files in RAM, instead
of a temporary file. This means that ed() sessions on large files
use up the mud's memory allocation, and changes to a file will be
lost over a crash or shutdown, unless the buffer is saved
explicitly during the editing session. (There is support,
however, to autosave buffers when the editor is dested or
disconnects. This will be explained in furthur detail later.)
The editor has two modes, the command mode and the insert mode.
When in the command mode, a ':' prompt will be printed and the
cursor is put just after the prompt, similar to the mud's regular
command prompt. The lines input in the command mode will be
interpreted as editor editor commands, and will not insert text.
To insert text, you must first give an "insert text" command, such
as 'i'. The insert mode will print a '*' on each new line with
the cursor in the same location, so that the '*' disappears when a
character is typed. Regardless of how the input mode was invoked,
it may always be exited by typing a single '.' on a blank line.
This will apply any changes you made to the buffer while in input
mode, and return you to command mode.
During an edit session, almost all input typed will be interpreted
by the editor as command or input, depending on which mode you are
in. If you want to issue a "regular command," that is, one that
would normally be typed outside the editor, you can precede that
command with a '!' character, and type it on an otherwise blank
line. The '!' will "bang" you out of the editor and the rest of
the line after the '!' will be interpreted as if you were not in
an edit session at all.
Entering the Editor
-------------------
The editor is invoked with the ed() efun. This efun can be passed
a string, in which case this string will be the filename that the
editor is visiting when the session starts. If a filename is not
supplied, it will default to the file returned by
get_error_file(this_player()). If that file is is null, then the
string "No file." will be printed before the ed prompt, and the
editor will start without a current filename.
Upon first entering the editor, you will see the ':' prompt meaning
that you are in the command mode. All the rest of the editing
session will involve issuing commands in some way. Even inserting
text is dependent on a command to put the user in input mode. The
majority of the remainder of this document will be a breakdown of
the function and syntax of each command.
Exiting the Editor
------------------
There are three commands that will exit the editor. None of them
take any arguments, either before or after the command. That is
to say that these commands will always be typed as a single letter
on a blank line, while in command mode. The commands are:
q quit editor
Q quit editor even if file modified and not saved
x save file and quit
qQx Typing 'q' to exit a buffer that has been modified will result in
an error message telling you just that: that the buffer has been
modified. If you wish to abort your changes to a file, you must
exit using the 'Q' command. The 'x' command is just a time-saver,
and is functionally equivilent to typing 'w', then 'q'.
Line Syntax and the k Command
-----------------------------
These commands took no arguments and were not associated with any
particular lines in the buffer. Many of the commands that will be
described do, however. Some commands act on a single line, and
some on a range of lines. Most of these commands will act on the
current line by default, but you can often explicitly declare the
line that the command should act upon. In addition to a simple
number, there are different ways of referring to special lines.
All of these conventions can be used to target a command, or
simply to change your current line inside the editor.
When issuing a command that can be targeted to a specific line or
lines, it will be done like so:
Xcommand (single line)
X,Ycommand (line range)
In the the single line syntax, 'command' will be executed on line
'X'. In the ranged line syntax, 'command' will be executed on
lines 'X' through 'Y', inclusive. 'X' and 'Y' can be simple
numbers, but can also be symbols with special meanings:
'.' : the current line
'$' : the last line in the buffer
'X-n' : whatever line X is, minus n lines
'X+n' : whatever line X is, plus n lines
(in the last two, X defaults to '.' and n defaults to 1)
k You can also assign special meanings to symbols with the 'k'
command. The syntax of the 'k' command is:
Xkc
where 'X' is a line number (defaults to .), and 'c' is a character
between 'a' and 'z'. When this is done, line 'X' will later be
referenced as "'c".
When a line number or one of the symbols described above is typed
on its own without a command, the current line will be set to
that line. Here are some examples using the techniques described
above:
:5 => set current line to 5
:- => set current line to line 4
:6ka => mark line 6 as 'a
:2p => print line 2
:5,6p => print lines 5 through 6
:'ap => print line 6
:p => print line 4
:.,+3 => print lines 4 through 7
:3-,$ => print line 2 through the end of the buffer
:'a => set current line to line 6
Editing Text Part I - insert mode
---------------------------------
There are four commands that will put you into insert mode.
Insert mode is the best way to add completely new text into your
file, or make major adjustments. There are other commands that
change the content of the buffer which will be explained later,
but these commands are most often used for minor adjustments.
The changes will be applied to the buffer upon exiting insert
mode. The lines will be added to the buffer just as they were
typed in insert mode. Insert mode is exited by typing a single
'.' on a blank line. These four commands all put you into insert
mode:
a append text starting after this line
A like 'a' but with inverse autoindent mode
i insert text starting before this line
c change current line, query for replacement text
aAic The 'a' and 'i' commands are relatively the same, they only differ
in where the code is to be inserted. When the 'a' command is
used, the text is inserted after the current line. When the 'i'
command is used, text is inserted before the current line. So if
we were on line 4 and used the 'i' command to insert 3 lines of
text, the text that was on line 4 will be moved to line 7. The
'a' and 'A' commands both append text, but one will use
autoindenting and one will not. If autoindenting is set to ON
(see Options section), 'a' will autoindent and 'A' will not. If
autoindenting is set to OFF, the opposite will happen. See the
Options section for a description of the autoindent feature. The
'c' command will replace the current line with the lines that were
typed in the insert buffer. This is just an alias for typing 'd'
and then 'i'.
All four of these commands will act on the current line by
default, but like many other commands can be applied to specific
lines in the buffer. The 'a', 'A', and 'i' commands can be
applied to a single line, and the 'c' command can be applied to
a range of lines. Here are some examples:
3a => append the text at line 3 (the first line of the
inserted text will be line 4, and the old line 4 will
be moved below our inserted text)
1i => insert text at the beginning of the buffer
2,5c => replace lines 2 through 5 (inclusive) with the inserted
text (same as typing '2,5d' then 'i')
Editing Text Part II - standalone commands
------------------------------------------
The commands listed in this section are all used for editing text,
yet none of them will put you into insert mode. Each of these
commands serves a different purpose, so there isn't much to be
said about all of them. We will break them down individually:
d delete line(s)
j join lines together
m move line(s) to specified line
t move copy of line(s) to specified line
r read file into editor at end of file or behind the given line
s search and replace
I indent the entire file (from DGD ed v0.1)
d The 'd' command can be applied to a target line or range of lines,
and will default to the current line if no line is given. This
command simply removes the target line from the buffer and shifts
the rest of the lines up in its place. It takes no additional
arguments.
j The 'j' command can be applied only to a range of lines, and will
default to the range, '.,+1' if no line is given. This command
will remove the trailing '\n' from all but the last line in the
specified range. The result is that all of the lines in the
range will be concatinated onto one line. This command takes no
additional arguments.
mt The 'm' and the 't' commands can both be applied to a target line
or range of lines, and will default to the current line if no line
is given. Both of these commands take a single argument after the
command character. This argument should evaluate to a single line
number. When the 'm' command is issued, the target line(s) will
be moved to the line just after the line specified by the
argument. When the 't' command is used, the target line(s) will
be copied, instead. So typing '6,7m2' will move lines 6 and 7
just after line 2. The text that was previously on lines 6 and 7
will now be on lines 3 and 4. If we typed '6,7t 2' the same would
happen, but the text that was on lines 6 and 7 would remain in
place (only it would be on lines 8 and 9 because two lines got
added to the beginning of the buffer). The whitespace between the
command character and the argument is optional.
r The 'r' command can be applied only to a single line, and will
default to the last line of the buffer ('$') if no line is given.
This command takes a single argument after the command character.
This argument should evaluate to a filename, which will be read
into the buffer just after the target line. So typing
'3r /open/bogleg/.quotes' would insert the contents of
/open/bogleg/.quotes between lines 3 and 4 in our current buffer.
This whitespace between the command character and the argument is
not optional.
s The 's' command can be applied to a target line or range of lines,
and will default to the current line if no line is given. This
command will search the target line(s) for a regular expression,
and replace occurances of that expression with a specified string.
The 's' command takes a very special syntax:
s<delim><regexp><delim><str><delim><opt1><opt2>...<optn>
In this syntax, <delim> is a single non-whitespace character,
which will separate the different parts of our command. Most
people use '/' for <delim>, but if your expressions contain that
character you may want to use something else, such as '!' or '#'.
The first argument, <regexp>, is a regular expression that will
be applied to each of the target lines. The first sequence of
characters to match the regular expression in the line, will be
removed from the line and replaced with <str>. The third
occurance of <delim> is optional, and is only needed if you wish
to specify options to the 's' command. Each option is given by
a single character, and there are only two options that may be
specified:
g : replace all occurances of <regexp> on the line, not just
the first
p : after processing the line, print out the new contents of
the line to the user
If you have already done a search with the 's', '/', '?', or 'g'
commands, <regexp> may be null. If you don't specify a value for
<regexp>, the last regular expression given to any of the 4
searching commands will automatically be used.
I The 'I' command can be applied only to a range of lines, and will
default to the range, '1,$' if no line is given. This command
will indent the target lines in a fashion that is suitable to LPC
code. Since determining proper indentation on a line is dependent
on the indentation of the lines that came before it, this command
is rarely applied to anything other than the entire document. The
exception would be if you wanted to indent just one function
definition. This command takes no additional arguments.
Here are some examples using the commands described in this
section:
:4d => delete line 4
:2,4j => concatonate lines 2 through 4 onto line 2
:m 3 => move the current line to line 3
:.,$t0 => copy from the current line to the end of
the buffer to the very top of the buffer
:0r fn => insert the contents of /fn into the very
top of the buffer
:5s/foobar/bogleg/ => replace the first occurance of "foobar"
on line 5 with "bogleg"
:s!or/and!and/or!g => replace all occurances of "or/and" on
the current line with "and/or"
:7s//but/p => replace first occurance of "or/and" on
line 7 with "but" and print out the new
contents of line 7
:I => indent the entire file
Searching
---------
So far all the commands listed have had something to do with
editing the text in the buffer. The rest of the commands we will
talk about do not edit the buffer at all, but perform different
functions that make it easier to get around inside the editor.
The set of commands in this section help you find different spots
in the buffer. They are:
<line> set current line to specified line
/ search forward for pattern
? search backward for a pattern
g Search and execute command on any matching line.
v Search and execute command on any non-matching line.
The first command isn't really a command at all. All of the line
specifiers you have been using so far to target commands may be
used on their own. If you type a line number as a command, the
current line will be changed to that line number.
/? The '/' and '?' perform basically the same task. Each command
must be immediately followed by a regular expression. The editor
will then search from the current line to find the next line that
matches that regular expression. If you use '/', the editor will
search forward from the current line; if you use '?', the editor
will search backwards. When it finds a matching line, the current
line will be changed to the matching line. The regular expression
can be omitted, in which case the editor will implicitly search
for the last expression given to any of the '/', '?', 's', 'g', or
'v' commands. Both the '/' and '?' commands will always search
the entire file; you may not supply line specifiers.
gv The 'g' and 'v' commands, like '/' and '?', perform very similar
tasks. Each command can be applied to a target line or range of
lines, and will default to '1,$' if no line is given. The 'g'
command will search the target lines for lines that match a
regular expression, and execute a command on any matching line.
The 'v' command will do the same, but will execute the command on
any non-matching lines. These commands take a special syntax:
g<delim><regexp><delim><command>
Like the 's' command, <delim> can be any non-whitespace character
and is used to separate the different arguments of the command.
On any line where <regexp> is found, the editor will execute
<command>. <command> is any valid editor command, except for the
'g' or 'v' commands.
Obligatory examples:
:3 => set current line to line 3
:/bubba => set current line to next occurance of "bubba"
:? => set current line to previous occurance of "bubba"
:g/fart/d => delete all lines containing "fart"
:v/^#/p => print all lines not starting with a '#'
Printing Text
-------------
The following commands all tell you information about the content
of the buffer. They are:
= show current line number
p print line(s) in range
l line line(s) with control characters displayed
z display 20 lines, possible args are . + -
Z display 40 lines, possible args are . + -
= The '=' takes no arguments or line specification. You just type
it by itself and it will print out the current line number.
pl The 'p' and the 'l' commands can both be applied to a target line
or range of lines, and will default to the current line if no line
is given. Neither of these commands take any additional
arguments. Both of these commands will print out the lines
specified by the line or range of lines preceding the command.
The 'p' command prints the lines as if the list option is set to
OFF, and the 'l' command prints them as if the list option is set
to ON. The 'p' command can also be typed as 'P'.
zZ The 'z' and the 'Z' commands are both shortcuts for the 'p'
command. They can be applied to a single target line, and will
default to the current line if no line is given. These commands
can take one of three possible arguments, '+', '-' and '.'; this
argument will default to '+' if not specified. The equivilant 'p'
commands are as follows (X is the line specifier):
Xz- => X-20,Xp
Xz. => X-10,X+10p
Xz+ => X,X+20p
XZ- => X-40,Xp
XZ. => X-20,X+20p
XZ+ => X,X+40p
Examples:
:p => print current line
:= => display current line number
:z => print current line and the 20 lines following it
:Z. => print the 20 lines before current line, and the 20
lines following the current line
File Operations
---------------
This group of commands deal with the buffer as a whole, and how it
interacts with the files on disk. No matter what the contents of
the buffer, there is always a filename set in the editor as well.
This filename will be the file associated with saves. It is
important to recognize that the filename and the contents of the
buffer are separate entities, and one can be changed independent
of the other. These are the file-related commands:
f show/change current file name
e replace this file with another file
E same as 'e' but works if file has been modified
w write to current file (or specified file)
W like the 'w' command but appends instead
f The 'f' can be used with or without a following argument. If used
without an argument, the name of the file associated with the
current buffer will be printed. You can give it one argument,
which will change the current filename to that argument. Changing
the current filename does not change the contents of the buffer in
any way.
eE The 'e' and 'E' commands will replace the contents of the buffer
with the contents of another file on the system. They also change
the current filename to that file. The file is specified as a
single argument after the command. If you use 'e' when the
current buffer has been modified, it will result in an error
message. If you want to abort your changes and replace with
another file, you must use the 'E' command. Both of these
commands are effectively the same as quitting the editor with 'q'
or 'Q', then reentering it with another filename. If you do not
specify a filename, the current filename will be used by default.
Thus, typing 'E' by itself is a way of reverting the file to its
original contents.
d The 'd' command can be applied to a target line or range of lines,
and will default to the current line if no line is given. This
command simply removes the target line from the buffer and shifts
the rest of the lines up in its place. It takes no additional
arguments.
wW The 'w' and 'W' commands can both be applied to a target line or
range of lines, and will default to the range '1,$' if no line is
given. These will write the specified lines to disk. They take
a single argument following the command character, which is the
filename to write the lines to. If this argument is not given, it
defaults to the current filename. Thus, a single 'w' is a way to
save the buffer without exiting. The 'w' command will do a
straight write to the specified file, while the 'W' command will
append to the file instead. Note that these commands will never
change the current filename.
Options
-------
set There are various options that change the way different things in
the editor operate. With the exception of the "shiftwidth"
option, all of the options are boolean values. When you type
'set optname' you will enable the option, and 'set nooptname' will
disable. The 'no' prefix can be added to all of the options
except the "shiftwidth" option. The "shiftwidth" option is set by
doing 'set shiftwidth n' where n is an integer (see below).
Typing 'set' by itself will show you a list of options and their
current settings. Typing 'set save' will call the save_ed_setup()
function in the master object, which allows you to save your
settings in a file so they can be restored automatically the next
time you enter the editor. Here is a list of all the options and
their meanings:
number : when set to ON, line numbers will be prepended to
lines when printing them in command mode, or
editing them in insert mode.
list : when set to ON, tabs will be printed as '^I'.
when set to OFF, tabs will be printed as
whitespace. also, when set to ON, a '$' will be
printed at the end of each line.
print : when set to ON, the current line will be
reprinted after using the 'd' or 's' commands.
eightbit : when set to OFF, the eigth bit of any character
read from a file (with the r, e, or E commands)
will be stripped. normal user input will not be
affected.
autoindent : when autoindent is ON, anytime a new line is
entered into the buffer while in input mode, it
will be indented the same amount of spaces as the
line before it. if the new line begins with ^D
or ^K, each occurance of these characters at the
beginning of the line will be removed, and the
indentation level will back up one step. this
won't happen on screen, but will take effect
after the line has been entered.
excompatible : when set to ON, the meanings of \( and \) will be
exchanged with the meanings of ( and ) when used
in regular expressions
tabindent : when set to ON, the 'I' command will use tabs to
indent lines which are indented more than 8
spaces.
smallnumber : when set to ON, line numbers will be padded to 3
characters. when set to OFF, line numbers will
be padded to 6. has no effect if line numbering
is turned off.
shiftwidth : this option is set to a numeric argument, which
is the number of spaces that make up one "level"
of indentation. this is the number of spaces
that will be backed up with ^D and ^K, and the
'I' command will indent your code this amount.
d In addition to the set command, there is a shortcut command for
setting the 'number' and 'list' options. The 'n' command takes
no line specifier and no arguments. When typed, it will set
both 'number' and 'list' to ON, if they are off; or if they are
already on, will set both of them to OFF.
Help!
-----
h Finally, there is one more command that has not been discussed.
The 'h' command takes no line specifier and an optional argument.
When typed without an argument, it will print a summary of all
the editor commands. It can also be issued as:
h<cmd>
which will display help for specific command, <cmd>. The 'h'
command may also be issued as 'H'.
Many of the commands that act on a line or range of line, will
implicitly change the current line to the last line that was
processed. For instance, '1,$p' will set the current line to
the last line in the buffer. The default command is '+p'.
That is, if you just hit enter at the command prompt, without
typing a command, the current line will be advanced one line,
and that line will be printed.
Many of the commands in the editor make use of the regular
expression package in the driver. For more information on LPC
regular expressions, see the 'regexp' manpage.
If the user is disconnected during an editing session, the user
will reconnect back into the same editing session. The buffer
will be the same as it was at the time of the disconnect. If
the user is destructed during an editing session, the contents
of the buffer will be dumped to "fname~" where 'fname' is the
current filename of the buffer. This will allow you to recover
your changes in the event of a desting. Changes will not be
recoverable if the game crashes or shuts down (though it is
good practice to nicely destruct all your users before a
shutdown).
SEE ALSO
get_error_file(E), save_ed_setup(M), retrieve_ed_setup(M),
regexp(E), ed(E)
[help topics]
[EotL Help Files]
[EotL Home]
|