Code Templates - Revision history

Paulb: /* Schema */

2008-04-09T21:28:02Z

‎Schema

Paulb: /* Contract Editor Requirements */

2008-03-24T19:14:46Z

‎Contract Editor Requirements

Paulb: /* Code Template Declarations */

2008-02-05T01:14:11Z

‎Code Template Declarations

Paulb: /* Code Template Declarations */

2008-02-05T00:39:38Z

‎Code Template Declarations

Paulb: /* Metadata */

2008-02-05T00:35:15Z

‎Metadata

Paulb: /* Assembly Library References */

2008-02-05T00:28:40Z

‎Assembly Library References

Paulb: /* Code Templates */

2008-02-05T00:13:29Z

‎Code Templates

Paulb: /* Assembly Library References */

2008-02-05T00:07:47Z

‎Assembly Library References

Paulb: /* Code Templates */

2008-02-05T00:05:37Z

‎Code Templates

Paulb: /* Metadata */

2008-01-30T01:24:56Z

‎Metadata

@@ Line 67: / Line 67: @@
        </literal>
-       <object id="list" conforms="LIST [ANY]" editable="true">
+       <object id="list" conforms_to="LIST [ANY]" editable="true">
          <description>Variable that is of a Eiffel list type structure, containing a for_all call.</description>
        </object>
      </declarations>

← Older revision		Revision as of 19:14, 24 March 2008
Line 257:		Line 257:

	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.		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.
		+
		+	=== ===
		+	To ensure correct formatting and yet clarity of a code template declaration template delimiters can be used in a template declaration.
		+
		+	<code>
		+	<templates>
		+	<template>
		+	~#
		+	code template
		+	#~
		+	</template>
		+	</templates>
		+	</code>
		+
		+	The template start (~#) and end (#~) delimiters can either be placed on their own line or placed before and after the template on the same line. In either case the trailing white-space after the start delimiter (~#) and the leading white-space before the end delimiter (#~) is removed. Without the delimiters all white-space is preserved.
		+
		+	To illustrate the semantics of the delimiters, consider the following template:
		+
		+	<code>
		+	<templates>
		+	<template>
		+	$var /= Void
		+	</template>
		+	</templates>
		+	</code>
		+
		+	In Eiffel code would be
		+
		+	<eiffel>
		+	f
		+	do
		+	if \| then
		+	end
		+	end
		+	</eiffel>
		+
		+	Inserting the template would result in the following code:
		+
		+	<eiffel>
		+	f
		+	do
		+	if
		+	var /= Void
		+	then
		+	end
		+	end
		+	</eiffel>
		+
		+	The template has inserted extra line breaks and white space before and after the actual template. To correct the template can be rewritten as follows:
		+
		+	<code>
		+	<templates>
		+	<template>$var /= Void</template>
		+	</templates>
		+	</code>
		+
		+	Or using delimiters:
		+
		+	<code>
		+	<templates>
		+	<template>
		+
		+	~#
		+	$var /= Void
		+	#~
		+
		+	</template>
		+	</templates>
		+	</code>

← Older revision		Revision as of 01:14, 5 February 2008
Line 148:		Line 148:

	== Code Template Declarations ==		== Code Template Declarations ==
		+	In order to facilitate code templates, variables will be required to replaces parts of the template with user supplied parameters.
		+
		+	=== Literal Declarations ===
		+
		+	Literal code definitions types are declaration variables that can be replaced in a code template text. There are two forms of literal declarations; simple, editable declarations and functional literals that retrieve their value from an in-built function.
		+
		+	Every literal declaration is created using a '''literal''' element with an ''id'' attribute, defined using the Eiffel identifier rules ([a-zA-Z][a-zA-Z0-9_]*]), which will be used in a tokenized code template text block. ''id'' should contain a unique indentifer to the code template file, as not to conflict with any other declaration. Each literal will contain another optional Boolean attribute ''editable'' indicating if the literal declaration can be edited by the user. The ''editable'' attribute is another piece of code template information for the UI. It should indicate to the UI if the user is able to directly edit the variable or if the value is retrieve from a default or internally.
		+
		+	==== Basic ====
		+
		+	The most fundamental literal declarations should be simple to define. As already stated, the '''literal''' element should be used and the ''id'' attribute present. The ''editable'' attribute should also be applicable and effective even in the simplest of declarations.
		+
		+	Ever literal needs a value, as a suggestion, place holder or indication of the value. For instance, if the code template mechanism is integrated into the editor, the rendered template should highlight portions of the code template text to indicate declarations that can be replaced. If there is no suggested or default value then it is impossible to display any indication. Rendered programmatically there is still a need for a default value.
		+
		+	<code>[xml]
		+	<literal id="var" editable="true">
		+	</code>
		+
		+	<code>[xml]
		+	<literal id="var" editable="true">
		+	<description>Editable literal.</description>
		+	<default>default value</default>
		+	<literal>
		+	</code>

	== Code Templates ==		== Code Templates ==

