Difference between revisions of "Code Templates"

Revision as of 12:24, 29 January 2008

This page is used to refine the specification for a code template mechanism in future releases of EiffelStudio.

Initial Design Descisions

For now XML has been chosen to describe code templates because is it structured, easy to read (programmatically) and can be converted with relative ease using transformation scripts.

The information discussed here is by no means final or reflects any work current under way. It's used to formualize a schema, part of which may be in the release of 6.2 under use in the Contract Editor Tool.

Schema

<code_templates format="1.0.0">
  <code_template>
 
    <metadata>
      <title>Completion title</title>
      <description>Code template description, for completion tooltip and other UI.</description>
      <author>Eiffel Software</author>
      <shortcut>shortcut</shortcut>
      <categories>
        <category>contract</category>
        <category>code</category>
        <category>class</category>
      </categories>
    </metadata>
 
    <references>
      <reference>
        <library location="$ISE_LIBRARY/base/base.ecf"/>
      </reference>
      <reference>
        <library id="6D7FF712-BBA5-4AC0-AABF-2D9880493A01"/>
      </reference>
      <reference>
        <assembly>mscorlib.dll</assembly>
        <version>2.0.54727</version>
      </reference>
      <reference>
        <assembly>System.dll</assembly>
      </reference>
    </references>
 
    <declarations>
      <choice id="opt">
        <description>Choice declaration.</description>
        <choices>
          <item>do</item>
          <item>once</item>
          <item>deferred</item>
        </choices>
      </choice>
 
      <literal id="var" editable="true">
        <description>Editable literal.</description>
        <default>default value</default>
      </literal>
 
      <literal id="var2" editable="false">
        <description>Function evaluation, non-editable but can be editable.</description>
        <default>CLASS_NAME</default>
        <function name="builtin_function">
          <arg type="STRING_32">make</arg>
          <arg>default to string</arg>
          <arg type="INTEGER_32">-12</arg>
        </function>
      </literal>
 
      <object id="list" conforms="LIST [ANY]" editable="true">
        <description>Variable that is of a Eiffel list type structure, containing a for_all call.</description>
      </object>
    </declarations>
 
    <templates>
      <template><![CDATA[${list}_contains_attached_items: not ${list}.has (Void)${cursor}]]></template>
    </templates>
 
  </code_template>
</code_templates>

Metadata

The metadata section describes the code template and is only used by part of the UI. It has no functional effect of the template or how it is rendered, the information is purely informative. As a result the entire metadata section of the code template could be optional, as with each element. However for the purpose of UI related integration the title element, and thus metadata, should be required.

The title element is used to title the code template. It's a brief description that can be shown in the completion window, in a code template manager or other aspects of the UI where brevity is required.

decription on the other hand is more verbose and deeper explains the function of the code template.

author is for acknowledgement and classifaction of a code template.

categories will be used to classify the code template. There are no set categories and are used and informative hints as to where the code template can be used. Categories can also be used by the UI to group or classify further a code template. By default there should be three well-known categories

• class: Templates used within the scope of a class.
• code: Templates used within the scope of a routine body.
• contract: Templates used within the scope of a contract.

Finally quick_text is an Eiffel-like identifier ([a-zA-Z][a-zA-Z0-9_]*) which can be used by aspects of the UI, such as the editor, to shortcut enter of the code template into an editor. Template expansion will come probably via the enter to the shortcut as text with a following key-based shortcut to expand the shortcut into a code template.

   <metadata>
     <title>Completion title</title>
     <description>Code template description, for completion tooltip and other UI.</description>
     <author>Eiffel Software</author>
     <quick_text>shortcut</quick_text>
     <categories>
       <category>precidate</category>
       <category>contract</category>
       <category>code</category>
       <category>class</category>
     </categories>
   </metadata>

Contract Editor Requirements

Due to the fast approaching date of the 6.2 release, if implemented only a subset of code templates will be implemented for the contract editor. Below is an example of a code template written for a contract:

<code_templates format="1.0.0">
  <code_template>
    <metadata>
      <title>Attached</title>
      <description>Code template for checking if an entity is attached.</description>
      <author>Eiffel Software</author>
      <categories>
        <category>contract</category>
      </categories>
      <shortcut>attached</shortcut>
    </metadata>
 
    <declarations>	
      <literal id="id"/>
    </declarations>
 
    <templates>
      <template>
        <![CDATA[${id}_attached: ${id} /= Void]]>
      </template>
    </templates>
 
  </code_template>
</code_templates>

Contracts should fully support the metadata section because the contract will need to produce a completion list of contracts, which will use the template's title. description is to ensure forward compatibility and will likely be used to describe the template in the completion UI. The shortcut element is expected to be utilized in 6.2 to quickly insert a contract using the contract editor tool's edition ability. categories is another future proofing addition and will probably not be respected in the release of 6.2. Post 6.2 however the category will be respected so those contracts without a category will not be available from the UI, because they do not fall into the contract category.

For the contract tool, only simple literal declarations will be supported, supporting the typed literals post the release of 6.2. No functions will be available for use yet.

For 6.2 code template versions will not be supported but the structuring for specifying code templates will be preserved for future proofing the contract code templates.