6. Language-Specific Notes

This chapter summarizes OO-Browser details that are specific to each language. There are no Smalltalk specifics.

6.1 C Specifics

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 except on operating systems where the OO-Browser cannot find a UNIX-type shell such as `sh' or `csh'. In those cases, C constructs cannot be categorized by the OO-Browser. Use `M-x br-toggle-c-tags RET' to toggle the value of this variable. If you set it false before building an Environment, then C constructs will not be included in the Environment.

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.

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 {}
         [enum_label]     label_name
         [function]       non-member function()
         [macro]          #define macro()
         [structure]      struct {}
         [type]           typedef {}
         [union]          union {}
         [variable]       <type> global_variable_name;

Within C, C++, or Objective-C code, an Action Key click on a reference to a global C identifier will display the identifier's definition.

6.2 C++ Specifics

See section 6.1 C Specifics, for details on C-specific support within C++ Environments.

6.2.1 C++ Listing Entries

C++ 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 pure virtual functions, which are specified but not defined within this class;

%

precedes friend functions and classes, which have access to the class' private parts;

+

precedes constructors and destructor functions;

-

precedes any other type of member function;

&

precedes static attributes (one attribute per class);

=

precedes instance attributes (one attribute per object instance).

The following paragraphs discuss each of these types of features in more detail.

C++ pure virtual function declarations, which specify method interfaces but no implementations, appear in class feature listings. Their function names are preceded by the "> " string to identify them as pure virtual (deferred) functions. Pure virtuals may be treated like any other member functions within the browser. Since they lack definitions within their base classes, their declarations are shown when a view or edit command is given.

Friend functions and friend classes give members of another class access to the private parts of their class. Friend functions and classes 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) in a listing window to view the definition of the friend itself. If you use {e}, which leaves point on the friend declaration, a press of the Action Key will then move to the definition of the friend itself.

Methods and operators for creating and destroying objects are preceded by the "+ " string in listing buffers. All other method listing entries are preceded by the "- " string.

Static attributes (data members instantiated once per class) are shown preceded by the "& " string regardless of their types. Instance attributes (data members instantiated at each object creation) are shown preceded by the "= " string regardless of their types.

6.2.2 Source Code Element Selection

Once you have loaded an Environment, whether or not the OO-Browser user interface is on screen, you can use the Action Key to follow a variety of references within the code. Simply press the Action Key on an identifier or C++ construct and its associated definition or list of possible definitions or its declaration (if no definitions exist within the Environment) will be displayed for you to inspect or edit. More specifically:

• You can jump from a C++ class or method declaration to its definition by pressing the Action Key within the declaration signature (with point prior to its argument list). A press of the Action Key on a method definition signature (with point prior to its argument list) will also jump to the associated declaration so that you can pop back and forth between the two (assuming their signatures match up). If the method is defined within an ancestor class, a message at the bottom of the frame will announce the defining class whenever its definition is displayed. (Note that the {j} key can be used within browser listing buffers to view class and feature declarations. The {J} key works the same way but displays the entry for editing rather than viewing.)

  One stylistic tip: Each feature declaration should be terminated with a semicolon, rather than declared in a list, to ensure accurate scanning by the OO-Browser, i.e. don't use declarations like: float f1, f2, f3;.

  When in a code buffer, {C-c M-j} (br-feature-edit-declaration) will prompt for a feature name and will then display its declaration for editing. The key, {C-c M-f} (br-find) displays works similarly but displays definitions instead. See section Using Standalone OO-Browser Features, for more complete operational descriptions of these commands.

• Classes can be browsed by pressing the Action Key on their names in inheritance clauses, feature signature argument lists or within scoped member references. It is therefore important to click on the method name part of a declaration when that is the element desired.

