Start using Eiffel Information System (EIS)

by Tao Feng (modified: 2012 Jul 13)

    Contents
  1. EIS Incoming
  2. EIS Outgoing
    1. Information tool
    2. Annotation
    3. Protocol
    4. Variable

In EiffelStudio 6.2, Eiffel Information System (EIS) will be introduced. The goal of EIS is to provide a unified mechanism for linking development objects — classes and features, or even targets and groups — 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 or Microsoft Word; we call them external tools.

The main apparent addition is the Information tool. But don't be tricked. The basic mechanisms that EIS makes available to users, at least Windows users, include two categories: outgoing (from Eiffel to external tools) and incoming (the reverse). The tool belongs to the former one.

What can people do via EIS?

EIS Incoming

EIS incoming mechanism, as the name implies, enables users to reference components of an Eiffel system in external tools. For the moment, only available on Windows. The whole thing implemented is protocol link of "eiffel".

For example, one can use the following links to refer to {STRING_8}.is_equal in a system.

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

As you see, the later one turns out to be more precise. They all works if the project `ec' with UUID D398E904-E3C8-4F8A-B9E7-6FE493CEA02F has been opened. Once you put this in a browser and enter, or click a link in MS word document, the opening EiffelStudio automatically locates {STRING_8}.is_equal in an open editor.
What if no EiffelStudio has been opened?
For 1, 2 and 3, a new EiffelStudio will be launched, since no project(system) has been specified, users need to choose one by themselves. When the project is successfully loaded, {STRING_8}.is_equal will be opened.
For 4, EiffelStudio introduces a new preference eis_path. EiffelStudio will search projects under the path, finally if project `ec' is found, {STRING_8}.is_equal will be opened.

EIS Outgoing

This part of EIS is used for annotating Eiffel classes, features or even target and clusters to include references to external information. The tool mentioned (Information tool) belongs to this part.

Information tool

The basic function of the tool is to manage all annotations in current system. Users can add, modify, remove or navigate such annotations via the tool. All annotations are arranged either by location or tags being navigated through the tree. One can see that in the tool, choosing a class shows all annotations from the class and those from "inherited" clusters/targets.

The following is what the tool looks like now:

See the following appears in EiffelStudio 7.1:
http://dev.eiffel.com/Image:Information_%28EIS%29_Tool.PNG

Annotation

Annotations if any either reside in actual code in the form of note or .ecf files in the form of note elements. Those annotations put in code are used to denote class/feature specific information. Those put in .ecf are actually binded to the target/cluster. If one add a piece of annotation into a target or a cluster - underlying info has been added into .ecf - he simply makes the annotation visible to all classes in Information tool. This is useful especially when a library developer want to share library-wide information to clients. The following are the examples of the actual written annotations.

  • code:

note EIS: "name=myDoc", "src=http://mysite.com/myDoc.pdf", "protocol=pdf", "nameddest=Chapter2", "tag=tagA, tagB"

  • .ecf:
<note protocol="pdf" name="myDoc" src="http://mysite.com/myDoc.pdf" ise_support="eis" tag="tagA, tagB" nameddest="Chapter2"/><br/>

Protocol

Everything in Source is treated as an URL if no protocol is specified or unknown protocol is specified. Protocols supported now:

  • Raw URL: Nothing more is interesting other than navigating to the URL
  • PDF: PDF protocol supports three attributes now. "type" "page" and "nameddest".
    • type: "file" is used to open PDF files in PDF reader. Otherwise in a browser.
    • page: Specify the page number to navigate to.
    • nameddest: Specify the named destination to navigate to.
  • DOC: DOC protocol supports "bookmark". Name of a bookmark predefined in a Microsoft Word document. (Introduced in 7.1)

Variable

In the value of Source(Shown in Information tool) variables can be used.
Types of variables , value is taken by priority from top to bottom if the same.(Introduced in 7.1, a completion list in "Source" column of the tool. Press Ctrl + Space, or '$' to see the list when editing)

  • IDE user defined variables. (Unavailable) These variables are applied over all projects. The main use is to override following types of variables.
  • IDE built in variables. These variables are built-in and go with the release. Such variables are mostly used by ISE to share users helpful references related to ISE.
    • 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
    • SYSTEM_PATH, the path of the system in which current entry is written (Introduced in 7.1)
  • Target variables. This kind of variables go with the .ecf file. They are mostly used by a library releaser or people who are working on the same project can share information with each other.
  • Environment variables.
  • Context related built in variables. They are feature_name, class_name, group_name and target_name.

