mirror of
https://github.com/EiffelSoftware/eiffel-org.git
synced 2025-12-06 23:02:28 +01:00
Committed pending modification.
git-svn-id: https://svn.eiffel.com/eiffel-org/trunk@1706 abb3cda0-5349-4a8f-a601-0c33ac3a8c38
This commit is contained in:
eiffel-org
@@ -11,6 +11,10 @@ To make the notations simpler, a number of extensions have been proposed. They i
|
||||
*Type inference (to avoid explicitly specifying the type when it can be deduced from the context). This is a facility for the programmer, useful in particular for local variables, but does not affect the type system: Eiffel remains strongly typed, it is just that you can be lazy about writing the type when there is no ambiguity.
|
||||
*In the same vein, omitting the entire list of generic parameters when it can be inferred.
|
||||
|
||||
see [[file:expression_language.pdf|document as pdf]].
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -58,12 +58,12 @@ In the root feature:
|
||||
-- Other local variables if necessary.
|
||||
do
|
||||
create ts.make
|
||||
ps.disable_tracing
|
||||
ts.disable_tracing
|
||||
-- Program execution continues.
|
||||
...
|
||||
|
||||
-- Restore tracing before exiting for proper cleanup.
|
||||
ps.enable_tracing
|
||||
ts.enable_tracing
|
||||
end
|
||||
</code>
|
||||
|
||||
@@ -76,10 +76,10 @@ Then, in a feature in which tracing is desired:
|
||||
-- Other local variables if necessary.
|
||||
do
|
||||
create ts.make
|
||||
ps.enable_tracing -- Enable trace
|
||||
ts.enable_tracing -- Enable trace
|
||||
-- Section needing trace.
|
||||
...
|
||||
ps.disable_tracing -- Disable trace
|
||||
ts.disable_tracing -- Disable trace
|
||||
end
|
||||
</code>
|
||||
|
||||
|
||||
@@ -4,58 +4,100 @@
|
||||
[[Property:weight|7]]
|
||||
|
||||
<span id="what_are_code_templates"></span>
|
||||
= What are code templates and how do they help me? =
|
||||
|
||||
EiffelStudio offers Code Templates. Introduced in version 16.11, code templates facilitate the programmer’s task by proposing program schemes that correspond to typical situations. Code templates are contextual: based on some properties of your code, EiffelStudio will offer a list of templates that could — just could! — do exactly what’s on your mind at the moment.
|
||||
EiffelStudio's code templates facilitate the programmer’s task by offering program schemes that correspond to typical programming needs. Templates are a simple idea (section 1); you can use templates that others have defined (section 2); you can define your own templates (section 3); and you can share them, so that they will become part of future EiffelStudio deliveries (section 4).
|
||||
|
||||
If all you need to know is how to use the template mechanism in EiffelStudio, you can just read sections 1 and 2.
|
||||
|
||||
= 1. What are code templates and how do they help me? =
|
||||
|
||||
Code templates are contextual: based on the properties of some part of your code, EiffelStudio will offer a list of templates that could — just could! — do exactly what you need at that very place.
|
||||
|
||||
For example, if you are using an integer array, EiffelStudio will offer a code template for a common operation: computing the array’s maximum. If you select the template, EiffelStudio will insert its code into your program, giving you the option of specifying the starting and ending indices (which it sets by default to the array’s bounds). You just have to specify the information relevant to your particular case; the template takes care of the implementation.
|
||||
|
||||
|
||||
EiffelStudio comes with a number of predefined templates; you can also contribute your own.
|
||||
There are two kinds of template:
|
||||
|
||||
* Targeted, that is, applied to a certain target entity. For example, if you have a variable of type <code>ARRAY [INTEGER]</code>, EiffelStudio will offer you templates that work on that array (the “target”).
|
||||
* Targetless (or “global’): applicable in all contexts, without a target.
|
||||
* '''Targeted''' templates apply to a certain target entity. For example, if you have a variable of type <code>ARRAY [INTEGER]</code>, EiffelStudio will offer you templates that work on that array (the “target”).
|
||||
* '''Targetless''' templates, also called "global", are applicable in any context, without a target.
|
||||
|
||||
Whether targeted or targetless, a template can be a fixed pattern or have '''arguments''' which enable you to parameterize to your needs.
|
||||
|
||||
<span id="how_do_i_use_templates"></span>
|
||||
= How do I use templates in EiffelStudio? =
|
||||
= 2. How do I use templates in EiffelStudio? =
|
||||
|
||||
Code templates are part of EiffelStudio’s code completion mechanism. Code completion lets you choose a code template at the same place where it offers you features to call, typically after you type a dot character “.” after the name of an applicable local variable. attribute or function
|
||||
|
||||
==Target templates==
|
||||
<span id="targeted_templates"></span>
|
||||
==Targeted templates==
|
||||
When you type a dot character “.” after the name of an applicable target, a menu appears:
|
||||
|
||||
[[Image:target_template_1_0]]
|
||||
|
||||
Figure 1. Auto-completion with code template option
|
||||
|
||||
If there are any applicable targeted templates, the first entry says “Show templates (Ctrl+Space)” and you can click it to get a list of applicable templates:
|
||||
Except for the first one in this example, the entries of this menu list the ''features'' applicable to the current target. But if you are interested in templates, select the first entry, which only appears if there are any applicable templates, and says “Show templates (Ctrl+Space)”
|
||||
|
||||
[[Image:target_template_1_1]]
|
||||
|
||||
Figure 2. Auto-completion with code templates option list
|
||||
Figure 2. Auto-completion gives list of code templates
|
||||
|
||||
As suggested, you can also type Control-space to get the same effect. If you find a template that you like, just click it (or navigate to it in the list using the up and down arrow keys, then type Return).
|
||||
As suggested, you can also type Control-space again to get the same effect. (Click "Show features" if you decide to go back to showing the applicable features, rather than templates.)
|
||||
|
||||
If you find a template that you like, just select it.
|
||||
|
||||
<span id="targetless_templates"></span>
|
||||
== Targetless templates ==
|
||||
It's also possible to use code templates without a target after type Control-Space, if there are any applicable targetless templates, the first entry says “Show templates (Ctrl+Space)” and you can click it to get a list of applicable templates. Choose the desired one by clicking or navigating.
|
||||
It is also possible to use code templates without a target. When you type Control-Space, if there are any applicable targetless templates, the first entry says “Show templates (Ctrl+Space)”:
|
||||
|
||||
[[Image:targetless_template_1_3]]
|
||||
|
||||
If you click this "Show templates"
|
||||
|
||||
Figure 3. Targetless auto-completion with code template option
|
||||
|
||||
When you insert a template into your code, it will often have some highlighted fields, corresponding to the template arguments, for example the lower and upper bounds of the array slice whose maximum you need:
|
||||
When you insert a template into your code, it will often have some highlighted fields, corresponding to the template arguments, for example, the lower and upper bounds of the part of an array or ("slice") whose minimum you seek:
|
||||
|
||||
[[Image:targetless_template_1_4|680px]]
|
||||
|
||||
Figure 4. Targetless auto-completion with code templates option list.
|
||||
|
||||
<span id="eiffel_studio_templates"></span>
|
||||
= Where does EiffelStudio find the templates? =
|
||||
|
||||
To offer the template menus seen above, EiffelStudio looks in two locations:
|
||||
<span id="filling_in_arguments"></span>
|
||||
== Filling in arguments ==
|
||||
|
||||
Some templates let you parameterize their code by filling ''arguments'' in a highlighted field. Initially, the field contains the corresponding argument's default value; you can leave that default, or override it with your own choice. If the template uses the argument several times, you can fill in the value in any of the corresponding fields, and all others will automatically be updated.
|
||||
|
||||
In the menu of targeted array templates shown above, the template <code>slice_minimum </code> is an example of template with arguments. It looks like this:
|
||||
|
||||
[[Image:target_template_with_input_parameters_1_0|680px]]
|
||||
|
||||
Figure 5. A template with arguments
|
||||
|
||||
This template, used to compute the minimum of a part, or "slice", of an array, has two arguments, representing the bounds of the slice. If you select the template, you will see two highlighted fields, initialized with the respective default values <code>default: "target.lower</code> and <code>target.upper"</code> of these arguments:
|
||||
|
||||
[[Image:target_template_with_input_parameters_1_1]]
|
||||
|
||||
Figure 6. Inserted template code, with highlighted argument fields
|
||||
|
||||
The reason for these defaults is that much of the time you will want the minimum of the ''whole'' array. If you are happy with that default, just leave the fields as they are But if you just need a smaller slice, for example excluding the first and last elements, just type the desired values in the corresponding fields:
|
||||
|
||||
[[Image:target_template_with_defaults_overridden_1_1]]
|
||||
|
||||
Figure 7. Inserted template code, with highlighted argument fields
|
||||
|
||||
Note that each argument appears in two different fields; if you edit any of these fields, the other will get updated automatically.
|
||||
|
||||
<span id="template_definition"></span>
|
||||
= 3. Can I define my own templates? =
|
||||
|
||||
It is very easy to define a template. It is all done in Eiffel, of course. You simply define a class that inherits from TEMPLATE, with any number of routines, each of which introduces one template, applicable to targets of the corresponding type. If the routine has arguments, those will be the arguments of the template.
|
||||
|
||||
|
||||
<span id="eiffel_studio_templates"></span>
|
||||
== Where does EiffelStudio find the templates? ==
|
||||
|
||||
To offer templates as part of code completion, EiffelStudio looks in two locations:
|
||||
* Standard templates, found in:
|
||||
** Linux: <code>$ISE_EIFFEL/studio/templates/code</code>
|
||||
** Eiffel: <code>%ISE_EIFFEL%/studio/templates/code</code>
|
||||
@@ -63,10 +105,10 @@ To offer the template menus seen above, EiffelStudio looks in two locations:
|
||||
** Linux: <code> ~/.es/eiffel_user_files/16.11/templates/code</code>
|
||||
** Windows: <code>C:/Users/your_user_name/Documents/Eiffel User Files/16.11/templates/code</code>
|
||||
|
||||
<span id="template_definition"></span>
|
||||
=What does a template definition look like?=
|
||||
If you define templates for your own specific use, store them in the second location.
|
||||
|
||||
It is very easy to define a template. It is all done in Eiffel, of course. You simply define a class that inherits from TEMPLATE, with any number of routines, each of which introduces one template, applicable to targets of the corresponding type. If the routine has arguments, those will be the arguments of the template. Basically, that’s it!
|
||||
<span id="targeted_definition"></span>
|
||||
== Defining a targeted template ==
|
||||
Here is how we defined the template used in the above targeted example:
|
||||
|
||||
<code>
|
||||
@@ -86,34 +128,96 @@ feature -- Templates
|
||||
end
|
||||
end
|
||||
|
||||
slice_maximum (low, high: INTEGER): T
|
||||
-- Maximum of an array,
|
||||
-- where the interval is defined by default
|
||||
-- by array.lower |..| array.upper.
|
||||
note
|
||||
tags: "Algorithm, Maximum, ARRAY"
|
||||
default: "target.lower, target.upper"
|
||||
do
|
||||
across low |..| high as i loop
|
||||
Result := Result.max (target [i.item])
|
||||
end
|
||||
end
|
||||
slice_minimum (low, high: INTEGER): T
|
||||
-- Minimum of `target' array, where the interval is defined by default by target.lower |..| target.upper.
|
||||
note
|
||||
title: "Array slice minimum"
|
||||
tags: "Algorithm, Minimum, ARRAY"
|
||||
default: "target.lower, target.upper"
|
||||
do
|
||||
Result := low
|
||||
across low |..| high as i loop
|
||||
Result := Result.min (target [i.item])
|
||||
end
|
||||
end
|
||||
end
|
||||
</code>
|
||||
|
||||
This class defines two templates: maximum for the maximum of an entire array, and slice_maximum for the maximum of some contiguous part (“slice”) of that array.
|
||||
That was a targeted template: EiffelStudio will propose it whenever the user types a dot after a target of type ARRAY [T] where T is a “COMPARABLE”. Note how you specify the target: as the actual generic parameters of TEMPLATE; that’s why the definition starts here as
|
||||
This class defines two targeted templates: ''maximum'' for the maximum of an entire array, and ''slice_minimum'' for the minimum of some contiguous part of that array.
|
||||
|
||||
To specify the target type, here arrays, just use it as the actual generic parameters of TEMPLATE (which is a generic class). Here indeed, the the definition starts as
|
||||
|
||||
<code>
|
||||
class ARRAY_TEMPLATE [T -> COMPARABLE] inherit
|
||||
|
||||
TEMPLATE [ARRAY [T]]
|
||||
</code>
|
||||
|
||||
|
||||
The correspondence between what you write in the template definition and what appears in EiffelStudio, as shown in previous sections, is straightforward:
|
||||
|
||||
# The list of templates will display the name of the feature, e.g. slice_minimum
|
||||
# It will use the header comment as explanation in the tooltip (always write a header comment!)
|
||||
#.On selection of a template, EiffelStudio will insert the template’s body into the code.
|
||||
# Argument occurrences will appear as fields for the user to fill in.
|
||||
|
||||
<span id="targetless_definition"></span>
|
||||
== Defining a targetless template ==
|
||||
|
||||
|
||||
For a targetless template, just just use TEMPLATE without a generic parameter:
|
||||
|
||||
<code>
|
||||
class TEMPLATE_READ_FILE_GLOBAL
|
||||
|
||||
inherit
|
||||
|
||||
TEMPLATE
|
||||
|
||||
feature -- Templates
|
||||
|
||||
read_file_line_by_line
|
||||
-- Read a file line by line., for binary files you can use {RAW_FILE}.
|
||||
note
|
||||
title: "Read a file line by line"
|
||||
tags: "Algorithm, Read, Files, Path"
|
||||
local
|
||||
l_file: FILE
|
||||
l_path: PATH
|
||||
do
|
||||
create l_path.make_current
|
||||
create {PLAIN_TEXT_FILE} l_file.make_with_path (l_path)
|
||||
if l_file.exists and then l_file.is_readable then
|
||||
l_file.open_read
|
||||
from
|
||||
until
|
||||
l_file.end_of_file
|
||||
loop
|
||||
l_file.read_line
|
||||
-- Use entry `l_file.last_string` such as `io.put_string (l_file.last_string); io.put_new_line`
|
||||
end
|
||||
l_file.close
|
||||
else
|
||||
io.error.put_string ("Could not read, the file:[" + l_path.name + " ] does not exist")
|
||||
io.put_new_line
|
||||
end
|
||||
end
|
||||
end
|
||||
|
||||
</code>
|
||||
|
||||
|
||||
<span id="share_code_templates"></span>
|
||||
=Sharing code templates=
|
||||
You can share your code templates using Github
|
||||
=4. Sharing code templates=
|
||||
You can share your code templates using Github.
|
||||
|
||||
<span id="fork"></span>
|
||||
== Fork the project ==
|
||||
Clone your fork, and configure the remotes.Eiffel Studio github repository at: [https://github.com/EiffelSoftware/EiffelStudio https://github.com/EiffelSoftware/EiffelStudio ]
|
||||
|
||||
# Clone your fork of the repo into the current directory: <code>git clone https://github.com/<your-username>/<repo-name></code>
|
||||
# Clone your fork of the repository into the current directory: <code>git clone https://github.com/<your-username>/<repo-name></code>
|
||||
# Navigate to the newly cloned directory: <code>cd <repo-name></code>
|
||||
# Assign the original repo to a remote called "upstream": <code>git remote add upstream https://github.com/<upstream-owner>/<repo-name></code>
|
||||
# Assign the original repository to a remote one called "upstream": <code>git remote add upstream https://github.com/<upstream-owner>/<repo-name></code>
|
||||
|
||||
If you cloned a while ago, get the latest changes from upstream:
|
||||
|
||||
@@ -122,6 +226,7 @@ git checkout <dev-branch>
|
||||
git pull upstream <dev-branch>
|
||||
</code>
|
||||
|
||||
<span id="branch"></span>
|
||||
== New branch ==
|
||||
Create a new topic branch (off the main project development branch) to contain your new code template
|
||||
<code>git checkout -b <topic-branch-name></code>
|
||||
@@ -136,20 +241,23 @@ Push your topic branch up to your fork:
|
||||
|
||||
<code>git push origin <topic-branch-name></code>
|
||||
|
||||
<span id="pull"></span>
|
||||
==Pull request==
|
||||
Open a pull request with a clear title and description
|
||||
|
||||
|
||||
<span id="review"></span>
|
||||
== Code template review ==
|
||||
For your work to be integrated into the project, the maintainers will review your work and either request changes or merge it.
|
||||
|
||||
|
||||
<span id="gui_template"></span>
|
||||
|
||||
<span id="UI"></span>
|
||||
=Associating a user interface with a template definition=
|
||||
The following image shows the relationship between the template definition and how they will look in the GUI.
|
||||
|
||||
[[Image:target_template_1_2|780px]]
|
||||
Figure 5. UI and template relationship.
|
||||
Figure 8. UI and template relationship.
|
||||
|
||||
|
||||
* Feature name or metadata `title` if present will be used as the value in the list of completion possibilities.
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 3.5 KiB |
@@ -0,0 +1 @@
|
||||
title=estore-generation.generator
|
||||
@@ -5,7 +5,7 @@
|
||||
|
||||
Type: Library <br/>
|
||||
Platform: Any <br/>
|
||||
Availability: Open Source, IFFEL License.
|
||||
Availability: Open Source, Eiffel Forum License version 2 (EFLv2)
|
||||
|
||||
The EiffelBase class library, covered by the open-source IFFEL license, is one of the principal contributions of Eiffel: a library of fundamental structures and algorithms covering the basics of computing, and resulting from a "Linnaean" effort at a general-purpose taxonomy of computing structures. EiffelBase is one of the most carefully designed and extensively used libraries in the object-oriented industry.
|
||||
The EiffelBase class library, covered by the open-source Eiffel Forum License version 2 (EFLv2), is one of the principal contributions of Eiffel: a library of fundamental structures and algorithms covering the basics of computing, and resulting from a "Linnaean" effort at a general-purpose taxonomy of computing structures. EiffelBase is one of the most carefully designed and extensively used libraries in the object-oriented industry.
|
||||
|
||||
|
||||
@@ -13,7 +13,7 @@ The "pebble" may then be dropped into any compatible "hole" (drop target—a wid
|
||||
[[Image:EiffelStudio after class pick and drop2|thumbnail|360px|center|EiffelStudio After Class Pick-and-Drop]]
|
||||
|
||||
|
||||
{{note|See [[uuid:a3789781-153b-7f4d-bb94-4bdf8923fb56|Retargeting Through Pick-and-Drop]] to see how EiffelStudio uses the Pick-and-Drop user interface.<br><br>}}
|
||||
{{note|See [[uuid:a3789781-153b-7f4d-bb94-4bdf8923fb56|Retargeting Through Pick-and-Drop]] to see how EiffelStudio uses the Pick-and-Drop user interface.}}
|
||||
|
||||
|
||||
Because the Pick-and-Drop operation has been so popular, classes have been added to the EiffelVision 2 library to make implementing this user interface very easy.
|
||||
@@ -37,7 +37,7 @@ A simple example of this is demonstrated here:
|
||||
|
||||
Because <eiffel>print</eiffel> takes an argument of type [[ref:libraries/base/reference/string_8_chart|STRING_8]], button2 becomes a valid drop-target for the pebble contained by button1. Right clicking the mouse pointer over the '''source''' will start the transport, and right clicking with the mouse pointer over a valid '''target''' will complete the transport. The transport can be canceled anytime with a simple left click, just as you would do in EiffelStudio.
|
||||
|
||||
{{note|Any type of object can be used as the '''pebble'''. When a transport completes, the '''pebble''' that was transported is passed as an argument to all agents in the '''target's''' <code>drop_actions</code> list to which the '''pebble''' [[uuid:b8c10baa-4f50-adfe-a6f8-9cb56a8f1917#Conformance|conforms]]. <br><br>}}
|
||||
{{note|Any type of object can be used as the '''pebble'''. When a transport completes, the '''pebble''' that was transported is passed as an argument to all agents in the '''target's''' <code>drop_actions</code> list to which the '''pebble''' [[uuid:b8c10baa-4f50-adfe-a6f8-9cb56a8f1917#Conformance|conforms]].}}
|
||||
|
||||
|
||||
==Three Different Modes of Transport==
|
||||
@@ -57,7 +57,7 @@ When <eiffel>mode_is_pick_and_drop</eiffel> or <eiffel>mode_is_drag_and_drop</ei
|
||||
|
||||
Example:
|
||||
|
||||
<code>
|
||||
<eiffel>
|
||||
add_some_widgets
|
||||
-- Add some widgets with a Pick-and-Drop example into `main_window'.
|
||||
local
|
||||
@@ -83,6 +83,6 @@ Example:
|
||||
create bullseye_ptr_style.make_with_pixel_buffer (bullseye_pix_buffer, 32, 32)
|
||||
my_button2.set_accept_cursor (bullseye_ptr_style)
|
||||
end
|
||||
</code>
|
||||
</eiffel>
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user