@database "Manual.guide" @author "Thomas Aglassinger" @remark "$VER: Manual.guide 2.1 (10.1.00)" @node MAIN "Eiffel/Sofa Mode for GoldEd Studio 6" @{b}Eiffel/Sofa Mode for GoldEd Studio 6@{ub} @remark @{b}WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING@{ub} @remark @remark This is a preliminary release. I'm pretty sure that most things work @remark without causing any damage (at least not more than the last release). @remark However, some parts of the manual are outdated. And the installation @remark might not work (though it should). Send bug reports to the author. @remark @remark The official release should happen soon, so don't play hero unless you @remark are a developer. @remark @remark @{b}WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING@{ub} About @{" Copyright " link "forum.txt/MAIN"} - Freeware @{" Requirements " link REQUIREMENTS} - What else you need @{" Installation " link INSTALLATION} - Installer script rulez Usage @{" Syntax parser " link SYNTAXPARSER} - Say it with colors @{" Scanner " link SCANNER} - Who's there? @{" Toolbar " link TOOLBAR} - Only one mouse-click away @{" Templates " link TEMPLATES} - Lazy is beautiful @{" Mouse'n'browse " link MOUSE} - Can I click it? Miscellaneous @{" Support " link SUPPORT} - Where to get updates @{" Advanced topics " link ADVANCED} - Some internals @{" Known problems " link PROBLEMS} - Watch out @{" Future " link FUTURE} - Things to come @{" History " link HISTORY} - Sofa, so good Copyright 1999 Thomas Aglassinger and others, see file @{" forum.txt " link "forum.txt/MAIN"} @endnode @remark @node COPYRIGHT "Copyright" @remark @remark GedEiffel is Copyright © 1999 Thomas Aglassinger. All rights reserved. @remark @remark GedEiffel is freely distributable as long the archive and its contents @remark remain unchanged, no data are added and no data are removed. @remark @remark You use it at your own risk. No responsibilities are taken for trashed @remark sources, damaged Amigas or any other components or data involved while @remark using GedEiffel. @remark @remark @endnode @node REQUIREMENTS "Requirements" Most of the ARexx scripts included use the "rexxdossupport.library", Copyright © Harmut Goebel and available from Aminet in util/rexx/rexxdossupport.lha. The Sofa distribution of the freeware SmallEiffel compiler is available from http://www.owlnet.net/sofa/ or aminet:dev/lang/sofa.lha. GoldEd Studio is a commercial product and Copyright © Dietmar Eilert. For more information refer to http://members.tripod.com/golded/. @endnode @node INSTALLATION "Installation" To install the whole package, use the included Installer script. If you also want to use the scanner from outside the toolbar, you have to update the scanner configuration manually. To do that, select "Search/Show function list". Click on "Mode" and then on "+" to add a new scanner. Assign "GOLDED:etc/scanner/eiffel" to the filetype "*.e". @endnode @node SYNTAXPARSER "Syntax Parser" The syntax parser highlights syntax elements in different colors. The syntax parser highlights syntax elements in different colors. It conforms to the rules of chapter 26 of the book @{i}Object Oriented Software Construction@{ui} (2nd ed., 1997). A PDF version of this chapter should also be available from http://www.eiffel.com/. @{b}Comment@{ub} Beginning with two hyphens (--) and lasting until the end of the line, for example @{i}-- a comment@{ui} @{b}Comment (identifier)@{ub} References inside comments to identifiers in the source code. They have to be embedded between a backquote (`) and a single quote ('), for example @{i}-- Draw circle with center at (`x', `y') and radius `r'.@{ui} @{b}String@{ub} Text enclosed in double quotes ("), for example @{i}"hello"@{ui}. Character constants enclosed in single quotes (') are rendered in the same color. @{b}String (escape)@{ub} Escape sequences inside strings, starting with a percent sign (%), for example @{i}"%N"@{ui} for newline. @{b}String (trailer)@{ub} If strings go over several lines, every such line uses percent sign (%) as trailers, for instance "This is a long % %text going over % %several lines." As these trailers make it hard to read the actual text, it is recommended to "low-light" them in a color quote similar to the background color, for example a slightly darker gray. @{b}Warning@{ub} Used for some things that are possibly wrong, for example unterminated strings or unknown escape sequences. This is no complete check. You code might still contain various errors that prevent it being compiled. @{b}Naming violation@{ub} Names used for classes, routine and variables should conform to certain conventions, in particular letter case. Example violations are @{i}MixedCaseCompund@{ui} and @{i}_begins_with_underscore@{ui}. @{b}Spelling mistake@{ub} See @{"Known Problems" link PROBLEMS}. @{b}Keyword@{ub} Used for keywords of the language that play a strictly syntactic role, for example @{i}if@{ui}, @{i}feature@{ui} or @{i}invariant@{ui}. @{b}Reserved word@{ub} Used for reserved words that carry an associated semantics, for example @{i}Current@{ui}, @{i}Result@{ui}, @{i}True@{ui} and @{i}Unique@{ui}. (Note: The rule for some of these have changed since 1992, when @{i}Eiffel: The Language@{ui} was published. For example, @{i}True@{ui} was initially written @{i}true@{ui}.) @endnode @node SCANNER "Scanner" The scanner extracts names of features declared in a class. It takes into account all types (functions, procedures, attributes and constants) and all available features (including those exported to {NONE}). You can activate it from the @{"Toolbar" link TOOLBAR}, by selecting the menu item "Search/Function list..." or by pressing Amiga-/. (Technically speaking, the scanner takes into account lines with an indention level of three blanks or one tab. It then expects the line to either end with "is" or contain a colon (:)). @endnode @node TOOLBAR "Toolbar" The functionality provided by the toolbar depend on the view mode the source code is in: @{b}All modes@{ub} @{b}Make@{ub} Starts GoldEd command `PROJECT MAKE'. You can change the `make' macro in in the GoldEd dialog "Filetype/Projects/Details". @{b}Open class@{ub} Find file for class of the word the cursor currently is positioned over using `finder'. Then load it in new window. Note: Control-double-clicking a class name has the same effect. @{b}Open short form@{ub} Display short form of the class of the word the cursor currently is positioned over in new window. Note: Shift-double-clicking a class name has the same effect. @{b}Help@{ub} Views this manual. @{b}View as class@{ub} @{b}View as short form@{ub} Changes the view mode. The image for the current view mode is always ghosted. @{b}Only in Eiffel mode@{ub} @{b}Feature list@{ub} Invoke the @{"scanner" link SCANNER} to view a list of all features declared in the current source code. Features inherited from other classes are not shown. (Use the short form for that.) @{b}Reformat@{ub} Reformats the current source code editor using SmallEiffel's `pretty'. Note that different when calling `pretty' from the CLI, no ".bak" file is created as GoldEd offers more sophisticated backup and undo facilities. This avoids clutter in the source directory. @{b}Create new class@{ub} Ask for name of new class, create its file in the current directory. Then fill it with a template and load it into a new window. The class name must consist of letters, digits and underscores (_). Case does not matter, the automatically script uses lower case for the filename and upper case in the class source. The ".e" suffix also is appended automatically. See @{" Advanced topics " link ADVANCED} on modifying the template to fit your personal preferences. @endnode @node MOUSE "Mouse'n'Browse" Using qualifiers when double-clicking the source code, you can browse classes without having to leave the editor. This gives you a simple version of a seamless environment without a dedicated class browser. @{u}C@{uu}ontrol-double-click = Open @{u}c@{uu}lass @{u}S@{uu}hift-double-click = Open @{u}s@{uu}hort form @endnode @node TEMPLATES "Templates" You can use the following templates to speed up typing certain structures: @{b}dE@{ub} (debug instruction) debug("")... end @{b}fE@{ub} (feature heading) feature -- @{b}fR@{ub} (simple loop) from... until... loop... end @{b}fR@{ub} (loop) from... invariant... variant... until... loop... end @{b}iF@{ub} (conditional) if... then... end @{b}eL@{ub} else @{b}elI@{ub} elseif...then @{b}iN@{ub} (multi-branch) inspect... when... else... end @{b}iS@{ub} (routine declaration) is... require... local... do... ensure... end; Some common operations can be abbreviated as: @{b}pR@{ub} print () @{b}prI@{ub} print ("") @{b}++@{ub} increment first word of line. For instance, type index ++ ^ to get index := index + 1 This is for C wimps who have a panic fear of typing. Note the blank between "index" and "++". If you just type "index++", the template is not recognized. @{b}+=@{ub} prepare first word of to be incremented by some value. For instance, type index += 17 to get index := index + 17 See notes for "++". Note: Unlike in most other environments, you don't need any qualifier key like Alt or Control to use templates. This is possible because the Eiffel naming conventions forbid a lower case letter immediately preceeding an upper case letter. @endnode @node SUPPORT "Support" New versions will be uploaded to Aminet. Look for text/edit/envSOF*.lha You can contact the author at the following e-mail address: Thomas Aglassinger @endnode @node ADVANCED "Advanced Topics" @{b}New class template file@{ub} The file "GoldEd:add-ons/eiffel/new_class.e" contains the template for new classes created from the @{" toolbar " link TOOLBAR}. You can change it if you like, but remember to bump the version number to something huge (e.g. 50.0) so that it is not overwritten by the installer when updating the environment. You can use the following placeholders: %/CLASS/ insert name of the new class %/CURSOR/ position where the cursor should go to after loading %/DELETE/ marks line to be deleted (useful for comments) @remark @{b}New syntax parser keyword file@{ub} @remark @remark Most parts of the syntax parser are hard-coded, meaning that it @remark needs a change in its source code and a recompilation to make the @remark Eiffel source look different. @remark @remark The only exception of this are keywords. The parser reads them from @remark an external file you can specify in @remark "Filetype settings/Syntax Highlighting/Details/Arguments". The @remark structure of this file is as follows: @remark @remark · every line contains exactly one keyword @remark · lines beginning with "--" are ignored @remark · empty lines are ignored @remark @remark Furthermore, the whole file has to be sorted. White space at the @remark beginning or end of a line is not allowed. For example: @remark @remark -- some keywords @remark Precursor @remark True @remark end @remark if @remark then @remark @remark If the keyword file does not exist or not conform to the above @remark rules, the parser views an error messages and refuses to render @remark anything. For some examples keyword files, take a look at @remark "golded:add-ons/eiffel/syntax/". @remark @remark (In theory, the parser could easily remove white space and sort the @remark keywords by itself. In practice, this is a pain in the arse because @remark it is written in C. As this feature is rarely needed, I considered @remark the inferior usability acceptable.) @endnode @node PROBLEMS "Known Problems" @{b}Problems with the syntax parser@{ub} Some types syntax errors with multi-line strings are not highlighted as such. For instance, print("next line should start with % "but doesn't"); Spell checking is not enabled or documented because of several minor bugs. Numeric escape sequences are not highlighted, for example "%/65/". @{b}Problems with the scanner@{ub} GoldEd's reference functions don't work in any useful way because they support only a global name space, but Eiffel has an own name space for every class. I haven't found a way yet to make the scanner work with the quasi-Eiffel outputted by `short'. The main problem is that a scanner can see only one line of the source code at a time and does not have any context. Consider the following source excerpt: class HUGO creation make feature make is ... To avoid that `make' shows up twice, it has to check for the " is" at the end of the line. This works nice in the full source. In the short form however, the interface looks like this: class interface HUGO creation make feature(s) from HUGO make ... Finally, some indexing lines and invariants might show up as attribute declarations. Consider the following example: indexing hinz: kunz -- indexing field consisting of only one word class HUGO ... invariant valid_state: valid_state -- boolean query without parameters ... Here, `hinz' and `valid_state' show up in the feature list. All these issues can only be addressed by an improved scanner concept of GoldEd. @endnode @node FUTURE "Future" This is a list of ideas that might be implemented in future versions. · Cleanup and document spell checking. · Make syntax parser highlight routine declarations. · Make SmallEiffel use ARexx for sending error messages to editor. Most on the things mentioned below depend on my laziness and how a possible SmallEiffel/Sofa movement develops on Amiga. So don't hold your breath. @endnode @remark@node CONSOLE "Console_obsolete" @remark @remark @{b}The idea behind the SmallEiffel console@{ub} @remark @remark Many buttons from the @{"Toolbar" link TOOLBAR} invoke normal CLI commands like `make' @remark and `pretty'. Though GoldEd allows such commands to open a new console @remark to show their output, this is not very practical. Quickly one finds @remark himself closing the console all the time. @remark @remark The SmallEiffel mode uses a different mechanisms: all commands write @remark their output to the same console, named @{i}SmallEiffel Console@{ui}. Its window @remark title is SMALLEIFFEL.1. Basically, you do not have to bother about that @remark because everything is set up properly during installation. @remark @remark The only important thing to keep in mind is that the SmallEiffel @remark console is @{i}output only@{ui}. That means, although you can apparently enter @remark commands into it, they will never be executed. @remark @remark @{b}Specifying an alternative console window dimension@{ub} @remark @remark If you do not like the window dimension of the console, you can specify @remark your own by setting the environment variable @remark "env:Console/SMALLEIFFEL.1" with a proper console specification, for @remark example @remark @remark makedir env:Console @remark setenv Console/SMALLEIFFEL.1 "CON:0/0/400/200/SMALLEIFFEL.1/SCREEN**/AUTO/CLOSE/WAIT/INACTIVE" @remark @remark The "SCREEN**" will be descaped to "SCREEN*", which refers to the @remark frontmost screen (usually "Workbench" or "GOLDED.1"). For more details @remark on console specifications, refer to the AmigaDOS manual or check the @remark guide that comes with KingCON (available from Aminet). @remark @remark This is all you have to know for just using the console. Stop reading, @remark unless you want to get confused. @remark @remark @{b}How it works inside@{ub} @remark @remark For those how want to know what going in "inside", here's a more @remark detailed description: The whole effect described above is achieved by @remark two ARexx scripts: @remark @remark @{i}Console.rexx@{ui} kind-of is a CLI with an ARexx-port. It simply tries to @remark execute every message as a CLI command. However, after executing a @remark command, the console does not quit and close its window, but simply @remark waits for the next command. @remark @remark @{i}Execute.rexx@{ui} is used to send such a command to the SmallEiffel console. @remark @remark This might sound more complicated than it actually is. Consider the @remark following CLI invocation: @remark @remark run <>nil: rx >CON: golded:add-ons/eiffel/rexx/console.rexx Port=SMALLEIFFEL.1 @remark @remark This simply starts a console offering an ARexx port named @remark `SMALLEIFFEL.1'. Because of the `run' command, it runs as an own @remark process. Because of the redirection to CON:, it opens an own window for @remark the new console. Theoretically, you can now make it execute a command @remark like seen below: @remark @remark rx "address SMALLEIFFEL.1 'echo hello'" @remark @remark This executes the CLI command `echo hello' in the SmallEiffel Console, @remark and also shows its output in it: the word "hello". @remark @remark However, this is not the recommended way. Instead, use the following: @remark @remark rx golded:add-ons/eiffel/rexx/execute.rexx Port=SMALLEIFFEL.1 echo hello @remark @remark The main reason for that is that the above script always takes care @remark that the output console has the same current directory as the sending @remark console. Furthermore, it will even invoke console.rexx if no console is @remark already running at the requested port. And it takes care of the little @remark magic needed to read the Console/SMALLEIFFEL.1 environment variable. @remark @remark@endnode @node HISTORY "History" @{b}Version 2.1 10-Jan-2000@{ub} · Rewrote syntax parser. · Changed it to a context parser supporting the official generic keyword configuration. · Added support for multi-line string manifests (again). · Removed syntax highlighting for "Type name" and "Constant name". · Fixed some broken buttons in the "Eiffel (Short)" toolbar. · Removed some unneeded files from the distribution. @{b}Version 2.0, 13-Oct-1999@{ub} · Updated for GoldEd Studio 6. @remark · Fixed bug in syntax parser: also removed "false" from list of @remark keywords. · Added @{" Mouse'n'browse " link MOUSE} · Added detection of attributes and constants to @{" scanner " link SCANNER} @remark · Added support for syntax parser to read keywords from external @remark file. · Renamed `finder.ged' to `open_class.ged' · Renamed `short.ged' to `open_short.ged' · Renamed `pretty.ged' to `reformat.ged' · Changed `open_short.ged' so that is caches short forms in a relative file "sofa/short/.e". This was necessary because the online creation of short forms is too slow to be useful in practice. · Changed `open_short.ged' so that the created short form is read-only. · Changed `reformat.ged' so that it automatically removes the *.bak created by `pretty'. I found the backups cluttering the source directory annoying, especially because GoldEd supports more sophisticated backup and undo facilities anyway. · Changed copyright to @{" Eiffel Forum Freeware License " link "forum.txt/MAIN"} and included full source code. · Removed "execute.rexx" and "console.rexx" from the archive. Changed (open_class|open_short|reformat).ged so that they won't need them anymore. Now errors cause a new console to pop up. This sucks. But I think it sucks less than not seeing the errors at all. The only reasonable solution to this is a message browser. Which is not included with Sofa yet. This sucks, but hopefully might change in future. · Removed support for GoldEd 4. But you can still download an older version that provides the basic functionality of this environment for GoldEd 4 from aminet:text/edit/GedEiffel.lha. @{b}Version 1.2, 4-Mar-1999@{ub} · Fixed bugs in (finder|pretty|short).ged, which all were still referring to an old internal version of "execute.rexx" not being part of the distribution. · Fixed bugs in scanner: · @{i}frozen@{ui} is skipped · @{i}infix@{ui} and @{i}prefix@{ui} include succeeding operator name · comments ending with " is" are ignored · Fixed bugs in syntax parser: · Added syntax class "Reserved word" for @{i}Result@{ui}, @{i}Unique@{ui}, @{i}True@{ui} etc · Added keyword @{i}not@{ui} · Documented that one can shift-double-click a class name to load it. · Added screenshot (yeah, yeah, yeah!) @{b}Version 1.1, 25-Jan-1999@{ub} · Added routine feature scanner · Added toolbar · Added various ARexx scripts to invoke most SmallEiffel tools from the toolbar · Added templates · Added SmallEiffel console · Added Installer script · Improved syntax parser. It now is a cached parser and supports a lot more different syntax elements. · Fixed "bugs" in Eiffel example shown in syntax parser configuration requester @{b}Version 1.0, 15-Jan-1999@{ub} · Initial release featuring syntax parser @endnode @node NAMING "Naming conventions" @{b}Type name@{ub} Any identifier that may be used as a type, or part of a type, should be written all in upper case. This includes: · Class names, in all possible uses · Formal generic parameters, such as @{i}G@{ui} in @{i}LIST@{ui}[@{i}G@{ui}]. · Basic types like @{i}BOOLEAN@{ui}, @{i}INTEGER@{ui} and @{i}BIT@{ui}. @{b}Constant name@{ub} Constant attributes should be written with an initial capital letter, with the rest in lower case, as in · @{i}Red@{ui}, @{i}Green@{ui}, @{i}Blue@{ui}: INTEGER is Unique · @{i}Something_to_stay_that_way@{ui}: REAL @endnode