One can use F1 in the editor to see if current position of the class has any usable annotations.

Comments
  • Colin Adams (16 years ago 13/5/2008)

    Invalid URIs

    The syntax of the eiffel: URIs is invalid.

    That is, the presence of the // indicates that what follows is an authority segment:

    According to RFC 3986, this is terminated by the first /, ? or # character.

    None of those is present, so the remainder of the URI needs to match the authority production syntax. As there is no @ or : present, this in turn means matching the syntax for host. Clearly it does not.

    I suggest that you appear to be parameter/value pairs, and that therefore this remainder should actually be part of the query segment.

    Accordingly, change eiffel:// into eiffel://? in order to conform to URI syntax.

    I assume that by protocol link you actually meant URI scheme.

    Colin Adams

    • Tao Feng (16 years ago 13/5/2008)

      Indeed. I think eiffel:/// would be nicer.

      • Colin Adams (16 years ago 13/5/2008)

        Perhaps a path

        You would need eiffel:///?... if you expected generic URI processing software to pick up the name/value pairs.

        or alternatively abandon the query parameters approach, and have a structured path (something like /system/target/cluster/class/feature). But that would make it hard to default the system and target.

        I can't see how this is supposed to work anyway. Surely you need an ecf file? In which case the obvious syntax is:

        eiffel:///path/to/my.ecf?class=my_class&feature=my_feature

        and the authority field is then available for a future extension for non-local access.

        Colin Adams

        • Tao Feng (16 years ago 14/5/2008)

          Though I am not aware of what kind of software processes the URI and how it would be useful picking up name/value pairs, it is would always be better to follow standard. Using eiffel:///? is OK for me, except that it looks uglier. Actually the .ecf is not needed for EIS incoming mechanism. Only optional system/system UUID is needed for locating project.

        • Franck Arnaud (16 years ago 17/5/2008)

          Path URI

          Yes path URI sounds so much better than the name value mess, and is not exclusive with defaulting of various types, with say a magic word as first component:

          eiffel:///byclass/STRING/is_equal eiffel:///bycluster/foo/STRING/is_equal

          etc

          • Tao Feng (16 years ago 18/5/2008)

            The following link is sufficient to locate {STRING_8}.is_equal<br> eiffel://system=ec&target=base&class=STRING_8&feature=is_equal By your means, it would be:<br> eiffel:///bysystem/ec/base/STRING_8/is_equal Note that cluster' is omitted here. It means that we don't know what STRING_8' is. It can be a cluster name and is_equal' is a class name. So this could be interpreted as class IS_EQUAL' is required in cluster `string_8'.

  • Colin Adams (16 years ago 20/5/2008)

    Are you going to register the Eiffel URI scheme?

    I am puzzled as to how you are implementing these incoming links.

    First, you talk about entering them in a browser. And the syntax looks like a URI but isn't.

    I would suggest the following actions:

    1) Read RFC 3986 - the definition of URI syntax. 2) If you still can't see why the examples are wrong, and why the design of the URI is poor, create a UT_URI object with one of those example "URI"s, and then stop in the debugger at the end of the creation procedure, and examine the attributes of the UT_URI object. 3) Read the procedures on registering a URI scheme (scheme - not protocol. Even the http URI scheme doesn't always mean the http protocol will be used). Even if you don't submit the scheme for registration (and I certainly think you should do so), considering the process should help a lot.

    Colin Adams

    • Tao Feng (16 years ago 21/5/2008)

      No plan for now.

      Thanks for the information, Colin.<br> I read more about this. Now I think "//" may not be needed. Since it is used ONLY when the syntax of the URI's <scheme-specific-part> contains a hierarchical structure. system/target/group/cluster/class/feature is kind of hierarchical structure, but not strict. Some parts are optional when certain parts present. It seems the best fit of current requirement is like "eiffel:?class=XXX&feature=XXX".

  • Colin Adams (16 years ago 22/5/2008)

    It could be still shorter in some circumstances

    That looks fine.

    In fact, you can drop the eiffel: too in some cases. The application can set a base URI of eiffel: .

    Colin Adams