• C++ method, function call and single-level attribute reference browsing is now supported by pressing the Action Key on the member name of a call. The OO-Browser deals with much of the complexity of the C++ calling syntax so you need not (though it doesn't yet account for method overloading). In cases where it cannot determine a unique definition (e.g. where dynamic binding is involved), it pops up a list of possible definitions (method signatures). An Action Key click on any of these (or on the class names separating these signature lines) will display the definition within the source code. If the browser determines a unique base class of the call, it produces an ancestry tree of classes and intersperses the possible matching method signatures indicating the base class of each method in a fashion similar to how inherited features are shown in browser listing buffers.

  If no definitions are found, the browser tries to display a matching declaration. See section 2.8 Browsing Elements.

• You can browse include files 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 <angled 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 be set to 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.

6.2.3 C++ Settings

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 to it any special file suffixes that you use.

6.3 CLOS Specifics

6.3.1 Method Handling

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 built-in root class, `t'. But a method is included in the class `t' by the OO-Browser only 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'.

6.3.2 CLOS Settings

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 dotted pair 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 standard value of clos-element-type-alist.

(("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 first items from the dotted pairs of clos-element-type-alist, namely those which require an argument list to uniquely distinguish them from other elements, e.g. functions.

6.4 Eiffel Specifics

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-bugs@xemacs.org>.

6.4.1 Eiffel Listings

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.

A detailed summary of a class may be generated with point on a class entry by pressing {i} (br-entry-info). By default, this shows a summary including the parents, attributes, routines and routine call summaries of the class. The command `M-x eif-info-use-short RET' instead causes the {i} key to run the Eiffel `short' command on the class, thereby displaying its specification. The command `M-x eif-info-use-flat RET' enables use of the `flat' command to the complete feature set of a class. `M-x eif-info-use-calls RET' resets the key to generate default summaries once again.

6.4.2 Source Code Element Selection

You can jump from an Eiffel element reference to its definition by clicking the Action Key on 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:

The user selects feature `subwindow' of POPUP_MENU
   inherited from WINDOW which renames `child' to `subwindow'
      inherited from TWO_WAY_TREE which renames `active' to `child'
         inherited from TWO_WAY_LIST
            inherited from LINKED_LIST which defines `active'.

The browser displays 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 is inserted into the inheritance structure given above, the feature definition will still be found.

6.4.3 Eiffel Settings

Emacs has a feature called error parsing which lets you quickly jump to the line of code that supposedly triggered an error. See section `Compilation Errors' in the XEmacs 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 you 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 (at least at one time) produced this type of error. The code for parsing ISE Eiffel error messages is included in `eif-ise-err.el'.

6.5 Java Specifics

The OO-Browser browses Java classes, interfaces, methods, and attributes. Earlier sections of this manual explain how to browse these entities. This section documents Java language specifics, including variable settings.

By default, Java Environments also include C constructs encountered when building each Environment. See section 6.1 C Specifics, for details on C-specific support within Java Environments.

Java entities are categorized when shown within OO-Browser listing buffers. Classes are shown by name, without any prefix. Interfaces are delimited by <angled brackets>. The following table describes the prefixes that preced each feature listing entry:

=

precedes attributes;

-

precedes regular methods;

+

precedes methods associated with creating and destroying objects;

>

precedes abstract method declarations; Abstract (deferred) methods may be treated like any other methods within the browser. Since there is no definition for such methods, their declarations are shown whenever an edit or view request is issued.

/

precedes native methods, to indicate that such methods are divided between Java and another language; 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.

Java interface specifications, which define formal protocols to which classes must conform, are treated just like class definitions in browser listings. All the methods of such interfaces are abstract, however.

6.5.1 Java Interfaces

The OO-Browser can list and browse the source for:

the interfaces to which a class or an interface conforms

(press {P} on a class or interface listing entry);

all interfaces in an Environment

(press {f} on the [interface] default class entry);

the implementors of a interface

(press {I} on a interface listing entry).

See section 2.10 Browsing Protocols, for more details.

6.5.2 Source Code Element Selection

You can jump from a Java class method declaration to its definition by clicking the Action Key when within the declaration. If a method is inherited from another class, a message at the bottom of the frame will announce the defining class whenever its definition is requested.

Parent classes and interfaces 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.

6.5.3 Java Settings

If you find that the browser is not scanning some of your Java source files, you may be using file suffixes which it does not recognize. Examine the value of java-src-file-regexp and add to it any special file suffixes that you use.

6.6 Objective-C Specifics

See section 6.1 C Specifics, for details on C-specific support within Objective-C Environments.

The OO-Browser browses 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. Categories are delimited by (parentheses), while protocols are delimited by <angled brackets>. 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

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

(press {C} on a class listing entry);

all class categories in an Environment

(press {f} on the [category] default class entry);

the classes which implement a category

(press {I} on a category listing entry).

See section 2.9 Browsing Categories, for more details.

6.6.2 Objective-C Protocols

The OO-Browser can list and browse the source for:

the protocols to which a class or a protocol conforms

(press {P} on a class or protocol listing entry);

all protocols in an Environment

(press {f} on the [protocol] default class entry);

the implementors of a protocol

(press {I} on a protocol listing entry).

See section 2.10 Browsing Protocols, for more details.

6.6.3 Source Code Element Selection

You can jump from an Objective-C class method declaration to its definition by clicking the Action Key when within the declaration. If a method is inherited from another class, a message at the bottom of the frame will announce the defining class whenever its definition is requested.

Parent classes and protocols 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 ...) or (#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 objc-include-dirs, and then in any directories included in the current environment.

Include files delimited by angled 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 be set to 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.

6.6.4 Objective-C Settings

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 to it any special file suffixes that you use.

6.7 Python Specifics

See section 6.1 C Specifics, for details on C-specific support within Objective-C Environments.

The OO-Browser can list and browse the source for the following Python constructs:

packages

(press {f} on the [package] default class entry to list all of the packages in the Environment, each of which is preceded)

modules

(press {f} on the [module] default class entry to list all of the modules in the Environment)

classes

(press {f} on a class entry to see its methods; there is no support for browsing its instance variables except by viewing the class' __init__ method definition)

functions

(press {f} on the [function] default class entry to list the non-member functions defined in the Environment; this includes C functions)

globals

(press {f} on the [global] default class entry to list all of the globals defined in the Environment)

Note that nested classes are not recognized by the browser, nor are run-time modifications to classes.

Documentation for the Python listing entry on the current line may be displayed with the {i} (br-entry-info) command. This displays documentation for packages, modules, classes, functions and methods. It utilizes the `pydoc.el' interface to the Python pydoc library, when available, to provide extended documentation but it will nevertheless display basic documentation strings if this package is not installed.

An Action Key press on a Python import or from statement will display the source of the item under point, which may be a module, class, method, function or variable name, if the source is found within the current Environment. First, the module is searched for within the current Environment directories. If it is not found, it is searched for within the paths listed in the variable, python-import-dirs, which is initialized to the value of the PYTHONPATH environment variable or if that is not defined, to `/usr/local/lib/python'.

This document was generated by XEmacs shared group account on December, 19 2009 using texi2html 1.65.