Difference between revisions of "Eiffel Information System"

(Protocol)
(Change analysis)
 
(22 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 
[[Category:EiffelStudio]]
 
[[Category:EiffelStudio]]
 +
[[Category:Eiffel Information System]]
  
 
== Purpose ==
 
== Purpose ==
Line 27: Line 28:
 
* 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.
 
* 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 rule 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.
+
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 basic way to specify a dependency is to include such an annotation. The required part of every annotation is:
Line 33: Line 34:
  
 
However the following parts are suggested:
 
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 is defaulted to web page.
+
* 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, identification of where to find information itself, for example a URL, or a file name optionally complemented by a page number.
+
* 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 ===
 
=== Variables ===
Line 42: Line 43:
 
** ISE_WIKI = http://dev.eiffel.com
 
** ISE_WIKI = http://dev.eiffel.com
 
** EIFFELROOM = http://www.eiffelroom.com
 
** EIFFELROOM = http://www.eiffelroom.com
* Context related built in variables. These variables can be used in specific context. For instance, '''feature_name''' refers to the name of the feature in which annotation is written.
+
** 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
 +
* 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
 
** feature_name
 
** class_name
 
** class_name
 
** group_name
 
** group_name
 
** target_name
 
** target_name
* Individual user preferences (Not implemented in 6.2)
+
** 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)
 
* Individual system or library preferences (in ECF)
 
* Environment variables
 
* Environment variables
  
It should be possible to enter an annotation graphically through EiffelStudio Information (EIS) Tool; in that case the relevant clause (feature, class, cluster, system) will be added automatically.
+
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 ===
 
=== Protocol ===
  
* Raw URL: This protocol does not need to specified. By default, it will be taken if nothing is specified or unknown protocol is specified.
+
* 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)
+
* PDF: PDF protocol supports three parameters for now. "type" "page" and "nameddest". (Windows only)
** type: "file" is used to open PDF files in PDF reader. Otherwise in a browser.
+
** 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.
 
** page: Specify the page number to navigate to.
 
** nameddest: Specify the named destination to navigate to.
 
** nameddest: Specify the named destination to navigate to.
* DOC: Microsoft Word document. (Not implemented)
+
* DOC: Microsoft Word document. "bookmark" parameter is supported (Windows Only)
 +
** bookmark: Name of the bookmark in Word document.
  
 
=== Syntax for Annotations ===
 
=== Syntax for Annotations ===
 
The following example illustrates the basic form of an EIS note entry:
 
The following example illustrates the basic form of an EIS note entry:
  
   <e>EIS: "name=Project Requirement", "src=($PROJ)/docs/requirements.pdf", "protocol=PDF", "nameddest=4.1", "tag=requirement"</e>
