Eiffel Information System

Purpose

The Eiffel Information System (EIS) provides a unified mechanism for linking development objects — classes, features and so on — of Eiffel systems with external information. This term refers to information other than Eiffel program texts. Usually the tools maintaining external information are separate tools, such as a browser; we call them external tools. Examples of external information and possible corresponding external tools are:

• Web page — the default browser
• PDF document — Acrobat
• MS Word documents — Microsoft Word

EIS is also intended to be the standard mechanism for obtaining help on Eiffel and EiffelStudio, replacing previous solutions. In that case "external tools" may actually be Eiffel tools.

Functionalities

The basic mechanisms that EIS makes available to users include two categories: outgoing (from Eiffel to external tools), incoming (the reverse).

• Examples of outgoing mechanisms include:
  • Annotating Eiffel targets, classes and features to include references to external information. Such annotations can include tags.
  • By selecting an annotation in EiffelStudio, automatically open the corresponding external tool to display or edit that information.
  • Provide a list of all external information (in a class, cluster or entire system) corresponding to a specified tag.
  • For a change to the software — either after the change has been performed, or before a contemplated change has been performed — display a list of all external information that may be affected as indicated by the annotations (not implemented in 6.2)

• Examples of incoming mechanisms include:
  • For supported tools, select external information linked to an Eiffel developer object and have EiffelStudio directly open on that object. In 6.2, eiffel: schema is supported on Windows.

Outgoing

Annotations

Annotations may be applicable to:

• An individual class or feature. In this case the annotation figures in the class text, as part of an Eiffel "note" clause ("indexing" is still supported, it depends on which syntax level the user choose).
• A target, library or cluster. In this case the annotation figures in the associated ECF file; EiffelStudio provides support for entering it through a Information (EIS) Tool.

Most of the following rules use note clauses as examples, but all applicable facilities must be supported by both variants; the syntax is designed to be as close as possible.

The basic way to specify a dependency is to include such an annotation. The required part of every annotation is:

• The "EIS" marker.

However the following parts are suggested:

• The "protocol", indicating the type of external information, and making it possible for EIS to determine the associated external tool. Without the "protocol" part, the source defaults to a web page.
• The source, which identifies where to find the information itself, for example a URL, or a file name optionally complemented by a page number.

Variables

Not all information must be literal: annotations can use variables, defined at various levels including:

• EiffelStudio installation built in variables
  • ISE_WIKI = http://dev.eiffel.com
  • EIFFELROOM = http://www.eiffelroom.com
  • ISE_DOC = http://docs.eiffel.com
  • ISE_DOC_UUID = http://doc.eiffel.com/isedoc/uuid
  • ISE_DOC_REF = http://doc.eiffel.com/isedoc/eis
