The Multi-language Object-Oriented Code Browser
Bob Weiner
Motorola Inc.
E-mail: <oo-browser@hub.ucsb.edu> (This is a mailing list.)
Edition 2.9.8
August 1995
Copyright © 1989-1995 Free Software Foundation, Inc.
All trademarks referenced herein are trademarks of their respective holders.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This edition of the OO-Browser User Manual is for use with any version 2.9.8 or greater of the OO-Browser. The OO-Browser is available for free use, distribution, and modification under the terms of version 2 or later of the GNU Public License (GPL). No representations are made about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty.
The OO-Browser was designed and written by Bob Weiner. Motorola, Inc. funded and donated this work for free redistribution as part of the InfoDock integrated productivity toolset. Torgeir Veimo and Mark Stern helped write the X OO-Browser core. Don Yacktman helped write the NEXTSTEP OO-Browser core. Jeff Sparkes helped with the Java language support.
The OO-Browser and InfoDock can be obtained via anonymous ftp on the Internet from: ‘/anonymous@cs.uiuc.edu:/pub/xemacs/infodock’. Installation instructions for the OO-Browser can be found in the ‘BR-README’ file in the OO-Browser distribution.
This manual documents the user interface and operation of the OO-Browser multi-language browser. It assumes a very basic familiarity in the use of the GNU Emacs editor as documented in [Stallman 87]. It also assumes familiarity with object-oriented software concepts. However, many technical terms used in this manual are given precise meaning in the glossary. See section Glossary. The OO-Browser is meant to be easy to use, so you can point and click to use it, rather than learning all of the key stroke commands.
Chapter 1 of the manual focuses on OO-Browser Environments to provide the reader with a picture of how to organize work for use with the OO-Browser (see section Working with Environments). See section Using the OO-Browser, if you would rather start with the interactive features of the browser. See section OO-Browser Features, for a quick overview of the browser’s features.
Throughout this manual, sequences of key strokes are delimited by braces, {}, command names are delimited by parentheses, (), and variable names are emphasized.
We hope that you enjoy using the OO-Browser and that it improves your productivity.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The OO-Browser is a multi-windowed, interactive, object-oriented class browser designed for professional use. Its user interface is similar to the well-known Smalltalk browsers [Goldberg 83], yet it is much more flexible and easy to use.
The OO-Browser is unique in several respects:
The picture on the following page highlights the major components of the OO-Browser user interface. (If you are reading the online Info version of this manual, see the last paragraph of this node for a link to the aforementioned picture.)
The windows across the top of the OO-Browser frame are called class listing windows; they display listing buffers with a single class name per line. The viewer window fills the bottom half of the frame. It is used to display class source and summary information. It is also used to display help on the OO-Browser command set. Pictured here in the viewer window is part of the browser help buffer, summarizing its command key bindings.
All key bindings described throughout this manual are effective only within listing buffers, unless otherwise indicated. This means that the keys may not be used within the buffers displayed in the class viewer window. Instead, all normal editing keys are available in most buffers displayed in the viewer window.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Whenever the OO-Browser is in use, an Environment is selected. An Environment may be built or simply specified. An Environment specification tells the browser what to include in the construction of an Environment. (See section Creating Environments, for more information.) An OO-Browser Environment includes a set of inter-class relationships together with a few browser settings. The phrase, the Environment, refers to the current OO-Browser Environment. Many browser commands depend on information in the Environment.
The set of classes included in an Environment is specified by two lists of directories, below which all of the Environment’s class source files are to be found. (The OO-Browser will automatically search sub-directories below the directories specified.) The first list of directories is called the Library search list; it defines the locations of stable, typically reusable classes that have been released for general use. The second list is called the System search list; it defines the locations of unreleased classes being developed, often for a particular system. All class names within a single Environment must be unique to ensure proper operation of the browser.
The OO-Browser lets one create, update and save Environments. Once an Environment file has been created, it may be loaded at any time. The browser will then use this Environment for all of its operations until another one is loaded.
The browser maintains a separate Environment for each programming language on which it is used. Thus, if one switches from Eiffel to C++ browsing and then back to Eiffel browsing, the Eiffel environment will not need to be reloaded; it will appear immediately and the frame will appear as if the Eiffel OO-Browser were invoked for the first time.
The recommended default name for Environment files is, ‘OOBR’. We recommend that you store each Environment in the top-level directory of the first system pathname in the Environment, i.e. the root directory of a system’s code.
Environment files are automatically created and loaded by the OO-Browser so that you need never become familiar with their format. You are responsible for remembering which Environment files you create and for requesting their use whenever desired. See section Invoking the OO-Browser, for information on how to specify a different Environment file for use.
1.1 Creating Environments | ||
1.2 Building Environments | ||
1.3 Loading Environments | ||
1.4 Saving Environments |
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Environment specifications are useful when one wants to describe a number of Environments to the OO-Browser but wants to defer their construction until later. Large environments then can be built overnight. See section Building Environments, for more information.
Every Environment must be specified before it can be built or used.
Thus, specifying an Environment is the first step in creating it.
Environment specifications are created with the {C-c C-c}
(br-env-create)
command, which prompts for all necessary
information. This command may be invoked repeatedly to quickly specify
a number of different Environments.
Here are the Environment specification components for which you will be prompted:
System search directories
List of directories below which other System directories containing class source code and directories of class source files may be found.
Library search directories
List of directories below which Library files of class source code and directories of class source files may be found.
EIFFEL NOTE: We strongly suggest that if you have previous versions of library class source below any of these directories, that you move them elsewhere, e.g. ISE’s Eiffel version "2.1" directory of source. These will cause class naming conflicts that the browser will not resolve to your satisfaction. The basic rule is that every class name within a single Environment should be unique. Use {M-e} to help find duplicate classes.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
An Environment specification tells the OO-Browser what to include in the Environment, but the Environment still must be built before use. When a new Environment must be built or when a large number of changes have been made to classes in the Environment, the following commands are useful:
build all Env classes (br-env-rebuild)
(This prompts for whether
or not to use a background process to build the Environment.)
build Env Library classes only (br-lib-rebuild)
build Env System classes only (br-sys-rebuild)
When class names or locations have changed or the Environment’s inheritance structure is modified, the Environment must be rebuilt. For small Environment changes, one may use the class addition and deletion features of the browser. See section Adding and Deleting Classes, for more information.
The OO-Browser lets you build large environments in the background so you can go on to other work while waiting on a build. When the build is complete, it will ask you whether you want to browse the built Environment.
Alternatively, very large Environments may be built overnight by
invoking Emacs in batch mode at a scheduled time. The shell command
line to use is of the form (substitute your local OO-Browser
installation directory for <BR-DIR> below):
emacs -batch -l <BR-DIR>/br-start.el Env-Spec-File \ ... Spec File -f br-env-batch-build > log-file
for example:
emacs -batch -l br-start.el OOBR -f br-env-batch-build > log-file
Typically when using the above command line, one should redirect the standard output stream to a log file for later examination, as is done in the above example. This helps ensure that either the Environment built successfully or a message indicating the cause of failure is provided.
Note that the Environment specification file must have been created prior to execution of this command so that the browser knows what to build.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
A new Environment may be loaded for use at any time within the
OO-Browser. One may either select the load Environment command from the
OO-Browser command summary or simply use the language-specific browser
invocation command originally used to start the browser, except
this time, precede it by a prefix argument. For example, {C-u C-c
C-e} which invokes (eif-browse)
, would prompt for and then load
a new Eiffel environment, even when one is already browsing an Eiffel
environment.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The OO-Browser automatically builds and saves Environments in most cases. Occasionally one may find a need to force the Environment to be saved to a file, as in the case when one wants to save an Environment under a different file name.
Use {C-c C-s}, the (br-env-save)
command to force an
Environment save to occur. The command will prompt for a file to save
to, with the default as the current Environment file name.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The OO-Browser supports the following languages: C++ or G++, C, Info (the online manual format), CLOS (Lisp), Eiffel, Objective-C, Java (as documented in [Java 95]) and Smalltalk. The OO-Browser may be used on source written in any of these languages by using {C-c C-o} or, if that key has not been setup, by using {M-x oobr <RET>}. This command will prompt for the language to browse, the Environment specification of directories to browse, and then will either load the Environment or build it and then display the set of classes (or nodes) in the Environment. (Choose C++ if you are browsing plain C code.)
Alternatively, you can invoke the browser on a specific language Environment, e.g. to bring back the last Environment browsed under that language. The language-specific browser invocation commands are: {M-x eif-browse <RET>}, {M-x c++-browse <RET>}, {M-x info-browse <RET>}, {M-x clos-browse <RET>}, {M-x objc-browse <RET>}.
A prefix argument given to any of these commands will cause it to prompt for an Environment file to use as the current Environment.
On startup, if the selected Environment has been saved to a file, it will be loaded; otherwise, the user will be asked to specify the Environment. The specification will be saved under the previously given file name. The browser will then load this Environment specification file.
If the browser loads an Environment file and finds only a specification,
it will prompt the user in the minibuffer window with a request to build
the Environment. It will continue to prompt the user until a full
Environment is built or loaded and then the browser will start,
displaying its multi-windowed interface. To abort from these prompts
and to cancel the browser invocation request at any time, use
{C-g} (keyboard-quit)
, the standard way to abort an
unfinished command within Emacs.
Once an Environment has been loaded, entering and quitting the browser are rapid actions, allowing a smooth transition between editing and browsing.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The OO-Browser starts by displaying all top-level classes in the Environment. Top-level classes are those that do not inherit from any others. The browser can show all top-level classes or System or Library classes only. Once in the browser, use:
System top-level classes only
Library top-level classes only
all top-level classes in Environment
Note that selection of any of these commands does not affect the ancestry or
descendancy trees for any given class. Each simply limits which trees are
easily accessible for browsing. For example, selection of Library
top-level classes only, followed by the browser show children command,
{c} (br-children)
, would display the name of a System
class if the System class directly inherits from the selected Library
class.
To see an ordered listing of all of the classes in a particular part of an Environment, use a prefix argument with the commands given above:
all System classes
all Library classes
all Environment classes.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Many browser commands operate on the current entry in a listing window.
{C-n} (br-next-entry)
moves point to
the next entry in a listing buffer. {C-p}
(br-prev-entry)
moves to the previous entry. Both take prefix
arguments and use them as the number of entries by which to move.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Many standard editing keys are rebound in listing buffers to
provide a useful set of accessible commands. Nonetheless, one needs to
be able to store and to edit listing buffers. The {C-c
C-w} (br-write-buffer)
command provides this capability. The
command prompts for a file name under which to save the current buffer.
One may then quit the browser, read in the file and edit it as a plain
text file.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
{c} displays the children of the class at point; {p} displays its parents. {C-u c} displays the children of all classes in the present listing window; {C-u p} does the same for parents.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The OO-Browser is very fast at computing ancestor and descendant hierarchies, accounting for multiple inheritance and cycles where permitted. Descendant and ancestor listings provide an immediate overview of some key relationships among class groupings.
With point on any class entry line in a listing buffer, {d} shows descendants for the class and {a} shows ancestors. {C-u d} shows the descendant trees for all classes in the current listing buffer and {C-u a} does the same for ancestors.
The ancestor tree for a given root class is normally shown branching out from the root class. This means that higher-level ancestors, those further away from the root class, are shown in descending trees below lower-level ancestors. The leaves of the tree represent the ancestors furthest from the root, as one might expect.
This, however, is the inverse of inheritance trees. Some people prefer
to see ancestor trees like inheritance trees, with parents above
children. This is an inverted ancestor tree. To obtain this
view of ancestors use {M- -1 a} for ancestors of the current
class. For ancestors of all classes in the current buffer, use
{M- -2 a}, or any negative prefix argument lest than -1.
Inverted ancestor trees may be made the default by setting
br-invert-ancestors
non-nil, as in:
{M-x set-variable <RET> br-invert-ancestors <RET> t <RET>}
This is a personal setting that affects all Environments used by the browser.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
One of the major uses of the OO-Browser is to view or edit class source texts. {v} will view the source for the class or element name at point in a read-only mode in the viewer window; it will not select the viewer window. {e} does the same, except that it edits the element source in a read-write mode, if the user has write permission for the source file. It also selects the viewer window.
A prefix argument to either of these commands, as in {C-u v} or {C-u e}, causes them to prompt for the entry to display. Full class and element name completion is provided once an Environment has been loaded and built. See section Completing Names.
The value of the variable br-edit-file-function is the function that the browser calls when a source file entity is displayed for editing. The value of br-view-file-function is the function called to view a source file entity. See section Using an External Viewer or Editor, for information on using non-Emacs editors and viewers with the browser.
If a user has no read access rights to a file, this will be apparent
when the browser tries to display the file and fails. If the user does
not have write permission to the class source file, the standard
br-edit-file-function may display the file in a read-only mode
(indicated by two percent signs, %%, at the front of the buffer mode
line). This is a warning that one should not attempt to edit the file.
In some cases, one really wants to try to edit such a file; in those
cases, the buffer may be toggled between read-only and read-write modes
via the Emacs command, (toggle-read-only)
, usually bound to
{C-x C-q}.
Once a class has been displayed for viewing, {<SPC>} will scroll its source text up (forward) almost a windowful; {<DEL>} will scroll it down (backward) almost a windowful. In fact, this is a general means for scrolling the OO-Browser viewer window whenever point, as shown by the Emacs cursor, is in a listing window. When a class is selected for editing, {C-v} will scroll up, {M-v} will scroll down, assuming the standard Emacs key bindings.
Sometimes one needs to quickly switch back and forth between the viewer
window and the current listing window. The normal Emacs window
movement commands often are cumbersome in such instances. Instead
(br-to-from-viewer)
bound to {C-c C-v}, allows the
desired back and forth movement. It acts as a toggle switch,
alternately moving between the buffer in the viewer window and the prior
listing buffer.
By default, the OO-Browser displays class definition files in their
entirety. If there are multiple classes in a file, you will be able to
scroll through all of them. If you prefer that only the selected class
be visible, enable the br-narrow-view-to-class
option flag. When
set to a non-nil value, this flag narrows the source buffer so that only
the class of interest and its preceding comments are visible. To
examine other classes in the same file, you must execute a {C-x n
w} (widen)
command when in the narrowed buffer. (Use
{C-x w} under Emacs 18.)
If the browser is used on a small screen, it may be helpful to use the
a full frame to view or edit a buffer of source code. If point is in a
listing buffer, pressing {1}, the number one, will expand the
viewer window buffer to the full frame. When the browser is
re-invoked, it will look just as it did before. If point is in the
viewer window, {C-x 1} (delete-other-windows)
, will do
practically the same thing, except that when the browser is re-invoked
it will not look precisely as it did before.
If point is in a listing window, the buffer displayed in the
viewer window may be killed with the {C-c C-k} (br-kill)
command. (A killed buffer is removed from the current Emacs session.)
If point is in the viewer window, as it will be after editing a class
buffer, use the standard Emacs command {C-x k}
(kill-buffer)
instead.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
A feature of a class is either a routine or attribute defined in
the class. An element is either a feature or an instance of a
class. A number of OO-Browser languages support feature browsing, as
documented in Language-Specific Notes. Instance browsing is only supported
in very limited form, for class instances which exist within the code
itself. For example, under Common Lisp and CLOS, a default class called
[function]
is defined whose instances are all named functions
defined within the environment. A default class is a class
created to categorize elements of the Environment for browsing; default
classes are not specified within the Environment source code.
Use {f} to display a listing of the features or elements of the class at point, including inherited features. Generally, this includes only routines. Use {M-0 f} to turn off the display of inherited features; use the same command again to re-enable display of inherited features.
If inherited features are off and there are no feature definitions for the class, the class definition is displayed instead, so that its feature declarations may be browsed.
Use {C-u f} to display a listing of the features or elements of all classes in the present listing window. Prior versions of the OO-Browser used {r} to display features. This key remains for backward compatibility but may be used for another purpose in the future.
Move point to an element name and use {v} to view its source definition or {e} to edit its source. Use {F} to see the full signature tag of an element, which includes its argument names and types, if any. {C-u F} lists the signatures of all elements in the current listing. This is handy when several elements from the same class have the same name but differ in signature.
See section Using the Mouse, for how the Action and Assist Keys may be used for browsing elements.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The definition of a category is language-specific. Some languages such as Smalltalk use categories to group related classes together. The OO-Browser does not yet support this kind of category.
A set of Objective-C categories segments a single class into groupings of related features. When a class category is defined, the category name appears within a set of parentheses, so the OO-Browser displays category names with parentheses around them to distinguish them from classes. The aggregation of all of the categories defined by a class and its ancestors represents the complete class definition. The OO-Browser does support this kind of category.
Use the {C} key when point is on a class listing entry to obtain a list of the categories defined for the class within the Environment source code (this excludes inherited categories). Use {C-u C} to list the categories for all classes in the current listing. Thus, to see the full set of categories for a class, use {a} to list the ancestors of the current class and then {C-u C} to show all direct and inherited categories of the class.
Use {v} or {e} to view or edit the class category definition associated with a category entry at point. See section Browsing Implementors, for an explanation of how to browse the classes that directly implement a category.
Use {f} with point on the default [category]
class to
list all categories defined in the Environment.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The definition of a protocol is language-specific. It generally refers to an interface specification to which a class is said to conform. A class conforms to a protocol by implementing the set of features defined in the protocol.
Presently, the OO-Browser support protocols only under Objective-C. Objective-C protocols are sometimes called formal protocols. Protocol interfaces are specified in a manner similar to classes but their features are only implemented in conforming classes. A single protocol can inherit from any number of other protocols; thus, any conforming class must conform to all of its ancestor protocols.
Class definitions list the protocols to which they directly conform, within a set of angle brackets. So the OO-Browser displays protocol names with angle brackets around them to distinguish them from classes.
Use the {P} key when point is on a class listing entry to obtain a list of the protocols to which the class directly conforms (this excludes inherited protocols). Use {C-u P} to list the direct protocols for all classes in the current listing. There is not yet a way to show the complete set of protocols to which a class conforms, which includes all protocols inherited from other protocols and all protocols inherited from ancestor classes.
If you use {P} when point is on a class’ protocol entry, the specification of the protocol will be displayed. Use {v} or {e} to view or edit the class or class category definition associated with a protocol entry at point.
Use standard class browsing keys when on a protocol entry to examine its parents, children, ancestors or descendants. See section Browsing Implementors, for an explanation of how to browse the classes that directly conform to a protocol.
Use {f} with point on the default [protocol]
class to
list all protocols defined in the Environment.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Sometimes it is important to see the list of classes that define a particular element name. These are called the element’s implementors. With point on an element listing, {I} will compute and display the element’s implementor list. {C-u I} will do the same for all elements in the present listing.
Move point to an implementor class name and then use {v} or {e} to view or edit the element associated with the class. If an element name is defined with different signatures in a single class, the class will be listed as an implementor multiple times. Each class entry can be used to display a different element. {C-u F} will display the element signature associated with each class entry in the same order as the class entries in the present listing buffer.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
When done with a browser listing buffer, one should clear and exit from the buffer’s display with {x}. This command also displays the previous listing level, if any, and moves point to its previous position within this buffer.
In this way, the command provides a quick and clean way to exit back to a previous listing level; you may exit a single level at a time or all the way back to the top-level listing buffer through repeated invocation of the command or by sending a prefix argument value to the command.
There is no need to exit from listing buffers to quit from the browser. You may quit, perform other actions, and then re-invoke the browser at the same point from which you left.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
{q} quits from the browser temporarily. The same command with a prefix argument quits from the browser permanently and kills all non-modified browser buffers. It will not kill any of the class source buffers.
If you are familiar with Emacs windowing, you may quickly alter the window configuration of the frame while in the browser, either intentionally or more likely unintentionally. If you execute non-browser Emacs commands while in the browser, you may find other buffers have taken the place of your browser buffers. In either case, you may refresh the browser display and restore it to the way it was when you originally invoked it, by using {M-x br-refresh <RET>} or with {C-c C-r} when in a browser listing buffer.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Once configured, mouse control within the OO-Browser is helpful and easy to use. Under InfoDock, XEmacs and Emacs 19, the right mouse button, called the Menu Key, pops up a menu of OO-Browser commands when clicked within an OO-Browser listing buffer. Under XEmacs and Emacs 19, the same menu is added to the menubar used in listing buffers. Under InfoDock with mode-specific menus turned on, the menubar is devoted to OO-Browser commands.
Even if the above features are not available to you, if you have mouse support in your Emacs, the following features are available. A single mouse button, called the Action Key, is used for most purposes. The Action Key is bound to the shift-middle mouse button under standard Emacs, to the middle mouse button under InfoDock, or to the shift-left button on a two-button mouse.
A second button, called the Assist Key, is used for help and other
ancillary functions. The Assist Key is bound to the shift-right button.
The ‘br-help-ms’ file uses a table format to summarize mouse
control within the browser, it may be displayed within the browser via
the {H} (br-help-ms)
command.
Within an empty listing buffer, clicking the Action Key displays the browser command menu; the Assist Key displays a menu listing language-specific source files. Within this menu, the Action Key selects a buffer for display, the Assist Key marks the buffer for deletion. To perform the deletes, click the Action Key after the last line of the menu. If the Assist Key is clicked after the last line, the deletes are undone and a list of all current editor buffers is shown, allowing you to select buffers other than those containing classes.
The mouse buttons can be used to scroll the viewer window a page at a time by clicking after the end of any line. The Action Key scrolls the window up (forward) a windowful and the Assist Key scrolls it down (backward) a windowful.
The Action Key acts as follows when in an OO-Browser listing buffer. If the button is pressed:
The Assist Key acts as follows when in a listing buffer. If it is pressed:
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The OO-Browser is very intuitive to operate, but help is always a key or button press away when needed. Besides the online and printed versions of this manual, there is an online quick reference built into the OO-Browser. Once the browser windows appear, press {h} at any time to bring up a buffer full of command help.
For more extensive documentation on each browser key, use the Emacs command {C-h k key-sequence}.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The {w} (br-where)
command can be used to locate the
source file associated with a listing entry. It prints the full
pathname of the source file in the minibuffer window.
A prefix argument as in, {C-u w}, causes the command to prompt
for the class or element name to locate. Full completion is
provided. See section Completing Names.
The {m} (br-match)
command provides a quick mechanism for
locating any classes in the Environment whose names match to an
expression in part or in whole. The browser will prompt for the
expression to use. All matching names are displayed in ascending order.
By default the expression is treated as a regular expression. A prefix argument sent to the command tells it to treat the expression as a string.
After each search, the command reports the number of matching classes found and displays them in the current listing window. It then prompts for another expression to key on. The selected set is then filtered once again. This cycle continues until the {<RET>} is pressed without giving an expression. This process allows for easy location of desired classes.
When the command is invoked (first time through the loop), if the {<RET>} key is pressed without giving a match expression, the search will match to all classes referenced in the Environment.
If you want a regular expression to match to whole class names exclusively, begin it with a ’^’ and end it with a ’$’ character which match to beginning of name and end of name, respectively. Thus, "^....$" would match to class names with exactly four characters. A string match always matches to any class name that contains the matching string.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The {M} (br-match-entries)
command works much like the
(br-match
) command described in, Locating Entries, except
that it matches only to entries in the current listing buffer. It thus
allows you to filter a listing to just those entries that you care to
browse. It prompts you for a regular expression of entries to match
and then deletes entries that don’t match. A prefix argument sent to
the command tells it to treat the match expression as a string.
After each search, the command reports the number of matching entries found and displays them in the current listing window. It then prompts for another expression to match. The selected set is then filtered once again. This cycle continues until the {<RET>} is pressed without giving an expression. This process allows for easy incremental filtering of listings.
When the command is invoked (first time through the loop), if the {<RET>} key is pressed without giving a match expression, the search will match to all entries in the listing, so no filtering will be done.
If you want a regular expression to match to whole entries exclusively, begin it with a ’^’ and end it with a ’$’ character which match to beginning of line and end of line, respectively. Thus, "^....$" would match to entry lines with exactly four characters. A string match always matches to any entry that contains the matching string.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Once you have a desired set of names in a browser listing window, you may want to re-order. For a simple ascending order sort by name, use {o}. To sort the lines in the current listing window accounting for leading whitespace, use a positive prefix argument. To sort the lines in descending order accounting for leading whitespace, use a negative prefix argument. Note that all of the top-level class display commands automatically order their output lists. See section Displaying Top-Level Classes.
To sort in descending order, first sort into ascending order with {o} to strip any leading whitespace and then use a negative prefix argument to sort the names into descending order.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The {#} (br-count)
command displays in the minibuffer the
number of entries in the present listing buffer.
The {M-c} (br-class-stats)
command displays in the
minibuffer window the number of parents and children for the selected
class; with a prefix argument, it prompts for the class name to use.
The {M-e} (br-env-stats)
command displays the
specification for the current Environment along with a few Environment
statistics (OO-Browser version used to build the Environment, total
classes, number of System and Library classes, number of duplicate and
undefined classes) in the viewer window. With a prefix argument, it
displays in the minibuffer window the basic statistics only, leaving the
contents of the viewer window intact.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Presently, this feature is available only for Eiffel browsing.
With point on a class name in a listing buffer, the command,
{i} (br-entry-info)
, displays the class’ parents,
attributes and routines with routine call summaries. This is its
default behavior.
{M-x eif-info-use-short} will instead cause the
(br-entry-info)
command to run the Eiffel ’short’ command on a
class, thereby displaying its specification.
{M-x eif-info-use-flat}, will cause the command to run
the Eiffel ’flat’ command on a class, thereby displaying its complete
feature set. Use {M-x eif-info-use-calls} to reset this command
to its default behavior.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
A file containing class definitions may be added to the Environment with
the {C-c ^} (br-add-class-file)
command. This will
prompt for the file name, scan the file, and then update the
Environment. If a class defined in the file is already in the
Environment, its information will be replaced with the information
gathered from the file; otherwise, the class will be added to the
Environment. This command does not update the browser display; one
must issue a browser command after the add command in order to see any
change.
To add a single class from a file containing multiple classes, read the file into an Emacs buffer, narrow the buffer to the desired class and then execute the add command. See Narrowing in The Gnu Emacs Manual.
{C-c ^} is normally globally bound in the OO-Browser initialization file, ‘br-init.el’, so that it may be used outside of the browser when editing classes.
To delete a class from the Environment, display the class name in a
listing window using the {m} (br-match)
command if
necessary. (See section Locating Entries.) Move point to the desired class
name and hit {C-c C-d} (br-delete)
to delete the class.
This will remove the class name at point after the class is deleted from
the Environment.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Whenever the browser prompts for a name and an Environment has already been loaded or built, one may use the browser’s identifier name completion facilities to help in entering the name. These features allow you to type as much of the name as you know and then have the browser fill in what it can. The relevant keys are:
complete as much as possible of a class or element name
complete up to one word of the class or element name
show all possible completions for class or element name
You may also use the browser’s completion facilities outside of the browser,
for example, when editing code. See section Using Standalone OO-Browser Features, and the description of
(br-complete-type)
.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The X interface to the OO-Browser is called, xoobr. It provides a simple but effective means of navigating through OO-Browser hierarchy and element relations. (The NEXTSTEP OO-Browser is very similar to the X version, so use the documentation herein if you need any help with it.)
Any number of xoobr sessions may be established at the same time. Each one is used to gain a particular view on an Environment. The textual OO-Browser is used to filter a set of classes for display in an xoobr process. For this reason, xoobr is invoked from within the textual OO-Browser.
{M-g} (br-tree-graph)
displays the current listing
buffer’s entries in a graphical form. It ignores the show
features setting so that you can capture the current listing without
the need to alter that setting.
{M-d} (br-tree)
selects the current class and displays
its descendancy graph in tree-form by starting a new xoobr session.
With a prefix argument, {C-u M-d}, displays descendancy trees
for all classes at the current browser level. They are all grouped
under some imaginary joining node so as to maintain the concept of one
tree per xoobr view.
{M-f} (br-tree-features-toggle)
is used before creating a
graphical descendency view to determine whether or not to include the
features of each class in the listing as child nodes of the class.
It toggles between showing features and not showing them in descendancy
views. The setting applies across all OO-Browser languages. The
default setting is to not add features to the view.
Xoobr views are meant to complement the textual browser interface. Therefore, the two most common actions used in the text browser are performed in a similar manner within an xoobr view. A click on a node with the left mouse button highlights the node and then displays the appropriate class text in the chosen editor, ready for editing. A click of the middle button performs similarly but displays the associated class for viewing only.
[The right mouse button is disable in this release of the X OO-Browser because of an inability to debug a problem in limiting its use to tree nodes.] The right mouse button when depressed over a node displays a short menu of commands that may be applied to the node. The only ones of real interest at this point are the collapse and expand entries which let you hide and then restore the display of a node’s subtree. This allows you precise control over the amount of detail you receive in various parts of the hierarchy.
The Help button in the upper right of the an xoobr session window when selected displays a few pages of help text regarding the program itself.
The {M-k} (br-tree-kill)
command will prompt to see if
you want to terminate all xoobr sessions started from within the current
editor session. If you answer affirmatively, all such processes
disappear, as your screen will quickly indicate.
The upper left of a session window contains a set of buttons which
display menus. The only menu entry you need be concerned with at all is
found under the file menu, labelled "Quit". xoobr processes may also be
terminated by issuing the kill command mentioned just before. A third
menas of killing such processes is by sending the permanent
(br-quit)
command, {C-u q}, to the textual browser. You
will then be prompted as to whether you want to terminate all xoobr
sessions started from within the current editor session.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The OO-Browser allows you to select your desired editor and viewer programs when you use a multi-windowed display. By default, both of these tasks are handled by Emacs so that the browser works on text terminals. If you choose an external editor or viewer, Emacs will still automatically be used whenever you invoke the browser from a text terminal.
If you wish to edit classes displayed by the browser in an editor other
than Emacs, set the br-editor-cmd variable to the command with
which you wish to edit. Arguments to the command should be placed in
the variables named br-ed[1-9], with one string argument per
variable. Unused variables should have the value nil
. Bear in
mind that the command must generate a new window under your window
system. For example, the vi editor under UNIX does not create its own
window, it runs within the window in which it is created. Under X one
would create a new xterm window and then invoke vi. The command line
would be xterm -e vi, the settings in your personal
initialization file would then be:
(setq br-editor-cmd "xterm" br-ed1 "-e" br-ed2 "vi"
br-ed3 nil br-ed4 nil br-ed5 nil
br-ed6 nil br-ed7 nil br-ed8 nil br-ed9 nil)
This editor will only be used when the browser is run under a window system external to Emacs, like X. (In such a case, the Emacs variable window-system will be non-nil).
If you want to view classes in a read-only fashion outside of Emacs, set the following br-viewer-cmd and br-vw[1-9] variables in a similar manner as you did for the editor variables above.
For example, to use ‘xmore’, an X-compatible version of ‘more’, as your viewer, use the following settings (assuming all the br-vw variables are already null):
(setq br-viewer-cmd "xmore")
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The br-keep-viewed-classes flag is turned off by default, indicating that each time a class is viewed immediately after another one, the prior one is deleted. If it is set to any non-nil value, all viewed classes are left around for selection.
In typical use, the burden of having to manage all viewed classes is greater than the benefit of leaving them in memory. This is why the flag is off by default. The class buffer menu can be used to delete buffers when you want to trim down the number with which you are dealing. See section Using the Mouse, for details on this technique.
The value of the br-keep-viewed-classes flag may be easily
toggled with the (br-toggle-keep-viewed)
command bound to
{V}.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
After you are familiar with the opening OO-Browser version screen, you may want to disable its display each time the browser is started. This is done by setting br-inhibit-version non-nil, as in the following line that would go in your personal OO-Browser initialization file:
(setq br-inhibit-version t)
This option has no effect on the display of the help screen which
follows the version screen. Even with this option set, you may display
the version screen at any time from within a browser listing
window by using {C-c #} (br-version)
.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
See section Browsing Descendants and Ancestors, for more information.
This is a global OO-Browser option, it affects all Environments.
Ancestor trees are normally shown to emphasize how the trees branch out from their origin. An initialization file line such as:
(setq br-invert-ancestors t)
will cause the display of ancestor trees to be inverted such that the further ancestors appear as roots of the trees and parents (the nearest ancestors) appear as leaves in the trees. This ensures that all listing displays reflect the class inheritance structure with children below parents.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This is an Environment-specific option set during Environment specification. See section Creating Environments.
Half of the browser lookup tables can be built whenever an Environment is loaded. If this option is set, these tables will be stored in the Environment file instead. This will speed Environment loading somewhat, at the cost of doubling the file size per saved Environment.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This is an Environment-specific option set during Environment specification. See section Creating Environments.
This is a highly recommended option that allows for fast descendant lookups. The only time one would turn off this option would be when a file system is extremely short of space.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The OO-Browser normally orders classes and elements in listing windows
according to the ASCII character set. This sort order is controlled by the
br-sort-options variable which specifies the command line options
sent to the system sort
command. (Under any Emacs 19 variant,
this variable is not used by the br-order
command, bound to
{o}.)
The value of this variable should be a single string of options such as
-fu
(the default) or nil
for no options. The -f
option folds upper and lower case to the same character for sort
comparisons. The -u
option leaves only unique elements in the
listing by eliminating any duplicate entries.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The following hook variables are provided so that one may customize what happens each time the OO-Browser is invoked. Set them as you would any other Emacs Lisp hook variables in a personal OO-Browser initialization file, ‘~/.br-init.el’. They all default to null operations.
If you want a set of actions to occur each time after the OO-Browser is invoked, attach them to br-mode-hook. For language-specific actions, a language-specific hook such as br-eif-mode-hook, or br-c++-mode-hook is run after br-mode-hook.
If you want a set of actions to occur after each time that a new browser listing buffer is created, set br-class-list-hook.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
A number of browser features may be used independently of the browser user interface, assuming that a site-wide or personal OO-Browser initialization file has been loaded into your current Emacs session.
First, an Environment must be selected and loaded into the OO-Browser via {C-c C-o}. When the browser user interface is displayed, use {q} to quit.
Alternatively, you can load an Environment without invoking the browser user interface by using {M-x br-env-load <RET>}. The standalone browser features will use the newly loaded Environment.
The commands that are available for standalone use include:
br-add-class-file
Add a file of classes to the current Environment. See section Adding and Deleting Classes.
br-find
Interactively complete class or ELEMENT name and jump to its definition.
br-find-class
Display file of class text matching CLASS-NAME in VIEW-ONLY mode if non-nil.
br-complete-type
Perform in-buffer completion of a type or element identifier before point.
br-class-path
Return full path, if any, to CLASS-NAME. With optional prefix argument INSERT non-nil, insert path at point.
All of these commands provide full completion. See section Completing Names, based upon the current OO-Browser Environment.
When editing and debugging code, one often wants to look at a class or
element definition without having to invoke the browser to locate it.
The (br-find)
command does exactly that by prompting for a name
and then displaying for editing the class or element definition given by
that name.
The (br-find-class)
command is similar. It prompts for a class name
and then displays its source file in a viewable, read-only mode. To
display a class file in an editable mode, send a prefix argument to this
command.
When writing code and entering class attribute definitions (variable
definitions), one often has to repetitively enter class names as the
static types for the attributes. The (br-complete-type)
command
completes and inserts a class name at point in the current buffer.
The traditional key to bind such a command to is {M-<TAB>}.
The following example illustrates its usage.
my_list: LIN<– (point is here) {M-<TAB>} is hit: my_list: LINKED_LIST
The (br-class-path)
command prompts for a class name and
displays the full path of the associated class source file in the
minibuffer. With a prefix argument, it inserts the path name at point
in the current buffer.
The following key bindings are recommended when using these standalone features:
(define-key eiffel-mode-map "\C-c\C-f" 'br-find)
(define-key c++-mode-map "\C-c\C-f" 'br-find)
(define-key lisp-mode-map "\C-c\C-f" 'br-find)
(define-key objc-mode-map "\C-c\C-f" 'br-find)
(define-key smalltalk-mode-map "\C-c\C-f" 'br-find)
;; {C-M-i} means {M-<TAB>}.(define-key eiffel-mode-map "\C-\M-i" 'br-complete-type)
(define-key c++-mode-map "\C-\M-i" 'br-complete-type)
(define-key lisp-mode-map "\C-\M-i" 'br-complete-type)
(define-key objc-mode-map "\C-\M-i" 'br-complete-type)
(define-key smalltalk-mode-map "\C-\M-i" 'br-complete-type)
(define-key eiffel-mode-map "\C-c\C-w" 'br-class-path)
(define-key c++-mode-map "\C-c\C-w" 'br-class-path)
(define-key lisp-mode-map "\C-c\C-w" 'br-class-path)
(define-key objc-mode-map "\C-c\C-w" 'br-class-path)
(define-key smalltalk-mode-map "\C-c\C-w" 'br-class-path)
.
See section Eiffel Specifics, for an Eiffel-specific standalone browser feature.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
6.1 C Specifics | ||
6.2 C++ Specifics | ||
6.3 CLOS Specifics | ||
6.4 Eiffel Specifics | ||
6.5 Java Specifics | ||
6.6 Objective-C Specifics |
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The br-c-tags-flag variable controls whether or not C constructs
are included within C and C-based language Environments. By default,
this flag is true. Use M-x br-toggle-c-tags RET
to toggle its
value. If you set it false before building an Environment, then C
constructs will not be included in the Environment. (Note that C
functions are always included in C++ Environments, regardless of this
flag value.)
If you wish to build an Environment whose source code is entirely C, ensure that the br-c-tags-flag is enabled and then select C++ when asked for the language to browse. In the future, a language setting for C will probably be added.
C constructs are grouped into default classes for browsing. The elements of each default class are the instances of the associated construct within the Environment. Use normal element/feature commands to browse each instance.
DEFAULT CLASS C CONSTRUCT -------------------------------------- [constant] #define constant [enumeration] enum {} [function] non-member function() [macro] #define macro() [structure] struct {} [type] typedef {} [union] union {}
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
See section C Specifics, for details on C-specific support within C++ Environments.
6.2.1 Source Code Element Selection | ||
6.2.2 C++ Settings |
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
C++ pure virtual function declarations, which specify method interfaces
but no implementation, appear in class feature listings. The function
name is preceded by the "> "
string to identify the function as a
pure virtual (deferred) function. Pure virtuals may be treated like any
other member functions within the browser. Since there is no definition
for such a function within the class in which it is listed, its
declaration will be shown instead, when requested.
Friend functions and friend classes give members of another class
access to the private parts of the current class. They appear
in class feature listings preceded by the "% "
string.
The keys, {v} or {e}, display the friend declaration
within the current class. Use {V}, (br-view-friend)
to
view the definition of the friend class or function.
Methods and operators associated with creating and destroying objects
are preceded by the "+ "
string in listing buffers. All other
method listing entries are preceded by the "- "
string.
One can jump from a C++ declaration to its definition by clicking the Action Key when within the declaration. Most importantly, once a class header file is displayed, simply click on a method declaration to see its corresponding definition. Each feature declaration should be terminated with a semicolon to ensure accurate scanning. If the method is inherited from another class, a message at the bottom of the frame will describe which class the method is defined in once the browser displays the method definition.
Parent classes may be browsed in a similar manner by clicking on their names in an inheritance or declaration clause. It is therefore important to click on the method name part of a declaration when that is the element desired.
Include files may be browsed by selecting their inclusion declarations (#include ...) within a source file. Include files delimited by double quotes are searched for in the following places: first, the directory of the current source file, then the directories listed in the variable c++-include-dirs, and then in any directories included in the current environment.
Include files delimited by angle brackets are searched for in the following places: first, the directories listed in the variable c++-include-dirs, then the directories listed in the variable c++-cpp-include-dirs, and then in any directories included in the current environment. The variable c++-cpp-include-dirs should hold a list of the standard directories searched by your C++ pre-processor. Each directory entry must end with a directory separator. On UNIX systems, this is the ’/’ character.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
By default, class
, struct
and union
definitions all
constitute class definitions to the C++ OO-Browser. If you prefer some
other criteria, you will need to modify the definition of
c++-class-keyword in ‘br-c++.el’.
If you find that the browser is not scanning some of your C++ source files, you may be using file suffixes which it does not recognize. Examine the value of c++-src-file-regexp and add any special file suffixes you use to it.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
6.3.1 Method Handling | ||
6.3.2 CLOS Settings |
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
In CLOS, methods may have typed parameters of the form,
(<parameter-name> <class>)
; these are called specialized
parameters. Each such parameter defines the method within
<class>
. Thus, a single method definition can generate methods
associated with many classes. The OO-Browser lets you navigate to a
method definition from any of the classes for which it is defined, since
a method is included as an element of each of its constituent classes.
CLOS permits compile-time computation of the <class>
of a
specialized parameter, through use of the expression, (eql
<form>)
. Since the OO-Browser cannot perform this computation, it
treats such a parameter as non-specialized.
Methods may also contain non-specialized parameters of the form,
<parameter-name>
. The type of each such parameter defaults to
the default root class t
in CLOS. But a method is only included
in the class t
by the OO-Browser if none of its parameters are
specialized. Otherwise, methods with more specific types which happened
to include one or more non-specialized parameters would appear to not
have a more specific type than t
.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The OO-Browser automatically works with CLOS class and method definitions. But Lisp contains many other standard object types such as functions, macros and variables which you may wish to browse. These are handled through a configuration variable as explained below.
The clos-element-type-alist variable determines the Lisp definition
constructs that the browser looks for and the associated default class
under which instances of each construct type are grouped. Each element
in the association list is a cons cell whose first part is the function
name string that defines an instance of a particular type,
e.g. "defun"
.
The second part is a default class name, a string, under which to assign
each instance of the type, e.g. "function"
. The OO-Browser
always displays default class names with square brackets around them,
e.g. [function]
, to distinguish them from classes defined within
the Environment.
Here is the default clos-element-type-alist setting:
'(("defconstant" . "constant") ("defconst" . "constant") ("defun" . "function") ("defgeneric" . "generic") ("defmacro" . "macro") ("defpackage" . "package") ("defparameter" . "parameter") ("defsetf" . "setfunction") ("defstruct" . "structure") ("deftype" . "type") ("defvar" . "variable") ("fset" . "function"))
The clos-def-form-with-args-regexp is a regular expression which includes a subset of the definition symbol names from clos-element-type-alist, namely those which require an argument list to uniquely distinguish them from other elements, e.g. functions.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Eiffel support has now been updated to Eiffel version 3, to the best of our knowledge. If you find any problems, please report them to <oo-browser@hub.ucsb.edu> (this is a public mailing list).
6.4.1 Eiffel Listings | ||
6.4.2 Source Code Element Selection | ||
6.4.3 Eiffel Settings |
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Eiffel entities are categorized when shown within OO-Browser listing buffers. Classes are shown by name, without any prefix. Features are shown by name but are preceded by a special character that indicates the kind of feature. The following table describes each prefix.
-
precedes regular routines;
=
precedes attributes;
1
precedes once routines, which create shared objects;
>
precedes deferred features, which are specified but not defined within this class;
/
precedes external features, which are defined in a non-Eiffel language.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
One can jump from an Eiffel element reference to its definition by clicking the Action Key when within the reference. Selection of a feature name in an export clause displays the feature definition, even if it is renamed several times within ancestors. Parent classes may be browsed in a similar manner by clicking on their names in an inheritance or declaration clause.
The following example of locating a renamed feature is taken from an actual set of Eiffel library classes:
User selects featuresubwindow
ofPOPUP_MENU
inherited fromWINDOW
which renameschild
assubwindow
inherited fromTWO_WAY_TREE
which renamesactive
aschild
inherited fromTWO_WAY_LIST
inherited fromLINKED_LIST
which definesactive
.
The browser would display the feature active
and explain to the
user that feature subwindow
of class POPUP_MENU
is
inherited from feature active
of class LINKED_LIST
.
Location of this sort of feature definition would be incredibly tedious
without programmatic support.
The algorithm used to locate features is dynamic, so if another class were inserted into the inheritance structure given above, the feature definition would still be located properly.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Be sure that the ’inherit’ and ’feature’ clauses in your classes begin in
column 0; otherwise the browser parser will not work properly. If you prefer
some other indentation style, you will need to slightly alter
(eif-get-parents-from-source)
in ‘br-eif.el’; specifically,
the lines that contain ’^inherit’ and ’^feature’.
Emacs has a feature called error parsing which lets one quickly jump to the line of code that supposedly triggered an error. (See Compilation Errors in The Gnu Emacs Manual, for information on error parsing.) Some object-oriented language compilers display the name of the class and line number with each error message but do not include the filename containing the class source code. Emacs then has no way of parsing the error message. The browser class location facilities enable one to perform error parsing across any set of classes in a single Environment, given only this type of message. Interactive Software Engineering’s Eiffel compiler is an example of a compiler that produces this type of error. The code for parsing these Eiffel error messages is included in ‘eif-ise-err.el’.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Java abstract method declarations, which specify method interfaces
but no implementation, appear in class feature listings. The method
name is preceded by the "> "
string to identify the method as an
abstract (deferred) method. Abstract methods may be treated like any
other methods within the browser. Since there is no definition
for such a method within the class in which it is listed, its
declaration will be shown instead, when requested.
Native methods are like abstract methods in that only their interfaces
are specified in Java. Unlike abstract methods, their method bodies are
defined in external languages such as C to allow for machine-specific
dependencies. Native methods are listed in the browser prefixed by the
"/ "
string, indicating that they are divided between Java and
another language.
Methods associated with creating and destroying objects
are preceded by the "+ "
string in listing buffers. All other
method listing entries are preceded by the "- "
string.
Java interface specifications, which specify protocols to which classes must conform, are treated just like class definitions in browser listings. All the methods of such interfaces are abstract, however.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
See section C Specifics, for details on C-specific support within Objective-C Environments.
The OO-Browser supports browsing Objective-C classes, methods, categories and formal protocols. Earlier sections of this manual explain how to browse these entities. This section documents Objective-C language specifics, including variable settings.
Objective-C entities are categorized when shown within OO-Browser listing buffers. Classes are shown by name, without any prefix. Methods are shown by name but are preceded by a special character that indicates the kind of method. The following table describes each prefix.
-
precedes instance methods;
+
precedes class (factory) methods that affect the factory object for the class.
6.6.1 Objective-C Categories | ||
6.6.2 Objective-C Protocols | ||
6.6.3 Source Code Element Selection | ||
6.6.4 Objective-C Settings |
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
An Objective-C category is an internal class grouping that specifies and implements a set of related class features. The aggregation of all of the categories defined by a class and its ancestors represents the complete class definition.
The OO-Browser can list and browse the source for: the categories of a class, all class categories in an Environment, and the classes which implement a category. See section Browsing Categories, for details.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
An Objective-C protocol is an interface specification to which a class may conform. The protocol includes a set of method signatures which any conforming class must implement. One protocol may inherit from a list of other protocols, and thus expand the set of methods which a conforming class must implement. The OO-Browser can list and browse the source for: the protocols to which a class conforms, all protocols in an Environment, and the implementors of a protocol. See section Browsing Protocols, for details.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
One can jump from an Objective-C declaration to its definition by clicking the Action Key when within the declaration. Most importantly, once a class header file is displayed, simply click on a method declaration to see its corresponding definition. If the method is inherited from another class, a message at the bottom of the frame will describe which class the method is defined in once the browser displays the method definition.
Parent classes may be browsed in a similar manner by clicking on their names in an inheritance or declaration clause. It is therefore important to click on the method name part of a declaration when that is the element desired.
Include files may be browsed by selecting their inclusion declarations (#import ...) within a source file. Include files delimited by double quotes are searched for in the following places: first, the directory of the current source file, then the directories listed in the variable objc-include-dirs, and then in any directories included in the current environment.
Include files delimited by angle brackets are searched for in the following places: first, the directories listed in the variable objc-include-dirs, then the directories listed in the variable objc-cpp-include-dirs, and then in any directories included in the current environment. The variable objc-cpp-include-dirs should hold a list of the standard directories searched by your Objective-C pre-processor. Each directory entry must end with a directory separator. On UNIX systems, this is the ’/’ character.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
By default, the @interface
keyword indicates a class definition to the
Objective-C OO-Browser. If you prefer some other criteria, you will need to
modify the definition of objc-class-keyword in ‘br-objc.el’.
If you find that the browser is not scanning some of your Objective-C source files, you may be using file suffixes which it does not recognize. Examine the value of objc-src-file-regexp and add any special file suffixes you use to it.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The following documentation is meant for programmers who want to modify the OO-Browser but is included here since some users of the OO-Browser may find it useful. All commands that are bound to keys and that are specific to the OO-Browser are listed here. Within each command description, identifiers shown in all capitals are the names of the command’s formal arguments; all formal arguments are presented in the order in which they are required by the command. If a command takes optional arguments, the first optional argument is labeled optional; all following arguments are assumed to be optional.
br-add-class-file {C-c ^}
Adds a file of classes to the current Environment. Interactively or when optional CLASS-PATH is nil, defaults to current buffer file as CLASS-PATH. If optional LIB-TABLE-P is non-nil, add to Library Environment, otherwise add to System Environment. If optional SAVE-FILE is t, the Environment is then stored to the filename given by br-env-file. If SAVE-FILE is non-nil and not t, its string value is used as the file to which to save the Environment.
br-ancestors {a}
Display ancestor tree whose root is the current class. With optional prefix ARG, display all ancestor trees whose roots are visible classes at the current level. ARG = -1 inverts current class ancestry tree. That is, it shows branches going down towards the root class, so that parents appear above children. ARG < -1 inverts all ancestry trees.
br-at {@}
Display current class location in the inheritance graph. The class is displayed among both its ancestors and descendants. With optional prefix ARG, display location for all visible classes at the current level.
br-buffer-menu {b}
Display selection list of buffers with attached files in viewer window.
br-children {c}
Display children of current class. With optional prefix ARG, display children of all visible classes at the current level.
br-class-stats {M-c}
Display statistics summary for current class. Optional prefix arg PROMPT means prompt for class name.
br-copyright
Display browser copyright information in viewer window.
br-count {#}
Count number of classes visible in current listing buffer. Print text result in minibuffer when called interactively.
br-delete {C-c C-d}
Delete class from current Environment. Optional prefix arg PROMPT means prompt for class name.
br-descendants {d}
Display descendant tree whose root is the current class. With optional prefix ARG, display all descendant trees whose roots are visible classes at the current level.
br-edit-entry {e}
Edits source for any browser listing entry, such as a class or a feature. Optional prefix arg PROMPT means prompt for entry name.
br-env-create {C-c C-c}
Create and save the specification of a new OO-Browser Environment. Interactively prompt for the Environment file name or use optional ENV-FILE. Interactively prompt for the Environment language to use or use optional LANG-PREFIX as language indicator. Return the name of the Envir spec file created. Do not build the Environment. Use ’br-env-build’ to construct an Environment from its specification.
br-env-load {C-c C-l}
Load browser Environment or spec from optional ENV-FILE or ’br-env-file’. Non-nil PROMPT means prompt user before building tables. Non-nil NO-BUILD means skip build of Environment entirely. Return t if load is successful, else nil.
br-env-rebuild {C-c C-e}
Rescan System and Library sources associated with the current Environment.
br-env-save {C-c C-s}
Save changed Environment to file given by optional SAVE-FILE or ’br-env-file’.
br-env-stats {M-e}
Display summary for current Environment in viewer window. With optional prefix ARG, display class totals in minibuffer.
br-exit-level {x}
Return to prefix ARGth previous inheritance level listing. The command is ignored with ARG < 1.
br-find
Interactively completes class or feature ELEMENT-NAME and jumps to its definition. Returns ELEMENT-NAME or signals an error.
br-feature-signature {F}
Show full feature signature in the view window. With optional prefix ARG, display signatures of all features from the current buffer.
br-help {h}
Display browser operation help information in viewer window.
br-help-ms {H}
Display browser mouse usage help information in viewer window.
br-entry-info {i}
Display attributes of the current entry in the viewer window.
br-implementors {I}
Display hierarchy of classes that define current feature. Ignore inherited features. With optional prefix ARG, display implementors of all features at the current level.
br-kill {C-c C-k}
Kill buffer in viewer window and redisplay help text.
br-lib-top-classes {l}
Display list of top level Library classes. With prefix ARG, display all Library classes.
br-lib-rebuild {L}
Rescan Library components of the current Environment.
br-match {m}
Show all class names in current Environment that contain optional EXPR. Nil value of EXPR means prompt for a value. With optional prefix ARG, EXPR is treated as a string. By default, it is treated as a regular expresion. AGAIN non-nil shows the number of classes MATCHED from the last search, allowing repeated narrowing of the search set. Empty EXPR when AGAIN is nil matches to all classes in the Environment.
br-match-entries {M}
Show all entries in current listing that contain optional EXPR. Nil value of EXPR means prompt for a value. With optional prefix ARG, EXPR is treated as a string. By default, it is treated as a regular expresion. AGAIN non-nil means show the number of entries MATCHED from last search, allowing repeated narrowing of the search set. Empty EXPR when AGAIN is nil matches to all entries in the listing.
br-next-entry {C-n}
Move point vertically down prefix ARG number of lines in listing buffer.
br-order {o}
Order current browser listing window entries. With prefix ARG other than 1 (the default), don’t remove leading space from entry lines before ordering. Negative ARG means order in descending Ascii sequence, otherwise order in ascending sequence.
br-parents {p}
Display parents of current class. With optional prefix ARG, display parents of all visible classes at the current level.
br-prev-entry {C-p}
Move point vertically up prefix ARG number of lines in listing buffer.
br-quit {q}
Quit browser. With optional prefix ARG, delete window configurations and listing buffers associated with the browser.
br-refresh {C-c C-r}
Restore OO-Browser to its state upon startup.
br-resize-narrow {C-x -}
Resize listing windows so are narrower by 10 characters.
br-resize-widen {C-x +}
Resize listing windows so are wider by 10 characters.
br-features {f}
Display features/elements of the current class (prefix ARG = 1) or of the current listing if ARG is other than 0 or 1.
With ARG = 0, the value of the variable, br-inherited-features-flag, is toggled and no other action is taken.
If br-inherited-features-flag is t
, all features of each
class are shown. If nil
, only lexically included features are
shown and if the features of a single class are requested and none are
defined, the class definition is displayed so that its feature
declarations may be browsed.
br-sys-rebuild {S}
Rescan System components of the current Environment.
br-sys-top-classes {s}
Display list of top level System classes. With prefix ARG, display all System classes.
br-to-from-viewer {C-c C-v}
Move point to viewer window or back to last recorded listing window.
br-toggle-keep-viewed
Toggle the value of the br-keep-viewed-classes flag.
br-top-classes {t}
Display list of top level classes. With prefix ARG, display all Environment classes.
br-unique {u}
Eliminate adjacent duplicate entry names from the current listing window. If two adjacent entries look the same one is eliminated, even if they refer to different class elements.
br-version {C-c #}
Display browser version number.
br-view-entry {v}
Displays source for any browser listing entry. Optional prefix arg PROMPT means prompt for entry name.
br-view-friend {V}
With point on a friend listing entry, view its source code definition. With optional OTHER-WIN non-nil, display in another window. With optional SIG-AT-POINT-FLAG non-nil, assume point is within a friend signature in a source buffer.
br-view-full-frame {1}
Use full frame to display contents of viewer window.
br-viewer-scroll-down {DEL}
Scroll viewer window downward ARG lines or a windowful if no ARG.
br-viewer-scroll-up {SPC}
Scroll viewer window upward ARG lines or a windowful if no ARG.
br-where {w}
Display in minibuffer and return full path of a browser listing entry. Optional prefix arg PROMPT means prompt for entry name."
br-write-buffer {C-c C-w}
Write narrowed portion of current browser buffer to a file.
br-tree {M-d}
Start the ‘xbr’ application with descendency tree of current class. With optional prefix ARG, a descendency tree for each class in current buffer.
br-tree-graph {M-g}
Start the appropriate tree application with the tree from current listing buffer.
br-tree-kill {M-k}
Prompt user whether to kill all ‘xbr’ sub-processes.
br-tree-features-toggle {M-f}
Toggle between showing features and hiding them when br-tree
is
invoked to display descendants graphically.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Concepts pertinent to operational usage of the OO-Browser are defined here.
If some GNU Emacs terms are unfamiliar to you, see [Stallman 87].
Ancestors
All classes above a class in the inheritance hierarchy.
Category
Under most languages, a logical grouping of related classes. The OO-Browser does not yet have any support for this kind of category.
Under Objective-C, a partial class definition that implements a related set of methods. The full class definitions is formed from the conjunction of all of the class’ categories. The OO-Browser supports Objective-C category browsing.
Children
First level of classes below a class in the inheritance hierarchy. Those that directly inherit from a class.
Class
A category from which object instances are created. The OO-Browser can display classes along with their elements, categories and formal protocols.
Class at Point
Class name in a listing buffer whose name appears on the same line as point.
Declaration
A specification of a programatic entity, for reference by other parts of
a program. See also Definition
. The declaration of a method
specifies its signature but not its body.
Default Class
A class that the OO-Browser creates to simplify browsing a particular
category of objects such as class protocols or global functions.
Default class names begin and end with square bracket delimiters, as in
[protocol]
.
Definition
Programmatic definition of an entity, e.g. defining the body of a method.
Completion
The act of filling in the non-ambiguous part of a requested item, such as a class name or a file name.
Decendants
All classes below a class in the inheritance hierarchy.
Element
A feature or an instance of a class.
Environment
A series of browser lookup tables and control variables that specify the set of classes and inter-class relationships with which the browser works.
Environment File
A file used to store browser Environments.
Environment Specification
Unambiguously tells the browser what to include in the construction of an Environment.
Feature
An element (method/attribute/component) of a class.
Formal Protocol
See Protocol
.
Implementor
A class in which a particular element is defined. This does not include classes which inherit an element.
Initialization File
See Personal Initialization File
.
Instance
An object which has a particular class as its type. The class serves as a template for instance creation.
Library Classes
Stable, seldomly changed classes that have been released for general usage.
Listing Window
One of a number of browser windows used to display lists of classes. Inheritance relations are shown by class name indentation and by the class level numbers in the listing buffer mode lines.
Lookup Table
A store used to help the browser quickly determine inter-class relationships.
Member
See Feature
.
Method
A callable function defined within one or more classes.
Minibuffer Window
The single line window at the bottom of an Emacs frame. It is used to interact with the user by displaying messages and prompting for input.
Parents
First level of classes above a class in the inheritance hierarchy. Those from which a class directly inherits.
Personal Initialization File
The optional file, ‘~/.br-init.el’, which sets user-specific options affecting operation of the OO-Browser, thereby configuring the browser for personal use.
Point
The point in the current buffer in front of the character which the Emacs cursor is over but after any prior character.
Protocol
An interface specification to which a class conforms. Some languages use abstract classes for this purpose. Under Objective-C, one may also define formal protocols which include a set of method signatures which a class must implement if it conforms to the protocol. Also under Objective-C, one protocol may inherit from a list of other protocols, and thus expand the set of methods which a conforming class must implement.
Routine
See Method
.
Signature
An interface specification for a method. It includes the method’s class, type of return value and the types of its formal parameters.
Smart System
The Smart System is another handy program that helps you to work smarter and faster. It consists of two parts, the Smart Key System, a direct manipulation keyboard interface that gives you control of most GNU Emacs subsystems by using only two keys, and the Smart Menu System. This provides a hierarchy of menus within Emacs that you use instead of keyboard commands. Just point and click on a menu entry. One of its uses is to invoke the OO-Browser on any desired language Environment. (The Smart Key System is included with the Smart Menu System.)
Smart Menu System
See Smart System
.
System Classes
Classes still in development whose interfaces are likely to change. They are typically part of a specific project and are often not meant to be reused elsewhere.
Top-Level Classes
Classes without parents. Those at the top of the inheritance tree for a given Environment.
Viewer Window
The largest, bottom-most window in the browser used for displaying class source and help information.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Meyer, Bertrand. Object-oriented Software Construction. Prentice Hall International: UK, 1988.
Meyer, Bertrand. Eiffel: The Language. Interactive Software Engineering: Santa Barbara, CA, 1989. (Also being republished by Prentice Hall.)
Goldberg, Adele and David Robson. Smalltalk-80: The Language and its Implementation. Addison-Wesley, 1983.
Stallman, Richard. GNU Emacs Manual. Free Software Foundation, Cambridge: MA, March 1987.
The Java Language Specification. Sun Microsystems Computer Corporation, Mountain View, CA, February 1, 1995.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Jump to: | #
1
A C D E F H I L M O P Q R S T V W X |
---|
Jump to: | #
1
A C D E F H I L M O P Q R S T V W X |
---|
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Jump to: | B C D E F I J K O S W |
---|
Jump to: | B C D E F I J K O S W |
---|
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Jump to: | #
A B C D E F G I J L M N O P Q R S T U V X |
---|
Jump to: | #
A B C D E F G I J L M N O P Q R S T U V X |
---|
[Top] | [Contents] | [Index] | [ ? ] |
[Top] | [Contents] | [Index] | [ ? ] |
[Top] | [Contents] | [Index] | [ ? ] |
This document was generated on December 6, 2024 using texi2html 5.0.
The buttons in the navigation panels have the following meaning:
Button | Name | Go to | From 1.2.3 go to |
---|---|---|---|
[ << ] | FastBack | Beginning of this chapter or previous chapter | 1 |
[ < ] | Back | Previous section in reading order | 1.2.2 |
[ Up ] | Up | Up section | 1.2 |
[ > ] | Forward | Next section in reading order | 1.2.4 |
[ >> ] | FastForward | Next chapter | 2 |
[Top] | Top | Cover (top) of document | |
[Contents] | Contents | Table of contents | |
[Index] | Index | Index | |
[ ? ] | About | About (help) |
where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:
This document was generated on December 6, 2024 using texi2html 5.0.