mirrors/eiffel-org
1
0
Fork 0
mirror of https://github.com/EiffelSoftware/eiffel-org.git synced 2025-12-06 14:52:03 +01:00
Code Issues Packages Projects Releases Wiki Activity

Author:admin

Browse Source 
Date:2008-09-18T14:32:43.000000Z


git-svn-id: https://svn.eiffel.com/eiffel-org/trunk@13 abb3cda0-5349-4a8f-a601-0c33ac3a8c38
This commit is contained in:
jfiat
2008-09-18 14:32:43 +00:00
parent 8177357757
commit 13b85fb9c9
20 changed files with 1144 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files

126
documentation/current/eiffelstudio/eiffelstudio-guided-tour/appendix-writing-documentation-filters-eff-eiffel-filter-format.wiki Normal file
View File

@@ -0,0 +1,126 @@
[[Property:title|19 APPENDIX: WRITING DOCUMENTATION FILTERS WITH EFF, THE EIFFEL FILTER FORMAT]]
[[Property:link_title|Appendix: Writing Documentation Filters with EFF, the Eiffel Filter Format]]
[[Property:weight|6]]
[[Property:uuid|0d17d433-3d4f-9575-49f7-d97eccb1a5b1]]
[[Help reading the EiffelStudio Guided Tour|Help reading this manual]]
This appendix provides reference information, not needed in simple uses of EiffelStudio.
We saw in the [[8 PRODUCING AND EXPORTING DOCUMENTATION|section on documentation]] that you can output documentation about your system in many different formats. A number of predefined formats are available, from Postscript to Microsoft's Rich Text Format, FrameMaker, HTML with and without style sheets, TEX and others. There's nothing special about these formats: they just make their conventions known to EiffelStudio through a '''filter''' expressed in a simple notation called EFF, or Eiffel Filter Format. If you have a favorite format that you'd like EiffelStudio to use for producing documentation, you can define your own filter in EFF. Applications include:
* Producing a variant of an existing format, to support some "house style" that you have defined, such as a different formatting or fonts.
* Producing documentation for a text processing tool that's not among those supported by default.
* Producing documentation that purposely omit some parts of Eiffel texts, in line with the ideas applied by the Contract and Flat Contract forms.
This appendix describes EFF and its conventions, enabling you to write filters. Note that in practice the best way to write an EFF filter is usually not from scratch, but by copying an existing filter -- one that seems closest to your needs -- and adapting the copy.
<div>
==Where to put filters==
When you choose to generate documentation, EiffelStudio will ask you to select a filter from a list it obtains by looking up the files of extension <span>.</span> <code> fil </code> in the directory
<code>$ISE_EIFFEL/studio/filters</code>
To make a new filter available to yourself and other users of this installation, just add the corresponding file <code> name </code> <span>.</span> <code> fil </code> to this directory. Make sure to choose the appropriate <code> name </code>, since this is what the menu of available filters will display.
</div><div>
==Filter basics==
An EFF filter follows a very simple structure. As with all other Eiffel-related notations (such as Eiffel itself and Lace, the control language for Eiffel systems), any line or part of a line beginning with two consecutive dashes <code> -- </code> is a comment, except if it immediately follows a percent sign since, as will be seen below, <code> - %- </code> is used to denote an Eiffel comment in the class text. Blank lines are also permitted. Comments and blank lines carry no semantic value.
Except for comments and blank lines, a filter is a sequence of entries, all of the form
<code>Construct | Replacement</code>
where: <code> Construct </code> is one of a set of possible strings, most of which correspond to Eiffel constructs such as <code> Class_declaration </code> or Eiffel keywords such as <code> class </code> ; and <code> Replacement </code> is a string indicating how to format specimens of the <code> Construct </code> that appear in a class text.
For readability, there may be any number of blanks or tabs between the <code> Construct </code> and the vertical bar <code> | </code>, so that you can align all the bars if you wish. On the right of the bar, however, all characters including blanks and tabs are significant, since they are part of the replacement for the <code> Construct </code>.
</div><div>
==The asterisk==
In the <code> Replacement </code> part, you may use the symbol <code> * </code> (asterisk) to denote the construct specimen itself. So for example the entry
<code>Feature_clause | %N%N*%N%N</code>
specifies the following formatting for any <code> Feature_clause </code>: two successive blank lines (expressed as <code> %N </code>, New Line, a convention taken from Eiffel); the feature clause itself; two blank lines.
Similarly, in an HTML format, the entry
<code>External |<B> * </B></code>
means that the Eiffel keyword <code> external </code> must appear in the filtered form immediately preceded by <code> <B> </code>, the HTML code for switching to boldface, and immediately followed by <code> </B> </code>, the code for reverting to the previous setup. Here you can also write the right-hand side without the asterisks, as <code> <B>external</B> </code>. If, however, all keywords are to use boldface, it is preferable to write a single entry
<code>Keyword |<B> * </B></code>
which, thanks to the asterisk, will govern all construct specimens of the <code> Keyword </code> category. You can still override this specification for an individual keyword by including a specific entry for it.
</div><div>
==Constructs==
The following general syntactic constructs may appear as the left-hand side, <code> Construct </code>, of an entry:
<code>
'''Class_declaration
Class_end
Class_header
Class_name
Comment
Creators
Escape
Feature_clause
Feature_declaration
Features
Formal_generics
Indexing_clause
Inheritance
Invariant_clause
Keyword
New_line
Obsolete_clause
Suffix
Symbol
Tab'''</code>
Most of these denote Eiffel constructs as they appear in the official language reference, the book <span> [http://www.eiffel.com/doc/ Eiffel: The Language] </span>. Since the Eiffel construct names <code> Feature </code>, <code> Invariant </code> and <code> Obsolete </code> are also keywords and EFF, like Eiffel, is case-insensitive, the EFF construct names use the suffix <code> _clause </code>, for example <code> Feature_clause </code>.
The constructs corresponding to syntactic constructs are self-explanatory. The others are:
* <code> Class_end </code>, denoting the final end of a class text.
* <code> Keyword </code>, denoting any Eiffel keyword among those listed in boldface in the corresponding appendix in <span> [http://www.eiffel.com/doc/ Eiffel: The Language] </span>
* <code> New_line </code>, denoting any passage to a new line in the class text.
* <code> Suffix </code>, used to introduce the file extension for the generated documentation files. If you don't specify this, EiffelStudio will use the filter's name as extension.
* <code> Symbol </code>, denoting any of the Eiffel symbols listed in the corresponding appendix of <span> [http://www.eiffel.com/doc/ Eiffel: The Language] </span>.
* <code> Escape </code>, to protect special characters of the external tool, as explained below.
* <code> Tab </code>, denoting any tab character appearing in the class text.
<div>
==Keywords==
A <code> Construct </code> part may consist of the name of an Eiffel keyword. To see the complete list of possible keywords, look at the <code> template </code> filter, file <code> format.fil-template </code> in the default filter directory <code> $ISE_EIFFEL/studio/filters </code>, which includes all of them with a single asterisk <code> * </code> as the <code> Replacement </code> part.
If entries are present for both the <code> Keyword </code> construct and individual keywords, the individual keyword entries will override the general entry for the keywords listed; the general entry will apply to all other keywords. This makes it possible to have both a general convention for keywords and a special convention for some of them.
</div>
==Symbol==
A <code> Construct </code> part may consist of an Eiffel symbol, such as <code> := </code>, <code> /= </code> and many others. Again, you may see the complete list by looking at <code> format.fil-template </code>. Note the following conventions:
* <code> % </code> <code> * </code> represents an asterisk. For example as a multiplication operator; the <code> % </code> avoids the confusion with the special meaning of the asterisk for EFF. You can find examples of this convention in the EFF filters for troff and gtroff.
* Similarly, the Eiffel comment symbol appears as <code> - %- </code>, since just writing <code> - - </code> would introduce a comment in the EFF filter itself.
As with keywords, you may specify a general convention for symbols, defined by an entry for the construct <code> Symbol </code>, and special conventions for certain individual symbols. Specific symbol entries will override the general <code> Symbol </code> convention.
</div>
==Escape characters==
A text processing system or other external tool may attach a special role to characters that may normally appear in Eiffel texts. For example, the braces <code> { </code> and <code> } </code>, used in Eiffel's Export clauses, have a special meaning for TEX. Including them without precaution in TEX input will cause trouble. Similarly, many text processing formats attach a special meaning to the backslash character <code> \ </code> which, although not special for Eiffel, may appear in an Eiffel string.
In such cases the filter must " <span>escape</span> " the special character, that is to say, protect it by other characters. For example troff and other text processing tools treat two successive backslash characters <code> \\ </code> as denoting a single backslash in the text to be output. The first backslash is the escape character, protecting the second one.
The <code> Escape </code> construct addresses such cases. The first character that follows <code> Escape </code> (after one or more blanks or tabs) is the character to be escaped. The string after the vertical bar is the replacement for that character.
Here for example is an escape entry for the backslash in tools that need to escape it through another backslash:
==Special characters and strings==
EFF uses Eiffel-like conventions, based on the percent sign, for control characters appearing in <span>Replacement</span> parts of entries. Two of these conventions have just been noted: <code> % </code> <code> * </code> to represent an asterisk and <code> %- </code> to represent a dash that does not introduce an Eiffel comment. In addition:
* <code> %| </code> denotes a vertical bar. (This is necessary since EFF uses <code> | </code> by itself in each entry to separate the <span>Construct</span> from the corresponding <span>Replacement</span>.)
* <code> %N </code> (recommended form) or <code> %n </code> denotes a new line.
* <code> %T </code> (recommended form) or <code> %t </code> denotes a tab.
* <code> %% </code> denotes a percent sign.
* <code> % </code> (percent followed by a space) denotes a space. This is equivalent to just a space, but more visible.
If <code> c </code> is not one of the characters for which special conventions have been listed, <code> % </code> <code> c </code> denotes the character <code> c </code> itself.
A multi-line entry uses the Eiffel convention for string continuations: <code> % </code> at the end of a line to signal that there is a continuation; a continuation line begins with zero or more spaces and tabs followed by a <code> % </code> ; the characters after the <code> % </code> are the continuation of the string.
[[18 EXECUTING A SYSTEM WITHIN AND WITHOUT EIFFELSTUDIO|<< Previous]]

79
documentation/current/eiffelstudio/eiffelstudio-guided-tour/browsing-features.wiki Normal file
View File

@@ -0,0 +1,79 @@
[[Property:title|9 BROWSING FEATURES]]
[[Property:link_title|Browsing Features]]
[[Property:weight|-6]]
[[Property:uuid|2c0b0a6c-08e8-fdbc-1eab-e2d87b01ce48]]
Let us get back to EiffelStudio. We won't need a browser any more for this Tour, so you may close any browser window (other than the <span>current</span> window if you are reading this in HTML!) opened to look up the generated documentation in the previous section.
Before studying the documentation generation we saw how to display properties of <span>classes</span>. It's also interesting to explore the properties of <span>features</span>. Let's look at this now, through the Feature View.
Your Development Window should still be targeted to class <code> LIST </code>, from the last view, <code> Routines </code>, that you displayed on it. If you've lost it, just retarget a Development Window to this class.
If the Features Tool is not visible, bring it back by clicking the <code> Features </code> button on the top toolbar, used earlier to remove it.
(Another way is through the menu entry <code> View </code> <code> --> </code> <code> Tools </code> <code> --> </code> <code> Features </code> ).
==Targeting to a feature==
The list of features, organized by feature clauses, appears on the left:
[[Image:index-51]]
The class only has a few immediate features because most of its interesting features are inherited. Make sure the Editing Tool is tall enough (as on the above figure) and click the feature <code> forth </code>, the last one, in the Feature Tree on the left. This makes the feature the Editing Tool's current target, and scrolls the text to its declaration:
[[Image:index-52]]
Note how both of the top target fields are now filled: the first one shows the target class, <code> LIST </code>, and the second one shows the target feature, <code> forth </code>.
==Basic feature information==
Now let's look at the feature views. Click the Feature Tab at the bottom of the Context Tool.
This brings up basic information on the selected feature in the Context Tool.
The bottom Context Tool shows one of the Feature views, by default <code> Flat </code>. The flat view of a feature, similar in concept to the flat view of a class, gives the full text of a feature, taking into account any inherited precondition or postcondition clauses. Here the feature as declared in the class appears in the top Editing Tool, with no precondition and an <code> ensure then </code> postcondition clause. But it's a redefinition of an inherited feature; the flat view in the bottom Context Tool shows the full precondition, inherited from the ancestor <code> LINEAR </code>, as well as the postcondition from <code> LIST </code>.
<code> Flat </code> is just one of the available Feature Views, shown by the buttons on the Feature View toolbar
<code> Text </code> gives the feature text, fully clickable.
<div>
==Who calls this feature?==
Next to <code> Flat </code> is <code> Callers </code>. Try it now by clicking the corresponding button (the following figure and the next only show the Context Tool, where the views appear):
[[Image:index-55]]
This view shows all the places in the system that call the routine, or one of its redefinitions. Such information can be invaluable for debugging in particular. The successive paragraphs correspond to the various versions of <code> forth </code> in class <code> LIST </code>, its ancestors and its descendants. Reading from the top we see that:
* The version from <code> LIST </code> is called in <code> LIST </code> itself by the function <code> is_equal </code>.
* The version from <code> LIST's </code> descendant <code> ARRAYED_CIRCULAR </code> is not called directly in this system, although it '''could''' be called through dynamic binding (on an entity declared of type <code> LIST </code> but dynamically attached to an instance of <code> ARRAYED_CIRCULAR </code>).
* About 60% down, <code> forth </code> from <code> ARRAYED_LIST </code>, a version in another descendant of <code> LIST </code>, is called by two routines of <code> ARRAYED_CIRCULAR </code>, one routine of <code> ARRAYED_LIST </code>, and two routines of <code> MULTI_ARRAY_LIST </code>.
* Also note, in the following entry, that after renaming <code> forth </code> is called <code> back </code> in the descendant <code> ARRAYED_STACK </code>.
The following five view buttons are similar except that they let you precise what kind of callers you are looking for, or what is being called by the currently selected feature.
==What happens to my feature through the inheritance hierarchy?==
After the caller/callee views, the next view button is <code> Implementers. </code>
This is a very useful view, showing all the ancestors and descendants of <code> LIST </code> that provide a separate version of <code> forth </code>, including the original introduction of this feature in <code> LINEAR </code> and subsequent redeclarations (redefinitions or effectings). The mention <code> (from version) </code> signals the version applicable to the current class, here <code> LIST </code>.
Since all class and feature names on these views are hyperlinks, you can display any of the listed versions in a new Development Window by control-right-clicking it (we will see shortly how to display it in the <span>same</span> tool). Right-click on the feature name <code> forth </code> on the line that reads <code> MULTI_ARRAY_LIST forth </code>. This brings up a context menu and chose `Show->Text'. The tool is now targeted to the routine <code> forth </code> from <code> MULTI_ARRAY_LIST </code>, so that you can see the implementation of the routine in that class.
We still have two unexplored views, <code> Ancestor versions </code> and <code> Descendant versions </code>. Click the first of these to obtain the ancestor versions of <code> forth </code> from <code> MULTI_ARRAY_LIST </code>.
The format is self-explanatory: for each ancestor of <code> MULTI_ARRAY_LIST </code> that has a version of <code> MULTI_ARRAY_LIST </code> 's <code> forth </code> feature, it indicates the name of that feature -- which could be something else than <code> forth </code> as a result of renaming, although here this happens only in descendants, not ancestors -- and the version of the feature applicable to the given class.
In the case of feature merging (combining several features inherited from different parents, in conformance with the rules of the language) there could be more than one history branch, in this case each branch is labeled <code> Branch #X. </code>
The next button, <code> Descendant versions </code>, similarly tells you all that happens to a feature in the descendants of the current class.
</div><div>
==Who has the same name?==
The last button, <code> Homonyms </code>, displays all the features of the system which, related or not to the current feature by redeclaration, have the same name. You can then explore any such feature to see if the relationship is more than casual.
In any system or library that takes advantage of inheritance and its associated mechanisms -- renaming, redefinition, effecting, undefinition, multiple and repeated inheritance, polymorphism, dynamic binding -- the feature browsing facilities that we have just explored are invaluable to track what happens to features. What makes them even more precious is their connection with the rest of the browsing and documentation capabilities, especially the pick-and-drop which we will now study.
</div>
[[8 PRODUCING AND EXPORTING DOCUMENTATION|<< Previous]] [[10 RETARGETING THROUGH PICK-AND-DROP|Next >>]]

20
documentation/current/eiffelstudio/eiffelstudio-guided-tour/command-line-compiler.wiki Normal file
View File

@@ -0,0 +1,20 @@
[[Property:title|17 THE COMMAND-LINE COMPILER]]
[[Property:link_title|The Command-Line Compiler]]
[[Property:weight|4]]
[[Property:uuid|62bd8d62-a734-3ec0-9533-eaa096e7b81f]]
[[Help reading the EiffelStudio Guided Tour|Help reading this manual]]
Along with compilation from within EiffelStudio, it is possible to start compilation from a command line (shell). This is useful in particular to recompile your system automatically as part of a script.
To use the command-line compiler -- <code> ec </code> for Eiffel Compilation -- execute
<code>
ec option & [class_name] [feature_name]
</code>
Specify <code> class_name </code> and <code> feature_name </code> only if you wish to produce information about a class or a feature. Otherwise <code> ec </code> will compile a system according to each specified <code> option </code>. [[EiffelStudio: Command line options|Click here to see the set of supported options.]]
[[16 HOW EIFFELSTUDIO COMPILES|<< Previous]] [[18 EXECUTING A SYSTEM WITHIN AND WITHOUT EIFFELSTUDIO|Next >>]]

48
documentation/current/eiffelstudio/eiffelstudio-guided-tour/computing-project-metrics.wiki Normal file
View File

@@ -0,0 +1,48 @@
[[Property:title|14 COMPUTING PROJECT METRICS]]
[[Property:link_title|Computing Project Metrics]]
[[Property:weight|0]]
[[Property:uuid|8d1a3556-d9a2-0ac8-4d54-458f18cb56ad]]
[[Help reading the EiffelStudio Guided Tour|Help reading this manual]]
In earlier sections we saw how EiffelStudio provides extensive documentation on your systems. That information was qualitative. Project managers and developers will also be interested in <span>quantitative</span> information about their projects. You can get such information through the <code> Metrics </code> tool, which enables you to perform a number of operations, detailed over the next few pages:
* Apply predefined metrics -- number of classes, number of invariants, number of features, number of compilations so far and many others -- to components of a system at various levels including feature, class, cluster, entire system.
* Define new metrics, through mathematical formulae or boolean selection, and apply them to your project.
* Store measurement results, as well as metric definitions, into an XML archive that can be stored locally or made available on the Web for future reference.
* Compare the measurements on a system to those on record locally or on a Web site. Eiffel Software has released on its own site an archive recording the metric properties of its basic libraries, available to any other project for comparison.
<div>
==Methodological observations==
Although the field of software metrics is a rich one with an abundant literature, its methodological basis is sometimes subject to question. One should resist the tendency to believe numbers just because they are numbers ("lies, damn lies, and metrics").
Software engineers and their managers expect, however, to reap at least some of the benefits that precise quantification has brought to other engineering fields. Such is the purpose of software metrics, defined as '''quantitative estimates of product and project properties'''. Object-oriented development, with the rich software structures that it induces, is a particularly amenable to metric analysis. Even when some of the measures do not seem to bring much by themselves, comparing them to those of other projects may reveal significant peculiarities of a system or of some of its parts.
The metrics capabilities of EiffelStudio were designed with these observations in mind. They result from a conservative approach, where no metric is provided without a credible assumption that it reflects some meaningful project or product attribute. For example, you will find a way to define a new metric as a <span>linear combination</span> of existing ones, but not a way to compute arbitrary arithmetic operations, since it isn't clear that -- say -- <span>multiplying</span> two metrics ever makes sense.
</div><div>
==Metric terminology==
The following terms are used in the presentation of EiffelStudio metric mechanisms.
A '''metric''' -- not to be confused with a measure -- is a quantitative property of software products or processes whose possible values are numbers. A '''measure''' is the value of a metric for a certain product or process.
For example, we can evaluate the metric "number of classes in the system", called just <code> Classes </code>, by counting the classes in our system. This yields a measure.
We may distinguish between '''product''' ''' metrics''', which measure properties of the elements being turned out (code, designs, documentation, bug reports...) and '''process''' ''' metrics''', which measure properties of the process used to turn them out (salaries, expenses, time spent, delays...). The current metric facilities of EiffelStudio are primarily product-oriented but include a process metric: "number of compilations".
Any metric should be relevant: related to some interesting property of the processes or products being measured, such as cost, estimated number of bugs, ease of maintenance...A '''metric theory''' is a set of metric definitions accompanied with a set of convincing arguments to show that the metrics are relevant. Neither EiffelStudio nor this manual provide a metric theory.
The numbers yielded by measures are meaningless unless we describe what they refer to. Every metric is relative to a certain '''unit''', specified as part of its definition. For example the unit for a metric that counts classes, such as <code> Classes </code>, is called <code> class </code>.
EiffelStudio provides a set of predefined units. Some simply serve to count occurrences of certain construct specimens in the software; examples include <code> group </code>, <code> class </code>, <code> feature </code>, <code> line </code>, <span>...</span> The metric <code> ratio </code> describes metrics whose values are divisions, for example "average number of classes per cluster", obtained by dividing the number of classes by the number of classes.
A metric can be computed over a scope, this scope is defined using a domain. In a domain
</div>
==Metric tool interface==
* [[Metric Evaluation Panel|Metric Evaluation panel]]
* [[Detailed Result Panel|Detailed Result panel]]
* [[Metric Definition Panel|Metric Definition panel]]
* [[Metric History Panel|Metric History panel]]
* [[Metric Archive Panel|Metric Archive panel]]

103
documentation/current/eiffelstudio/eiffelstudio-guided-tour/debugging-and-run-time-monitoring.wiki Normal file
View File

@@ -0,0 +1,103 @@
[[Property:title|13 DEBUGGING AND RUN-TIME MONITORING]]
[[Property:link_title|Debugging and Run-time Monitoring]]
[[Property:weight|-2]]
[[Property:uuid|a53f6a74-7145-35ab-ed5e-2905aeb88774]]
[[Help reading the EiffelStudio Guided Tour|Help reading this manual]]
The next set of EiffelStudio capabilities enable you to control and monitor the execution of your systems. The obvious immediate application is to debugging; but the more general goal is to let you follow the execution of your systems, explore the object structures, and gain a better understanding of the software.
<div>
==A reminder about debugging in Eiffel==
Before looking at debugging facilities don't forget that debugging in Eiffel is different. The presence of Design by Contract mechanisms gives the debugging process a clear sense of direction. The speed of the recompilation process makes it easy to recompile after a change; after getting rid of syntax and validity errors, you run the system again, and remaining errors are often caught as violations of contract clauses -- routine preconditions, routine postconditions, class invariants.
The facilities to be described now are also useful when you find such an error, as they will help you study its execution context. In fact, one of the characteristics of the debugging mechanism is that there is no "debugger" proper, no more than there is a "browser"; you have instead a set of facilities supporting controlled execution and debugging. This means for example that:
* While debugging, you can access all the browsing capabilities to explore the features and classes surrounding the cause of an error.
* While browsing, you can launch or resume execution, and follow its progress through the debugging facilities.
* If execution stops on an exception -- assertion violation, arithmetic overflow, call on a void target <span>...</span> -- you have all the environment's facilities at your disposal to understand what happened.
</div><div>
==Setting breakpoints==
To control the execution you will set breakpoints, indicating places where you want to interrupt the execution. You may set a breakpoint on an individual instruction of a routine, on the routine's precondition or postcondition, or on the routine as a whole, meaning its first operation (precondition or instruction).
A group of icons on the Project Toolbar help control breakpoints. They are known in EiffelStudio terminology as "''buttonholes''", meaning that they can serve both as buttons (you can click them to get some functions) and holes (you can pick-and-drop into them to get some other functions).
<div> [[Image:index-82]] [[general/guided_tour/studio/index-82.png|(link)]] </div>
The labels correspond to the icons' use as buttons: enable all set breakpoints, disable them all, clear all, display information on current breakpoints. The difference between "disabling" and "removing" is that disabling turns off breakpoints until further notice but remembers them, so that you can later re-enable them, whereas "removing" clears them for good.
Target a Development Window to the class <code> TESTROOT </code> and pick-and-drop the name of the procedure <code> make </code> (the first routine, after the declaration of the two attributes <code> o1 </code> and <code> o2 </code>) to the <code> Enable all </code> icon, used here as a hole. This sets and enables a breakpoint on the routine. Click the button labeled <code> Show/Hide information about breakpoints </code> above to get the list of breakpoints, as shown in the next figure.
<div> [[Image:index-83]] [[general/guided_tour/studio/index-83.png|(link)]] </div>
This shows that so far you have enabled only one breakpoint. For a finer degree of control, let's look at the feature's flat form. Pick-and-drop <code> make </code> to the Context Tool -- from the Context Tool itself, since its name appears there, or the Editing Tool); this sets the Context to the <code> Feature </code> Tab. Select the <code> Flat </code> view if that wasn't the last one used:
<div> [[Image:index-84]] [[general/guided_tour/studio/index-84.png|(link)]] </div>
The small circles on the left side of the Flat form indicate breakpoint positions. Empty ones are not set; enabled breakpoints are marked by a circle filled with red. At the moment only one is enabled, corresponding to the first instruction of the routine since, as noted, setting a breakpoint on a routine as a whole means setting it on its first operation.
By (left) clicking on a breakpoint mark, you toggle it between enabled and not set. You can also right-click on a mark to get a menu of possibilities. Try enabling and unsetting a few of these marks; you might get something like this:
<div> [[Image:index-85]] [[general/guided_tour/studio/index-85.png|(link)]] </div>
The breakpoint mark for the routine's third instruction, <code> create </code> <code> o2 </code>, is red but not filled; this means it is set but not enabled. You can obtain this by right-clicking on the mark and choosing <code> Disable breakpoint </code> on the menu that comes up. Any potential breakpoint will be in one of three states: not set; enabled; set but disabled.
You can see the list of enabled and disabled breakpoints by clicking the <code> Output </code> Tab, or the <code> Display info </code> button in the Project Toolbar.
For the continuation of this tour it doesn't matter which exact breakpoints of <code> make </code> you've set, as long as the one on its first instruction is set and enabled (red-filled circle) as above. Please make sure this is the case before proceeding.
</div><div>
==Executing with breakpoints==
To execute, you will use the following Run buttons in the Project toolbar, or the corresponding entries in the <code> Debug </code> menu:
<div> [[Image:index-82]] [[general/guided_tour/studio/index-82.png|(link)]] </div>
The buttons are shown here in full bloom, but at any times some of them will be grayed out. <code> Terminate </code> is only active when execution has started and not terminated; <code> Interrupt </code> is only active when the execution is active (not stopped at a breakpoint).
The <code> Debug </code> menu entries will also remind you of shortcuts: F10 for <code> Step-by-step </code>, F11 for <code> Step into routine </code>, Shift-F11 for <code> Step out of routine </code>, CTRL-F5 for <code> Run without breakpoints </code>, F5 for <code> Run with breakpoints </code>, CTRL-Shift-F5 for <code> Interrupt </code>, Shift-F5 for <code> Terminate </code>.
Start execution of the compiled system by clicking <code> Run with breakpoints </code>. The display automatically switches to accommodate supplementary tools providing debugging information. Execution stops on the breakpoint that you have enabled on the first instruction of procedure <code> make </code>:
<div> [[Image:index-87]] [[general/guided_tour/studio/index-87.png|(link)]] </div>
The pane at the bottom left indicates that execution has stopped in <code> make </code>. The Context shows the flat form of that routine, with a new icon to indicate the stop point which execution has reached. At the bottom right is a new tool, the '''Object Editor''', which shows the content of current object and (later) related objects. At the moment you can see that:
* The current object is an instance of class <code> TESTROOT </code>.
* The class (as you could also see from its text in a Development Window) has two attributes <code> o1 </code> and <code> o2 </code>, for which the corresponding fields in the current object are both void; this is as expected since you haven't yet executed the two creation instructions <code> create </code> <code> { </code> <code> HEIR </code> <code> } </code> <code> o1 </code> and <code> create </code> <code> o2 </code>, as they come after the breakpoint.
* Along with attributes, an Eiffel class may have '''once functions''', executed at most once -- the first time they are called -- in a given session, and from then on always returning the same value. Here the once function <code> io </code> has not yet been called, but when it is it will return an object of type <code> STD_FILES </code>.
The execution-time objects that you may display in an Object Editor are our latest kind of EiffelStudio "development object", along with classes, features, explanations, clusters; notice the distinctive icon, a rectangular mesh shape suggestive of an object's division into fields. It appears colored for actual objects and gray for Void references such as <code> operating_environment. </code>
</div><div>
==Monitoring progress==
Click twice on <code> Step-by-step </code> (or press the function key F10 twice). Monitor, in the flat form of <code> make </code>, the marker that shows execution progress; note that the marker always points to the <span>next</span> operation to be executed. After the two steps, the Context and Object Tools look like this:
<div> [[Image:index-88]] [[general/guided_tour/studio/index-88.png|(link)]] </div>
The last instruction that you executed is <code> create </code> <code> { </code> <code> HEIR </code> <code> } </code> <code> o1 </code>, meaning create an object and attach it to <code> o1 </code>, but instead of using the declared type <code> PARENT </code> of <code> o1 </code> use its proper descendant <code> HEIR </code>. As a result, the entry for <code> o1 </code> in the Object Tool no longer shows <code> Void </code> but an object of type <code> HEIR </code>. Note that all objects are identified by their addresses in hexadecimal; such an address is by itself meaningless, but enables you to see quickly whether two object references are attached to the same object. The addresses you see as you run the Guided Tour will -- except for some unlikely coincidence -- be different from the ones appearing here.
Note that since the garbage collector compacts memory and hence may move objects around, the address of a given object is not guaranteed to remain the same throughout a session.
To see the details of the object, pick-and-drop its identifier in place (that is to say, drop it in the Object Tool itself). A new object entry appears, showing the object.
</div><div>
==From the instance to the class==
Now try pick-and-dropping that same object, the instance of <code> HEIR </code>, to the Context Tool above the Object window. The effect is the same as if you had pick-and-dropped the '''class''' name <code> HEIR </code>: retarget the Context Tool to that class.
In the same way that you can drop a <span>feature</span> pebble into a tool that expects a class, you can also drop an <span>object</span> pebble, which will be understood as denoting the object's generating class.
Because the Context Tool is showing a class, it has switched to the default format for classes, <code> Ancestors </code>, and is showing the ancestors of <code> HEIR </code>. Click the <code> Feature </code> Tab of the Context Tool to set it back to feature information for the continuation of our debugging session. No feature is currently displayed.
</div><div>
==Stepping into and out of a routine==
Click <code> Step-by-step </code> once more to advance just before the call <code> o1 </code> <span>.</span> <code> display </code>.
Choosing <code> Step-by-step </code> again would execute the next step in the current routine, the call <code> o1 </code> <span>. </span> <code> display </code>, treating the entire execution of <code> display </code> from class <code> HEIR </code> as a single operation. Assume instead that you want to go <span>into</span> that routine and follow the details of its execution. For one thing, you might not know that it's a routine of class <code> HEIR </code>, since <code> o1 </code> is declared of type <code> PARENT </code> and it's only through polymorphism, <code> o1 </code> being dynamically of type <code> HEIR </code> at this point, and through dynamic binding, that the execution ends up calling a routine from <code> HEIR </code>. Of course here it's obvious because of the wording of the <code> create </code> a few lines up, but in many cases, especially all those for which polymorphism and dynamic binding are <span>really</span> interesting, the exact type won't be immediately clear from the neighboring software text.
Click the <code> Step into routine </code> button (or press F11). This brings execution to the beginning of the appropriate <code> display </code> routine in class <code> HEIR </code>.
You can also expand the <code> Call stack </code> pane on the left to see the full call stack, consisting here of only two levels. Minimize it to get the above display back.
Now click <code> Step out of routine </code> (Shift-F11) to finish the execution of <code> display </code>. This brings you back to the next instruction of the calling routine, <code> make </code> of <code> TESTROOT </code>.
</div><div>
==Terminating==
You may now click the <code> Terminate </code> button (Shift-F5) to end execution. The execution-specific tools go away and the display returns to what it was before execution.
</div><div>
==Other debugging capabilities==
In this little application nothing runs long enough to give you the time to interrupt it. In a longer-running application you may want to interrupt execution, <span>without</span> necessarily terminating it, while it's running (not stopped on a breakpoint). This is the purpose of the <code> Interrupt </code> button (CTRL-Shift-F5). It will interrupt execution at the closest potential breakpoint position, letting you -- as when execution stops because of an exception -- take advantage of all the debugging and browsing facilities to see what's going on inside the program. You may then restart execution -- with or without breakpoints, single-stepping, out of the current routine, into the next routine -- by choosing the appropriate Run button
In debugging sessions for more advanced applications, you will also find self-explanatory mechanisms enabling you, in addition to what we have seen, to examine all the objects on the "call stack": arguments and local entities of the current routine, its caller, caller's caller and so on.
The combination of these facilities provides you with a level of <span>dynamic</span> information on the execution of your system that matches the <span>static</span> information that the browsing mechanisms studied in preceding sections provide about the system's structure.
</div>
[[12 HANDLING SYNTAX AND VALIDITY ERRORS|<< Previous]] [[14 COMPUTING PROJECT METRICS|Next >>]]

47
documentation/current/eiffelstudio/eiffelstudio-guided-tour/executing-system-within-and-without-eiffelstudio.wiki Normal file
View File

@@ -0,0 +1,47 @@
[[Property:title|18 EXECUTING A SYSTEM WITHIN AND WITHOUT EIFFELSTUDIO]]
[[Property:link_title|Executing a System Within and Without EiffelStudio]]
[[Property:weight|5]]
[[Property:uuid|8256398e-d1a9-0471-664a-3225c7dfb306]]
[[Help reading the EiffelStudio Guided Tour|Help reading this manual]]
To complete this study of the compilation process let's see a few more properties of how you can <span>execute</span> an Eiffel system, both in EiffelStudio and as a compiled system that you deliver to its users, who may need to run it without EiffelStudio.
<div>
==Arguments==
Our example system is very simple and has no need for execution arguments. In more advanced cases you may want to pass values to the execution, such as a numeric parameter or a file name, so that you can have different executions without changing and recompiling the software.
In the Eiffel text, you can access such run-time arguments through the Kernel Library class <code> ARGUMENTS </code>. There is another technique -- using the arguments to the root creation procedure -- but using <code> ARGUMENTS </code> is the most general way. Any class of your system can inherit from <code> ARGUMENTS </code> and use queries <code> argument_count </code> to know the number of arguments passed to the execution, and <code> argument </code> <code> ( </code> <code> i </code> <code> ) </code>, for <code> i </code> between 1 and <code> argument_count </code> to access the <code> i </code> -th element. Class <code> ARGUMENTS </code> has more features; since you have Eiffelstudio up, you can check the details if you wish (use the contract form).
There are 2 ways to specify execution arguments from within EiffelStudio. The first is through the <code> Project </code> <code> --> </code> <code> Project Settings </code> <code> --> </code> <code> Debug/Profile </code> <code> --> </code> <code> Program Execution </code> tab. The second is through the argument dialog which can be opened by right-clicking on any of the debugging or program execution buttons on the main toolbar. The latter is more convenient for quick and easy access to execution arguments.
</div><div>
==Executing from EiffelStudio==
We have seen how to execute a compiled system from within EiffelStudio: choose one of the appropriate execution buttons, with or without breakpoints.
</div><div>
==Executing a finalized system outside of EiffelStudio==
A finalized system can be executed on any computer of the appropriate platform; it doesn't need EiffelStudio. The executable version is in the directory
<code> project_directory/EIFGENs/target_name/F_code</code>
where <code> project_directory </code> is the project's directory and <code>target_name</code> ist the name of the target. The name of the executable file is <code> system_name </code> <code> .exe </code>, where <code> system_name </code> is the name that you have assigned to your system in the project settings (reflected in the ECF file).
The target of the Guided Tour system is <code> classic </code> and the name is <code> simple </code>, so you can locate <code> simple </code> <span>.</span> <code> exe </code> in <code> EIFGENs/classic/F_code </code> for your project, and run it stand-alone if you like.
If you run the system from a command line, and it requires arguments ( <code> simple </code> doesn't), you will provide the appropriate arguments after the command name:
<code> system_name.exe ... arg ...</code>
Because various platforms have different conventions, "relative paths" referenced in your system will mean something different under Unix/Linux, where they relate to the directory from which the command is launched, and under Windows, where they relate to the application's directory.
</div><div>
==Executing a frozen or melted system outside of EiffelStudio==
A system compiled in "Workbench mode" -- frozen or melted -- is normally meant for execution within EiffelStudio, not for outside delivery, since it is not optimized. If you need to execute it outside of EiffelStudio, make sure that you have access to the <code> system_name </code> <span>.</span> <code> melted </code> file in <code> project_directory </code> <code> /EIFGENs/target_name/W_code </code>.
</div><div>
==Moving on==
With this discussion of compilation and execution we have finished our review of the key capabilities of EiffelStudio. Not everything has been covered, but you are now familiar with the essentials and ready to discover the rest by yourself, both by trying out various capabilities -- most of which should be self-explanatory -- and examining the extensive online documentation that accompanies the product.
</div>
[[17 THE COMMAND-LINE COMPILER|<< Previous]] [[19 APPENDIX: WRITING DOCUMENTATION FILTERS WITH EFF, THE EIFFEL FILTER FORMAT|Next >>]]

147
documentation/current/eiffelstudio/eiffelstudio-guided-tour/graphics-based-design.wiki Normal file
View File

@@ -0,0 +1,147 @@
[[Property:title|15 GRAPHICS-BASED DESIGN]]
[[Property:link_title|Graphics-based Design]]
[[Property:weight|1]]
[[Property:uuid|78239225-67a7-8718-857d-f2c8fb70ef18]]
[[Help reading the EiffelStudio Guided Tour|Help reading this manual]]
So far the project modifications that we have made used the text editor in the Editing Tool. We used graphics, but as a way to reflect system structures, not to build them ( [[6 STARTING TO BROWSE|See "A Peek at Diagrams" in STARTING TO BROWSE]] , and subsequent discussions).
In line with the principles of seamlessness and reversibility recalled at the beginning of this Tour, EiffelStudio's text-diagram interaction is bi-directional. When you make a textual modification, the next incremental recompilation will update the diagram; but you can also work directly from the diagram, and the text will be generated or updated after each graphical operation.
Many people like to use the graphical mechanisms at the beginning of a project, to draft the overall structure of a system in "bubbles-and-arrows" style, then concentrate on text as they get closer to implementation. But there is really no such obligation. At any point in the development, just use the form that is more suited to your taste and to your needs of the moment.
<div>
==Displaying a cluster view==
We are going to play with the root cluster. Make sure the Cluster tree and the Context Tool are up. Also make sure that the Context tool is in Isolate rather than Linked behavior; you can see this by going to the <code> Edit menu </code>: if there is an entry <code> Unlink context tool </code>, select it; otherwise (the corresponding entry reads "Link context tool") don't do anything, you're fine. (You can also use the Link/Isolate button added earlier to the Browsing toolbar for this very purpose.)
The earlier diagrams were "class views", giving a picture of the world around a class. For a change, we are now going to start working with '''cluster views''', showing the content of a cluster. Select the Diagram Tab in the Context Tool; from the Cluster Tree, pick-and-drop <code> root_cluster </code> to the Context Tool. This displays the graphical view of the root cluster in the Context Tool:
<div> [[Image:index-113]] [[general/guided_tour/studio/index-113.png|(link)]] </div></div><div>
==Hiding a class==
First we decide that we don't want to be bothered with class <code> INVALID </code>. We could delete it altogether from the system by pick-and-drop its bubble to the Delete hole. This is not what we want, but try this now to see the confirmation request:
<div> [[Image:index-114]] [[general/guided_tour/studio/index-114.png|(link)]] </div>
Make sure to answer <code> Cancel </code> to that confirmation request (you want to keep the class even though it wouldn't be a catastrophe to lose it) and instead pick-and-drop the <code> INVALID </code> bubble into the <code> Hide </code> hole. This time there is no confirmation request, since the operation is reversible -- it just affects what's displayed in the cluster view -- and the class is removed from the display:
<div> [[Image:index-115]] [[general/guided_tour/studio/index-115.png|(link)]] </div>
You can try undoing this change, then redoing it.
You can also click <code> History </code> which, during the rest of the session, will display the list of executed operations, and let you undo or redo many operations at once by clicking the oldest to be kept or the youngest to be redone.
For the rest of this discussion we assume <code> INVALID </code> is hidden.
</div><div>
==Adding a class==
We are now going to add a class graphically to our system. This means you don't have to worry about creating and initializing a file; EiffelStudio will take care of the details.
The useful button here is <code> New class </code>.
This button is a pebble, meant to be dropped into the diagram. Drop it somewhere above the bubble for <code> TESTROOT </code>; the exact place doesn't matter, but it has to be within the area of the cluster <code> root_cluster </code> because we'll want our class to part of it. You're asked to name the class:
<div> [[Image:index-118]] [[general/guided_tour/studio/index-118.png|(link)]] </div>
Overwrite the default name being proposed, <code> NEW_CLASS </code>, by the name <code> HEIR2 </code>, as we are going to create a new heir of <code> PARENT </code>. Don't touch the file name in the second field; as you type the class name EiffelStudio automatically sets the file name to <code> heir2.e </code>, so you would only set it if you wanted to override the default convention for names of class files.
The new class is now in the diagram, part of <code> root_cluster </code>:
<div> [[Image:index-119]] [[general/guided_tour/studio/index-119.png|(link)]] </div>
Using conventional drag-and-drop (not pick-and-drop), move the class bubbles for <code> HEIR2 </code>, <code> TESTROOT </code> and <code> PARENT </code> so that the display looks approximately like the following. The double circle around <code> TESTROOT </code> is the BON convention to identify a system's root class.
<div> [[Image:index-120]] [[general/guided_tour/studio/index-120.png|(link)]] </div></div><div>
==Adding an inheritance link==
Now we are going to make <code> HEIR2 </code> an heir of <code> PARENT </code>. To create inter-class relations, you will select a relation by clicking one of the "Create link" buttons, then use pick-and-drop from the source class to the target class. There are three possibilities:
<div> [[Image:index-121]] [[general/guided_tour/studio/index-121.png|(link)]] </div></div>
Click the button marked <code> heir </code> above. Now pick-and-drop from the <code> HEIR2 </code> bubble to the <code> PARENT </code> bubble. (Now you see why conventional drag-and-drop is used to move bubbles: pick-and-drop on the diagram serves to add links between classes).
<div> [[Image:index-122]] [[general/guided_tour/studio/index-122.png|(link)]] </div>
To convince yourself that the new class has been made an heir of <code> PARENT </code>, in its text and not just in the diagram, pick-and-drop <code> HEIR2 </code> bubble to the Editing Tool at the top to see its text. (You could also control-right-click to the bubble to bring up a new Development Window on this class.) All the code has been generated from your graphical operations: creating the class produced a class template with all the standard style and clauses, and the reparenting operation made <code> HEIR2 </code> inherit from <code> PARENT </code>.
In a moment we'll use this Editing Tool to see how, conversely, EiffelStudio will automatically reflect in the diagram a change made to the text. For the moment go back to the Development Window.
In the Cluster Tree in the top-left pane, you will notice that the name of <code> HEIR2 </code> appears grayed out; so does the name of <code> INVALID </code>:
<div> [[Image:index-124]] [[general/guided_tour/studio/index-124.png|(link)]] </div>
This is EiffelStudio's way of telling us that these two classes, listed because they appear in one of the system's clusters, are not actually in the system because the root class doesn't reference them directly or indirectly.
<div>
==Adding a client link==
Let's add <code> HEIR2 </code> to the system by making <code> TESTROOT </code> a client of this class. Click the button that selects <code> Client </code> as the next relation to make links (the link creation buttons were shown on page [[EiffelStudio General: A Guided Tour|click here]] ). Pick-and-drop from the <code> TESTROOT </code> bubble to the <code> HEIR2 </code> bubble. This asks you what kind of client link you want:
<div> [[Image:index-125]] [[general/guided_tour/studio/index-125.png|(link)]] </div>
This technique gives you many option and in fact is a convenient way to build your classes, whether at the analysis, design or implementation level. Here, fill the fields as follows. For the top choice, keep the default, <code> Attribute </code>; we'll give class <code> TESTROOT </code> an attribute of type <code> HEIR2 </code>. For its feature category, keep the choice currently displayed, <code> Access </code>. For its name, replace the default, <code> new_feature </code>, by the name <code> my_heir </code>. In the <code> invariant </code> clause, choose
<code>
my_heir_not_void: my_heir /= Void
</code>
from the list to specify the invariant property that this attribute should never be void. Finally, to see how EiffelStudio can generate the full accompaniment to an attribute, check the box <code> Generate set procedure </code>. Click <code> OK </code>.
The diagram -- shown below after a slight move of the bubble for <code> TESTROOT </code> for more readability -- shows that <code> TESTROOT </code> is now a client of <code> HEIR2 </code>. By default it only displays inheritance links; now it has switched automatically to a mode that shows client links as well, so that we also see that <code> TESTROOT </code> is (and always was) a client of <code> PARENT </code> through attributes including <code> o2 </code>.
<div> [[Image:index-126]] [[general/guided_tour/studio/index-126.png|(link)]] </div>
Now pick-and-drop the class bubble <code> TESTROOT </code> to the top Editing Tool to see how the class has been modified. The situation here is different from what we saw earlier with <code> HEIR2 </code>, which had been generated from scratch by the diagram. Here <code> TESTROOT </code> existed before, in text form; so the diagram mechanisms have had to preserve the existing feature and feature clauses, and add the elements corresponding to what you have specified through the diagram mechanisms. Here is the beginning of class <code> TESTROOT </code> in its updated form.
Note how EiffelStudio has generated both the attribute and the associated "set" procedure, <code> set_my_heir </code>, complete with a precondition -- deduced from the invariant you have specified, <code> Void /= my_heir </code> -- and a postcondition. The unlabeled Feature clause of the existing class has been kept; the new features have been entered into clauses labeled <code> Access </code> and <code> Element change </code>, observing the Eiffel standard for common feature clauses in libraries.
If you look at the end of the class, you will see an <code> invariant </code> clause listing the invariant that you have entered.
</div><div>
==Updating the diagram from the text==
In this tour of the diagram facilities we have, so far, worked on the diagram and seen the text updated immediately. Of course we want full reversibility. So let's make a change in the text and check the diagram.
The change will be very simple. We'll make <code> TESTROOT </code> a client of <code> HEIR </code>. In the top Editing Tool, use the editor to add an attribute declaration
<code>
other: HEIR
</code>
without further ado, as this is just a simple check.
{{note|If you are concerned about the correctness of the class, you may wish to update its creation procedure <code> make </code> to add a creation instruction <code> create </code> <code> my_heir </code>. Without it the just added invariant would be violated upon creation. }}
Nothing happens yet to the diagram. This is normal: EiffelStudio doesn't update the diagram every time you type some text (which, for one thing, might be syntactically incorrect, or invalid). You need to recompile first. Click the <code> Compile </code> button. Then on the Context Tool click <code> Diagram </code>; the new relation appears:
<div> [[Image:index-128]] [[general/guided_tour/studio/index-128.png|(link)]] </div>
If the label <code> other </code> of that relation doesn't appear in the exact place shown here, try moving it using conventional drag-and-drop. You can only move such a link label within a small area on either side of the link.
</div><div>
==Creating a cluster==
Earlier on, we saw how to create a class from the EiffelStudio diagram, letting EiffelStudio take care of creating and initializing the file. Similarly, you can create a new cluster graphically, and let EiffelStudio create the corresponding directory.
To create a cluster, you can go through <code> Project </code> <code> --> </code> <code> Project settings </code>, or you can click the little Cluster Creation button at the top of the Cluster Tree. Click this button. The resulting dialog asks you for the cluster name, and the existing cluster (non-precompiled) of which you want to make it a subcluster, here leaving only one choice:
<div> [[Image:index-130]] [[general/guided_tour/studio/index-130.png|(link)]] </div>
Instead of the <code> NEW_CLUSTER </code> default name, type <code> my_cluster </code>; select the only possible supercluster, <code> root_cluster </code>, and click <code> Create </code> at the bottom of the dialog.
Recompile the project and bring up the cluster diagram again. It shows the subcluster:
<div> [[Image:index-131]] [[general/guided_tour/studio/index-131.png|(link)]] </div>
Make sure that the display looks approximately like the above; you may have to resize either or both clusters (drag a corner), and move the small cluster (drag-and-drop).
</div><div>
==Moving a class to a different cluster==
Among the many operations you can do graphically is to move a class from one cluster to another. Pick-and-drop the <code> HEIR2 </code> class bubble to the rounded rectangle for <code> MY_CLUSTER </code>.
This graphical manipulation has caused a structural change: class <code> HEIR2 </code> is now part of <code> MY_CLUSTER </code>. Check this by expanding the Cluster Tree on the left:
<div> [[Image:index-132]] [[general/guided_tour/studio/index-132.png|(link)]] </div>
If you like, you can also look into the project directory -- using the Windows Explorer, or <code> cd </code> and <code> ls </code> on Unix/Linux -- and check that it now has a subdirectory <code> my_cluster </code> with a file <code> heir2 </code> <span>. </span> <code> e </code> containing the text of class <code> HEIR2 </code>.
Clearly, it's much more convenient to use EiffelStudio for such manipulations than to move files around manually.
</div><div>
==Adjusting the display==
A number of buttons enable you to customize the display. So far all class bubbles had the same default color (yellow). Try pick-and-dropping a bubble into the <code> Color hole </code> to get a color palette that enables you to select a different color. This is useful if you want to highlight classes possessing certain properties, for example classes that are part of a certain Design Pattern.
<code> Relation depth </code> enables you to select the depth at which inter-class relations will be displayed. (Don't change this setting now.) <code> Extend to cluster </code> is more useful for class diagrams than for the cluster diagram we have now, which by default included all classes of the cluster; if you click it here it will add the class <code> INVALID </code> that you removed earlier. There is no need to do this now.
</div><div>
==Views==
So far the top-right <code> View </code> field has always shown <code> DEFAULT </code>. You can define any number of views in your project, and apply them to various class and cluster diagrams.
For example, using the buttons to show and hide links of various kinds you can produce diagrams that only show the inheritance links, and others that only show the client links. If you want to keep both kinds of diagram, simply define views by typing view names -- such as <code> Inheritance </code>, <code> Client </code>, <code> All_links </code> -- into the <code> View </code> field.
You can also use views to retain some of the choices seen just before, such as different colors and depths.
To load a previously defined view, just use the menu associated with the <code> View </code> field.
You may remember that when we generated HTML documentation, the dialog asked you to select a view among the available ones. You can choose a different view for each cluster.
</div><div>
==Class diagrams, cluster diagrams==
Whereas our initial encounter with diagrams at the beginning of this Tour used class diagrams, in the present discussion we have used cluster diagrams. Both are interesting. To obtain a class diagram, you will target a Context Tool to a class, and select the <code> Diagram </code> Tab. By default, this shows the parents of the class. Do this now for <code> TESTROOT </code>:
<div> [[Image:index-138]] [[general/guided_tour/studio/index-138.png|(link)]] </div>
It's for class diagrams that the <code> Relation depth </code> button is most interesting. It will let you select the exact depth that you wish displayed for every relation:
<div> [[Image:index-139]] [[general/guided_tour/studio/index-139.png|(link)]] </div>
This will conclude our review of the Diagram facilities of EiffelStudio, although you'll surely discover some further riches by yourself and through the rest of the documentation. We hope the complete seamlessness between text and pictures will enable you to increase the effectiveness of your analysis work, or your design work, or your programming -- whatever level of system development you need to tackle.
</div>
[[14 COMPUTING PROJECT METRICS|<< Previous]] [[16 HOW EIFFELSTUDIO COMPILES|Next >>]]

69
documentation/current/eiffelstudio/eiffelstudio-guided-tour/handling-syntax-and-validity-errors.wiki Normal file
View File

@@ -0,0 +1,69 @@
[[Property:title|12 HANDLING SYNTAX AND VALIDITY ERRORS]]
[[Property:link_title|Handling Syntax and Validity Errors]]
[[Property:weight|-3]]
[[Property:uuid|c2be8123-b793-f8ce-e082-d4fdacc6bbe6]]
[[Help reading the EiffelStudio Guided Tour|Help reading this manual]]
So far we have tried to make sure that everything went smoothly. But in actual software development you may encounter error situations, and it is useful to know what can happen then.
<div>
==Levels of language description==
Let's remind ourselves first of how the language is specified. The book <span> [http://www.eiffel.com/doc/ Eiffel: The Language] </span>, the language reference, carefully distinguishes between three levels of description: '''syntax''', '''validity''' and '''semantics'''. Their roles are clearly distinct:
* <span>Syntax</span> defines the structure of software texts. A typical syntax rule states that an assignment starts with a <code> Writable </code> entity, continues with the symbol <code> := </code>, and ends with an <code> Expression </code>. This is a purely structural specification, saying nothing for example about the types of the <code> Writable </code> and the <code> Expression </code>.
* <span>Validity</span>, applicable only to syntactically legal texts, defines required consistency conditions. A typical validity rule states that in an assignment the right-hand-side <code> Expression </code> must <span>conform</span> -- a property of its type, defined rigorously on the basis of inheritance -- to the left-hand-side <code> Writable </code>. Eiffel has about 75 validity rules; part of the language's originality is that these rules are of the " <span>if and only if</span> " form, not only telling you individual error cases ("this is valid <span>only if</span> <span>...</span> ") but also reassuring you that your text will in fact be valid <span>if</span> it satisfies the conditions listed exhaustively.
* Semantics, applicable only to valid texts, defines the software's expected run-time behavior. A typical semantic rule states that an assignment replaces the value of its left-hand-side <code> Writable </code> by the value of the right-hand-side <code> Expression </code> at the time the assignment is executed, with precise rules on the different possible cases involving references, objects and simple values.
You may make an error at any of these levels:
* Writing <code> = </code> instead of <code> := </code> for the assignment symbol is a syntax error.
* Writing <code> your_integer </code> <code> := </code> <code> your_real </code>, with the types suggested by the names, is a validity error.
* Calling a feature on a void target, violating a precondition, causing a division by zero, are semantic errors.
Syntax and validity errors will be detected by the compilation process. For semantic errors, you will rely on contract checking and on the debugging tools described later. Let's look now at examples of the first two cases.
</div><div>
==A syntax error==
To see what happens for a syntax error, replace the keyword <code> is </code> by <code> ist </code> in the first line of routine <code> display </code> of class <code> PARENT </code> (click the position immediately after the <code> s </code> and type a <code> t </code>.). Save the file by clicking the Save button or using CTRL- <code> S </code> and then compile the system.
<div> [[Image:index-75]] [[general/guided_tour/studio/index-75.png|(link)]] </div>
To correct the error, just bring the mouse back to its location, remove the spurious <code> t </code>, and click Save again; also click Compile to make sure that the project is recompiled up-to-date.
You may wonder why the syntax error messages are not a little more verbose than just <code> Syntax error </code>. The reason is merely that Eiffel's syntax, being simple and regular, does not require sophisticated error messages; syntax errors usually result from trivial oversights. If you make a syntax error and the reason is not immediately clear, check the syntax summary in the appendix of <span> [http://www.eiffel.com/doc/ Eiffel: The Language] </span>.
</div><div>
==A validity error==
A validity error is a violation of one of the validity constraints given in <span> [http://www.eiffel.com/doc/ Eiffel: The Language] </span>. Every such constraint is identified by a four-letter code of the form <code> V </code> <code> XXX </code> (the first letter is always <code> V </code>).
A validity error will produce a precise error message, which includes the validity code. Although short, the error message is usually sufficient to find out what the error is. If not, you can get the complete rule, straight from the book.
To see this mechanism at work, let us introduce a validity error. There is in fact one ready for you in class <code> TESTROOT </code>. Target a Development Window to this class; at the end of its text, just before the final <code> end </code>, you will find the following comment line:
<code>
-- inv: INVALID;</code>
If uncommented, this is a declaration of a feature of type <code> INVALID </code>. A class called <code> INVALID </code> indeed exists in file <code> invalid.e </code> of the root cluster, but it contains a validity error. To see what it is, remove the initial double-dash <code> -- </code> in the above line from class <code> TESTROOT </code> so that it is not a comment any more.
<div> [[Image:index-76]] [[general/guided_tour/studio/index-76.png|(link)]] </div>
Click <code> Save </code>, then <code> Compile </code>. Compilation starts but after a few degrees it stops with an error message that appears in the bottom Context Tool (you may have to do some resizing to see it in its entirety):
<div> [[Image:index-77]] [[general/guided_tour/studio/index-77.png|(link)]] </div>
As the error message indicates, you have (shame on you) violated the validity rule <code> VUAR </code>, which requires the number and types of actual arguments in a routine call to match the number and types of formal arguments declared in the routine.
One of the interesting properties of the error message is that everything in color is '''clickable''' : class name, feature name, but also the error code. This means that you can start a Pick-and-Drop on any of these elements to find out more.
For example, to see the exact context of the error, pick-and-drop the name of the affected feature, <code> display </code> -- appearing on the fifth non-blank line, after <code> Feature: </code> -- and pick-and-drop it to the top Text window. (As you remember this means: right-click on it and release; move the mouse to the text window, without clicking any button; right-click again. During the move the cursor shows a cross, the symbol for features.) This displays the erroneous feature:
<div> [[Image:index-78]] [[general/guided_tour/studio/index-78.png|(link)]] </div>
Note on this display a special property of Pick-and-Drop when its source is a feature name appearing in a validity error message: the instruction that causes the error is highlighted.
In the error message in the Context Tool, the error code itself, <code> VUAR </code>, is also clickable. Assuming the message was not sufficient to understand the error, you can use it to start a Pick-and-Drop. Do this now, by picking that code and starting to move the mouse, but not dropping yet:
<div> [[Image:index-79]] [[general/guided_tour/studio/index-79.png|(link)]] </div>
The icon shape for such information elements is a question mark <code> ? </code>. If it is not on a droppable target, as in the bottom Context Tool, that icon will be crossed. In principle the place to drop is the Explanation hole in the Project toolbar, the only one that remains highlighted during the Move step of Pick-and-Drop:
<div> [[Image:index-80]] [[general/guided_tour/studio/index-80.png|(link)]] </div>
As is often the case when dropping into a specific hole, you don't need to shoot straight; dropping the pebble anywhere in the Editing Tool has the same effect as dropping it into the Explanation hole:
<div> [[Image:index-81]] [[general/guided_tour/studio/index-81.png|(link)]] </div>
The result is to display the complete text of the violated rule, straight from the pages of <span> [http://www.eiffel.com/doc/ Eiffel: The Language] </span>.
The rule has several clauses, numbered. Since the error message showed the error code as <code> VUAR(1) </code>, the violated clause is the first; this convention of showing the clause number in parentheses applies to all multi-clause validity constraints.
To correct the error the easiest is to go back to class <code> TESTROOT </code> and reinstate the comment symbol <code> -- </code> (two consecutive dashes) on the erroneous line. Save and compile to continue with a valid system.
</div>
[[11 RECOMPILING AND EDITING|<< Previous]] [[13 DEBUGGING AND RUN-TIME MONITORING|Next >>]]

3
documentation/current/eiffelstudio/eiffelstudio-guided-tour/how-eiffelstudio-compiles.wiki
View File

@@ -1,6 +1,7 @@
[[Property:title|16 HOW EIFFELSTUDIO COMPILES]]
[[Property:link_title|How EiffelStudio Compiles]]
[[Property:weight|3]]
[[Property:uuid|6fc86303-8afe-78af-6ca7-2853e8bfcbc3]]
[[Help reading the EiffelStudio Guided Tour|Help reading this manual]]
So far we have relied on the compiling capabilities of EiffelStudio without exploring them in any detail. We must now understand the principles behind EiffelStudio's compiling strategy, in particular how it reconciles fast turnaround, efficient generated code, and strong typing.
@@ -161,7 +162,7 @@ Note the <code> No </code> option: by default, freezing will start a C compilati
Click <code> Yes </code> to confirm freeze and C-compilation. Once the Eiffel compilation is complete, a message in the Development Window ( <code> C compilation launched in background </code>) tells you when that C-compilation has started. C-compilation does not block EiffelStudio: at this point you can continue working with the environment. Any messages from C compiler will appear:
* On Windows, in a new console that comes up for the occasion (minimize it if you don't want to see the messages).
* On Unix/Linux and VMS, in the window from which you launched EiffelStudio.
* On Unix/Linux and OpenVMS, in the window from which you launched EiffelStudio.
You will be able to execute the frozen system as soon as the C compilation finishes.

61
documentation/current/eiffelstudio/eiffelstudio-guided-tour/producing-and-exporting-documentation.wiki
View File

@@ -1,6 +1,7 @@
[[Property:title|8 PRODUCING AND EXPORTING DOCUMENTATION]]
[[Property:link_title|Producing and Exporting Documentation]]
[[Property:weight|-7]]
[[Property:uuid|ca43a3c2-9e1a-a69f-81cf-55d0b12294ea]]
[[Help reading the EiffelStudio Guided Tour|Help reading this manual]]
Software development is, most of the time, cooperative work. You must tell the rest of the team what you're up to, and find out what they can offer you. Bring in distributed development -- increasingly common these days, with some people working at headquarters, others at home, others traveling, an offshore team half a world away <span>...</span> -- and the problem becomes even more critical.
@@ -20,14 +21,14 @@ EiffelStudio's documentation generation satisfies all these requirements.
Let's see how documentation works by starting to generate it for our Guided Tour system -- which really means for EiffelBase, since that's what it mostly consists of. The HTML result is available as part of the present documentation (we'll tell you where in just a minute), so you don't have to regenerate it unless you want to. Indeed we'll show you when to click <code> Cancel </code> if you are happy with the pre-generated version. But let's get started anyway to understand the principles and possibilities.
Click the following menu entry, used to generate documentation:
<code>
Project --> Generate documentation...
</code>
<code>Project --> Generate documentation...</code>
This is the next-to-last entry in the <code> Project </code> menu. The last one, by the way, <code> XMI Export </code> <span>...</span>, is directly relevant too: it will make it possible to export information in the standard XML representation for UML, for consumption by third-party products such as Rational Rose. But for the moment we choose the <code> Documentation </code> entry to start the Eiffel Documentation Wizard.
The Wizard starts with a list of available output formats, also called <span>filters</span>:
<div> [[Image:index-37]] [[general/guided_tour/studio/index-37.png|(link)]] </div>
[[Image:index-37]]
The filter names correspond to major documentation formats which EiffelStudio supports by default. Among the most important, listed here in rough order of appearance in the list:
* <code> ASCII </code> : plain text, no formatting codes.
* <code> eiffel </code> : essentially the same as ASCII; useful if you want EiffelStudio to pretty-print your class texts and replace the originals, as explained below.
@@ -41,16 +42,16 @@ The filter names correspond to major documentation formats which EiffelStudio su
* <code> html-stylesheet </code> : HTML with style sheets. This is particularly attractive for Web publishing not only because the output makes full use of style sheet capabilities (fonts, colors, layout, formatting) but also because it becomes trivial to change the look-and-feel to support any style you or your users like, even <span>after</span> generation, simply by editing the style sheet file.
Not only do these predefined filters provide support for a number of important industry formats; better yet, if you want <span>another</span> format not represented on the list, or would like to adapt an existing format to your own style preferences, it's easy to define a new filter. The list that EiffelStudio displays comes from the files with a <span>.</span> <code> fil </code> extension that it finds in a subdirectory of the installation:
<code>
$ISE_EIFFEL/studio/filters
</code>
<code>$ISE_EIFFEL/studio/filters</code>
To define a new filter, simply add a file to this directory. Filters are expressed in a simple notation called EFF ( <span>Eiffel Filter Format</span> ), general enough to support a wide variety of tools for text processing, project management, Web publishing etc. The best way to define a new filter is usually to start from an existing one and adapt it. You will find the specification of EFF at the end of this manual, [[19 APPENDIX: WRITING DOCUMENTATION FILTERS WITH EFF, THE EIFFEL FILTER FORMAT|here]] .
==Generating an HTML record of your project==
Let's select the most obviously attractive of the predefined filters: HTML with stylesheets. Click the line <code> html-stylesheet </code> in the list to make it active, then click <code> Next </code> at the bottom of the Documentation Wizard window. The next window appears:
<div> [[Image:index-38]] [[general/guided_tour/studio/index-38.png|(link)]] </div>
[[Image:index-38]]
This is to let you decide which clusters of your system the documentation will include. Initially all clusters/libraries appear in the <code> Include </code> list on the right; but you might want to exclude some standard libraries or other clusters from the documentation.
To move a cluster from the right column to the left one, click it to select it, and click the left arrow button; for the reverse, use the right arrow.
@@ -60,7 +61,9 @@ You can play with moving a couple of clusters back and forth, but for this Tour
==Generating Metatags from Indexing entries==
The next step of the documentation wizard asks you to select indexing entries:
<div> [[Image:index-39]] [[general/guided_tour/studio/index-39.png|(link)]] </div>
[[Image:index-39]]
Eiffel classes, as you know, may start with an <code> Indexing </code> entry that enables class authors to include documentary information in any category they like. It is standard (and part of the official style guidelines) to include at the very least an entry of the form <code> description: </code> <code> Descriptive text </code> in every class. The earlier displays of class <code> LIST </code> showed that entry, which read " <code> Sequential lists, without commitment to a particular representation </code>".
You may have noted that the purpose of Eiffel's <code> Indexing </code> clauses is, conceptually, similar to that of '''metatags''' in HTML. Metatags carry information which Web page visitors do not normally see in the browser; this information is available, however, to search engines and other tools that explore and classify Web pages. So it seems quite appropriate to generate metatags from <code> Indexing </code> entries.
@@ -72,7 +75,9 @@ There is no need to change the default selection, so just click <code> Next </co
==Choosing a level of detail==
The next step of the Documentation Wizard lets you specify what kinds of documents you want to generate:
<div> [[Image:index-40]] [[general/guided_tour/studio/index-40.png|(link)]] </div>
[[Image:index-40]]
This is a very important facility since it gives you control over how much you want to publish about the properties of the software:
* You may want to publish <span>everything</span>, source included, for example on your Intranet for a group of developers working closely together on the same classes, or on the Internet for open-source software.
* You may want to publish only the <span>interfaces</span> (Contract or Flat-Contract views). This is not necessarily to protect proprietary information; even if you don't care about showing your source code, it is usually too detailed for client programmers, especially in the case of libraries. If various teams work on separate parts of a project, what each releases to the other should usually be the specification, not the implementation.
@@ -87,7 +92,9 @@ This time, if we generate anything, we'll generate everything. Please check '''a
==Specifying cluster views==
The next dialog only appears when you have asked to generate diagrams:
<div> [[Image:index-41]] [[general/guided_tour/studio/index-41.png|(link)]] </div>
[[Image:index-41]]
Although we didn't use this possibility yet, the Diagram view lets you define different subviews of any cluster. One view might show inheritance only, the other client links only; one might include all classes, the other hide some library classes. The last dialog shown will allow you, for any cluster, to select a subview other than the default for the generated diagram.
Here we only have the default view, so just click <code> Next </code>.
@@ -95,7 +102,9 @@ Here we only have the default view, so just click <code> Next </code>.
==Generating==
The last dialog simply asks you where you want to generate the result:
<div> [[Image:index-42]] [[general/guided_tour/studio/index-42.png|(link)]] </div>
[[Image:index-42]]
By default, as shown, EiffelStudio will produce the documentation in a subdirectory -- created for the occasion, if it doesn't exist yet -- of the project directory:
<code>
Project_directory /Documentation
@@ -110,23 +119,37 @@ To continue the Guided Tour, you do '''not''' need to complete the generation no
==Browsing generated documentation==
Let's take a look at the generated documentation. We start with the root of the generated documentation, <code> Documentation/index.html </code> :
<div> [[Image:index-43]] [[general/guided_tour/studio/index-43.png|(link)]] </div>
[[Image:index-43]]
This root page shows overall information about the system. The top set of links, repeated at the bottom, enables you to browse the system from its list of classes, its list of clusters, or the cluster hierarchy; note the box labeled <code> to Go </code>, which provides a built-in search engine, enabling you to type any class list and go directly to the corresponding page. Let's look at the class list: click the box <code> Classes </code> at the top left.
<div> [[Image:index-44]] [[general/guided_tour/studio/index-44.png|(link)]] </div>
[[Image:index-44]]
This shows the beginning of the list of classes, alphabetically sorted. You could click any class to get the corresponding information, but wait; we'll look at individual classes in a moment. Instead, click <code> Cluster hierarchy </code> to see the overall organization of the system into clusters:
<div> [[Image:index-45]] [[general/guided_tour/studio/index-45.png|(link)]] </div>
[[Image:index-45]]
Click <code> BASE </code> to see details of the EiffelBase library where (under EiffelStudio) we had found the class <code> LIST </code> used as example in the preceding sections:
<div> [[Image:index-46]] [[general/guided_tour/studio/index-46.png|(link)]] </div>
[[Image:index-46]]
This indicates the relations of the cluster to others in the hierarchy, and its list of classes. Again you could click any class name but instead note the mention <code> (diagram) </code> next to the cluster name near the top. Remember that when generating the documentation we elected to generate everything, diagrams included. Hadn't we checked the corresponding check box, the <code> (diagram) </code> link wouldn't be there. Click it now to get the generated diagrams:
<div> [[Image:index-47]] [[general/guided_tour/studio/index-47.png|(link)]] </div>
[[Image:index-47]]
The output is a diagram showing graphically the classes of the cluster and their inheritance relations. All EiffelStudio-generated HTML diagrams use the PNG graphics format ( <span>Portable Network Graphics</span> ), supported by all recent browsers.
The class bubbles in a diagram are all hyperlinks. To see the HTML documentation for our old friend the class <code> LIST </code> -- which you could also obtain by clicking its name on one of the preceding diagrams, or typing it in the <code> Go to </code> field -- just click its bubble:
<div> [[Image:index-48]] [[general/guided_tour/studio/index-48.png|(link)]] </div>
[[Image:index-48]]
The display shows key information on the class, in a form called the "Chart format" listing the ancestors and then the features, divided into <code> Queries </code> (shown in part on the figure) and <code> Commands </code>. Note that all class names and feature names are hyperlinks, which would lead you to the appropriate place in a class text.
The top row of hyperlinks now includes class formats corresponding to those we discovered under EiffelStudio ( [[7 CLASS VIEWS|"CLASS VIEWS"]] ): <code> Relations </code> (covering ancestors, descendants, clients, suppliers, ), full <code> Text </code>, <code> Contracts </code>, <code> Flat contracts </code>. Click <code> Flat contracts </code> to see the full interface of the class:
<div> [[Image:index-49]] [[general/guided_tour/studio/index-49.png|(link)]] </div>
[[Image:index-49]]
We'll stop this brief review here but you may continue browsing through the HTML pages if you like. Note how closely the appearance of the class texts, flat forms, contract forms, diagrams and other forms of documentation matches the corresponding formats under EiffelStudio.
Although we suggest staying with the standard, you can easily change any convention that doesn't match your own preferences:

138
documentation/current/eiffelstudio/eiffelstudio-guided-tour/recompiling-and-editing.wiki Normal file
View File

@@ -0,0 +1,138 @@
[[Property:title|11 RECOMPILING AND EDITING]]
[[Property:link_title|Recompiling and Editing]]
[[Property:weight|-4]]
[[Property:uuid|6574a573-48b9-6088-aa98-53d7119d7c5c]]
[[Help reading the EiffelStudio Guided Tour|Help reading this manual]]
So far we have relied on existing class texts. Fascinating as it may be to explore excellent software such as EiffelBase, you probably want to write your own too (with the help of the reusable components in the Eiffel libraries). EiffelStudio provides a built-in editor -- as well as the ability to use some other editor if you prefer -- and sophisticated compilation mechanisms.
==Recompiling==
When we started, we compiled the example system. Let's recompile it, just to see. We'll see compilation entries in the <code> Project </code> menu, but the easiest for the moment is to use the compilation button in the Project toolbar, the lower toolbar in the Development Window. Click this button. You haven't changed anything in the project since it was compiled (you were not supposed to!), so EiffelStudio will very quickly detect this and finish compilation. On our test platform this takes less than a second. Now of course we should see what happens if you do change something.
<div>
==Editing==
We don't want to touch EiffelBase classes (and in fact can't, since it is used in precompiled form), so let's focus on classes of our small root cluster. In the Cluster tree on the left, expand cluster <code> root_cluster </code> and click class <code> PARENT </code> to retarget the Development Window to it.
Make sure that the Editing Tool is big enough to display the text of the class:
<div> [[Image:index-66]] [[general/guided_tour/studio/index-66.png|(link)]] </div>
The Editing Tool hosts a text editor which you can use to change the class text. Here the routine <code> display </code> starts by outputting a simple message; let's precede it by another line of display to check that we affected the outcome. We'll want to add the following two lines just after the <code> do </code>, before the first two instructions of the routine:
<code>
io.put_string ("This is some more added text")
io.new_line
</code>
They are very similar to the current first two lines of the routine, so you can just use copy-paste: select the first two lines with the mouse, copy them using CTRL- <code> C </code> (or <code> Copy </code> from the <code> Edit </code> menu), then paste them just after the <code> do </code> using CTRL- <code> V </code> (or <code> Paste </code> from the <code> Edit </code> menu). Add or remove tabs to align with the rest of the routine, and change the string to <code> THIS IS SOME MORE ADDED TEXT </code> so that the result will look like what's shown on the next figure. This is all there is to change; the second line remains untouched. Please check the result and be careful not to introduce any mistakes; in the next section we'll study how EiffelStudio will report syntax and other errors, but right now we want to see what happens when everything is right!
<div> [[Image:index-67]] [[general/guided_tour/studio/index-67.png|(link)]] </div>
Now save your changes; you may indifferently use CTRL- <code> S </code>, the <code> Save </code> entry from the <code> Edit </code> menu, or the Save button highlighted on the figure. (If you forget to save, the next compilation will tell you so, and ask you if from now on you want all non-saved class edits to be saved automatically.)
</div><div>
==Recompiling and executing after a change==
Next compile again, using the Compilation button. Some "degree" messages appear quickly; EiffelStudio has found out what class has changed and deduced what exactly to recompile -- only a subset of the whole system. So this again will proceed very quickly.
Execute the system again now, using one of the execution buttons, with or without breakpoints, on the right in the bottom Project toolbar. You will see that the message output by the execution has changed to include the added string.
</div><div>
==Views in the Editing Tool==
In studying the Context Tool we discovered a number of views of a class text. For convenience, you can also display a number of these views in the Editing Tool, although only the basic Text view is editable. A row of buttons next to the Class and Feature fields lets you choose between them.
You can try some of these view now, although there is nothing exciting to show about class <code> PARENT </code>. Make sure to come back to the <code> Text </code> view -- through the leftmost of these buttons -- so that we can continue exploring the editing facilities.
</div><div>
==Basic editing facilities==
The editing facilities in the Editing Tool are provided by the EiffelStudio Editor, a specialized tool supporting the development and update of Eiffel texts. As we'll see next, if you have a preferred editor you can use it instead, but the EiffelStudio Editor is worth knowing.
The online documentation provides many more details about editing functions. Here are the essentials.
First, the key property of any interactive system: '''Undo'''. You can cancel the latest editing command, or any earlier one performed during the current session, by choosing <code> Undo </code> from the <code> Edit </code> menu, or typing CTRL- <code> Z </code>. To cancel more than one command, apply Undo repetitively; there is no limit to the number of undoable commands within a session. (When you exit EiffelStudio, however, the editing history is lost.) To redo an undone command, use <code> Redo </code> from the <code> Edit </code> menu or CTRL- <code> Y </code>.
{{note|Since right now we don't need to do any actual editing to continue this Guided Tour, we suggest that you don't change the text of class <code> PARENT </code> but simply look up the menu entries described next, without actually selecting them. If you do make a change, voluntary or not, you should at the end of this editor discussion perform enough Undo commands to get the text of class <code> PARENT </code> back to its original state. }}
To '''copy''', '''cut''' and '''paste''' use the corresponding entries in the <code> Edit </code> menu or the familiar keyboard shortcuts CTRL- <code> C </code>, CTRL- <code> X </code> and CTRL- <code> V </code>.
When you edit text, it will be automatically '''indented''' according to standard Eiffel style rules. If you prefer to remain in charge of your own indenting, you can disable this facility through <code> Tools </code> <code> --> </code> <code> Preferences </code> <code> --> </code> <code> Editor </code>.
To indent a sequence of lines, select the lines, then use <code> Edit </code> <code> --> </code> <code> Advanced </code> <code> --> </code> <code> Indent selection </code>. You can also use the Tab key, but only if the selection consists of one or more entire lines; otherwise typing Tab will simply replace the selected text with a Tab character. Shift-Tab will similarly decrease indentation by one step.
To '''comment out''' a sequence of lines, select them and use <code> Edit </code> <code> --> </code> <code> Advanced </code> <code> --> </code> <code> Comment </code> or CTRL- <code> K </code>. Conversely, CTRL-Shift- <code> K </code> will uncomment. Also in the <code> Edit </code> <code> --> </code> <code> Advanced </code> menu are "set to upper case", with the keyboard shortcut CTRL- <code> U </code>, and to lower case, CTRL-Shift- <code> U </code>.
Other useful facilities of the <code> Edit </code> <code> --> </code> <code> Advanced </code> menu are:
* <code> Embed in "if" </code>, or CTRL- <code> I </code>, which will create a conditional instruction and include the selected instructions in it.
* <code> Embed in "debug" </code>, CTRL- <code> D </code>, which will include the selected instructions in a <code> debug </code> <span>...</span> <code> end </code> instruction, so that their execution becomes conditional on a Debug compilation option.
<div>
==Search and replace==
The editor lets you search for text and replace occurrences, individually or globally. We assume you have seen a text search facility before, so we'll just emphasize some of the less obvious features.
To start a search, make sure the Search Tool is active by clicking the Search button in the top toolbar (this one we'll let you find) or using the <code> Edit </code> <code> --> </code> <code> Find </code> menu entry.
{{note| ''Note that although we are studying Search as part of the Editor, this function also applies to any textual form displayed in the Context Tool; make sure to start a Search from the tool that you want to search.'' }}
{{note|If you press CTRL - <code>F</code> in a tool you will get a quick search bar that quickly allows to search for something in the current text.}}
The Search Tool presents a number of self-explanatory options:
<div> [[Image:index-69]] [[general/guided_tour/studio/index-69.png|(link)]] </div>
You can enter a term to replace your search term in the <code> Replace with </code> box.
Having filled the two fields, you can elect to replace the last found occurrence, or all occurrences at once.
The <code> Search for </code> field has an associated drop-down list, so that you can reuse a recently entered search string without retyping it.
</div><div>
==Let the editor do the typing==
Particularly interesting are the editor's '''automatic completion''' facilities. Well, particularly interesting for <span>most</span> people: maybe you like your editor to do the grunt work for you, or maybe you don't. In the latter case -- if you prefer to be in control of all the details -- don't worry: through <code> Tools </code> <code> --> </code> <code> Preferences </code> <code> --> </code> <code> Editor </code> you can easily disable any facility that you don't like. The behavior described here is the default.
The EiffelStudio Editor knows about Eiffel syntax and will recognize syntactic elements as you type them. It will color them according to standard conventions: basic elements in black, keywords in blue, comments in dark red. You can change these conventions through Preferences.
If you start typing a control structure through its opening keyword, such as <code> if </code>, or <code> from </code> for a loop, the editor will automatically display the structure of the whole construct. Here for example is the result if you type the <code> from </code> followed by Return/Enter at the beginning of our example routine:
<div> [[Image:index-71]] [[general/guided_tour/studio/index-71.png|(link)]] </div>
This has produced the structure of an Eiffel loop: <code> from </code> <span>...</span> <code> until </code> <span>...</span> <code> loop </code> <span>...</span> <code> end </code>. You can then fill in the blanks with the appropriate expression and instructions. The generated lines start with the appropriate number of Tab characters to support the standard Eiffel indenting conventions. If you want a more compact style, follow the <code> from </code> with a space rather than Return. Typing <code> if </code> followed by Return or a space will similarly produce the outline of a conditional instruction.
To start a routine, type the routine name followed by the keyword <code> is </code> and a Return. The editor generates the basic structure of a routine text:
<div> [[Image:index-72]] [[general/guided_tour/studio/index-72.png|(link)]] </div>
This prompts you to enter the header comment (no self-respecting Eiffel developer even <span>thinks</span> of writing a feature without a header comment). At the end of the header comment, type Return if the header comment continues, otherwise type a down arrow to continue with the indentation for the beginning of the routine, with one of the keywords <code> require </code>, <code> local </code>, <code> do </code>, <code> external </code>, <code> once </code>. Once you type <code> do </code>, followed by a Return or space, the completion mechanism will insert the appropriate <code> end </code>, but other than that it doesn't try to produce an entire routine structure because there are too many syntactical choices (precondition or not, postcondition or not, locals or not etc.).
Also interesting is '''feature completion''', using the '''CTRL-SPACE''' key. It works at two levels:
* You can type the beginning of the name of a feature of the current class, then CTRL-SPACE to get possible completions.
* Once you have typed the name of a query (attribute or function), either all by yourself or aided by the previous completion technique, you can type a period followed by CTRL-SPACE to get the list of possible features to be applied, deduced from the list of features in the corresponding class (the type of the query).
In both cases, if more than one completion is possible, you will get a menu of the possibilities. You can scroll through it with the up and down arrow keys, or the mouse, and select one through Enter or double-click. You can also or give up through the Escape key.
Here for example is the menu you will see in the body of our example routine if you type <code> io </code> <span>. </span> followed by CTRL-SPACE, where <code> io </code> is the feature, coming from class <code> ANY </code>, that provides access to standard input and output facilities:
<div> [[Image:index-73]] [[general/guided_tour/studio/index-73.png|(link)]] </div>
The following properties enhance the convenience of the completion mechanisms:
* If only one completion is possible, no menu appears; the completion is selected.
* If the cursor is just after the name of a query (which you have fully typed, or obtained through completion), typing CTRL-SPACE once more will produce a period, as if you had typed it.
* When a menu of possible completions is displayed, typing CTRL-SPACE will select the first of them.
The combination of these facilities means that you can often obtain what you want simply by typing CTRL-SPACE repeatedly.
Also note the following properties of automatic feature completion:
* The mechanism will only work for queries that were present at the time of the last successful compilation. So if you add an attribute, say <code> attr </code>, to the current class, and do not recompile, typing <code> a </code> -CTRL-SPACE will not display <code> attr </code>. To make sure that it's included in completion proposals, save and recompile. (Remember, incremental compilation is fast in EiffelStudio, so there is nothing wrong in compiling early and often.) The same rule holds for features of <span>other</span> classes, those that will appear in proposed completions after a period.
* Automatic completion is applicable to features, not local entities or formal arguments.
* The features proposed for automatic completion include all features of the class: those declared in the class itself, or <span>immediate</span> features, and those <span>inherited</span> from proper ancestors, direct or indirect, with one exception: by default the list will not include features from the universal class <code> ANY </code>, which serves as ancestor to all classes and provides many features for comparison, copying, input-output, reflection etc. Including <code> ANY's </code> features would clutter all menus with too many features. So for example typing <code> i </code> followed by CTRL-SPACE will not suggest <code> io </code> among the possible completions. You can change this policy through Preferences. The policy does not apply to remote feature completion for an entity <code> x </code> declared of type <code> ANY </code> : typing CTRL-SPACE after <code> x </code> <span>. </span> will produce the list of <code> ANY </code> 's features.
==Using your own editor==
You may have a favorite editor and prefer to use it, at least in some cases. The EiffelStudio incremental compilation mechanism, to be studied shortly, recognizes that files have been modified outside of EiffelStudio (by checking their time stamps) and will without any fuss take their modified versions into account.
You can also call an outside editor on a class from within EiffelStudio. Just use <code> File </code> <code> --> </code> <code> External editor </code> or the corresponding button in the top toolbar.
This will call the editor of your choice. The default is Notepad on Windows and Vi on Unix and Linux. You can easily change this to any editor by entering the desired editor command in <code> Tools </code> <code> --> </code> <code> Preferences </code> <code> --> </code> <code> Global Preferences </code>. In this command text you can use the two special notations <code> $target </code> and <code> $line </code> ; when EiffelStudio calls the selected command, it will replace any occurrence of <code> $target </code> by the name of the file where the current class resides, and <code> $line </code> by the line number at which the Editing Tool is currently scrolled. If you include one or both of these markers at the appropriate argument positions for the command, this will enable you -- assuming the editor supports the appropriate options -- to make sure it starts at exactly the right place. For example the default editor command under Unix is
<code>
vi +$line $target</code>
meaning: start the Vi editor on the <code> $target </code> file, initially positioned at line <code> $line </code> (the <code> + </code> <code> line_number </code> command-line option of Vi directs it to start at line <code> line_number </code> ).
If you start an external editor on a class, then exit the editor after possibly making changes, EiffelStudio will immediately update the class text in the Editing Tool. More generally, note that EiffelStudio will detect changes made separately on the same class, and warn you of possible conflicts.
Several important text editors from various providers have '''Eiffel modes''', which support the syntax-directed editing of Eiffel texts. They include:
* <span>Vim</span>, for Vi iMproved, an extension of Vi available on both Unix/Linux and Windows -- see www.vim.org
* <span>Emacs</span> -- see www.emacs.org.
* <span>Editeur</span>, a Windows syntax highlighting editor -- see www.studioware.com.
</div></div>
[[10 RETARGETING THROUGH PICK-AND-DROP|<< Previous]] [[12 HANDLING SYNTAX AND VALIDITY ERRORS|Next >>]]

162
documentation/current/eiffelstudio/eiffelstudio-guided-tour/retargeting-through-pick-and-drop.wiki Normal file
View File

@@ -0,0 +1,162 @@
[[Property:title|10 RETARGETING THROUGH PICK-AND-DROP]]
[[Property:link_title|Retargeting Through Pick-and-Drop]]
[[Property:weight|-5]]
[[Property:uuid|a3789781-153b-7f4d-bb94-4bdf8923fb56]]
You now know quite a few ways of re-targeting a Development Window to a "development object" -- a class or a feature -- but haven't yet seen one of the most important: "Pick-and-Drop", which lets you pick a development object that you have spotted anywhere in the display, and retarget the current tool, or another, to it.
<div>
==Trying Pick-and-Drop==
We restart from the last state, with a Development Window target to feature <code> forth </code> of class <code> LIST </code>. The next figure shows the whole window; it should be exactly what you see as a result of the last operations. We'll use the <code> Ancestor versions </code> view of the <code> Feature </code>Tab.
If for some reason the window doesn't look like the next figure, it's easy to reconstruct it: make sure both the Cluster tree and the Feature tree are visible (if not, click the corresponding buttons as detailed [[7 CLASS VIEWS|here]] ); target the tool to class <code> LIST </code> ; target further to its feature <code> forth </code> by clicking that feature name in the Feature tree; make sure both the top-right Editing Tool and the bottom-right Context Tool are visible; in the Context Tool, select the <code> Feature </code> Tab and its <code> Descendant versions </code>format.
<div> [[Image:index-60]] [[general/guided_tour/studio/index-60.png|(link)]] </div>
In the Context Tool near the bottom right, there is an entry that reads
<code>
ARRAYED_CIRCULAR forth
</code>
referring to the version of feature <code> forth </code> in class <code> ARRAYED_CIRCULAR </code>. Let's assume you want to see what that version actually is. It suffices to retarget the tool to it. Of course you could type or copy-paste the class name <code> ARRAYED_CIRCULAR </code> in the Class field at the top of the window, and the feature name <code> forth </code> in the adjacent Feature field. But this is too much work; after all, you have just seen a reference to the feature, through its name as it appears in the Descendant version format, so it's natural to use it directly from the graphical interface.
As we've seen before, you could control-right-click on the feature name at the place where it appears; this would create a new Development Window targeted to <code> forth </code> from <code> ARRAYED_CIRCULAR </code>. But you don't necessarily want a new window. Instead you can use Pick-and-Drop to retarget the current window.
Here is how it works. Position the cursor on the desired feature reference: the word <code> forth </code> in the line <code> forth ARRAYED_CIRCULAR </code>. Right-click, that is to say click the rightmost mouse button, and '''release the button immediately'''. That's right: you use a simple click, and do '''not''' maintain the button down.
Now move the mouse a trifle, <span>without pressing any button</span> :
<div> [[Image:index-61]] </div>
The cursor has changed into a new shape, a cross representing the type of development object that you have picked, a feature. For a class, as you may have guessed, it would be a small ellipse ("bubble"). Each kind of development object that you may create and manipulate during your work with EiffelStudio has its distinctive icon.
The display reflects that you have " <span>picked</span> " the feature <code> forth </code>. Now you can <span>drop</span> it at any appropriate place to retarget the corresponding tool. In fact you can drop it right where it is, in the Context Tool of the current Development tool. To drop, just '''right-click''' again. (That is to say, as before, press the rightmost mouse button and release it immediately.) This achieves a "drop", and retargets the Development Window to the chosen feature, <code> forth </code> from <code> ARRAYED_CIRCULAR </code>. The retargeting affects both the Editing Tool and the Context Tool (assuming the Link Content View option is selected on the toolbar, see below "Isolating the context" for more information), which keeps its current view ( <code> Descendant versions </code> in the <code> Feature </code> Tab). We'll see shortly how to give them separate targets if that's preferred.
<div> [[Image:index-62]] [[general/guided_tour/studio/index-62.png|(link)]] </div></div><div>
==How Pick-and-Drop works==
The Pick-and-Drop mechanism is very simple. It consists of three steps:
* '''Pick''' step: find the development object you want to pick, right-click it, release the mouse button.
* '''Move''' step: move the mouse to the desired drop point, <span>without pressing any button</span>.
* '''Drop''' step: right-click (again releasing the button immediately) at the drop position.
During the Move step, you can at any time '''cancel the whole operation''' simply through a '''left-click'''.
The Move step is actually optional: if the current position is a valid drop target, as explained next, you can drop immediately after the pick without moving the mouse.
</div><div>
==Pebbles, holes, drop targets and type compatibility==
The Pick-and-Drop mechanism relies on the metaphor of '''pebbles and holes'''. When you pick a development object, the cursor changes into a "pebble" whose shape represents the type of the development object: cluster, class, feature, run-time object <span>...</span> You may then drop it into a "hole", which can be a window, a tree view entry, or a hole-shaped icon. This performs the appropriate action such as retargeting a tool.
In the same way that Eiffel is a typed object-oriented language, the Pick-and-Drop mechanism is typed: you can only drop a pebble into a compatible hole. For example you may drop a class pebble into a Development Window, to retarget it to the chosen class.
In Eiffel, type compatibility is not necessarily type identity, but is governed by <span>conformance</span>, based on inheritance and polymorphism: to an entity of type <code> POLYGON </code>, you may assign not only an expression of that same type, but also one of type <code> RECTANGLE </code>, if class <code> RECTANGLE </code> inherits from -- conforms to -- class <code> POLYGON </code>. Similarly, EiffelStudio considers that the development type "feature" conforms to "class"; this means you may drop a feature into a Development Window targeted to a class; this will retarget the tool to the feature's class and the feature itself, with the text of the class scrolled to the position of the feature.
In the Pick-and-Drop example -- for <code> forth </code> of <code> ARRAYED_CIRCULAR </code> -- you did not have to go to a new target: the current window was a valid drop target, so you just dropped right away. In such a case you don't even have to move the mouse; Pick-and-Drop is just a matter of two right-clicks.
This is similar to a '''double-click''', a commonly used interaction technique, but without the stress of the usual double-click, which requires you to wait no more than a specified time -- typically half a second or so -- between the two clicks. With Pick-and-Drop the effect is the same whether the second click follows the first after one tenth of a second or two days.
</div><div>
==Multiple tools==
In the previous example we pick-and-dropped a feature to its own tool. You can also pick-and-drop to a different tool.
Try this now. Bring up a new Development Window by choosing the menu entry <code> File </code> <code> --> </code> <code> New window </code> (unless you already have a second Development Window open, in which case you can simply reuse it). Make sure the two Development Window do not overlap too much, so that you can see enough of each. In the first Development Window, pick a class (right-click it). Move the mouse to the Editing Tool of the second Development Tool. Drop the class by right-clicking again. The tool retargets itself to the chosen class.
Many people like to take advantage of this possibility to keep two or more Development Windows open, and pick-and-drop frequently from one to the other when they see a development object of interest and want to know more about it, without losing its original context.
</div><div>
==Clickable formats==
A good deal of the power of Pick-and-Drop comes from its connection with the various views of the Context Tool -- Class Views, Feature Views, Diagram View. As was mentioned when we saw these views, all the feature and class names or other graphical representations that appear in these views are '''clickable''' ; this means that you can select any of them as the source of a Pick-and-Drop.
As a result, you can quickly traverse a system and get to its essential properties by displaying the information of a class in any of the many available views -- the contract and flat contract of a class, its routines, its attributes, its clients, its ancestors, the ancestor and descendant versions of a feature, and so on -- then wherever you see a feature or class name follow the corresponding link. This '''proximity-based''' form of browsing, combined with the other techniques seen earlier, provides considerable help when you are dealing with a large, possibly complex system, and want to master its intricacies, be it for development, testing, debugging, maintenance or revision.
Other places where you can pick development objects include the class bubbles in a Diagram View, and the icons representing classes and features in the Cluster Tree, Feature Tree and Favorites list.
</div><div>
==Semantic consistency==
An important property of the pick-and-drop mechanism, shared by its cousin the right-click mechanism, has already been mentioned in this chapter: semantic consistency, which guarantees that the operations you can perform on a class, such as pick-and-drop, only depend on the <span>development object</span> to which you are applying the operation. It doesn't matter where you picked the object -- in any development tool under any view -- and in what form: textual, as a class or feature name; graphical representation, as a class bubble in a Diagram View; or an icon, for example in the Cluster Tree, Feature Tree, Favorites list.
The pebble that you see during the Move step of Pick-and-Drop represents the underlying development object -- such as a class or a feature -- regardless of how you got to it.
</div><div>
==Behind the Pick-and-Drop conventions==
Pick-and-Drop works differently from the usual Drag-and-Drop present on many computing platforms. The usual Drag-and-Drop retains a role within EiffelStudio (to move class bubbles around in the Diagram view) and you may of course have to use it for operating system functions such as copying files. But the key EiffelStudio operation is Pick-and-Drop. This technique is motivated by careful consideration of ergonomics and user comfort. In particular:
* Pick-and-Drop is much less stressful. Drag-and-Drop requires you to maintain pressure throughout the move, being careful not to drop on the wrong place. With Pick-and-Drop there is no stress: you click and release; get a drop from your coffee cup if you like (optional step); move the cursor with no pressure from your fingers or on your mind; make sure, at your leisure, to find the right drop place; and right-click again on it. At the end of the day, after many such operations, the stress reduction can make a real difference.
* With Drag-and-Drop, it's easy to lessen the pressure involuntarily and drop on the wrong place. The consequences can be damaging, especially since in such a case you may well <span>not know</span> where you dropped the element; after all, that wasn't intentional. It is possible, for example, to lose files that way. With Pick-and-Drop this is much less likely to happen.
* Pick-and-Drop makes it easy to cancel the operation if you change your mind: just left-click anywhere. With Drag-and-Drop you have to find an invalid place to drop; this may be difficult, or even impossible! (Sometimes pressing the Escape key works, but this is not universal.)
If you are new to EiffelStudio you may find Pick-and-Drop surprising at first. We trust you will join the ranks of EiffelStudio users who consistently rate it among the most convenient features of the environment.
</div><div>
==Isolating the context==
In all the examples so far, the Context Tool was targeted to the same target as the enclosing Development Window and its Editing Tool. You can retarget the Context Tool separately, for example by pick-and-dropping a class or feature into it; but the next time you retarget the Development Window as a whole the Context Tool will follow.
This is called <span>linked</span> behavior, meaning that the target if the Context Tool is linked with the target of the enclosing Development Window and Editing Tool. By default the tools are not linked.
This enables you to see, in the same window, information on two different classes, and is called <span>isolating, </span> or <span>unlinking</span> the Context.
The choice between linked and isolated behavior is a matter of taste; let's see how you can change it, so that you can set your own preference.
To change the behavior, choose the menu entry
<code>
View --> Link context tool</code>
After this, the entry will change to <code> View </code> <code> --> </code> <code> Unlink context tool </code>, so that you can later revert to isolated behavior. Under isolation behavior, try pick-and-dropping a class or feature into the top Editing Tool; then pick-and-drop a class or feature into the bottom Context Tool. You will notice that each of these operations retargets the affected tool, but not the other.
</div><div>
==Customizing the view==
If you will often alternate between the linked and isolated behaviors, you can use the <code> Link/Isolate </code> button of the top toolbar. This button is <span>not</span> present by default on the toolbar, so this is a good opportunity to take a quick look at the user interface customization mechanism, which you can use later to tailor the interface to the exact form you need. Select
<code>
View --> Toolbars --> Customize standard toolbar</code>
(The adjacent entry is <code> toolbar project Customize </code> which provides complementary capabilities under a similar form.) You see a list of available buttons:
<div> [[Image:index-63]] [[general/guided_tour/studio/index-63.png|(link)]] </div>
The icons in the list on the right are currently displayed in the toolbar, but not those on the left. Among the latter you see (fourth from the bottom on the left-side list) <code> Link or not the context tool to other components </code>. Select it by clicking; this makes the <code> -> Add </code> button active. Click this button to move the Link/Isolate icon to the list of displayed icons. It becomes the first item of the list, which is fine for the moment. (Later on you can change the order of buttons in the toolbar if you like, by using the <code> Up </code> and <code> Down </code> buttons.) Click <code> OK </code>. The toolbar of your development tool has a new button which you can now use to switch, for the enclosing Development Window, between the isolated and linked behaviors of the Context Tool.
</div>
==Context memory==
If you start repeatedly retargeting the Context Tool -- especially under "isolated" behavior -- you will notice the following properties:
* In most cases, pick-and-dropping a <span>class</span> to the Context switches the view to the <code> Class </code> Tab, and pick-and-dropping a <span>feature</span> switches to the <code> Feature </code> Tab.
* The view displayed in each case -- for example <code> Ancestors </code> for the <code> Class </code> Tab and <code> Flat </code> for the <code> Feature </code> Tab -- is default view for the corresponding Tab.
==The many paths to retargeting==
As a conclusion to this review of Pick-and-Drop let's recapitulate the various ways we've seen for retargeting a whole Development Window or a tool to a class:
{|
|-
| '''How to retarget'''
| '''Same window/tool, or new?'''
| '''Where described'''
|-
| Type class name, then Enter, in class field at top-left of tool
| Same
| [[6 STARTING TO BROWSE|"Retargeting by name" in Chapter 6, "Starting To Browse".]]
|-
| Choose class in Cluster tree
| Same
| [[6 STARTING TO BROWSE|"Retargeting from the Cluster Tree" in Chapter 6, "Starting To Browse". ]]
|-
| Choose class in Favorites
| Same
| [[6 STARTING TO BROWSE|"Adding to Favorites" in Chapter 6, "Starting To Browse".]]
|-
| "Back" button
| Same
| [[6 STARTING TO BROWSE|"Moving back and forth" in Chapter 6, "Starting To Browse".]]
|-
| "Forth" button
| Same
| [[6 STARTING TO BROWSE|"Moving back and forth" in Chapter 6, "Starting To Browse".]]
|-
| Pick class from history list
| Same
| [[6 STARTING TO BROWSE|"The Target History" in Chapter 6, "Starting To Browse".]]
|-
| Pick-and-drop: right-click on class name or graphical representation found in any tool, then move, then right-click
| Existing window/tool (of drop target)
| [[10 RETARGETING THROUGH PICK-AND-DROP|"How Pick-and-Drop works" In Chapter 10, "Retargeting Through Pick-and-Drop.]]
|-
| Control-right-click on class name or graphical representation found in any tool
| New
| [[6 STARTING TO BROWSE|"Starting a new tool" in Chapter 6, "Starting To Browse".]]
|}
[[9 BROWSING FEATURES|<< Previous]] [[11 RECOMPILING AND EDITING|Next >>]]

24
documentation/current/eiffelstudio/eiffelstudio-guided-tour/starting-browse.wiki
View File

@@ -29,9 +29,13 @@ Whether you have one Development Window or many, each may have as its '''target'
==Retargeting by name==
Our first example screen was targeted to the whole system. To retarget it to a particular class, you can just type the class name -- if you know it -- into the Class Field at the top left:
<div> [[Image:index-9]] [[general/guided_tour/studio/index-9.png|(link)]] </div>
[[Image:index-9]]
Let's use one of the most basic classes, <code> ARRAY </code> from the Kernel Library of EiffelBase. Bring the cursor to the Class Field, click to make it active, type <code> array </code> (or <code> ARRAY </code> ) and the Enter key. As shown on the next figure, this retargets the tool to class <code> ARRAY </code>. Note that you didn't have to worry about where the class resides in the files of your computer. Also, the Class Field will now show the target's class name, <code> ARRAY </code>, in upper case, since that is the standard Eiffel convention for class names. It doesn't matter, when you enter the name into the field, whether you use lower or upper case, or some mix; EiffelStudio will show the name back in all upper case.
<div> [[Image:index-10]] [[general/guided_tour/studio/index-10.png|(link)]] </div>
[[Image:index-10]]
The Development Window is now targeted to class <code> ARRAY </code>. Each of the four panes contains a tool:
* Features Tree, top-left: a tree view of all the features of the class, grouped by the feature categories ( <code> Initialization </code>, <code> Access </code>, <span>...</span> ) as they appear in the class.
* Editing Tool, top-right: the source text of the class, editable. For the moment the pane is too small to display much of interest -- it only shows the very first few lines -- but we'll enlarge it when we need to modify class texts. (Not <code> ARRAY </code>, though, as it's not the kind of class you want to change during your first session with EiffelStudio, so just wait a bit.)
@@ -41,17 +45,21 @@ The Development Window is now targeted to class <code> ARRAY </code>. Each of th
==A peek at diagram==
There's indeed a lot in the Context Tool, too much to see right now, but to feed our curiosity let's just take a peek at the Diagram View. Click the <code> Diagram </code> Tab at the bottom:
[[Image:index-11]]
This displays a class diagram in the Context Tool:
[[Image:index-12]]
{{note| ''If nothing appears in the Context Tool when you click the Diagram Tab, that's because the Context Tool and the Class View are not linked. Linking the two tools together will ensure that whenever a change is made in one tool the other will update to reflect that change. To link the tools select the menu entry '' <code> View </code> <code> --> </code> <code> Link context tool </code> ''; this will display the diagram as shown. We'll see the explanation for this behavior in '' [[10 RETARGETING THROUGH PICK-AND-DROP| ''Isolating the context, pg 68'' ]] }}
The diagram is cropped to the available area; to get the whole picture, resize the window from the bottom-right corner. You can now see the inheritance structure:
[[Image:index-13]]
The red arrows show <span>inheritance</span> relations: <code> STRING </code> inherits from <code> INDEXABLE </code> and so on. We'll see later how to display the other key inter-class relation, <span>client</span>, but it's not particularly interesting for <code> STRING </code>. The default placement of the classes is quite good in this case, but if you don't like it you can change it; your changes will be retained the next time you bring up this diagram, in this session or a later one. (That's part of the information the <code> Diagram </code> directory keeps.) It will also be used in Web diagrams if you choose to generate an HTML form. To move a class bubble, just use standard drag-and-drop. For example you may move everything to the left and make the figure more compact:
[[Image:index-14]]
Later on you will learn how to use the Diagram View not just to display system structures graphically but also to build and modify systems. EiffelStudio indeed integrates the functionality of a CASE (Computer-Aided Software Engineering) workbench, seamlessly integrated with the programming facilities. But for the moment this peek at the Diagram View is enough, so let's get back to browsing.
@@ -59,22 +67,27 @@ Later on you will learn how to use the Diagram View not just to display system s
==Retargeting from the Cluster Tree==
Your first browsing action used a class of which you knew the name, <code> STRING </code>. What if you don't know what's in the system and want to explore it? Among other techniques, you can let the Cluster Tree, in the Cluster Tool at the bottom left of the Development Window, guide you through the system's structure:
<div> [[Image:index-15]] [[general/guided_tour/studio/index-15.png|(link)]] </div>
[[Image:index-15]]
An Eiffel system, as you know, is organized into clusters and libraries (and assemblies on some .NET systems), clusters can be structured hierarchically into subclusters. Here we see one cluster: <code> root_cluster </code>, containing the few classes specific to our Guided Tour system. There are also two libraries: <code>base</code> which provides the base classes and <code>precompile</code> which does not provide any classes directly (precompiles are present to speed up compilation time by precompiling classes). Let's go into <code> base </code>, ISE's open-source library of fundamental reusable mechanisms. Click the little <code> + </code> sign to the left of its name; this expands the clusters and libraries in the base library. Expand now the base cluster and you will see the its six subclusters: <code> event </code> for event handling, <code> kernel </code> for the Kernel Library, <code> refactoring </code> for help with refactoring, <code> serialization </code> for serialization, <code> structures </code> for the Data Structure Library, and <code> support </code> for additional supporting mechanisms.
[[Image:index-16]]
The most extensive of these EiffelBase libraries is <code> structures </code>, which contains implementations of major data structures and algorithms of computing science. Click the <code> + </code> next to <code> structures </code> to see its own subclusters:
[[Image:index-17]]
{{note| ''If you initially don't see as many details as shown on this figure, you may get them by resizing the window, moving the vertical pane boundary, and possibly scrolling.'' }}
The EiffelBase Data Structure library and its subclusters are described in the book <span> [http://www.eiffel.com/doc/ Reusable Software] </span>. Let's go to one of the most frequently used subclusters, <code> list </code>, containing implementations of list structures. Click the <code> + </code> next to <code> list </code>. This time, since list is a terminal cluster, it's not subclusters you'll see, but '''classes''', identified by small ellipses:
[[Image:index-18]]
The ellipse, or "bubble", is indeed throughout EiffelStudio, as in the Business Object Notation (BON, the underlying graphical convention), the distinctive symbol for classes; remember the larger bubbles showing classes in the Diagram View a few moments ago.
Our second technique for retargeting a Development Window to a class (other than typing the class name as we did before) is to click the class in the Cluster Tree. Do this now: click <code> LIST </code> in the tree. It doesn't matter whether you click on the class name or the adjacent bubble. This retargets the tool to class <code> LIST </code>. Because the Context Tool is still in <code> Diagram </code> view, it will display the inheritance structure for the new target class:
[[Image:index-19]]
While this view is being produced you may see (or just get a glimpse of, if your machine is fast) messages indicating that it's producing the diagram for <code> LIST </code>. In a moment we'll switch views in the Context Tool as we won't need the diagrams.
@@ -84,6 +97,7 @@ As the tool is now targeted to <code> LIST </code>, the Class Field at the top l
==Moving back and forth==
Here now is a third way to retarget. Towards the top-left part of the Development Window there are <code> Back </code> and <code> Forth </code> buttons, which will enable you to revisit classes already seen during the current session:
[[Image:index-20]]
Click the <code> Back </code> button. This retargets the tool to the class you visited previously: <code> STRING </code>. The <code> Forth </code> button, immediately to the right of <code> Back </code>, becomes active. Click it to retarget back to <code> LIST </code>.
@@ -93,6 +107,7 @@ Note that all buttons of the interface have a "tooltip": if you move the cursor
==The Target History==
As a fourth way to retarget -- there are more, and after this one we'll stop counting -- you can also use the Target History menu, which you can bring up through the little arrow to the right of the Class Field:
[[Image:index-21]]
If you click this arrow -- the little black triangle -- you will see a menu of all your recent targets. Doing this now will only show the two classes visited so far, <code> STRING </code> and <code> LIST </code>, but later on there will be more entries. By default EiffelStudio remembers 10 classes; this is one of the settings you can change later if you wish, through the menu <code> Tools </code> <code> --> </code> <code> Preferences </code>. (There's no point in doing this now.)
@@ -102,11 +117,13 @@ If you click this arrow -- the little black triangle -- you will see a menu of a
If you find yourself often needing to examine a particular class, you can add it to your "Favorites", similar to the favorites, also called <span>bookmarks</span>, which you use to retain interesting pages in a Web browser.
It's easy to add the current target -- currently, <code> LIST </code> -- to your Favorites. Do it now: go to the <code> Favorites </code> menu and select <code> Add to favorites </code>. Now display the favorites; one way is to go back to that same Favorites menu and select <code> Show favorites </code>. The Favorites Tool appears below the Cluster Tree:
[[Image:index-22]]
This also means one more way to retarget a Development Window: click a class in the Favorites Tool. <span>Two</span> ways actually, since even if you don't see the Favorites Tool the class will appear in the <code> Favorites </code> menu and you can select it there.
Right now we don't need the Favorites Tool, so you can get rid of it by either selecting <code> Hide favorites </code> in the <code> Favorites </code> menu or clicking the little Close icon at the top right of the Favorites Tool:
[[Image:index-23]]
==Starting a new tool==
@@ -114,6 +131,7 @@ Right now we don't need the Favorites Tool, so you can get rid of it by either s
With all the techniques seen so far, you were able to retarget the current Development Window to a new class. As noted, you may also wish to have two or more Development Windows targeted to different classes; this is useful to keep track of several things at once. A simple way to start a new tool on a class is to find the class somewhere in the interface and '''control-right-click''' it.
Here, for example, the editor lists <code> CHAIN </code>, as a parent of <code> LIST. </code> Go to that word and control-right-click it, that is to say, click with the rightmost button of the mouse while holding the CONTROL key on the keyboard. This starts a new Development Window, targeted to the chosen class, <code> CHAIN </code> :
[[Image:index-24]]
The place where we found the class <code> CHAIN </code> in the original tool (the one targeted to <code> LIST </code> ) was the bubble representing the class in the Diagram View. But that's just one possibility. A general principle of EiffelStudio is '''semantic consistency''' : when you want to work with a development object -- a class, a feature, a cluster -- you can grab it wherever it appears in the interface, and in whatever format it is displayed: you might have spotted it be in the Diagram View, in the text of a class in the Editing Tool, in the Cluster or Feature Tree, or in any of the class documentation formats that we will soon see; and the form under which you found it may be text -- the name of the class in a text document -- or some graphical representation, such as a class bubble in a diagram. These variants don't matter: if the class or other development object catches your fancy, you can do whatever operations make sense for it, such as Control-right-click to start a new development object targeted to it, or any of the other operations we'll see next.

13
documentation/current/eiffelstudio/eiffelstudio-guided-tour/viewing-classes.wiki
View File

@@ -1,6 +1,7 @@
[[Property:title|7 CLASS VIEWS]]
[[Property:link_title|Viewing Classes]]
[[Property:weight|-9]]
[[Property:uuid|78136af1-5d7a-f3d2-9619-17f4c0541f1e]]
[[Help reading the EiffelStudio Guided Tour|Help reading this manual]]
We haven't even looked at a class text yet, but it's important anyway to see how EiffelStudio provides you with numerous, complementary <span>views</span> of your software. The Context Tool is the primary place to look for such views.
@@ -16,7 +17,9 @@ You can get these panes back later by clicking the buttons in the toolbar or by
{{note| ''Another way to hide a pane is to click on the button in the toolbar or by unselecting them in the View, Tools Menu.'' }}
Two panes remain, showing the Editing Tool and the Context Tool.
<div> [[Image:index-26]] [[general/guided_tour/studio/index-26.png|(link)]] </div>
[[Image:index-26]]
Make sure the Context Tool pane is large enough; you can resize the window and, if necessary, narrow down the Editing Tool pane since we don't need it for the moment. Don't worry, though, if the Context Tool shows only part of the diagram, as it does on the last figure, since we will now use the Context Tool to display information other than the diagram, by selecting the corresponding tabs.
==The Class Tab==
@@ -26,13 +29,17 @@ The first tab we'll look at is the Class Tab. You'll find it at the bottom of th
This gives you access to many forms of information about the current class -- the target of the Development Window. A set of buttons at the top of the Context Tool enables you to display a number of '''views''' of the class. The currently highlighted button indicates the default view: <code> Ancestors </code>. You can see the others' names by moving the cursor over the various view icons, '''without clicking''', and reading the tooltips.
The view currently displayed, <code> Ancestors </code>, shows the inheritance structure that leads to the current target, <code> LIST </code> :
<div> [[Image:index-29]] [[general/guided_tour/studio/index-29.png|(link)]] </div>
[[Image:index-29]]
This shows that <code> LIST </code> is an heir of <code> CHAIN </code> which itself, as an example of multiple inheritance, is an heir of <code> CURSOR_STRUCTURE </code>, <code> INDEXABLE </code>, and -- twice, as an example of <span>repeated</span> inheritance -- <code> SEQUENCE </code>. 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 <code> BAG </code>, <code> ACTIVE </code> 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.
Next to <code> Ancestors </code> button is <code> Descendants, </code>which will give you the descendants of a class in a similar format:
[[Image:index-30]] [[general/guided_tour/studio/index-30.png|(link)]]
[[Image:index-30]]
The progeny of <code> LIST </code>, 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, <code> Clickable </code>, 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:

2
documentation/current/method/eiffel-tutorial-et/index.wiki
View File

@@ -6,8 +6,6 @@
[[MANUAL IDENTIFICATION AND COPYRIGHT: Tutorial|MANUAL IDENTIFICATION AND COPYRIGHT]]
{{note|This is '''not''' an introduction to the EiffelStudio development environment. See the [[Getting started with Eiffel|list of introductory documents]] for a Guided Tour of EiffelStudio and a detailed Eiffel Tutorial. }}
==[[1 Overview|1 OVERVIEW]]==
==[[2 General Properties|2 GENERAL PROPERTIES]]==

10
documentation/current/solutions/basic-computing/index.wiki Normal file
View File

@@ -0,0 +1,10 @@
[[Property:title|Fundamental computing and data structures]]
[[Property:link_title|Basic computing]]
[[Property:weight|-15]]
[[Property:uuid|be2b9c40-f2ff-d6dc-738d-b240deb69407]]
* EiffelBase
**EiffelBase Tutorial http://ise181.ise/book/documentation/eiffelbase
**EiffelBase class reference
**EiffelBase samples http://ise181.ise/book/documentation/eiffelbase-samples

9
documentation/current/solutions/dates-and-times/index.wiki Normal file
View File

@@ -0,0 +1,9 @@
[[Property:title|Date and time manipulation]]
[[Property:link_title|Dates and times]]
[[Property:weight|-13]]
[[Property:uuid|082fd8e1-b531-6cf1-3409-9cd9bc6483ad]]
* Date and time manipulation
** EiffelTime
*** EiffelTime tutorial http://ise181.ise/book/documentation/eiffeltime
*** EiffelTime class reference

15
documentation/current/solutions/gui-building/index.wiki Normal file
View File

@@ -0,0 +1,15 @@
[[Property:title|Graphical user interfaces]]
[[Property:link_title|GUI building]]
[[Property:weight|-14]]
[[Property:uuid|df3cec75-5fe4-7b6b-c5f3-f07932857e70]]
* Graphical user interfaces
** EiffelBuild http://ise181.ise/book/documentation/eiffelbuild-introduction
*** EiffelBuild How To's http://ise181.ise/book/documentation/eiffelbuild-how-tos
*** EiffelBuild Reference http://ise181.ise/book/documentation/eiffelbuild-reference
** EiffelVision 2 http://ise181.ise/book/documentation/eiffelvision-2-library
*** EiffelVision 2 introduction http://ise181.ise/book/documentation/eiffelvision-introduction
*** EiffelVision 2 tutorial http://ise181.ise/book/documentation/eiffelvision-interface-content
*** EiffelVision 2 class reference
*** EiffelVision 2 samples http://ise181.ise/book/documentation/eiffelvision-2-samples

81
documentation/current/solutions/index.wiki Normal file
View File

@@ -0,0 +1,81 @@
[[Property:title|Solutions]]
[[Property:weight|-8]]
[[Property:uuid|0f0913fe-d71c-43d3-6c22-706c8ed5d4ad]]
== Eiffel Solutions, Technologies, and Class Libraries ==
Provide content on the technologies Eiffel applies to solve common computing needs and, where applicable, the libraries and/or samples that support the technologies
{{note|
* The emphasis is primarily on needs of developers, then on Eiffel's offerings to satisfy those needs.
* Items are ordered based on an intuitive assessment of likelihood of need.
* Most items labelled "tutorial" are those that were labelled "content" in the existing online documentation.
}}
* Fundamental computing and data structures
** EiffelBase
*** EiffelBase Tutorial http://ise181.ise/book/documentation/eiffelbase
*** EiffelBase class reference
*** EiffelBase samples http://ise181.ise/book/documentation/eiffelbase-samples
* Graphical user interfaces
** EiffelBuild http://ise181.ise/book/documentation/eiffelbuild-introduction
*** EiffelBuild How To's http://ise181.ise/book/documentation/eiffelbuild-how-tos
*** EiffelBuild Reference http://ise181.ise/book/documentation/eiffelbuild-reference
** EiffelVision 2 http://ise181.ise/book/documentation/eiffelvision-2-library
*** EiffelVision 2 introduction http://ise181.ise/book/documentation/eiffelvision-introduction
*** EiffelVision 2 tutorial http://ise181.ise/book/documentation/eiffelvision-interface-content
*** EiffelVision 2 class reference
*** EiffelVision 2 samples http://ise181.ise/book/documentation/eiffelvision-2-samples
* Date and time manipulation
** EiffelTime
*** EiffelTime tutorial http://ise181.ise/book/documentation/eiffeltime
*** EiffelTime class reference
* Interacting with software in other languages Put a reference to .NET and COM, as well as to external features syntax -Kwaxer 9/16/08 7:47 PM
** C externals tutorial http://ise181.ise/book/documentation/c-externals
** C++ externals tutorial http://ise181.ise/book/documentation/c-externals-0
** CECIL tutorial http://ise181.ise/book/documentation/cecil
** Eiffel2Java http://ise181.ise/book/documentation/eiffel2java
*** Eiffel2Java tutorial http://ise181.ise/book/documentation/eiffel-java-interface
*** Eiffel2Java class reference
*** Eiffel2Java samples http://ise181.ise/book/documentation/eiffel2java-sample
* Platform porting of applications http://ise181.ise/book/documentation/porting-instructions
** Porting from Unix to Windows or vice versa http://ise181.ise/book/documentation/porting-eiffel-application-unix-windows-or-vice-versa
* Multi-threading
** Threads tutorial http://ise181.ise/book/documentation/threads
** EiffelThread class reference
* Network communication
** EiffelNet http://ise181.ise/book/documentation/eiffelnet-library
*** EiffelNet tutorial http://ise181.ise/book/documentation/eiffelnet
*** EiffelNet class reference
*** EiffelNet samples http://ise181.ise/book/documentation/eiffelnet-samples
** cURL library？ -Larryliuming 08-9-16 下午11:46
* Database access
** EiffelStore http://ise181.ise/book/documentation/eiffelstore-library
*** EiffelStore introduction http://ise181.ise/book/documentation/eiffelstore-introduction
*** EiffelStore tutorial http://ise181.ise/book/documentation/eiffelstore-content
*** EiffelStore class reference
*** EiffelStore samples http://ise181.ise/book/documentation/eiffelstore-samples
* Web CGI forms processing
** EiffelWeb http://ise181.ise/book/documentation/eiffelweb-library
*** EiffelWeb tutorial http://ise181.ise/book/documentation/eiffelweb-content
*** EiffelWeb class reference
*** EiffelWeb samples http://ise181.ise/book/documentation/eiffelweb-sample
* Text processing (Lexical analysis and parsing)
** EiffelLex http://ise181.ise/book/documentation/eiffellex-library
*** EiffelLex tutorial http://ise181.ise/book/documentation/lexical-analysis-lex-library
*** EiffelLex class reference
*** EiffelLex samples http://ise181.ise/book/documentation/lex-sample
** EiffelParse http://ise181.ise/book/documentation/eiffelparse-library
*** EiffelParse tutorial http://ise181.ise/book/documentation/parsing-parse-library
*** EiffelParse class reference
*** EiffelParse samples http://ise181.ise/book/documentation/parse-sample
* Application preferences management
** EiffelPreference http://ise181.ise/book/documentation/eiffelpreference-library
*** EiffelPreference tutorial http://ise181.ise/book/documentation/preference-library
*** EiffelPreference class reference
*** EiffelPreference samples http://ise181.ise/book/documentation/preferences-sample

15
documentation/current/solutions/other-languages/index.wiki Normal file
View File

@@ -0,0 +1,15 @@
[[Property:title|Interacting with other languages]]
[[Property:link_title|With other languages]]
[[Property:weight|-12]]
[[Property:uuid|6029d6d9-bb73-5c74-02f6-70d202a65ceb]]
== Interacting with software in other languages ==
{{note|Put a reference to .NET and COM, as well as to external features syntax -Kwaxer 9/16/08 7:47 PM }}
** C externals tutorial http://ise181.ise/book/documentation/c-externals
** C++ externals tutorial http://ise181.ise/book/documentation/c-externals-0
** CECIL tutorial http://ise181.ise/book/documentation/cecil
** Eiffel2Java http://ise181.ise/book/documentation/eiffel2java
*** Eiffel2Java tutorial http://ise181.ise/book/documentation/eiffel-java-interface
*** Eiffel2Java class reference
*** Eiffel2Java samples http://ise181.ise/book/documentation/eiffel2java-sample