+
   <e>EIS: "name=Project Requirement", "src=$(SYSTEM_PATH)/docs/requirements.pdf", "protocol=PDF", "nameddest=4.1", "tag=requirement"</e>
  
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.  
+
The label (Note_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:
 
Similarly, the following example demonstrates how annotations look like in ECF files:
  <note ise_support="EIS" protocol="pdf" name="Project Requirement" src="($PROJ)/docs/requirements.pdf" nameddest="4.1"/>
+
<code>
There is only one major difference here, the attribute '''ise_support'''. '''ise_support''' here takes place of label of Node_entry. '''EIS''' plays the same role as the one for note entry. '''ise_support''' tells the parser of the note element is of interest of tools from ISE rather than other tool that might be developed in the future. The note element in ECF is supported in [[http://www.eiffel.com/developers/xml/configuration-1-4-0.xsd schema 1.4]].
+
<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>
 +
</code>
 +
 
 +
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 [[http://www.eiffel.com/developers/xml/configuration-1-4-0.xsd schema 1.4]] and greater.
 +
 
 +
=== Automatic Entry ===
 +
 
 +
Targets in a .ecf file are allowed to specify automatic entry like this:
 +
<code>
 +
<eis auto="true" src="$(ISE_DOC_REF)/$(unique_id)"/>
 +
</code>
 +
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 ===
 
=== Information (EIS) Tool ===
Line 77: Line 103:
 
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.
 
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.
 
There is a screen shot of the tool.
 +
 
[[Image:Information_(EIS)_Tool.PNG]]
 
[[Image:Information_(EIS)_Tool.PNG]]
  
Line 111: Line 138:
 
***** (Default) = "%ISE_EIFFEL%\studio\spec\windows\bin\estudio.exe" /ec_action eisi:"%1"
 
***** (Default) = "%ISE_EIFFEL%\studio\spec\windows\bin\estudio.exe" /ec_action eisi:"%1"
  
=== EiffelStudio Action Protocol (Incoming Implementation) ===
+
=== EiffelStudio Action Protocol ===
{{red|(immature and incomplete)}} <br>
+
 
 
EiffelStudio uses estudio.exe to interact with all existing instances of ec.exe. The protocol is used for this goal.
 
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.
 
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.
Line 133: Line 160:
  
 
The protocol is loaded through [https://svn.origo.ethz.ch/eiffelstudio/trunk/Src/framework/command_tunnel Command Tunnel Library]. This library is now only implemented on Windows.
 
The protocol is loaded through [https://svn.origo.ethz.ch/eiffelstudio/trunk/Src/framework/command_tunnel Command Tunnel Library]. This library is now only implemented on Windows.
 +
 +
== Change analysis ==
 +
Within EiffelStudio 7.3, there will be new functions in Infomation tool to track changes on target or external resouce side, and potentially affected items on either side are listed.
 +
* New functions are:
 +
** List of elements of current system that would be affected by external resource changes. (The first version limits the external resource to local files.)
 +
** List of external resources that might be affected by changes of current system. (No limit of the type of external resources)
 +
** Change acknowledgement.
 +
 +
Typical work flow to demo affected external resources caused by current system change:
 +
# Open a class, add an Information entry with an external source in the class.
 +
# Start working on that class, save it at as you normally do on regular basis.
 +
# Open Info tool, go to Affected source item in the left tree.
 +
# Check the list of external resouces that might be affected by last changes, as shown in the sceen cast bellow.
 +
# Acknowledge the changes if you find that the external resources do not need a change for last changes of current system.
 +
 +
Typical work flow to demo affected items in the system caused by external resource change:
 +
# Open a class, add an Information entry with an external document (limited to local files in 7.3) in the class.
 +
# Start working on that document, save it at as you normally do on regular basis.
 +
# Open Info tool, go to Affected target in the left tree.
 +
# Check the list of targets that might be affected by last changes of the document. (You may need to click on the "sweep the system now." button to get a full list if auto-sweeping is not enabled.)
 +
# Acknowledge the changes if you find that current system does not need a change for last changes of the document.
 +
 +
[[Image:Information_Tool_change_analysis.PNG]]

Latest revision as of 02:29, 4 April 2013


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
  • 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 parameters 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. "bookmark" parameter is supported (Windows Only)
    • bookmark: Name of the bookmark in Word document.

Syntax for Annotations

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

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

The label (Note_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.

Information (EIS) Tool.PNG

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.

Information.png 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

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.

Change analysis

Within EiffelStudio 7.3, there will be new functions in Infomation tool to track changes on target or external resouce side, and potentially affected items on either side are listed.

  • New functions are:
    • List of elements of current system that would be affected by external resource changes. (The first version limits the external resource to local files.)
    • List of external resources that might be affected by changes of current system. (No limit of the type of external resources)
    • Change acknowledgement.

Typical work flow to demo affected external resources caused by current system change:

  1. Open a class, add an Information entry with an external source in the class.
  2. Start working on that class, save it at as you normally do on regular basis.
  3. Open Info tool, go to Affected source item in the left tree.
  4. Check the list of external resouces that might be affected by last changes, as shown in the sceen cast bellow.
  5. Acknowledge the changes if you find that the external resources do not need a change for last changes of current system.

Typical work flow to demo affected items in the system caused by external resource change:

  1. Open a class, add an Information entry with an external document (limited to local files in 7.3) in the class.
  2. Start working on that document, save it at as you normally do on regular basis.
  3. Open Info tool, go to Affected target in the left tree.
  4. Check the list of targets that might be affected by last changes of the document. (You may need to click on the "sweep the system now." button to get a full list if auto-sweeping is not enabled.)
  5. Acknowledge the changes if you find that current system does not need a change for last changes of the document.

Information Tool change analysis.PNG