- 17.05 (released) ...
Making some room
We'll need just one development window for the moment, the one that was targeted to
LIST. You should still have that window available from the previous Tour topic, and it should look about like this:
First let's give ourselves more space. Right now we don't need the Groups tool or any of the other tools sharing that pane. We could get rid of them by clicking the close buttons on the top right corner of the panes. Then we could get them back later by following the menu path:
View --> Tools --> x
where "x" is the name of a tool we want restored. But there is an easier way. Let's just hide them away until later.
Click the icon and you'll see the pane shrink into a set of tabs on the right window margin and the remaining panes will expand to fill the abandoned space. The tools in the pane will temporarily expand back out if you move your mouse cursor over their tabs. Try it with one. When you want the pane back in its original place permanently, you just expand one of the tabs by mousing over it, then click the Disable Auto Hide icon, which is the pushpin again, just horizontal this time.
Two panes remain, showing the Editor tool and the lower pane containing the Outputs tool and others. You can resize the panes by dragging the border between them. Make sure there's plenty of room in the lower pane.
The Class tool
Before we look at the Class tool, let's make sure that we set linked data share mode which will always display information about the current target. Go to the main menu bar and expand the menu item
View. If you see a choice marked with the link context icon () and labeled
Link Context Tool, then select it. After it has been selected, or if it has already been selected, then the label will read:
Unlink Context Tool.
At the bottom of the lower pane you'll find a tab labeled Class. This gives you access to many forms of information about the current class -- the target of the development window. Click on the Class tab to bring up the Class tool. A set of buttons at the top enables you to display a number of views of the class. The currently highlighted button indicates the default view:
Ancestors. You can see the others' names by moving your cursor over the various view icons, and reading the tooltips.
The view currently displayed,
Ancestors, shows the inheritance structure that leads to the current target,
This shows that
LIST is an heir of
CHAIN which itself, as an example of multiple inheritance, is an heir of
INDEXABLE, and -- twice, as an example of repeated inheritance --
SEQUENCE. If, because of direct or indirect repeated inheritance, a class appears more than once, the display doesn't repeat its ancestry the second and subsequent times; the omitted repetition appears as just three dots, ..., as illustrated here for the second occurrences of
ACTIVE and others.
As you may have guessed, all the class names that appear on this display, by default in blue, can function as hyperlinks: you can use any one of them to retarget the Development Window to the corresponding class. This will be another major retargeting mechanism. But let's not pursue it for the moment and instead continue looking at the documentation views.
Ancestors button is
Descendants, which will give you the descendants of a class in a similar format:
The progeny of
LIST, as you can see, is just as impressive as its ancestry.
Let's now look at the other formats, starting from the left. The first button,
Clickable, gives the class text. It's essentially the same information as appears in the top Editing Tool (whose pane was reduced to its bare minimum in the last few pictures, showing only the first three lines or so), but with some differences:
- The Text view in the Editor is editable. In fact it's EiffelStudio's primary tool for entering software texts. The Class tool's
Clickableview is just a view; you can't change it.
- The Text view retains the formatting of the class text the way it was typed in; the
Clickableview is automatically formatted -- "pretty-printed" -- according to the standard Eiffel layout rules.
Clickableview does not include comments inside routine implementations (
onceclauses), although it does retain features' header comments.
- As part of the pretty-printing, the
Clickableview uses colors and fonts to distinguish keywords, identifiers, comments and other syntactical elements. You can change the fonts and colors, like many other elements of the interface, through
Tools --> Preferences. (Now is not the time.)
This view is called "Clickable" because, as we'll see later, every syntactical element on it is a hyperlink, which you can use for browsing.
Clickable comes the
Flat view button. The layout of the result is similar. The flat form of a class is the reconstructed class text including not only what's declared in the class itself but also everything that it inherits from its ancestors, direct or indirect. This applies to the flat form's features, which include ancestor features, but also to contracts: the flat form's invariant includes all clauses from ancestors' invariants, and the preconditions are expanded to take
require else and
ensure then clauses into consideration. (The Eiffel Tutorial explains these notions in detail.)
As a result, the
Flat view shows the class text as it might have come out had inheritance (what a horrible thought even to contemplate!) not been available to write it.
The first two features appearing in the above display,
first, are indeed inherited from ancestors, rather than declared in
LIST itself. Note how EiffelStudio, when producing the flat form, adds a line of the form
-- (from CLASS_OF_ORIGIN)
to the header comments of inherited routines, to document where they come from.
The flat form is an important notion of object technology, making it possible to understand a class by itself, regardless of the possibly rich inheritance structure that led to it. Looking at the Flat view of
LIST, you may note how few of its properties come from the class itself; most of the interesting work has been done in ancestors, and
LIST just adds a few details.
Next come two essential documentation views:
Interface. Based on Eiffel's principles of Design by Contract, they document the interface properties of a class. Unlike the previous two, they do not show actual Eiffel texts, but information useful for client classes.
The contract form (also known as the short form of a class) is the class text deprived of any internal detail to retain interface information only. It discards any feature that's not exported (available to all clients); for the retained features, it discards the implementation --
once clause -- but retains the header (feature name, arguments, results), the header comment, and the contracts (precondition, postcondition, invariant) minus any contract clause that refers to a non-exported feature and hence would be useless to clients.
As you will know, particularly if you have read the book Object-Oriented Software Construction, 2nd Edition, the contract form is the preferred way of documenting software elements, especially reusable components, as it provides clients with just the right level of abstraction: precise enough thanks to the type signature and the contracts; clear enough thanks to the header comments; and general enough since it omits implementation details that are irrelevant to client programmers (and might lead them to write client code that won't work any more if the implementation changes).
In practice you will often want to use, instead of the
Contract view, the next one,
Interface, also known as "flat-short form" and "flat contract form", which applies the same rules to the flat form rather than to the original class. This means it shows information on all the features of the class, immediate (defined in the class itself) as well as inherited, whereas the short form, non-flat, only considers immediate features. The
Interface view provides the complete interface information for the class. Try it now on class
The next two buttons are for the
Descendants views, which we have already seen, showing classes connected with the target through one of the two inter-class relations, inheritance. After them come
Suppliers, to list the classes connected through the other relation, client. Clicking the
Clients button shows the list of clients of
Now click the next button to see the
The only two classes that
LIST needs for its own algorithms are basic types from the Kernel Library,
INTEGER_32. In Eiffel, as you may remember, all types are defined by classes, even those describing such elementary values as integers and booleans.
Feature information in the Class View
Let's resist the natural urge to go see now what the classes
BOOLEAN look like, and instead continue our survey of views. The remaining views will all display information about the features of the class. The first of them,
Attributes, lists the attributes. It's not very interesting for
LIST, a deferred class with only one attribute -- you can check this for yourself by clicking the
Attributes button -- so let's look at the next one. Click the
Routines button now to display information about the routines of class
The sections of this display group routines according to the ancestors of
LIST -- including
LIST itself -- that first introduced them; for example
append originally comes from
BILINEAR. Much of the benefit of this display comes from its support for browsing: all the colored elements, representing classes and features, will be "clickable" hyperlinks.
Invariants button shows the complete class invariant for
LIST. This includes all invariant clauses that have been inherited from all ancestors.
Other Class tool buttons display information in the same format as
Routines. Each selects a specific subset of the target class's features. You can now try any of the others by clicking the corresponding button:
Deferredfeatures: abstract features which don't have an implementation in the current class, only in eventual descendants. Try this for
LIST; you'll see that this deferred class indeed has a number of deferred features.
Onceand constants: constant attributes, "once functions" which provide shared objects (close to the "singleton" pattern), and once procedures which provide a convenient initialization mechanism.
LISThas 'Operating_environment' and 'Io' inherited from the parent class ANY.
Externalfeatures, implemented as calls to routines, macros or other elements implemented in other languages.
Exportedfeatures: those available to all clients.
LISThas quite a few.
Restoring the look of the development window
Once you're done looking at the different views, let's undo the changes that we made to the configuration of the development window at the beginning of this section in Making some room.
Reduce the relative size of the lower pane.
Then go to one of the tabs on the right margin of the development window, Groups, will work. Hold your cursor over it for a moment and it should expand. Then click the Disable Auto Hide icon, the horizontal pushpin, to restore the rightmost pane.
- Parent <Using AutoTest>