• Context related built in variables. These variables can be used in a specific context. For instance, feature_name refers to the name of the feature in which the annotation is written.
  • feature_name
  • class_name
  • group_name
  • target_name
  • unique_id
    • The `unique_id' returns a unique id of a class in a compiled system. The id usually consists of target uuid, target name, group name and class name.
• Individual user preferences (Not implemented)
• Individual system or library preferences (in ECF)
• Environment variables

It should be possible to enter an annotation graphically through the EiffelStudio Information (EIS) Tool; in that case the relevant clause (feature, class, cluster, system) will be added automatically.

Protocol

• URI: This protocol does not need to specified. By default, it will be taken if nothing is specified or unknown protocol is specified.
• PDF: PDF protocol supports three attributes for now. "type" "page" and "nameddest". (Windows only)
  • type: "file" is used to open PDF files in the PDF reader. Otherwise it opens in a browser.
  • page: Specify the page number to navigate to.
  • nameddest: Specify the named destination to navigate to.
• DOC: Microsoft Word document. (Not implemented)

Syntax for Annotations

The following example illustrates the basic form of an EIS note entry:

 EIS: "name=Project Requirement", "src=$(PROJ)/docs/requirements.pdf", "protocol=PDF", "nameddest=4.1", "tag=requirement"

The label (Node_entry as called in the ECMA/ISO Eiffel Standard syntax) is EIS, EIS Note_value tells the Eiffel Information System that this Note_entry is of interest to EIS, as distinct from any other information that might be expressed through a Note_entry. The file name (src) includes $PROJ, referring to a variable — set at any of the above 5 levels, rather than the second one "Context related built in variables" — defining the project location. The protocol is PDF. The nameddest property (name destination) is a specific property of PDF documents. The tag requirement indicating that this entry links the enclosing Eiffel class or feature with some part of the requirements document.

Similarly, the following example demonstrates how annotations look like in ECF files:

<note>
	<eis auto="true" src="$(ISE_DOC_REF)$(unique_id)"/>
	<eis src="$(ISE_DOC_UUID)/3d96626f-11f3-67a2-dec6-69f7faf4a8d6" tag="EiffelTime" name="EiffelTime"/>
</note>

There is only one major difference here, targets in .ecf support automatic entry specification which enables automatic entry for classes in that target. The note element in ECF is supported in [schema 1.4] and greater.

Automatic Entry

Targets in a .ecf file are allowed to specify automatic entry like this:

<eis auto="true" src="$(ISE_DOC_REF)/$(unique_id)"/>

When `auto' is set with `true', automatic entry is enabled in the target. In Info tool, each class in a target with automatic entry enabled displays an entry, actually not existing in code, is bound to a source `src'.

An automatic entry of a class can be overridden too, by specifying "override=true" in one of the written entry, or check the check box in the column of Info tool.

One can modify the automatic entry specification in a target via the first button with an "A" in Info tool. Of course, select a target node in the tree first.

Information (EIS) Tool

The tool is an output of the EIS outgoing mechanism. Through the tool, users can graphically manage all EIS information in current system. See Information (EIS) Tool for more information. There is a screen shot of the tool.

Incoming

Incoming mechanism is based on URI, and introduces a new URI scheme: eiffel. By entering the URI into address of a browser, or clicking on the hyper link, an existing EiffelStudio instance or new EiffelStudio instance will try to resolve the URI and display corresponding resources.

URI scheme Syntax

 eiffel:?<eiffel-resource>

<eiffel-resource> is a combination of following parts, connected by "&" if more than one part are required:

• <system>, in the form of system=to_be_replaced, "to_be_replaced" consists of system_name or uuid of the system, or both connected by ".".
• <target>, in the form of target=to_be_replaced, "to_be_replaced" consists of target_name or uuid of the system, or both connected by ".".
• <cluster>, in the form of cluster=to_be_replaced, "to_be_replaced" is the name of the cluster.
• <class>, in the form of class=to_be_replaced, "to_be_replaced" is the name of the class.
• <feature>, in the form of feature=to_be_replaced, "to_be_replaced" is the name of the feature.

Note: All parts above are unordered.

Examples:

 eiffel:?class=STRING_8&feature=is_equal
 eiffel:?cluster=elks&class=STRING_8&feature=is_equal
 eiffel:?target=base&cluster=elks&class=STRING_8&feature=is_equal
 eiffel:?system=ec.D398E904-E3C8-4F8A-B9E7-6FE493CEA02F&target=base&cluster=elks&class=STRING_8&feature=is_equal

Protocal Registration (Windows)

The following example shows how to register eiffel scheme on Windows, estudio.exe in this case, to handle an eiffel URI.

• HKEY_CLASSES_ROOT
  • eiffel
  • (Default) = "URL:Eiffel Protocol"
  • URL Protocol = ""
    • DefaultIcon
    • (Default) = "estudio.exe"
    • shell
      • open
        • command
        • (Default) = "%ISE_EIFFEL%\studio\spec\windows\bin\estudio.exe" /ec_action eisi:"%1"

EiffelStudio Action Protocol (Incoming Implementation)

(immature and incomplete)
EiffelStudio uses estudio.exe to interact with all existing instances of ec.exe. The protocol is used for this goal. The action protocol can be used for those tools that want to control running EiffelStudio instances. For the moment, this is completely transparent to end users because of its immaturity. It was designed to fit the requirement of EIS incoming mechanism, with limited extendibility. In the future, as required, it could be designed as XML style, after precise analysis on requirements of all kinds of new functionalities.

The pattern EiffelStudio accept is:

 [<eiffelstudio-module-ID><predefined-status>]<eiffelstudio-module-ID><modulewise-action>

The part bracketed is optional condition. A command with conditional part is a conditional command. Without conditional part, the command is direct command. <eiffelstudio-module-ID> refers to a module defined in EiffelStudio. For example, <com.eiffel.compiler>, the compiler module in EiffelStudio; <com.eiffel.eis_incoming>, EIS incoming module. <predefined-status> stands for a status of that module, as a conditional status which should trigger the actual <modulewise-action>. <modulewise-action> indicate the predefined action a module in EiffelStudio should actually react.

The following are examples now implemented on the purpose of EIS incoming functions:

 Example: <com.eiffel.eis_incoming><eiffel:?class=string_8&feature=out>
 Explanation: Demand EiffelStudio open the feature {STRING_8}.out in the editor now.

 Example: <com.eiffel.compiler><project_ready><com.eiffel.eis_incoming><eiffel:?class=string_8&feature=out>
 Explanation: Demand EiffelStudio open the feature {STRING_8}.out in the editor, when the project is ready.

The protocol is loaded through Command Tunnel Library. This library is now only implemented on Windows.