.+c "Handling Files"
.LP
\*N provides several commands to display and modify
files.
@(L
\*ccontents\*p       \(em display information about loaded files
.sp
\*clist\*p           \(em display source code lines
.sp
\*cedit\*p           \(em edit a file
@)L
.SH Listing Loaded Files
.LP
The
.CO contents
command lists the names of all loaded modules, or the contents
of one individual module.
.XX contents
If
.CO contents
is called without an argument, it prompts the user for which
subset (or all) of the loaded modules to list.
In the example below, the user opted to list all loaded files.
@(E
	5 -> \*ucontents() ;\*p
	Options: user/library/all/quit [u] ?\*ua\*p
	saber: object code
	environment: source code
	/lib/libc.a: archived library
	(void)
	6 ->
@)E
The files
.FN saber
and
.FN environment
are loaded when \*n starts up.
The file
.FN /lib/libc.a
is loaded as a result of a
.CO load
command in the system startup file.
.LP
If
.CO contents
is called with the name of a loaded file as an argument,
it will list the variables, functions and types defined in the file.
In the example below, the user lists the contents of
the 
.FN environment .
@(E
	1 -> \*ustruct S { int i, j ; } info ;\*p
	2 -> \*uint xyz ;\*p
	3 -> \*uvoid test() { return ; }\*p
	4 ->
	5 -> \*ucontents("environment") ;\*p
	Options: functions/variables/types/all [f] ?\*ua\*p

	Contents: environment: source code
	struct S { ... } ;
	struct S info ;
	int xyz ;
	void test() ;
	(void)
	6 ->
@)E
If
.CO contents
is called with the name of a library as its argument, it will
list all the modules archived in the library.
.SH "Listing Source Code"
.LP
The
.CO list
command displays source code lines.
.XX list
If no argument is given to
.CO list ,
listing begins from the current 
.ID "list location" .
The list location is set to either the first line of a file
when it is loaded, the line where execution
was interrupted when entering a break level, or the
last line displayed by a previous
.CO list
command.
@(E
	-> \*ulist() ;\*p
	/* begin listing at the current list location */
@)E
.LP
If a line number is supplied as the argument,
listing will begin at the specified line number
in the current file.
If the line number is negative, listing will begin
from the current list location minus the specified number
of lines.
If both a starting and ending line number are
specified, the source code between the two
lines will be displayed.
@(E
	-> \*ulist(10) ;\*p
	/* list lines starting a line 10 */

	-> \*ulist(-5) ;\*p
	/* list from list location - 5 */

	-> \*ulist(10, 30) ;\*p
	/* list from line 10 to line 30 */
@)E
If the argument to
.CO list
is a function, listing will begin at the beginning of the function.
If the argument is a filename, listing will begin at the beginning of
the file.
.LP
.CO List
displays the number of lines specified by the
.OP page_list
option.
.XX page_list
If more lines can be displayed,
.CO list
prompts the user for more.
If \*n is executing in a windowing system, the user can specify that
the output of
.CO list
be sent to a separate window by setting the
.OP win_list
option.
.LP
The source line corresponding to the current execution 
location will have a 
.EX * 
preceding the line number.
Lines at which breakpoints are set are displayed with a 
.EX B 
preceding the line.
Signals and errors are noted after the source line
at which they occurred.
.LP
Actions are listed in full above the line on which they are set.
Each line of the action is preceded by the notation 
.EX <An> ,
where 
.EX n
represents the debugging reference number. 
Tags and tagactions are displayed after the source line
that triggered them. 
Each line of a tagaction is preceded by the notation
.EX <Tn> ,
where
.EX n
represent the debugging reference number.
.SH "Editing Files"
.LP
The 
.CO edit
command allows users to edit source files.
.XX edit
If
.CO edit
is called without an argument, it
uses the list location to determine which file to edit.
.LP
If the argument
is a line number, editing will begin at that line in the file
specified by the current list location.
If the argument
is the name of a file, the editor will begin on
the first line of the specified file.
If
.CO edit
is called with the name of a function, the editor will begin
on the first line of the function.
.LP
The 
.CO edit
command will use the editor specified by the
.OP edit_name
option, which is set to the environment variable 
.SV EDITOR , 
or the editor 
.SC vi 
if the environment variable does not exist.
.LP
The
.OP edit_jobs
option sets the maximum number of new edit jobs that \*n should start.
.XX edit_jobs
If the editor is
.SC emacs ,
the value 
will be set to 1.
If the editor is
.SC vi ,
the value will be set to 2 on a windowing system or to 5 on a
non-windowing system.
.LP
\*N keeps track of the files that are currently open so
that windows can be reused whenever possible.
The
.CO jobs
command lists the currently open files.
If a request is issued to edit a new file, and there are already
.OP edit_jobs
number of jobs active, \*n will ask one of the existing edit jobs
to switch to the new file.  \*N uses a 'least recently used' algorithm
to determine which file to switch out of.
.LP
For example, users who prefer to have only one
.SC emacs
job active at a time can set the
.OP edit_jobs 
option to 1.
\*N will reuse the one emacs job for every new request to edit.
The 'switch to a new file' request in emacs
will open a new buffer for each new file that is edited.
.LP
\*N uses the string specified by the
.OP edit_options
option to determine the command line arguments for the editor.
Normally, this option is set to a sequence such as "+%d %s" to
indicate that the editor should start at line "%d", in file "%s".
\*N will fill in these two fields with the starting line number
and filename.
Versions of editors that create their own window must 
be told not to do so (with gnuemacs, the -nx or -nw switch). 
.LP
The 
.OP edit_line_file 
option describes the editor command sequence used to move to another
file at another line.  
The sequences "%d" and "%s" must be present
somewhere, and \*n will fill them in with the proper line number
and filename.  This is how \*n tells the editor to switch files 
if it cannot start another editing job.
.LP
The
.OP edit_query
option describes the editor command sequence to report the current
file name.  This command sequence must force the editor to echo a
string in the following format: '%s"%s"%s\en', where the '%s' inside
the quotation marks represents the current filename.  The first '%s'
string and the last '%s' string may contain garbage.
Each request to edit and the
.CO jobs
command cause \*n to send this query string the each active editing job.
If this option is not set, the \*(^Z feature on a windowing system 
will not work properly.
.LP
\*N attempts to initialize all of these options properly for the
.SC vi
and 
.SC gnuemacs
editors so that the
user does not have to set their values.
.LP
When moving between the editor and \*n, the user must leave the
editor is a state such that the command
specified by the
.OP edit_line_file
and the
.OP edit_query
options will be accepted.  
When using
.SC vi ,
the editor should not be left in the ex mode.
When using
.SC gnuemacs ,
the editor should not be left in the minibuffer.
\*N will report a 'query timed out' error if sending the 
.OP edit_query
string does not produce the correct response. 
If this should happen, it is usually
sufficient to change the state of the editor and retry the query.
.SH Editing and Windows
.LP
The
.OP win_edit
option determines whether \*n will place editing jobs in separate
windows.
.XX win_edit
If the option is unset, \*n will be suspended while an editing
job is active.
If the 
.OP win_edit
option is set, edit jobs will be placed in a separate window
and \*n will remain active.  The 
.OP win_edit_opts
can be set to specify options when the edit windows are created.
.LP
On a non-windowing system (or if the
.OP win_edit
option is not set), entering a \*(^Z to the editor
will suspend the edit job and return control to \*n.
If the edit was started on an option line or a previously loaded
file is being edited, a prompt will appear asking if the file should 
be reloaded.  To avoid this prompt, unset the 
.OP auto_reload 
option.
In a manner similar to the 
.SC csh ,
the 
.CO fg
command can be used to resume suspended editing jobs.
Loading successive files will reuse previously suspended 
editing jobs if an edit is requested (subject to the 
.OP edit_jobs
option).
.LP
On a windowing system, \*n is not suspended while editing.
Entering a \*(^Z in the edit window does not suspend the edit job, 
but rather tells \*n to load (or reload) the current file.  If \*n
was waiting on an option line, it would be as if a 'r' (for reload)
was entered.  If \*n is waiting for user input at a break level, 
(including the top level of the environment) 
it would be as if the command 'load("filename");' was entered.
The file should be saved before pressing \*(^Z.
.LP
A special exception occurs if the file being edited does not end
in a '.c' extension, in which case the command 'load()' is executed.
.LP
If an error or warning is detected while the file is being
reloaded, the edit job is updated automatically to the location
of the violation.
.SH "Editing in the Environment"
.XX environment
.LP
\*N provides a convenient way to edit statements in the environment.
If a syntax violation in the environment extends over one line, 
the user is prompted to edit the lines of input containing the
violation.
If the user selects the edit option, the text of the violation
will be copied to a temporary file, which is then loaded into
the editor.  
.LP
After correcting the input error and saving the file, 
the user can resubmit the contents of the editor by entering a \*(^Z.
\*N will echo each line of the file as it is read.
If another violation occurs, the user is placed back in the
temporary file. 
If the user quits the editor instead of entering \*(^Z, the
contents of the editor will not be submitted.
.LP
The 
.OP win_redo
option, if set, indicates that a new editor should be started 
on this temporary file.  
.XX win_redo
If the option is unset, a previous editing job is reused if possible.
.	\" Needed at end of every chapter
.he ''''
.fo ''- % -''