@@ Line 146: / Line 146: @@
 === Assembly Library References ===
 Assembly references are specific to only .NET projects and are specified using the fusion name parts. '''name''' will always be required, as it is when attempting to load an assembly using the Common Language Runtime. All other parts are optional and will be used to narrow multiple matches; '''version''' indicates the minimum version of the assembly to, '''culture''' indicates the assembly located required when referencing an assembly and finally, '''key''' indicates the assembly's public key token, required to match any located assembly.
 == Code Templates ==

@@ Line 104: / Line 104: @@
 * ''contract'': Templates used within the scope of a contract.
-Finally, '''shortcut''' is an Eiffel-like identifier ([a-zA-Z][a-zA-Z0-9_]*) which can be used by aspects of a tool's UI, such as an editor, to render a code template using shorthand identifier, rather than use a slower system of code template navigation. 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 fully rendered code template. This is purely to assists end-users when typing, to retain edit-flow without having to resort to showing completion or any other UI to insert and render a code template.
+Finally, '''shortcut''' is an Eiffel-like identifier ([a-zA-Z][a-zA-Z0-9_]*) which can be used by aspects of a tool's UI, such as an editor, to render a code template using shorthand identifier, rather than use a slower UI-based system of code template navigation. 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 fully rendered code template. This is purely to assists end-users when typing, to retain edit-flow without having to resort to showing completion or any other UI to insert and render a code template.
 == Code Library References ==

@@ Line 197: / Line 197: @@
 </code>
-Because there is no minimum version specified for the template, regardless of the compiler used or targeted, the template will be rendered upon request.
+It will probably be necessary at some point to develop code templates that function for a specific platform or code generation target. For the simplification of the code template schema, platform segregation should be performed through organization of an installation. Currently this accomplished by the Eiffel compiler's built-in mechanism.
 == Contract Editor Requirements ==

@@ Line 145: / Line 145: @@
 === Assembly Library References ===
-Assembly references are specified using the fusion name parts. '''name''' will always be required, as it is when attempting to load an assembly using the Common Language Runtime. All other parts are optional and will be used to narrow multiple matches.
+Assembly references are specific to only .NET projects and are specified using the fusion name parts. '''name''' will always be required, as it is when attempting to load an assembly using the Common Language Runtime. All other parts are optional and will be used to narrow multiple matches.
 '''version''' indicates the minimum version of the assembly to

@@ Line 157: / Line 157: @@
 The fundamental of code templates is the actual code template. The code template schema should not only support the specification of a template but also versioned templates.
-It is necessary to version templates based on the compile version targeted or the current compiler in use. A long term vision of code templates is that they are not just prepackaged templates distributed with a release of EiffelStudio, but instead be distributed by first and third-parties. Even today development house run different version of EiffelStudio and may want to author their own code templates for in-house use with proprietary libraries.
+It is necessary to version templates based on the compile version targeted or the current compiler in use. A long term vision of code templates is that they are not just prepackaged templates distributed with a release of EiffelStudio, but instead be distributed by first and third-parties. Even today, development houses run different version of EiffelStudio and may want to author their own code templates for in-house use with proprietary libraries.
 === Versioned Code Templates ===

@@ Line 85: / Line 85: @@
 Below shows an initial draft of the metadata section of a code template:
-<code>[xml]
+<code>[xml]<metadata>
 <metadata>
    <title>Short title</title>
    <description>Code template description.</description>
@@ Line 96: / Line 95: @@
    </categories>
    <shortcut>shortcut</shortcut>
-</metadata>
+</metadata></code>
 </code>
 The '''title''' element is used to title the code template. It is to be a terse description to be shown in parts of the EiffelStudio UI; such parts as the completion window, in a code template manager or other aspects of the UI where brevity is required. '''description''' on the other hand is more verbose and deeper explains the function of the code template, to explain all that '''title''' is unable to. '''author''' is last element used in describing the code template, for acknowledgment and possible classification.
@@ Line 106: / Line 104: @@
 * ''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.
+Finally, '''shortcut''' is an Eiffel-like identifier ([a-zA-Z][a-zA-Z0-9_]*) which can be used by aspects of a tool's UI, such as an editor, to render a code template using shorthand identifier, rather than use a slower system of code template navigation. 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 fully rendered code template. This is purely to assists end-users when typing, to retain edit-flow without having to resort to showing completion or any other UI to insert and render a code template.
 == Code Library References ==